docs: reframe migration guide as 'most servers: just bump' + 21 doc gaps

[felixweinberger]

Part of the v2 backwards-compatibility series — see reviewer guide.

Migration guide currently reads as a full rewrite checklist. With the BC layer, most servers just bump and follow deprecation warnings. This reframes the top + fills 21 specific gaps found during real-repo testing.

Motivation and Context

Migration guide currently reads as a full rewrite checklist. With the BC layer, most servers just bump and follow deprecation warnings. This reframes the top + fills 21 specific gaps found during real-repo testing.

v1 vs v2 pattern & evidence

v1 pattern:

n/a — docs

v2-native:

n/a

Evidence: 21 doc gaps catalogued from real-repo migration friction.

How Has This Been Tested?

• n/a
• Integration: validated bump-only against 5 OSS repos via the v2-bc-integration validation branch
• pnpm typecheck:all && pnpm lint:all && pnpm test:all green

Breaking Changes

None — additive @deprecated shim. Removed in v3.

Types of changes

• New feature (non-breaking change which adds functionality)

Checklist

• I have read the MCP Documentation
• My code follows the repository's style guidelines
• New and existing tests pass locally
• I have added or updated documentation as needed

Additional context

Stacks on: none

[changeset-bot]

🦋 Changeset detected

Latest commit: d556ce5

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 7 packages

Name	Type
@modelcontextprotocol/core	Patch
@modelcontextprotocol/client	Patch
@modelcontextprotocol/server	Patch
@modelcontextprotocol/node	Patch
@modelcontextprotocol/express	Patch
@modelcontextprotocol/fastify	Patch
@modelcontextprotocol/hono	Patch

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[pkg-pr-new]

Open in StackBlitz

@modelcontextprotocol/client

npm i https://pkg.pr.new/@modelcontextprotocol/client@1910

@modelcontextprotocol/server

npm i https://pkg.pr.new/@modelcontextprotocol/server@1910

@modelcontextprotocol/express

npm i https://pkg.pr.new/@modelcontextprotocol/express@1910

@modelcontextprotocol/fastify

npm i https://pkg.pr.new/@modelcontextprotocol/fastify@1910

@modelcontextprotocol/hono

npm i https://pkg.pr.new/@modelcontextprotocol/hono@1910

@modelcontextprotocol/node

npm i https://pkg.pr.new/@modelcontextprotocol/node@1910

commit: d556ce5

[felixweinberger]

@claude review

[felixweinberger]

@claude review

[felixweinberger]

@claude review

[felixweinberger]

@claude review

[claude]

🔴 The new Path B SSE callout has three problems in one sentence: (1) it contradicts SKILL.md — d556ce5 reverted SKILL §3 to server/sse.js → "REMOVED (migrate to Streamable HTTP)" and §8 to "SSEServerTransport removed entirely", so migration.md offers Path B users an SSE escape hatch while SKILL.md (the LLM-applied Path B procedure) says none exists; (2) it routes SSE users to @modelcontextprotocol/server-auth-legacy (which your own forward-ref map assigns to #1908, the auth package), not the SSE package (#1909) — and rg 'LegacySSEServerTransport|server-auth-legacy' returns only this line, so please confirm which v2-bc PR actually ships LegacySSEServerTransport; (3) "per the example below" is dangling — the SSE section ends one sentence later, and the NodeStreamableHTTPServerTransport example is in the section above (link to #streamablehttpservertransport-renamed instead).

Extended reasoning...

What changed

Commit d556ce5 (the Path A/B restructure) added a new callout to the SSE section at docs/migration.md:212-214:

Path B users: the v2 server package does not include SSE. Install @modelcontextprotocol/server-auth-legacy (which also bundles LegacySSEServerTransport) or migrate to Streamable HTTP per the example below.

The same commit touched docs/migration-SKILL.md only to add the new Path A/B preamble (+15/-3); it did not update §3 or §8.

(1) Cross-doc contradiction with SKILL §3 / §8

docs/migration-SKILL.md now reads:

• §3 server-imports table, row @modelcontextprotocol/sdk/server/sse.js → "REMOVED (migrate to Streamable HTTP)" — no fallback package.
• §8, titled "## 8. Removed Server Features", body: "SSEServerTransport removed entirely. Migrate to NodeStreamableHTTPServerTransport."

SKILL's own preamble says "Apply §2 onwards only if the user explicitly wants to drop @modelcontextprotocol/sdk" — i.e., §3 and §8 are the Path B procedure. So for the same path, migration.md says "install server-auth-legacy and keep SSE", while SKILL.md says "SSE is gone, rewrite to Streamable HTTP". An LLM following SKILL.md will force a Streamable-HTTP rewrite even when migration.md says a one-line install suffices.

This is the same cross-doc-disagreement category accepted and fixed in 10164d3 and 2126a9d. It is not a duplicate of resolved comment 3148499526 — that comment described the previous state (SKILL §8 said "Relocated… @modelcontextprotocol/node/sse", migration.md heading said "removed"). d556ce5 was the response: it inverted the polarity (SKILL now says removed, migration.md now offers an escape hatch) and changed the referenced package, so this is a fresh instance.

(2) server-auth-legacy vs the SSE package

Your forward-reference map in comment 3096386106 assigns server-auth-legacy → #1908 (auth) and /node/sse → #1909 (SSE) as separate v2-bc PRs. Earlier revisions of this PR pointed SSE users at @modelcontextprotocol/node/sse (#1909); d556ce5 silently switched to @modelcontextprotocol/server-auth-legacy with no citation. rg 'LegacySSEServerTransport|server-auth-legacy' returns only docs/migration.md:214 — nothing under packages/, nothing in SKILL.md.

It's possible #1908 deliberately consolidated the legacy SSE transport into the auth-legacy package, but per the cite-or-drop standard established in this thread, please confirm which v2-bc PR ships LegacySSEServerTransport (or correct the package name if it's a copy-paste from the auth row).

(3) Dangling "per the example below"

The callout ends "…or migrate to Streamable HTTP per the example below." But the SSE section contains exactly one more prose sentence (:216) before ### WebSocketClientTransport removed begins at :218 — there is no example below. The NodeStreamableHTTPServerTransport before/after example is in the preceding section ("StreamableHTTPServerTransport renamed", :194-208), i.e. above. The diff hunk @@ -111,6 +209,10 @@ added 4 lines and removed 0, so the section never had an example.

Step-by-step proof

1. A user on Path B with an SSE-based server reads docs/migration.md:214 and sees they can keep SSE by installing @modelcontextprotocol/server-auth-legacy.
2. They (or an LLM) cross-check against migration-SKILL.md — the doc this PR's own footer says is "designed for tools like Claude Code to mechanically apply all the changes".
3. SKILL §3 says server/sse.js → "REMOVED (migrate to Streamable HTTP)"; §8 says "SSEServerTransport removed entirely." Neither mentions server-auth-legacy or LegacySSEServerTransport.
4. The agent forces a Streamable-HTTP rewrite. The user, reading migration.md, expected to keep SSE. The two docs gave opposite instructions.
5. Separately, a reader who chooses "migrate to Streamable HTTP per the example below" scrolls down, finds only one prose sentence and then the WebSocket section, and has to scroll back up to find the example at :194-208.

Fix

• Cross-doc: either propagate the server-auth-legacy / LegacySSEServerTransport fallback into SKILL §3's server/sse.js row and SKILL §8's SSE paragraph, or drop the escape-hatch clause from migration.md:214 so both docs agree on "removed, migrate to Streamable HTTP".
• Package name: confirm feat(server-auth-legacy): add frozen v1 Authorization-Server package #1908 ships LegacySSEServerTransport, or correct to whatever feat(node): restore SSEServerTransport under /node/sse, @deprecated #1909 (or its successor) actually exports.
• Pointer: change "per the example below" → "per the example above".

[claude]

🟡 🟡 nit: Same uncited-codemod issue previously flagged for mcp-codemod v1-to-v2 at :251 (resolved by dropping it) has reappeared here under a different name — npx @modelcontextprotocol/codemod-v2 has no implementation in the monorepo and no cited v2-bc companion PR (unlike #1887/#1903/#1906/#1907/#1908/#1909/#1913/#1916/#1917). The table above already links each item to its manual fix, so the sentence stands without the parenthetical; either cite the PR that ships @modelcontextprotocol/codemod-v2 or drop (npx @modelcontextprotocol/codemod-v2).

Extended reasoning...

What changed

Commit d556ce5 (the Path A/B restructure) added a new "What the meta-package doesn't shim" table at docs/migration.md:43-49 and closed it with line 51:

These five were intentionally not shimmed because the codemod handles them mechanically (npx @modelcontextprotocol/codemod-v2).

What ships

rg -i 'codemod' across the entire repo returns exactly one hit: docs/migration.md:51 itself. packages/ contains only client, core, middleware, server — there is no codemod-v2 package, no bin entry in any package.json, and no other reference. A user running npx @modelcontextprotocol/codemod-v2 will get npm ERR! 404 Not Found.

Why this isn't a duplicate of resolved comment 3148499514

That comment flagged mcp-codemod v1-to-v2 at :251. The author resolved it in d556ce5 by dropping the reference (rather than citing a PR — strong evidence no codemod PR exists in the v2-bc series). But the same commit simultaneously introduced this new reference at :51 with a different package name. The target line of 3148499514 no longer contains a codemod reference; :51 is new content added after that thread was resolved, so it never went through the cite-or-drop vetting.

Why this isn't covered by the top-of-doc disclaimer

The note at :5 ("compatibility shims … land across the v2-bc PR series") licenses forward-references to shims, and the established standard in this PR's thread (comments 3096147312 / 3096386106 / 3096432260) is that each forward-reference maps to a specific cited PR. Every other not-yet-on-this-branch reference in the doc has one: isSpecType/specTypeSchema → #1887, /zod-schemas → #1906, OAuthError#errorCode → #1903, 3-arg setNotificationHandler → #1916, Protocol/ProtocolSpec → #1917, /sdk meta-package → #1913, /express RS-auth → #1907, /node/sse → #1909, server-auth-legacy → #1908. The codemod has none.

Step-by-step proof

1. A Path A user reads the new "What the meta-package doesn't shim" section — the only section the doc tells them to read.
2. Line 51 says the five not-shimmed items are handled by npx @modelcontextprotocol/codemod-v2.
3. They run npx @modelcontextprotocol/codemod-v2.
4. npm responds npm ERR! 404 Not Found - GET https://registry.npmjs.org/@modelcontextprotocol%2fcodemod-v2 — no such package exists in the monorepo or anywhere in the cited v2-bc series.
5. They fall back to the table at :43-49, which links each of the five items to a §-section with the manual one-line fix. Migration completes; the codemod parenthetical added a 30-second dead end without adding a working path.

Impact

Low — hence nit, matching the precedent set for the same issue at :251. The rationale ("intentionally not shimmed") and the table's per-row §-links stand on their own; only the convenience-tool parenthetical is unbacked. A failed npx is a brief detour, not a blocked migration.

Fix

Same two options applied at :251:

• Cite the v2-bc PR that ships @modelcontextprotocol/codemod-v2 (matching feat(core): add isSpecType / specTypeSchemas Records for runtime validation of spec types #1887/feat(compat): McpError/ErrorCode/JSONRPCError/StreamableHTTPError + OAuth subclass aliases #1903/etc.), or
• Drop the parenthetical so the line reads e.g. "These five were intentionally not shimmed; apply the one-line edits linked above."