# swiftadopt-mcp

An [MCP](https://modelcontextprotocol.io) server that helps developers **migrate
Swift projects to Apple's 2026 ("27") platforms** — iOS 27, iPadOS 27, macOS 27,
watchOS 27, tvOS 27 and visionOS 27 — adopt the new frameworks announced at WWDC
2026, and apply current best practices to existing code.

It ships a knowledge base built from WWDC 2026 session transcripts
and a heuristic Swift code scanner, exposed as MCP tools, resources and prompts.
Works with Claude Code, Claude Desktop and the Xcode 27 agent (any stdio MCP
client).

## What it can do

- **Find what to change.** Scan a Swift file or whole project for deprecated /
  removed APIs and concrete adoption opportunities (e.g. `MXMetricManager` →
  `MetricManager`, `CXProvider` → LiveCommunicationKit, `ObservableObject` →
  `@Observable`). Every finding cites the WWDC 2026 session behind it.
- **Explain how to migrate.** Consolidated per-framework adoption guides, a
  searchable deprecation index, and full per-session detail (new APIs, migration
  steps, best practices, code patterns).
- **Explore what's new.** What's-new overviews per platform/topic and full-text
  search across every session.
- **Guided workflows.** Ready-made prompts for migrating a file, auditing a
  project, adopting a framework, or getting a platform briefing.

## Install & run

Requires Python ≥ 3.10. Distributed as a console script, so it runs with
[`uv`](https://docs.astral.sh/uv/)/`uvx` or `pipx` without a manual install.

```bash
# from a local checkout
uv run swiftadopt-mcp            # runs the stdio server

# or install the package
pipx install .                   # then: swiftadopt-mcp
```

The server speaks MCP over **stdio** by default, and over **streamable HTTP**
when you want to host it (`SWIFTADOPT_TRANSPORT=http`).

### Register with a client

**Claude Code:**

```bash
claude mcp add swiftadopt -- uvx --from /ABS/PATH/TO/swiftadopt-mcp swiftadopt-mcp
# (after publishing to PyPI:  claude mcp add swiftadopt -- uvx swiftadopt-mcp)
```

**Claude Desktop / Xcode 27** (`claude_desktop_config.json` or the editor's MCP
config) — add an entry like:

```json
{
  "mcpServers": {
    "swiftadopt": {
      "command": "uvx",
      "args": ["--from", "/ABS/PATH/TO/swiftadopt-mcp", "swiftadopt-mcp"]
    }
  }
}
```

## Tools

| Tool | Purpose |
| --- | --- |
| `whats_new(platform?, topic_area?)` | Overview of new/updated frameworks and headline sessions. |
| `search(query, limit?, topic_area?)` | Full-text search across all 40 sessions. |
| `get_session(session_id)` | Full distilled record for one session (e.g. `wwdc2026-241`). |
| `list_frameworks(status?)` | All frameworks, filterable by `new` / `updated`. |
| `get_framework_guide(name)` | Consolidated adoption/migration guide for a framework. |
| `find_deprecations(query?, framework?)` | Deprecated/removed/replaced APIs and their replacements. |
| `scan_swift_code(code)` | Scan a Swift snippet for findings. |
| `scan_swift_project(path, max_files?)` | Scan a file or directory tree. *(local/stdio only; reads the host filesystem so it is not exposed over HTTP)* |

**Resources:** `swiftadopt://catalog`, `swiftadopt://deprecations`,
`swiftadopt://session/{session_id}`, `swiftadopt://framework/{name}`.

**Prompts:** `migrate_swift_file`, `audit_project`, `adopt_framework`,
`platform_migration_briefing`.

## Run it hosted (remote)

You can host one instance and let many clients connect over HTTP, while the
knowledge base stays on your server. The filesystem scanner is disabled in this
mode; remote clients paste source into `scan_swift_code` instead.

```bash
docker compose up --build          # serves http://localhost:8000/mcp
# or:  SWIFTADOPT_TRANSPORT=http uv run swiftadopt-mcp
```

It runs fully open (no auth). Clients point at the URL, e.g. Claude Code:

```bash
claude mcp add --transport http swiftadopt https://your-host.example/mcp
```

## How it's built

```
src/swiftadopt_mcp/
├── server.py            # FastMCP server: tools, resources, prompts
├── kb.py                # knowledge-base loading + search
├── scanner.py           # heuristic Swift code scanner
└── data/                # gitignored; provide your own, then run build_kb.py
    ├── sessions/        # knowledge base
    ├── catalog.json     # built: sessions / frameworks / topics / platforms
    ├── deprecations.json# built: flattened deprecations
    └── scanner_rules.json# built: scanner regex rules
scripts/build_kb.py      # regenerates the three built files from sessions/
```

## Develop

```bash
uv sync --extra dev
uv run pytest
uv run mcp dev src/swiftadopt_mcp/server.py   # MCP Inspector (needs mcp[cli])
```

## License

MIT — see [LICENSE](LICENSE).