Trim the migration guide to genuine v1-to-v2 breaking changes#3183
Trim the migration guide to genuine v1-to-v2 breaking changes#3183maxisbey wants to merge 2 commits into
Conversation
The guide had accumulated entries that are not v1-to-v2 migration items: new v2 feature notes, spec-adoption commentary, deprecations of APIs that still work, and internal fixes with nothing for a migrator to change. Remove those, including the whole Deprecations and "Notes for 2026-era connections" groups. Correct code that was wrong for v1.x or stale for current main, and verify every remaining before/after example against the v1.x and main trees. Fold closely related entries together (dependency requirements, default server identity, direct calls to MCPServer's protocol methods, the in-memory testing helper), standardize on the documented `from mcp.server import MCPServer` import, regenerate the index and suggested-order blocks to match, and cut history and over-explanation throughout. No-Verification-Needed: documentation-only change
![cubic-dev-ai[bot]](https://avatars.githubusercontent.com/in/1082092?s=60&v=4){kind=small}
There was a problem hiding this comment.
No issues found across 1 file
Not reviewed (too large): docs/migration.md (~2,117 lines) - if these are generated or fixture files, add them to ignored paths to exclude them from future reviews.
Tip: cubic can generate docs of your entire codebase and keep them up to date. Try it here.
Re-trigger cubic
📚 Documentation preview
|
The trimmed guide removed the `mcp dev`/`mcp install` pinning and `Mcp-Param-*` header sections, and the strict docs build aborts on the now-missing anchors. Both whats-new bullets already carry the substance, so remove the trailing links rather than reinstating the sections. No-Verification-Needed: documentation-only change
![claude[bot]](https://avatars.githubusercontent.com/in/1236702?s=60&v=4){kind=small}
There was a problem hiding this comment.
Thanks for fixing the two dangling whats-new.md anchors from my earlier comment — commit 426de27 resolves that, and I found no new issues this run. Still deferring to a human for a final pass, since this is a large editorial rewrite of the migration guide whose behavioral claims (which v1 examples run, what was cut as non-migration content) can't be fully verified mechanically.
What was reviewed:
- Every cross-page link to
migration.md#...anchors (7 remaining) resolves against the trimmed headings; no other page links to a deleted section. - Every intra-document anchor in
migration.md(the "Find your changes" tables, suggested order, and inline cross-references) matches an existing heading slug. - Relative doc links check out; the two
api/targets are generated at build time permkdocs.yml.
Extended reasoning...
Overview
This PR is documentation-only: it trims docs/migration.md from 91 to 73 sections, removing entries that were changelog/deprecation notes rather than genuine v1-to-v2 breaking changes, correcting several before/after code blocks, and folding near-duplicate entries. It also drops two links from docs/whats-new.md whose target sections the trim removes — the exact issue a prior run of this review flagged, now resolved by commit 426de27.
Security risks
None. No code, configuration, or CI changes — only Markdown under docs/. The removed sections include some security-adjacent content (SEP-2243 header validation, credential binding), but removing documentation of shipped behavior does not change the behavior itself.
Level of scrutiny
Docs-only changes warrant moderate scrutiny: the failure mode is misleading migration guidance, not broken software. I mechanically verified everything verifiable — all cross-page and intra-document anchors resolve, no other docs page links to a deleted section, and relative links point at real (or build-generated) files. What cannot be verified mechanically is the content accuracy of the rewritten prose and code examples: the author states every surviving before/after block was executed against v1.x and main respectively, but I cannot reproduce that here, and the judgment calls about which entries count as "genuine migration content" (e.g. dropping the SEP-2352/SEP-2350 notes and the "Notes for 2026-era connections" group entirely) are editorial decisions a maintainer should sign off on.
Other factors
The prior review cycle worked as intended: the one concrete defect (dangling anchors) was reported inline and fixed in a follow-up commit before this run. The bug hunting system found nothing further. Given the size of the rewrite (~700 changed lines in migration.md) and the repository's own AGENTS.md emphasis on migration-guide accuracy for the v2 line, a human skim of the removed and rewritten sections is the remaining review work — hence deferral rather than approval.
1 participant
Cuts
docs/migration.mddown to what it is for: someone with working v1.x code that breaks (or silently changes behavior) on v2, and needs to know what to write instead. Only that file changes.Motivation and Context
The guide had drifted into a changelog. It carried new-in-v2 feature notes, spec-adoption commentary, deprecations of APIs that still work, and internal fixes with nothing for a migrator to change, alongside genuinely stale before/after code and a fair amount of history narration ("this was X, then Y"). A porter or an agent pointed at the file had to sieve for the parts that actually apply.
What changed:
mcp dev/mcp installpinning note, the 4 MiB body limit (also shipped on v1.x; kept as a one-clause note next tomax_request_body_size), the resolver capability gate, thestdio_clientshutdown rework, SEP-2352 credential binding, SEP-2350 scope unioning, lowlevel-handler registration through private attributes, thesubscribe-capability advertisement fix, and the unknown-method-32601change.McpErrorsection wrongly presented the top-levelMCPErrorexport as new (v1 already exportedMcpErrorfrommcp) and hid thate.errorstill works; several after-blocks used APIs that currentmainhas since moved past; theraise_exceptionsand missing-resource sections misstated v1 behavior. Every remaining before/after block was re-run — v1 blocks againstv1.x, v2 blocks againstmain.MCPServer.call_tool()/get_prompt()/read_resource()directly, and the in-memory testing helper with theClient(server)mode notes.from mcp.server import MCPServer.How Has This Been Tested?
Each surviving before/after example was executed or import-checked against the corresponding tree (
v1.xfor "Before",mainfor "After"), and every intra-document anchor and relative docs link was checked.markdownlintpasses.Breaking Changes
None — documentation only.
Types of changes
Checklist
Additional context
Also touches
docs/whats-new.md, but only to drop two links whose target sections this removes (themcp dev/mcp installpinning note and theMcp-Param-*header section) — the strict docs build aborts on missing anchors. Every other heading that another page links to was left intact.AI Disclaimer