mcp-migrate

mcp-migrate finds and fixes what the MCP 2026-07-28 spec revision breaks in
your server: protocol sessions and Mcp-Session-Id removed, initialize /
notifications/initialized replaced by server/discover, ping and
logging/setLevel gone, resources/subscribe replaced by
subscriptions/listen, required resultType and cache metadata on results,
server-initiated Sampling/Roots/Elicitation replaced by Multi Round-Trip
Requests, and more. The official Python SDK ships no codemod for any of
this -- only a manual migration guide. The TypeScript codemod only handles
the v1→v2 package rename, not the protocol changes. mcp-migrate fix is the
only thing that edits your server's code for you.

uvx mcp-migrate check .
uvx mcp-migrate fix . --write

mcp-migrate check

$ uvx mcp-migrate check tests/fixtures/fixer_roundtrip

mcp-migrate v0.1.3  ->  fixer_roundtrip
2 Python files, 21 rules, spec 2026-07-28

            rule    where         what
breaking    R001    server.py:28  Mcp-Session-Id was removed from the Streamable HTTP transport.
breaking    R001    server.py:29  Mcp-Session-Id was removed from the Streamable HTTP transport.
breaking    R017    errors.py:8   -32002 for resource-not-found is the old code; 2026-07-28 uses -32602.
deprecated  R006    server.py:15  HTTP+SSE transport is deprecated.
deprecated  R006    server.py:24  HTTP+SSE transport is deprecated.
advisory    R004    server.py:32  Tools are returned without an explicit sort.
advisory    R005    server.py:16  Capabilities are declared but `extensions` is absent.
advisory    R010    (project)     This project registers MCP request handlers (tools/resources/prompts)
                                  but has no server/discover implementation anywhere in the project.
advisory    R016    server.py:32  This file implements a list/read handler but neither `ttlMs` nor
                                  `cacheScope` appears in it.

  R001  Uses Mcp-Session-Id, which no longer exists
  SEP-2567 https://github.com/modelcontextprotocol/modelcontextprotocol/pull/2567
  Sessions are gone from the transport. Mint an explicit handle server-side and take it as an
  ordinary tool argument instead.

  [... one block like this per rule that fired ...]

Grade F (26/100)  3 breaking, 2 deprecated, 4 advisory

Add your server to the board:  mcp-migrate entry --repo owner/name

Zero findings prints Grade A and a ready-to-paste badge instead. Add
--json for machine-readable, uncapped output (the terminal table caps each
rule at 5 rows with a "+N more" line so it stays readable; JSON always has
every finding).

Exit codes, so it drops straight into CI:

The third one matters. mcp-migrate only reads Python today. Point it at a
TypeScript server and it refuses, with no grade and no badge:

$ mcp-migrate check ./my-ts-server

mcp-migrate v0.1.3  ->  my-ts-server

Nothing scannable here. Found 24 TypeScript, 3 JavaScript, but no Python --
and mcp-migrate only reads Python today.
TypeScript support is the most-wanted thing in this repo and it is up for
grabs: https://github.com/dheerajjha/mcp-migrate/issues/30
No grade and no badge: this tool has no opinion about code it could not read.

An empty finding set means "we read it and it's clean" or "we read
nothing", and a grade that can't tell those apart is worthless. So a tree
with nothing readable in it gets silence instead of an A — see
issue #30 if you want
to make TypeScript work.

By default, check skips test code: anything under a tests/, test/,
testing/, fixtures/, examples/, or docs/ directory, plus test_*.py,
*_test.py, and conftest.py files. A backward-compat test that
deliberately exercises a deprecated transport, or an integration test that
posts a literal {"method": "tools/list"} payload, is evidence your project
is well tested -- not evidence the server itself is broken. Pass
--include-tests to scan those paths too.

mcp-migrate fix

$ uvx mcp-migrate fix tests/fixtures/fixer_roundtrip

errors.py
--- a/errors.py
+++ b/errors.py
@@ -5,7 +5,7 @@
 
 def read_resource(handle: str) -> dict:
     if not _exists(handle):
-        return {"code": -32002, "message": "resource not found"}
+        return {"code": -32602, "message": "resource not found"}
     return {"contents": _load(handle)}
 
 
  [R017/safe] line 8: resource-not-found error code -32002 -> -32602

server.py
--- a/server.py
+++ b/server.py
@@ -12,26 +12,29 @@
 from __future__ import annotations
 
 from mcp.server import Server
-from mcp.server.sse import SseServerTransport
+from mcp.server.streamable_http import StreamableHTTPServerTransport
 from mcp.types import ServerCapabilities, Tool, ToolsCapability
 
 server = Server("fixture-server")
 
 capabilities = ServerCapabilities(
     tools=ToolsCapability(list_changed=True),
+    extensions={},
 )
 
-transport = SseServerTransport("/messages")
+# TODO(mcp-migrate): verify no constructor args were lost moving off SSE, see https://modelcontextprotocol.io/specification/draft/changelog
+transport = StreamableHTTPServerTransport()
 
 
 def _session_for(request):
-    mcp_session_id = request.headers.get("Mcp-Session-Id")
+    # TODO(mcp-migrate): replaced by an explicit handle argument, see https://github.com/modelcontextprotocol/modelcontextprotocol/pull/2567
+    # mcp_session_id = request.headers.get("Mcp-Session-Id")
     return mcp_session_id
 
 
 @server.list_tools()
 async def list_tools() -> list[Tool]:
-    return [
+    return sorted([
         Tool(name="zeta", description="Last alphabetically."),
         Tool(name="alpha", description="First alphabetically."),
-    ]
+    ], key=lambda t: t.name)
  [R001/review] line 28: commented out Mcp-Session-Id header access, added TODO
  [R004/safe] line 35: wrapped returned tool list in sorted(key=lambda t: t.name)
  [R005/safe] line 20: added extensions={} to ServerCapabilities(...)
  [R006/review] line 15: import Streamable HTTP transport instead of SSE
  [R006/review] line 25: SseServerTransport(...) -> StreamableHTTPServerTransport(), flagged for review

2 file(s), 6 change(s): 3 safe, 3 flagged for human review
4 finding(s) still need a human after this fix -- run `mcp-migrate check tests/fixtures/fixer_roundtrip` for details.
Dry run -- nothing was written. Re-run with --write to apply.

fix runs in dry-run mode by default (that's what --dry-run names
explicitly; it's implied when you pass neither flag) -- it prints the exact
unified diff for every file that would change and writes nothing. Pass
--write to apply it. --dry-run and --write are mutually exclusive.

Every change is tagged safe or review in the diff output:

• safe -- the fixer is certain the transformation can't change
  behavior (e.g. wrapping an already-unordered list literal in sorted(),
  or adding extensions={} where absent already meant "no extensions").
  Apply these with confidence.
• review -- the fixer did the mechanical part it can be sure of
  (renaming an import, commenting out a now-nonexistent header read) and
  left a # TODO(mcp-migrate): ... exactly where a human has to finish the
  job, because the rest genuinely requires a judgment call this tool can't
  make for you (what do you name the new handle argument? what constructor
  args did the old transport need that the new one doesn't take?).

Pass --safe-only to apply only safe fixers, --rule R006 to restrict to
one rule, --include-tests to also fix test/fixture paths (skipped by
default, same rule as check). Only 5 of the 21 rules ship a fixer at all --
see the table below and mcp-migrate fixers. Fixers are
deliberately conservative: when a fixer can't be sure a transformation is
correct, it leaves the source untouched rather than guess. A wrong fix that
silently corrupts your server is worse than reporting the finding and doing
nothing.

Other commands

mcp-migrate rules                     # list every rule this version ships, with severity and spec ref
mcp-migrate fixers                    # list every fixer, with confidence (safe/review)
mcp-migrate entry --repo owner/name   # print a registry/servers/*.yaml entry for the board

Every rule

Run mcp-migrate rules to see this list for the exact version you have
installed, and mcp-migrate fixers for the fixer confidence table. Full
spec changelog: https://modelcontextprotocol.io/specification/draft/changelog.

Missed something and want to fill in a fixer, or just document the manual
fix? See Contribute below and
cookbook/ for every change that doesn't have a
recipe yet.

The grade

Every finding costs points, but no single rule can sink your grade by
itself: each rule's total contribution is capped, no matter how many times
it fires. Real evidence for why this matters: mcp-atlassian's R003 once
hit 19 times on the same false-positive pattern, for 475 raw penalty
points -- over 4x what one rule is now allowed to cost.

Score starts at 100 and floors at 0. The letter grade comes from the score:

Get your badge

Run the check, fix what's breaking, then generate your entry and badge in
one shot:

uvx mcp-migrate entry --repo owner/name > registry/servers/name.yaml

entry refuses — writing nothing to stdout, so the redirect above leaves no
file behind — if it can't read your server, or if your Python is a small
minority of a repo that's mostly something else. A board entry is a claim
about a whole repo, and this project would rather publish nothing than
publish a grade it can't stand behind.

That prints something like:

# registry/servers/name.yaml
name: name
repo: owner/name
language: python
grade: A
score: 100
checked_with: mcp-migrate 0.1.0
spec: "2026-07-28"
status: ready
notes: >-
  Replace this line with one sentence about what your server does.

Edit the notes: line to one sentence about what your server does, then PR
it into this repo (steps in
CONTRIBUTING.md).
CI validates the YAML against registry/schema.yaml and regenerates the
board below on merge. Listing is automated and unopinionated: schema
passes and the repo exists, it merges -- no maintainer reviews the server
itself or argues about your grade.

Drop this in your own README once you know your grade (swap the letter and
color using the table above):

[![MCP 2026-07-28](https://img.shields.io/badge/MCP%202026--07--28-A-brightgreen)](https://github.com/owner/name)

The board

14 servers checked (6x A, 6x B, 1x C, 1x D)

Contribute

Three ways in, cheapest first:

• A cookbook recipe (~5 minutes). Pick an open slot in
  cookbook/ -- markdown, no Python, no tests. See
  CONTRIBUTING.md.
• A rule (~15 minutes). A Rule subclass -- a check(project) method,
  a regex or an AST walk, a Finding for every hit. Most rules are under 25
  lines. See CONTRIBUTING.md.
• A fixer (~45 minutes). A Fixer subclass that turns one rule's
  finding into a text-level edit, tagged safe or review. See
  CONTRIBUTING.md.

The standing principle behind all three: a false positive is worse than a
missed finding. When a rule can't be made precise, it ships advisory, or
it doesn't ship. Reviews happen within 48 hours; one passing test is enough
to merge.

Listing your own server on the board is separate from all three and takes
about 60 seconds -- see
CONTRIBUTING.md.

Contributors

TypeScript support exists because these people built it. The language
backend shipped with two reference ports (R001 and R006). The other twelve
were contributed -- in parallel, by seven people who mostly hadn't spoken
to each other, each working from a separate issue.

git shortlog -sne is the authoritative list; .mailmap folds
the duplicate identities so nobody is counted twice or split in half.

Working principles

A false positive is worse than a missed finding. This tool publishes
public grades about other people's projects. A wrong breaking verdict costs
a maintainer their badge and their trust in the tool; a missed advisory
costs a little visibility and nothing else. When a detection can't be made
precise it ships advisory, or it doesn't ship. Fixers follow the same rule:
one that can't be certain a transformation is correct leaves the source
untouched.

An unearned grade is as damaging as an undeserved finding, and harder to
notice. A server that scores A because a rule couldn't see its handlers is a
bug, not a pass -- see
r010_server_discover_missing.py,
where three registration idioms used by real servers went undetected.

No grade is published that hasn't been reproduced. Every entry in
registry/servers/ comes from a scan someone ran and read, at that server's
own directory. Nothing is estimated, and nothing is carried forward from a
previous version of the rules.

Contributing stays cheap. One small file is the unit of contribution, and
a submission that passes schema validation and points at a real repository is
merged -- there's no usage bar, no curation step, and no reviewer taste test.
Reviews happen within 48 hours and one passing test is enough to merge a rule.

The longer form of all of this, with the API you'd actually use, is in
CONTRIBUTING.md.

License

Apache-2.0. See LICENSE.

Listing on the board is automated and unopinionated: if
registry/servers/*.yaml passes schema validation and the repo it points at
exists, it gets merged. No maintainer reviews the server itself.