# AI Switch MCP Server

Open-source MCP server for **session continuity across AI coding assistants**.

When one assistant runs out of credits, another one can continue with full context from the same persistent session store.

## What This Solves

- Preserve coding context between Cursor, Claude Code, Claude Desktop, and other MCP clients.
- Generate clean handoff markdown + resume prompts.
- Keep a timeline of progress, files touched, current step, and next steps.
- Store sessions in one shared location so every client sees the same state.

## Included MCP Tools

- `continue_task` - one-call auto-continue tool for prompts like "continue auth feature".
- `start_session` - create a new handoff session.
- `append_progress` - append assistant progress to a session.
- `update_session` - patch task metadata, notes, status, files, and optional progress.
- `get_session` - fetch a session by ID (with optional handoff text).
- `get_latest_session` - get most recently updated session for a project.
- `list_sessions` - list recent sessions with filters.
- `complete_session` - close out a session.
- `generate_handoff` - produce portable handoff markdown + resume prompt.
- `delete_session` - delete a session (requires `confirm=true`).
- `store_info` - show the active session store path.

## Storage

By default, sessions are stored in:

- `~/.aiswitch/sessions.json`

You can override this (recommended when sharing across multiple clients/sandboxes):

- `AISWITCH_STORE_DIR`
- `AISWITCH_STORE_FILE`

## Local Development

```bash
npm install
npm run build
npm test
```

Run server over stdio:

```bash
node dist/src/index.js
```

## Cursor Setup

Use global `~/.cursor/mcp.json` or project `.cursor/mcp.json`:

```json
{
  "mcpServers": {
    "ai-switch": {
      "command": "node",
      "args": ["/ABSOLUTE/PATH/TO/AISwitchMCPServer/dist/src/index.js"],
      "env": {
        "AISWITCH_STORE_DIR": "/ABSOLUTE/PATH/TO/shared-aiswitch-store"
      }
    }
  }
}
```

After saving, reload Cursor and confirm the server appears in MCP settings.

## Claude Code Setup

Recommended (CLI-managed):

```bash
claude mcp add --transport stdio --scope user ai-switch -- \
  node /ABSOLUTE/PATH/TO/AISwitchMCPServer/dist/src/index.js
```

With shared storage path:

```bash
claude mcp add --transport stdio --scope user \
  --env AISWITCH_STORE_DIR=/ABSOLUTE/PATH/TO/shared-aiswitch-store \
  ai-switch -- node /ABSOLUTE/PATH/TO/AISwitchMCPServer/dist/src/index.js
```

Project-scoped alternative: create `.mcp.json` in repo root.

```json
{
  "mcpServers": {
    "ai-switch": {
      "type": "stdio",
      "command": "node",
      "args": ["/ABSOLUTE/PATH/TO/AISwitchMCPServer/dist/src/index.js"],
      "env": {
        "AISWITCH_STORE_DIR": "/ABSOLUTE/PATH/TO/shared-aiswitch-store"
      }
    }
  }
}
```

## Claude Desktop Setup (macOS)

Edit:

- `~/Library/Application Support/Claude/claude_desktop_config.json`

Add:

```json
{
  "mcpServers": {
    "ai-switch": {
      "command": "node",
      "args": ["/ABSOLUTE/PATH/TO/AISwitchMCPServer/dist/src/index.js"],
      "env": {
        "AISWITCH_STORE_DIR": "/ABSOLUTE/PATH/TO/shared-aiswitch-store"
      }
    }
  }
}
```

Then fully restart Claude Desktop.

## Quick Continue (Minimal Prompting)

The server includes `continue_task`, designed for short prompts like:

- "continue the auth feature"
- "resume payment webhook work"

How it works:

1. Tries explicit `session_id` if provided.
2. Otherwise matches by `project_path` (or current working directory).
3. Otherwise searches by your request text across recent sessions.
4. Returns:
   - `resume_prompt`
   - `handoff_markdown`
   - `quick_continue_instruction`

In practice, tell the assistant:

```text
Use ai-switch continue_task for: "continue auth feature", then continue implementation.
```

## Recommended Workflow

1. In current assistant, call `start_session` at task start.
2. During work, call `append_progress` or `update_session`.
3. When switching assistants, call `generate_handoff`.
4. Paste `resume_prompt` into the next assistant (or call `get_latest_session` there).
5. Continue updating the same `session_id`.

## Open Source + GitHub Release

1. Create a GitHub repository and push this project.
2. Keep `README.md` + `LICENSE` (MIT) in root.
3. Add CI (optional): run `npm test` on PRs.
4. Tag releases (`v1.0.0`, `v1.1.0`, etc.).
5. (Optional) Publish to npm so others can install easily.

### Optional npm publish flow

```bash
# Update name if needed (must be unique on npm)
npm version patch
npm publish --access public
```

Then users can run it in MCP configs with:

```json
{
  "mcpServers": {
    "ai-switch": {
      "command": "npx",
      "args": ["-y", "ai-switch-mcp-server"]
    }
  }
}
```

## Security Notes

- Do not store secrets in session notes.
- Keep `AISWITCH_STORE_DIR` in a location with proper filesystem permissions.
- If sharing `.mcp.json` in a repo, avoid hardcoded secret env vars.

## License

MIT