Metadata-Version: 2.4
Name: swaitch
Version: 1.0.0
Summary: Switch IDEs without losing your AI conversation context. An MCP server that bridges conversations across coding assistants.
Project-URL: Homepage, https://github.com/yourusername/swaitch
Project-URL: Documentation, https://swaitch.mintlify.app
Project-URL: Repository, https://github.com/yourusername/swaitch
Project-URL: Issues, https://github.com/yourusername/swaitch/issues
Author: Ramraj Bishnoie
License-Expression: MIT
License-File: LICENSE
Keywords: ai,context,conversation,copilot,cursor,ide,mcp,model-context-protocol
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Libraries
Classifier: Topic :: Software Development :: Quality Assurance
Classifier: Typing :: Typed
Requires-Python: >=3.10
Requires-Dist: fastmcp>=3.0.0
Requires-Dist: pydantic>=2.0
Requires-Dist: sqlalchemy>=2.0
Requires-Dist: watchfiles>=1.0.0
Provides-Extra: dev
Requires-Dist: pytest-asyncio>=0.24; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: ruff>=0.8; extra == 'dev'
Description-Content-Type: text/markdown

<div align="center">

# swAItch

### Switch IDEs without losing your AI conversation context.

[![PyPI version](https://img.shields.io/pypi/v/swaitch?color=blue&logo=pypi&logoColor=white)](https://pypi.org/project/swaitch/)
[![Python](https://img.shields.io/pypi/pyversions/swaitch?logo=python&logoColor=white)](https://pypi.org/project/swaitch/)
[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)
[![MCP](https://img.shields.io/badge/MCP-Compatible-purple?logo=data:image/svg+xml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHZpZXdCb3g9IjAgMCAyNCAyNCIgZmlsbD0id2hpdGUiPjxjaXJjbGUgY3g9IjEyIiBjeT0iMTIiIHI9IjEwIi8+PC9zdmc+)](https://modelcontextprotocol.io/)

**An MCP server that bridges AI conversations across coding assistants.**
<br/>
Stop losing context. Start where you left off — in any IDE.

[Install](#install) · [Quick Start](#quick-start) · [Tools](#tools) · [Docs](https://swaitch.mintlify.app) · [Contributing](#contributing)

</div>

---

## Why swAItch?

You're deep in a conversation with your AI assistant in Cursor. You've discussed architecture, iterated on a plan, debugged a tricky issue. Now you want to switch to another IDE — but **all that context is gone**.

swAItch makes IDE conversations portable. It's an [MCP server](https://modelcontextprotocol.io/) that reads your conversation history from any supported IDE and exposes it as tools that any MCP-compatible client can call.

```
┌─────────────┐     ┌─────────────┐     ┌─────────────┐
│   Cursor    │     │  VS Code    │     │  Windsurf   │
│  (source)   │     │  (source)   │     │  (source)   │
└──────┬──────┘     └──────┬──────┘     └──────┬──────┘
       │                   │                   │
       └───────────┬───────┘───────────────────┘
                   │
           ┌───────▼────────┐
           │    swAItch     │
           │   MCP Server   │
           │                │
           │  ┌───────────┐ │
           │  │  Parsers  │ │  ← Extensible parser registry
           │  │  Registry │ │
           │  └───────────┘ │
           │  ┌───────────┐ │
           │  │   File    │ │  ← Live updates via filesystem watching
           │  │  Watcher  │ │
           │  └───────────┘ │
           └───────┬────────┘
                   │
       ┌───────────┼───────────┐
       ▼           ▼           ▼
  list_sources  list_convs  get_conv
  (MCP tools exposed to any client)
```

## Highlights

- **MCP-native** — built with [FastMCP v3](https://gofastmcp.com), works with any MCP client (Cursor, Claude Desktop, etc.)
- **Extensible** — plugin-style parser system. Add new IDEs by implementing one class.
- **Live updates** — file system watcher detects new conversations in real-time.
- **Zero config** — auto-detects installed IDEs and their conversation data.
- **One command** — `pip install swaitch && swaitch` and you're running.
- **SOLID architecture** — clean abstractions, dependency inversion, single-responsibility modules.

## Supported IDEs

| IDE | Status | Storage Format |
|-----|--------|---------------|
| **Cursor** | Supported | SQLite (`state.vscdb`) |
| **VS Code Copilot** | Roadmap | JSON (`chatSessions/`) |
| **Windsurf** | Roadmap | Protobuf (`.pb`) |
| **Codex** | Roadmap | Pending |

> Want to add support for your IDE? See [Contributing](#contributing) — just implement `BaseParser`!

## Install

### pip

```bash
pip install swaitch
```

### uv (recommended)

```bash
uv pip install swaitch
```

### From source (development)

```bash
git clone https://github.com/yourusername/swaitch.git
cd swaitch
uv pip install -e ".[dev]"
```

## Quick Start

### 1. Run the server

```bash
# stdio mode (default — for MCP clients)
swaitch run

# HTTP mode (for remote/web access)
swaitch run --transport http --port 8000
```

### 2. Connect from your IDE

Add to your MCP client configuration:

**Cursor / Claude Desktop** (`mcp_config.json`):
```json
{
  "mcpServers": {
    "swaitch": {
      "command": "swaitch",
      "args": [
        "run"
      ]
    }
  }
}
```

### 3. Use the tools

Once connected, your AI assistant can:

```
You: "What conversations do I have from my other IDEs?"
→ Agent calls list_sources → list_conversations

You: "Bring in that architecture discussion from Cursor"
→ Agent calls get_conversation with the ID
→ Full context is now available in your current session
```

## Tools

swAItch exposes three MCP tools:

| Tool | Description | Parameters |
|------|-------------|------------|
| `list_sources` | Discover which IDEs have conversation data available | — |
| `list_conversations` | List conversations from an IDE with summaries | `source`, `limit` |
| `get_conversation` | Get full conversation content (messages + artifacts) | `conversation_id`, `source` |

### Typical Workflow

```mermaid
sequenceDiagram
    participant User
    participant Agent
    participant swAItch

    User->>Agent: "Bring in my Cursor conversations"
    Agent->>swAItch: list_sources()
    swAItch-->>Agent: [{ide: "cursor", status: "available", count: 4}]
    Agent->>swAItch: list_conversations(source="cursor")
    swAItch-->>Agent: [{id: "abc-123", title: "Auth Architecture", ...}]
    Agent->>User: "Found 4 conversations. Which one?"
    User->>Agent: "The auth architecture one"
    Agent->>swAItch: get_conversation(id="abc-123", source="cursor")
    swAItch-->>Agent: {messages: [...], artifacts: {...}}
    Agent->>User: "Got it! Here's the context..."
```

## Architecture

swAItch follows **SOLID principles** with a clean, extensible design:

```
src/swaitch/
├── server.py          # FastMCP server + lifespan management
├── models.py          # Pydantic v2 data models (the shared language)
├── config.py          # Platform-aware path resolution
├── tools.py           # MCP tool definitions (depend on abstractions)
├── watcher.py         # Async file system watcher (watchfiles)
└── parsers/
    ├── base.py        # Abstract BaseParser (the contract)
    ├── registry.py    # Parser registry (discovery + lookup)
    └── cursor.py      # Cursor parser implementation
```

### Adding a new IDE parser

```python
from swaitch.parsers.base import BaseParser
from swaitch.models import IDEType, IDESource, Conversation

class MyIDEParser(BaseParser):
    @property
    def ide_type(self) -> IDEType:
        return IDEType.MY_IDE

    @property
    def display_name(self) -> str:
        return "My IDE"

    def detect(self) -> IDESource:
        # Check if data exists on the system
        ...

    def get_watch_paths(self) -> list[Path]:
        # Return directories to monitor
        ...

    def list_conversation_ids(self) -> list[str]:
        # Return a list of all conversation IDs
        ...

    def get_conversation(self, conversation_id: str) -> Conversation:
        # Return full conversation with messages
        ...
```

Then register it in `server.py`:

```python
registry.register(MyIDEParser())
```

## Contributing

Contributions are welcome! Here's how to get started:

1. Fork the repository
2. Clone your fork: `git clone https://github.com/yourusername/swaitch.git`
3. Install dev dependencies: `uv pip install -e ".[dev]"`
4. Create a branch: `git checkout -b feature/my-parser`
5. Make your changes
6. Run linting: `ruff check .`
7. Submit a PR

### Adding a new IDE parser

The fastest way to contribute is by adding support for a new IDE:

1. Add the IDE type to `IDEType` enum in `models.py`
2. Add data paths to `IDEPaths` in `config.py`
3. Create `parsers/my_ide.py` extending `BaseParser`
4. Register it in `server.py`'s `_build_registry()`

## License

MIT — see [LICENSE](LICENSE)

---

<div align="center">

[⬆ Back to top](#swaitch)

</div>
