[do not merge] Add mcp-codemod, an automated v1 to v2 migration tool

.github/workflows/publish-pypi.yml

@@ -30,6 +30,7 @@ jobs:
         run: |
           uv build --package mcp
           uv build --package mcp-types
+          uv build --package mcp-codemod
 
       - name: Upload artifacts
         uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1

README.v2.md

@@ -17,7 +17,7 @@
 
 > **Important: this documents v2 of the SDK, which is in alpha.** Pre-releases are published to PyPI as `2.0.0aN`, and each alpha may contain breaking changes from the previous one.
 >
-> v2 is a major rework of the SDK, both to support the [2026-07-28 MCP specification release](https://blog.modelcontextprotocol.io/posts/2026-07-28-release-candidate/) and to fix long-standing architectural issues. See the [migration guide](https://py.sdk.modelcontextprotocol.io/v2/migration/) for what's changed. We're targeting a beta on 2026-06-30 and a stable v2 on 2026-07-27, alongside the spec release. Before stable, we plan to add a significant set of backwards compatibility shims so the final upgrade is much smaller than today's diff.
+> v2 is a major rework of the SDK, both to support the [2026-07-28 MCP specification release](https://blog.modelcontextprotocol.io/posts/2026-07-28-release-candidate/) and to fix long-standing architectural issues. See the [migration guide](https://py.sdk.modelcontextprotocol.io/v2/migration/) for what's changed; `uvx mcp-codemod v1-to-v2 ./src` automates the mechanical half of it and marks the rest with `# mcp-codemod:` comments. We're targeting a beta on 2026-06-30 and a stable v2 on 2026-07-27, alongside the spec release. Before stable, we plan to add a significant set of backwards compatibility shims so the final upgrade is much smaller than today's diff.
 >
 > **v1.x is the only stable release line and remains recommended for production.** It is in maintenance mode and continues to receive critical bug fixes and security patches. Installers never select a pre-release unless you opt in (for example `pip install mcp==2.0.0a3`), so existing installs are unaffected. **If your package depends on `mcp`, add a `<2` upper bound to your version constraint (for example `mcp>=1.27,<2`) before the stable release lands.**
 >

docs/migration.md

@@ -6,6 +6,19 @@ This guide covers the breaking changes introduced in v2 of the MCP Python SDK an
 
 Version 2 of the MCP Python SDK introduces several breaking changes to improve the API, align with the MCP specification, and provide better type safety.
 
+## Automated migration
+
+The `mcp-codemod` tool (published from `src/mcp-codemod` in this repository) rewrites every change in this guide whose meaning is unambiguous from the file alone -- the import moves, the symbol renames, the `MCPError` reshape, the camelCase to snake_case field renames, and the `mcp` requirement in `pyproject.toml` / `requirements*.txt` -- and inserts a `# mcp-codemod:` comment above every site it recognized but would not guess at. Run it on a clean branch first, then work through what it marked:
+
+```bash
+uvx mcp-codemod v1-to-v2 ./src
+grep -rn '# mcp-codemod:' ./src
+```
+
+Names are resolved through each file's imports, never matched as text, so an aliased import or an unrelated symbol that shares a name with an SDK one is never touched. Re-running on its own output is a no-op, so it is safe to apply again after a manual fix-up. To preview without writing anything, pass `--dry-run` (add `--diff` to see the full unified diff).
+
+The sections below remain the reference for the changes it cannot make for you: the lowlevel `Server` handler rewrite, relocating transport keyword arguments off the `MCPServer` constructor, and every behavioural change that has no source-level signature.
+
 ## Breaking Changes
 
 ### `MCPServer.call_tool()` returns `CallToolResult`

pyproject.toml

@@ -57,6 +57,9 @@ build-constraint-dependencies = [
 dev = [
     # We add mcp[cli] so `uv sync` considers the extras.
     "mcp[cli]",
+    # The codemod is a standalone tool, not a dependency of `mcp`; pull it in here
+    # so the workspace's test environment has it.
+    "mcp-codemod",
     "mcp-example-stories",
     "tomli>=2.0; python_version < '3.11'",
     "pyright>=1.1.400",
@@ -135,6 +138,7 @@ packages = ["src/mcp"]
 typeCheckingMode = "strict"
 include = [
     "src/mcp",
+    "src/mcp-codemod/mcp_codemod",
     "src/mcp-types/mcp_types",
     "tests",
     "docs_src",
@@ -213,10 +217,18 @@ max-returns = 13                                           # Default is 6
 max-statements = 102                                       # Default is 50
 
 [tool.uv.workspace]
-members = ["src/mcp-types", "examples", "examples/clients/*", "examples/servers/*", "examples/snippets"]
+members = [
+    "src/mcp-codemod",
+    "src/mcp-types",
+    "examples",
+    "examples/clients/*",
+    "examples/servers/*",
+    "examples/snippets",
+]
 
 [tool.uv.sources]
 mcp = { workspace = true }
+mcp-codemod = { workspace = true }
 mcp-example-stories = { workspace = true }
 mcp-types = { workspace = true }
 strict-no-cover = { git = "https://github.com/pydantic/strict-no-cover" }
@@ -265,7 +277,7 @@ MD059 = false    # descriptive-link-text
 branch = true
 patch = ["subprocess"]
 concurrency = ["multiprocessing", "thread"]
-source = ["src", "src/mcp-types/mcp_types", "tests"]
+source = ["src", "src/mcp-codemod/mcp_codemod", "src/mcp-types/mcp_types", "tests"]
 omit = [
     "src/mcp/client/__main__.py",
     "src/mcp/server/__main__.py",

scripts/codemod-batch-test/.gitignore

@@ -0,0 +1 @@
+work/

scripts/codemod-batch-test/README.md

@@ -0,0 +1,42 @@
+# Codemod batch test
+
+Runs the `mcp-codemod` v1 -> v2 migration against real, pinned repositories and
+audits the result with pyright, to find silent misses the unit tests and the
+in-repo example corpus cannot.
+
+## How it works
+
+For each repository in `repos.json`:
+
+1. Clone the pinned commit (shallow).
+2. Run the codemod (sources and dependency files) over a copy.
+3. Type-check the pristine clone against an environment holding the latest v1
+   SDK, and the migrated copy against this workspace's v2 environment, with
+   identical pyright settings.
+4. Diff the two error sets. Errors only on the migrated side are the migration
+   surface; baseline noise (the repo's own issues, missing third-party stubs)
+   appears on both sides and cancels out.
+5. Correlate each new error with the inserted `# mcp-codemod:` markers.
+
+The codemod's contract is that the markers are the complete list of remaining
+manual work, so every new error should sit on or next to a marker. **A new
+error with no nearby marker is a silent miss** -- those are printed, written to
+`work/results/<slug>.json`, and make the run exit 1.
+
+## Usage
+
+From the repository root (the v1 environment is created on first run):
+
+```bash
+uv run --frozen python scripts/codemod-batch-test/run.py            # all repos
+uv run --frozen python scripts/codemod-batch-test/run.py --repo mcp-obsidian
+uv run --frozen python scripts/codemod-batch-test/run.py --fresh    # re-clone
+```
+
+## Adding a repository
+
+Add an entry to `repos.json` with a pinned `sha` (never a branch), an
+`include` list when only part of the repository uses the SDK (empty means the
+whole tree), and a one-line `note`. Prefer repositories that depend on the
+`mcp` package directly; servers built on the external FastMCP library exercise
+that library's surface, not this SDK's.

scripts/codemod-batch-test/repos.json

@@ -0,0 +1,30 @@
+[
+  {
+    "slug": "official-servers",
+    "url": "https://github.com/modelcontextprotocol/servers",
+    "sha": "7b1170d1da1e36bc9f553f51e76e64cbfd652b3e",
+    "include": ["src/fetch", "src/git", "src/time"],
+    "note": "The official reference servers; lowlevel Server and FastMCP usage."
+  },
+  {
+    "slug": "mcp-obsidian",
+    "url": "https://github.com/MarkusPfundstein/mcp-obsidian",
+    "sha": "32285e9ac07049a8a23ea7d7903603a3e48a1bf7",
+    "include": [],
+    "note": "Popular community server; lowlevel Server with mcp.types throughout."
+  },
+  {
+    "slug": "awslabs-aws-documentation",
+    "url": "https://github.com/awslabs/mcp",
+    "sha": "3a5294539de4de3a91d0ee72d5487bc8b8b1fcd7",
+    "include": ["src/aws-documentation-mcp-server"],
+    "note": "One server from the awslabs monorepo; production FastMCP usage."
+  },
+  {
+    "slug": "android-mcp-server",
+    "url": "https://github.com/minhalvp/android-mcp-server",
+    "sha": "451d255a7305e6efef8a1a2b7374a21c512bba45",
+    "include": [],
+    "note": "Small community FastMCP server."
+  }
+]