mcp-codemod
4 Commits
| Author | SHA1 | Message | Date | |
|---|---|---|---|---|
 Max Isbey
|
d99b1400c6 |
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). |
||
|
Max Isbey
|
ecafdc78d6 |
Re-scope the codemod to run-on-v2 minimalism
The goal is that migrated v1 code runs on v2 on its legacy paths, not that it adopts v2 idioms. Applying that bar: - Leave e.error.code / .message / .data chains alone: v2's MCPError keeps a typed .error ErrorData, so the v1 spelling runs and type-checks unchanged. The except-binding tracking goes with it. - Rewrite one-argument McpError(...) calls to MCPError.from_error_data(...) instead of flattening the inline ErrorData: the user's expression is kept as written and the non-inline form no longer needs a marker. - Convert v1 positional arguments on the lowlevel Server constructor to keywords (v2 is keyword-only after name but kept v1's names and order), pinned against the installed signature by a new ratchet test. - Reword every marker message that pointed at replaced internals or at the successor of the removed experimental tasks API; state removals plainly instead of steering users onto new surfaces. - Teach the batch harness that a reportArgumentType error naming a detonating argument type (timedelta, AnyUrl) is a real break, never v2 strictness drift, and ignore stale work/ directories. |
||
|
Max Isbey
|
801095acad |
Flag removed modules, update dependency files, add a batch-test harness
Three additions to mcp-codemod, closing the gaps a comparison with the TypeScript codemod surfaced: Imports of module namespaces v2 deleted outright (the experimental tasks namespaces, the WebSocket transports, `mcp.shared.progress`) are now marked with replacement guidance. A new ratchet test freezes the 107 public modules v1 shipped and asserts every one imports on v2, is renamed, or is in the removed table, so the whole v1 module namespace is provably accounted for. The codemod now also updates the `mcp` requirement in `pyproject.toml` (PEP 621 tables and dependency groups) and `requirements*.txt` to `>=2,<3` -- only where the current constraint cannot accept any v2 release, and only the version specifier: name, extras, environment marker, and spacing keep the user's spelling. Poetry tables and the removed `ws` extra are marked instead of guessed at, under the same `# mcp-codemod:` contract as source markers. `scripts/codemod-batch-test/` runs the codemod against pinned real repositories and audits the marker contract end to end: it type-checks the pristine clone against the latest v1 and the migrated copy against this workspace's v2 with identical pyright settings, then requires every error that exists only on the migrated side to sit next to a marker. Across the four repos in the manifest every migration-surface error is covered, and the audit caught two real bugs now fixed here: `Context` imported from the old `.server` submodule is rehomed to the package (the submodule holds the name at runtime, but a type checker treats a non-re-exported name as private), and `request_context` on a receiver the pre-pass proved holds a lowlevel `Server` is flagged again -- receiver-matched, so the live `ctx.request_context` idiom stays untouched. |
||
|
Max Isbey
|
8900f2527c |
Add mcp-codemod, an automated v1 to v2 migration tool
A new `mcp-codemod` workspace package (`uvx mcp-codemod v1-to-v2 ./src`) that rewrites every v1 -> v2 change whose meaning is unambiguous from the file alone, and inserts a `# mcp-codemod:` comment above every site it recognized but would not guess at. Built on libCST. 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. The camelCase to snake_case rename is restricted to the field names v1's `mcp.types` actually declared. Anything whose correct rewrite depends on information that is not in the file -- the lowlevel decorator to `on_*` relocation, the transport keywords on the `MCPServer` constructor -- is left exactly as written and marked instead, so the remaining work is one grep. Re-running on the output is a no-op. The mapping tables are pinned against the installed v2 package by ratchet tests so they cannot silently drift: every rename target must resolve, every removed API must be provably absent, and no flagged constructor keyword may survive on `MCPServer.__init__`. Measured against the example files that exist on both `v1.x` and `main` (whose diff is the hand-written migration), the codemod fully reproduces 13 of the 51 with a real migration diff, improves 35 more, and makes none worse. Also adds an "Automated migration" section to docs/migration.md, a mention of the tool in README.v2.md, and the package to the publish workflow's build step (the PyPI project and its trusted publisher must exist before a release is tagged with this in it). |