Rewrite lowlevel decorator registrations through generated adapters

The twelve v1 @server.* decorator kinds are gone on v2. Their sites now
become add_request_handler / add_notification_handler calls at the
decorator's exact source position (registration there is when the v1
decorator ran, so execution order is preserved and the deprecated
capabilities land on the warning-free path), wired through generated
adapters that reproduce the v1 wrapper semantics: bare-list wrapping,
call_tool's any-exception-to-isError contract with jsonschema input and
output validation (tool lookup through the registered tools/list
handler, v1's own cache mechanism, so cross-module list_tools works),
read_resource content conversion, and the completion None-mapping.
Handler bodies are never touched. Shapes the adapter cannot serve
honestly -- a stacked decorator, an attribute receiver, a non-v1
signature, a non-literal decorator argument, a taken name -- are marked
with the reason. The suite migrates a six-registration server and
serves it to a v1-shaped ClientSession over the legacy protocol; the
templates are pinned against the installed v2 (method strings register,
params models exist, imports resolve, no 2026-era surface is emitted).

Also on the client surface: inline timedelta session timeouts convert
to float seconds and non-provable values are marked (the mismatch only
fails on the first request); cursor= on session list_* methods wraps
into params=PaginatedRequestParams(...); pydantic URL wrappers around
resource URIs are dropped where the target provably takes v2's plain
str and marked elsewhere; constructions of and pydantic method calls on
the v1 RootModel wrappers that became plain union aliases are marked
with the TypeAdapter fix; ._mcp_server and the type-keyed handler dicts
are marked with their v2 homes. Adapters honor an explicit `uri: str`
annotation and keep v1's AnyUrl otherwise, and keep the emitted code
insensitive to user return annotations so a wrong annotation cannot
manufacture type errors inside generated code.

Batch harness: seven more pinned repositories (two seven-decorator
servers, a multi-package lowlevel server, the method-local-server
marker path, two client libraries including a positional timedelta
timeout and the old streamablehttp spelling, and an exact ==1.6.0 pin).
Markers now cover the full statement they precede rather than a fixed
radius, Unknown-typed errors in files that carry markers classify as
cascade of a marked break, and the work directory is a dot-directory so
pytest never collects the cloned repositories' own suites. All eleven
repositories audit at zero uncovered errors.

An adversarial review round over the full change confirmed ten defects,
all fixed with regression tests: adapter imports now inject at the top
of the module (a mid-file import as the anchor left registration code
running before its imports bound); the rewrite gates now also block a
handler named like a template local, and any module-level non-import
binding of a name the adapter references (both were silent runtime
breaks past the gates); import injection dedup now reads the updated
module's top-level import binds, so conditional or function-local
imports no longer suppress a needed injection; list_* adapters pass a
returned full result model through instead of double-wrapping (v1's
runtime behavior); the blocked-progress marker names
add_notification_handler (a request-handler registration would never
fire); the timeout transform skips already-v2 shapes so re-runs stay
no-ops; the emitted name scheme is defined once and shared between
templates and gates; and the harness classifier no longer lets a
marker cover a whole def/class body or write off arbitrary
Unknown-typed errors (header-only spans; cascade restricted to
propagation rules and never detonators).

Author: maxisbey

docs/migration.md

@@ -8,7 +8,7 @@ Version 2 of the MCP Python SDK introduces several breaking changes to improve t
 
 ## 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:
+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, the lowlevel `@server.*()` decorator registrations (through generated adapters that keep your handler bodies untouched), 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
@@ -61,6 +61,13 @@ the raised `code`, `message`, and `data` intact. Previously the tool wrapper
 caught it like any other exception and returned `CallToolResult(isError=True)`,
 which discarded the error code and structured `data`.
 
+The same applies to `@mcp.prompt()` and resource-template functions: an
+`MCPError` raised there propagates verbatim as the JSON-RPC error. On v1
+those wrappers converted it into a generic rendering error (for prompts, a
+`ValueError("Error rendering prompt ...")`), so a client matching on the
+error code or message will see the raised values instead of the wrapped
+generic ones.
+
 `MCPError` carries `ErrorData` and is the SDK's protocol-error type — raise it
 when the request itself should be rejected (missing client capability,
 elicitation required, invalid parameters). For tool *execution* failures the
@@ -550,9 +557,14 @@ from mcp.shared.exceptions import MCPError
 try:
     result = await session.call_tool("my_tool")
 except MCPError as e:
-    print(f"Error: {e.message}")
+    print(f"Error: {e.error.message}")
 ```
 
+Only the exception's name changes: `MCPError.error` still carries the full
+`ErrorData`, so an existing handler body keeps working as written. `e.code`,
+`e.message`, and `e.data` also exist as direct read-only properties if you
+prefer the shorter spelling.
+
 `MCPError` is also exported from the top-level `mcp` package:
 
 ```python
@@ -963,6 +975,17 @@ async def handle_call_tool(ctx: ServerRequestContext, params: CallToolRequestPar
 server = Server("my-server", on_call_tool=handle_call_tool)
 ```
 
+Registration does not have to move to the constructor: `add_request_handler`
+(see [below](#lowlevel-server-add_request_handler-is-now-public-and-takes-params_type))
+registers the same handler into the same registry at any point before `run()`,
+which preserves your module's statement order — `mcp-codemod` migrates decorator
+registrations this way for exactly that reason:
+
+```python
+server = Server("my-server")
+server.add_request_handler("tools/call", CallToolRequestParams, handle_call_tool)
+```
+
 ### `RequestContext` type parameters simplified
 
 The `mcp.shared.context` module has been removed. `RequestContext` is now split into `ClientRequestContext` (in `mcp.client.context`) and `ServerRequestContext` (in `mcp.server.context`).

scripts/codemod-batch-test/repos.json

@@ -3,7 +3,11 @@
     "slug": "official-servers",
     "url": "https://github.com/modelcontextprotocol/servers",
     "sha": "7b1170d1da1e36bc9f553f51e76e64cbfd652b3e",
-    "include": ["src/fetch", "src/git", "src/time"],
+    "include": [
+      "src/fetch",
+      "src/git",
+      "src/time"
+    ],
     "note": "The official reference servers; lowlevel Server and FastMCP usage."
   },
   {
@@ -17,7 +21,9 @@
     "slug": "awslabs-aws-documentation",
     "url": "https://github.com/awslabs/mcp",
     "sha": "3a5294539de4de3a91d0ee72d5487bc8b8b1fcd7",
-    "include": ["src/aws-documentation-mcp-server"],
+    "include": [
+      "src/aws-documentation-mcp-server"
+    ],
     "note": "One server from the awslabs monorepo; production FastMCP usage."
   },
   {
@@ -26,5 +32,68 @@
     "sha": "451d255a7305e6efef8a1a2b7374a21c512bba45",
     "include": [],
     "note": "Small community FastMCP server."
+  },
+  {
+    "slug": "mysql-mcp-server",
+    "url": "https://github.com/designcomputer/mysql_mcp_server",
+    "sha": "e25be7fc4e9e79d7efc52eb69d776129429a837f",
+    "include": [
+      "src/mysql_mcp_server"
+    ],
+    "note": "Seven lowlevel decorators on a module-level Server in one file; stdio + SSE wiring."
+  },
+  {
+    "slug": "kaltura-mcp",
+    "url": "https://github.com/zoharbabin/kaltura-mcp",
+    "sha": "567f016e536692959e294c1ee94c9fc901576cd8",
+    "include": [
+      "src/kaltura_mcp"
+    ],
+    "note": "Full seven-decorator lowlevel server with an explicit mcp>=1,<2 pin; handlers dispatch into other modules."
+  },
+  {
+    "slug": "arxiv-mcp-server",
+    "url": "https://github.com/blazickjp/arxiv-mcp-server",
+    "sha": "d58901760d7ede4adb162eaba1725209a933f100",
+    "include": [
+      "src/arxiv_mcp_server"
+    ],
+    "note": "Decorator-registered lowlevel server whose handlers live across tools/, prompts/, resources/ subpackages."
+  },
+  {
+    "slug": "fastapi-mcp",
+    "url": "https://github.com/tadata-org/fastapi_mcp",
+    "sha": "e5cad13cabfc725bbcb047e526816d887d96da62",
+    "include": [
+      "fastapi_mcp"
+    ],
+    "note": "Decorators on a method-local Server closing over self, with request_context introspection: the marker path."
+  },
+  {
+    "slug": "langchain-mcp-adapters",
+    "url": "https://github.com/langchain-ai/langchain-mcp-adapters",
+    "sha": "6a10b83516e825b8ff73870e5595113acc1c8c6d",
+    "include": [
+      "langchain_mcp_adapters"
+    ],
+    "note": "Client library exercising every v1 transport, session kwargs pass-through, and cursor pagination."
+  },
+  {
+    "slug": "mcpadapt",
+    "url": "https://github.com/grll/mcpadapt",
+    "sha": "538cd85628b555ef4ad9392b7270b52274f444d4",
+    "include": [
+      "src/mcpadapt"
+    ],
+    "note": "Client library on the old streamablehttp_client spelling with a positional timedelta session timeout."
+  },
+  {
+    "slug": "chroma-mcp",
+    "url": "https://github.com/chroma-core/chroma-mcp",
+    "sha": "98ff67589bdcc31b730a5415ff9529433f949077",
+    "include": [
+      "src/chroma_mcp"
+    ],
+    "note": "Org-backed FastMCP server frozen on mcp[cli]==1.6.0: the exact-pin dependency rewrite."
   }
 ]

scripts/codemod-batch-test/run.py

@@ -1,23 +1,14 @@
 """Run the v1 -> v2 codemod against real pinned repositories and audit the result.
 
-For each repository in `repos.json` this script clones the pinned commit, runs
-the codemod over a copy, and type-checks both sides with pyright: the pristine
-clone against an environment holding the latest v1 SDK, the migrated copy
-against this workspace's v2 environment. Errors that appear only on the
-migrated side are the migration surface; each one is then correlated with the
-`# mcp-codemod:` markers the codemod inserted.
+Each pinned repo is migrated and pyright-checked on both sides (pristine against the
+latest v1 SDK, migrated against this workspace's v2). Every new error must sit on or
+near a `# mcp-codemod:` marker; an uncovered error is a silent miss and exits 1.
 
-The codemod's headline 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 -- the exit code is 1 when any
-exists, and each is printed for triage.
-
-Usage, from the repository root:
-
-    uv run --frozen python scripts/codemod-batch-test/run.py [--repo SLUG] [--fresh]
+Usage: uv run --frozen python scripts/codemod-batch-test/run.py [--repo SLUG] [--fresh]
 """
 
 import argparse
+import ast
 import json
 import shutil
 import subprocess
@@ -32,28 +23,23 @@
 
 HARNESS_DIR = Path(__file__).resolve().parent
 WORKSPACE_ROOT = HARNESS_DIR.parents[1]
-WORK_DIR = HARNESS_DIR / "work"
+# Dot-directory: pytest's default norecursedirs keeps cloned repos' test suites out of `./scripts/test`.
+WORK_DIR = HARNESS_DIR / ".work"
 
-# The marker-to-error distance (in lines) still counted as "this error is
-# explained by that marker". Markers sit on the line above their site; a small
-# allowance covers multi-line statements.
+# Max line distance for an error to still count as explained by a marker.
 MARKER_RADIUS = 3
 
-# Uncovered errors default to actionable. Only these pyright rules, in a file
-# the codemod did not touch and with no mcp symbol in the message, are written
-# off as v2's own typing getting stricter about the repo's code (mocks no
-# longer satisfying defaulted generics, narrower `| None` returns). Notably
-# `reportAttributeAccessIssue` is NOT here: a removed attribute the codemod
-# failed to flag looks exactly like that.
+# Rules written off as v2 strictness drift, but only in a file the codemod did not touch and with
+# no mcp symbol in the message. `reportAttributeAccessIssue` is absent: a missed removal looks like it.
 DRIFT_RULES = frozenset({"reportArgumentType", "reportOptionalSubscript", "reportOptionalMemberAccess"})
 
-# Argument types that detonate at RUNTIME on v2 (`timedelta` where v2 takes float
-# seconds, `AnyUrl` where v2 takes `str`). A `reportArgumentType` error naming one
-# of these is a real break pyright happens to catch, never strictness drift.
+# A `reportArgumentType` error naming one of these is a real runtime break on v2, never strictness drift.
 DETONATOR_TYPES = ("timedelta", "AnyUrl")
 
-# The v1 environment lives OUTSIDE the SDK checkout: inside it, uv resolves the
-# SDK workspace itself no matter the cwd, and the env would silently hold v2.
+# Rules that carry a break's downstream type propagation rather than its source.
+CASCADE_RULES = frozenset({"reportArgumentType", "reportAssignmentType", "reportCallIssue", "reportReturnType"})
+
+# Outside the SDK checkout: inside it, uv resolves the SDK workspace itself and the env would hold v2.
 V1_ENV_DIR = Path.home() / ".cache" / "mcp-codemod-batch-test" / "v1env"
 
 V1_ENV_PYPROJECT = """\
@@ -115,9 +101,7 @@ def _load_repos(only: str | None) -> list[Repo]:
 def _ensure_v1_environment() -> Path:
     """Create (once) an environment holding the latest v1 SDK; return its python.
 
-    The returned interpreter is verified to really import a v1 `mcp.types` --
-    a baseline accidentally type-checked against v2 reports no migration delta
-    at all, so this fails loudly instead.
+    Fails loudly unless it really holds v1: a v2 baseline would report no migration delta.
     """
     env_dir = V1_ENV_DIR
     python = env_dir / ".venv" / "bin" / "python"
@@ -159,9 +143,9 @@ def _pyright_errors(repo: Repo, *, python: Path, side: Path) -> list[PyrightErro
     """Type-check one side against the env of `python`, or None when pyright dies.
 
     The config is written into the side's own root with relative includes, so
-    that root is the project root and nothing outside it is ever scanned. The
-    interpreter goes on the command line: `--pythonpath` beats the implicit
-    `VIRTUAL_ENV` that `uv run` exports, which a config `venvPath` does not.
+    nothing outside it is ever scanned.
+
+    `--pythonpath` beats the implicit `VIRTUAL_ENV` that `uv run` exports, which a config `venvPath` does not.
     """
     config = {
         "include": list(repo.include) or ["."],
@@ -181,8 +165,7 @@ def _pyright_errors(repo: Repo, *, python: Path, side: Path) -> list[PyrightErro
     summary = output.get("summary")
     assert isinstance(summary, dict)
     if not summary.get("filesAnalyzed"):
-        # A bad include path makes pyright "succeed" over nothing; a verdict
-        # based on that would be a lie, so the repo fails instead.
+        # A bad include path makes pyright "succeed" over nothing; fail the repo instead.
         print(f"  pyright analyzed zero files in {side} -- check the include paths", file=sys.stderr)
         return None
     diagnostics = output.get("generalDiagnostics")
@@ -206,21 +189,57 @@ def _pyright_errors(repo: Repo, *, python: Path, side: Path) -> list[PyrightErro
     return errors
 
 
-def _collect_markers(roots: list[Path], side: Path) -> dict[str, list[int]]:
-    """Every `# mcp-codemod:` line in the migrated tree, by file."""
-    markers: dict[str, list[int]] = {}
+def _statement_spans(source: str) -> list[tuple[int, int]]:
+    """The (lineno, end_lineno) of every statement in a parseable Python file.
+
+    A compound statement contributes only its HEADER lines (up to its first body
+    statement): a marker above a `with` covers the multi-line call in its header,
+    never the hundreds of lines inside a def or class body.
+    """
+    try:
+        tree = ast.parse(source)
+    except SyntaxError:
+        return []
+    spans: list[tuple[int, int]] = []
+    for node in ast.walk(tree):
+        if not isinstance(node, ast.stmt):
+            continue
+        end = node.end_lineno or node.lineno
+        body = getattr(node, "body", None)
+        if isinstance(body, list) and body and isinstance(body[0], ast.stmt):
+            end = min(end, body[0].lineno - 1)
+        spans.append((node.lineno, end))
+    return spans
+
+
+def _collect_markers(roots: list[Path], side: Path) -> dict[str, list[tuple[int, int]]]:
+    """Every `# mcp-codemod:` line in the migrated tree, by file, as covered spans.
+
+    A marker covers `MARKER_RADIUS` around itself plus any statement starting within that radius below it.
+    """
+    markers: dict[str, list[tuple[int, int]]] = {}
     needle = f"# {MARKER}:"
     for root in roots:
         candidates = [path for path in root.rglob("*") if path.suffix == ".py" or path.name == "pyproject.toml"]
         candidates += list(root.rglob("requirements*.txt"))
         for path in candidates:
             try:
-                lines = path.read_bytes().decode("utf-8").splitlines()
+                source = path.read_bytes().decode("utf-8")
             except (OSError, UnicodeDecodeError):
                 continue
+            lines = source.splitlines()
             hits = [number for number, line in enumerate(lines, start=1) if needle in line]
-            if hits:
-                markers[str(path.relative_to(side))] = hits
+            if not hits:
+                continue
+            spans = _statement_spans(source) if path.suffix == ".py" else []
+            covered: list[tuple[int, int]] = []
+            for hit in hits:
+                end = hit + MARKER_RADIUS
+                for start, stop in spans:
+                    if hit < start <= hit + MARKER_RADIUS:
+                        end = max(end, stop)
+                covered.append((hit - MARKER_RADIUS, end))
+            markers[str(path.relative_to(side))] = covered
     return markers
 
 
@@ -256,13 +275,18 @@ def _audit_repo(repo: Repo, *, v1_python: Path, fresh: bool) -> tuple[dict[str,
     markers = _collect_markers(roots, migrated)
     actionable: list[PyrightError] = []
     drift: list[PyrightError] = []
+    cascade: list[PyrightError] = []
     for error in new_errors:
-        nearby = markers.get(error.file, [])
-        if any(abs(line - error.line) <= MARKER_RADIUS for line in nearby):
+        spans = markers.get(error.file, [])
+        if any(start <= error.line <= end for start, end in spans):
+            continue
+        # A break's source always errors without "Unknown" in its message, so
+        # "Unknown" only appears in downstream propagation -- and in a marked file
+        # the roots are the marked ones. Detonators stay actionable regardless.
+        is_detonator = any(f'of type "{detonator}"' in error.message for detonator in DETONATOR_TYPES)
+        if "Unknown" in error.message and spans and not is_detonator and error.rule in CASCADE_RULES:
+            cascade.append(error)
             continue
-        # Uncovered errors are actionable unless everything says v2 strictness
-        # drift: an untouched file, no mcp symbol in the message, and a rule
-        # from the drift list. A silent codemod miss fails any one of these.
         if (
             error.file not in rewritten_files
             and "mcp" not in error.message.lower()
@@ -273,10 +297,11 @@ def _audit_repo(repo: Repo, *, v1_python: Path, fresh: bool) -> tuple[dict[str,
         else:
             actionable.append(error)
 
-    covered = len(new_errors) - len(actionable) - len(drift)
+    covered = len(new_errors) - len(actionable) - len(drift) - len(cascade)
     print(
         f"  pyright: {len(baseline)} baseline errors, {len(new_errors)} new after migration "
-        f"({resolved} resolved): {covered} covered by markers, {len(drift)} v2 strictness drift"
+        f"({resolved} resolved): {covered} covered by markers, {len(cascade)} marked-break cascade, "
+        f"{len(drift)} v2 strictness drift"
     )
     for error in actionable:
         print(f"  UNCOVERED  {error.file}:{error.line}  [{error.rule}] {error.message.splitlines()[0]}")

src/mcp-codemod/README.md

@@ -40,6 +40,21 @@ manual fix-up.
   change.
 - The `streamable_http_client(...) as (read, write, _)` three-tuple to the v2
   two-tuple.
+- Lowlevel `@server.list_tools()` / `@server.call_tool()` / ... decorator
+  registrations, to `server.add_request_handler(...)` calls at the same source
+  position, each wired through a generated adapter that reproduces the v1
+  wrapper semantics your handler relied on: bare-list wrapping, the `call_tool`
+  isError contract with jsonschema input/output validation, `read_resource`
+  content conversion, and the completion None-mapping. Your handler bodies are
+  not touched. A shape the adapter cannot serve honestly (a stacked decorator,
+  a `self.`-attribute server, a non-v1 signature) is marked instead.
+- Positional arguments after the name on the lowlevel `Server(...)` constructor
+  to keywords (v2 is keyword-only there but kept v1's names and order).
+- An inline `timedelta(...)` passed as a `ClientSession` timeout to
+  `.total_seconds()` (v2 takes float seconds and would only fail on the first
+  request), `cursor=` on the session's `list_*` methods to the v2
+  `params=PaginatedRequestParams(...)` form, and a pydantic `AnyUrl(...)` /
+  `FileUrl(...)` wrapper around a resource URI to the plain string v2 expects.
 - The `mcp` requirement in `pyproject.toml` and `requirements*.txt`, to
   `>=2,<3`, wherever the current constraint cannot accept any v2 release. Only
   the version specifier changes; the name, extras, environment marker, and
@@ -69,9 +84,11 @@ The codemod never guesses at these; it leaves them exactly as written and adds a
   `stateless_http=`, ...), which moved to `run()` or one of the app methods. The
   right destination depends on how you start the server, so the kwarg is left in
   place -- v2 then fails loudly -- rather than silently dropped.
-- Lowlevel `@server.call_tool()` decorators, which became `on_call_tool=`
-  constructor arguments with a different handler signature. Rewriting the
-  registration also means rewriting the handler body, which is yours to do.
+- Lowlevel decorator registrations the generated adapters cannot serve
+  honestly: a second decorator stacked on the handler, a server reached through
+  an attribute (`self.server`), a handler signature away from the v1 form, or a
+  decorator argument the codemod cannot evaluate. The marker names the reason
+  and the `add_request_handler(...)` destination.
 - Renames the codemod applied but cannot prove are right: a camelCase rename
   whose receiver could plausibly not be an mcp type gets a `# mcp-codemod: review:`
   marker so you look at it instead of trusting it.