Uh oh!
There was an error while loading. Please reload this page.
docs: restructure migration guide — codemod-first, two-journey split, SKILL folded into upgrade-to-v2 - #2360
Merged
Conversation
|
| Name | Type |
|---|---|
| @modelcontextprotocol/core | Major |
| @modelcontextprotocol/client | Major |
| @modelcontextprotocol/server | Major |
| @modelcontextprotocol/express | Major |
| @modelcontextprotocol/fastify | Major |
| @modelcontextprotocol/hono | Major |
| @modelcontextprotocol/node | Major |
Click here to learn what changesets are, and how to add one.
Click here if you're a maintainer who wants to add a changeset to this PR
@modelcontextprotocol/client@modelcontextprotocol/codemod@modelcontextprotocol/server@modelcontextprotocol/server-legacy@modelcontextprotocol/express@modelcontextprotocol/fastify@modelcontextprotocol/hono@modelcontextprotocol/nodecommit: |
Uh oh!
There was an error while loading. Please reload this page.
Uh oh!
There was an error while loading. Please reload this page.
… SKILL folded into upgrade-to-v2 Replace the 1679-line flat migration.md and the drifting migration-SKILL.md twin with a two-journey structure under docs/migration/: - index.md (41 lines) — router: v1.x→v2 vs already-on-v2-adopting-2026-07-28. - upgrade-to-v2.md — codemod-first spine with skill frontmatter (this file IS the agent skill). TL;DR = Node20/ESM → npx codemod → grep @mcp-codemod-error → tsc. Mechanical-rename tables LINK to packages/codemod/…/mappings/*.ts instead of being reproduced; the three judgment tables (extra→ctx with optional-chaining notes, OAuth error consolidation, SdkErrorCode when-to-throw scenarios) stay inline in their subsystem section. ctx is now introduced before any usage. Unchanged-APIs is corrected: Zod *Schema constants are NOT public (core/public:19 — the SKILL had it right, the old guide had it wrong); Server low-level no longer claimed unchanged where setRequestHandler/request() changed. - support-2026-07-28.md — per-era codecs, wire-only members, multi-round-trip, subscriptions/listen, SEP-2243 headers, cache hints, tasks deprecated vocabulary, 2025-vs-2026 behavior matrix. The §12b/§12c v2-alpha framing is now explicit "If you were on a v2 alpha". Serving section consolidates and cross-references createMcpHandler/serveStdio/versionNegotiation (those source sections in server.md/client.md stay where they are). - packages/codemod/README.md — invocation, mapping links, @mcp-codemod-error marker convention. migration.md / migration-SKILL.md become 3-line redirect stubs (external links keep resolving). CLAUDE.md, REVIEW.md and docs/behavior-surface-pins.md drop the 'document in BOTH' rule for the new contribution rule. server.md/client.md links updated. Content fixes from the 2026-06-24 6-lens analysis: the L479 'Before (v1)' example that used v2 syntax is corrected; InMemoryTransport and the missing SdkErrorCode values (UnsupportedResultType, MethodNotSupportedByProtocolVersion, plus ListPaginationExceeded/EraNegotiationFailed/InputRequiredRoundsExceeded) are documented; the schema→method-string drift is resolved by linking to schemaToMethodMap.ts; the §15 stale checklist becomes the TL;DR.
felixweinbergerforce-pushed
the
fweinberger/migration-restructure
branch
from
June 24, 2026 15:30
4d691c7 to
ae11d80CompareUh oh!
There was an error while loading. Please reload this page.
9 tasks
Uh oh!
There was an error while loading. Please reload this page.
Uh oh!
There was an error while loading. Please reload this page.
Uh oh!
There was an error while loading. Please reload this page.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for freeto join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Replace the 1,678-line flat
migration.mdand the driftingmigration-SKILL.mdtwin with a two-journey structure underdocs/migration/, codemod-first.Motivation and Context
The two-file model had failed: three large tables duplicated-and-drifted, the docs flatly contradicted each other on Zod-schema export status, the SKILL §15 checklist had stopped tracking after §8, and neither file mentioned
@modelcontextprotocol/codemod(which mechanically handles ~80% of what the docs describe). Analysis atmcp/projects/v2-2026-impl/docs/2026-06-24-migration-doc-analysis.md.How Has This Been Tested?
pnpm docs:check(0 warnings),pnpm sync:snippets --check,pnpm lint:all, custom link-check (0 broken). 6-dimension adversarial coverage audit (111 agents) over the restructure; all BLOCKER/ERROR findings fixed in this commit.Breaking Changes
None (docs-only).
docs/migration.mdanddocs/migration-SKILL.mdare now redirect stubs.Types of changes
Checklist
Additional context
Structure:
docs/migration/index.md(41-line router) →upgrade-to-v2.md(codemod-first; manual sections grouped by subsystem; SKILL frontmatter — this file IS the agent skill) +support-2026-07-28.md(per-era serving, MRTR, requestState, listen, SEP-2243, cache hints, auth pointer). Mechanical-rename tables are links topackages/codemod/src/migrations/v1-to-v2/mappings/*.ts, not reproduced.packages/codemod/README.mdadded.CLAUDE.md"document in BOTH" rule replaced.Word count: 22,088 → 9,175 (−58%).