# 🎭 PhantomSwap

> **"Your data, ghosted."** — Privacy-first, bidirectional data masking & unmasking service for safe AI interactions.

[![FastAPI](https://img.shields.io/badge/FastAPI-0.115+-009688.svg?logo=fastapi&logoColor=white)](https://fastapi.tiangolo.com)
[![Python 3.11+](https://img.shields.io/badge/Python-3.11+-3776AB.svg?logo=python&logoColor=white)](https://www.python.org/)
[![SQLite](https://img.shields.io/badge/SQLite-Local%20First-003B57.svg?logo=sqlite&logoColor=white)](https://sqlite.org/)
[![MCP](https://img.shields.io/badge/Model%20Context%20Protocol-Compatible-8A2BE2.svg)](https://modelcontextprotocol.io/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

---

## 💡 The Problem & The Solution

When collaborating with Large Language Models (LLMs) on resumes, portfolio websites, codebases, or sensitive documents, personal identifiers (PII) like names, emails, phone numbers, colleges, and internal company project names are exposed.

**PhantomSwap** solves this locally:
1. **Define a Swap Session**: Map your real personal data to realistic fake placeholders.
2. **🎭 Mask**: Swap real values with fake placeholders before sending your text or code to AI.
3. **🤖 Send to AI**: Let AI build your portfolio website, optimize your resume, or refactor your code.
4. **🔓 Unmask**: Seamlessly restore all real personal values back across the generated text or entire codebase directories!

**100% Local Execution** — Your real data never leaves your computer.

---

## 🌟 Key Features

- ⚡ **Bidirectional Replacement Engine**: Guaranteed collision-safe two-pass replacement avoiding chain-replacement corruption.
- 🎨 **Modern Dark Glassmorphism UI**: Beautiful web dashboard with live stats, copy buttons, search, and directory inspector.
- 📁 **Bulk Directory Processing**: Recursively mask and unmask entire projects (e.g. AI-generated portfolio website folders) with automatic `.bak` safety backups.
- 🤖 **Native MCP Server**: Integrated Model Context Protocol server for AI coding assistants (Claude Desktop, Cursor, Windsurf).
- ⌨️ **Rich CLI**: Feature-complete terminal CLI with rich formatted tables and pipe support.
- 📜 **Task Audit History**: Complete tracking and logging of every masking operation.

---

## 🏗️ Architecture

```mermaid
flowchart TD
    subgraph Interfaces
        UI["🎨 Web UI Dashboard (Port 8000)"]
        CLI["⌨️ Terminal CLI (Typer + Rich)"]
        MCP["🤖 MCP Server (Claude / Cursor / Windsurf)"]
        API["🌐 REST API (FastAPI)"]
    end

    subgraph Core
        ENGINE["🔧 Two-Pass Replacement Engine"]
        FILEOPS["📁 Bulk File & Directory Ops"]
    end

    subgraph Storage
        DB[("💾 Local SQLite DB (phantomswap.db)")]
        BAK[("🛡️ Automatic .bak File Backups")]
    end

    UI --> API
    CLI --> API
    API --> ENGINE
    API --> FILEOPS
    MCP --> ENGINE
    MCP --> FILEOPS
    API --> DB
    MCP --> DB
    FILEOPS --> BAK
```

---

## 🚀 Quick Start

### 1. Setup & Installation

**Using `uv` (Fastest):**
```bash
# Create virtual environment and install dependencies
uv venv
uv pip install -r requirements.txt
```

**Or using standard Python (`venv`):**
```bash
# Windows
py -m venv .venv
.venv\Scripts\pip install -r requirements.txt

# Linux / macOS
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
```

### 2. Run the Web Dashboard & API

**Local:**
```bash
# With uv
uv run python -m app.main

# Or with python virtualenv
.venv\Scripts\python -m app.main
```

**Or with Docker / Docker Compose:**
```bash
# Build and run container with persistent SQLite volume
docker compose up --build -d
```

Open your browser at:
- 🌐 **Web Dashboard**: [http://127.0.0.1:8000](http://127.0.0.1:8000)
- 📚 **Interactive Swagger API Docs**: [http://127.0.0.1:8000/docs](http://127.0.0.1:8000/docs)

---

## ⌨️ Command Line Interface (CLI)

```bash
# List swap sessions
uv run python -m cli.main sessions list

# Create a new session
uv run python -m cli.main sessions create my-resume \
  --description "Masking resume personal details" \
  -m "Shiva Patel:Alex Johnson" \
  -m "shiva.patel@gmail.com:alex.johnson@example.com" \
  -m "IIT Delhi:State University"

# Mask text directly from terminal
uv run python -m cli.main mask --session my-resume --text "Shiva Patel graduated from IIT Delhi."
# Output: Alex Johnson graduated from State University.

# Unmask text
uv run python -m cli.main unmask --session my-resume --text "Alex Johnson graduated from State University."
# Output: Shiva Patel graduated from IIT Delhi.

# Mask an entire directory (e.g. portfolio project)
uv run python -m cli.main dir mask D:\projects\MyPortfolio --session my-resume --ext .html,.css,.js

# Unmask the directory when AI generation is complete
uv run python -m cli.main dir unmask D:\projects\MyPortfolio --session my-resume --ext .html,.css,.js

# View task history
uv run python -m cli.main history
```

---

## 🤖 Model Context Protocol (MCP) Integration

PhantomSwap includes a built-in MCP server that allows AI assistants to mask and unmask sensitive project context autonomously.

### Claude Desktop Configuration

Add the following to your `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "phantomswap": {
      "command": "uv",
      "args": [
        "run",
        "--directory",
        "d:/DEVELOPMENT/MulipleStringChanger",
        "python",
        "-m",
        "mcp_server.server"
      ]
    }
  }
}
```

### Available MCP Tools:
- `phantomswap_list_sessions`: List all available masking profiles.
- `phantomswap_get_session`: Retrieve replacement mappings.
- `phantomswap_create_session`: Create new session with key-value pairs.
- `phantomswap_mask_text`: Anonymize text before sending to AI.
- `phantomswap_unmask_text`: Restore original values in AI responses.
- `phantomswap_mask_directory`: Bulk mask project directories.
- `phantomswap_unmask_directory`: Bulk unmask project directories.

---

## 🧪 Testing

Run the automated test suite with pytest:

```bash
uv run pytest tests/ -v
```

---

## 📄 License

MIT License © 2026. Built with privacy in mind.