Migration guide fixes and editor-visible deprecation for the 1.x handler form

[ochafik]

Pre-release pass over docs/migrate-to-2.md: every claim in the guide was checked against the built package (each "after" snippet typechecked, each "gone" form confirmed to fail, each deprecated form confirmed to compile and warn once, each wire delta matched to a test assertion). 48 of 52 claims held as written; this PR fixes the three that were imprecise, adds the seven things the guide did not mention, and fixes one code issue the check surfaced.

Guide changes:

• Server-author row names @modelcontextprotocol/express (createMcpExpressApp) explicitly; "express" alone was ambiguous.
• "The two SDKs do not interoperate" read as wire incompatibility. Now: they share no classes or types, but speak the same wire protocol.
• zod 4.0 and 4.1 are rejected too (no ~standard.jsonSchema before 4.2.0), not only zod 3.
• Handler-context bullet covers registerAppTool and app.registerTool callbacks, sessionId, and authInfo → http?.authInfo.
• The 1.x-shaped extra list is complete (sendRequest, sendNotification, authInfo) and names the exported LegacyRequestHandlerExtra.
• New bullet: the double-registration guard now also covers the base Protocol's notifications/progress and notifications/cancelled handlers, which 1.7.5 let you replace silently (SDK 2.0 fixups: lockfile, peers, handler guards, docs, wire-compat tests #768 extended the guard; this is the one behaviour change nothing documented).
• ResourceNotFoundError note under errors; Express row in the checklist import map; a short "What stays the same" section for 1.7.x readers.

Code change: the @deprecated tag on the legacy setRequestHandler(Schema, handler) overload sat on the parameter inside an intersection type, which TypeScript never reports, so editors did not flag the 1.x form (the raw-shape registerAppTool overload was flagged correctly). The overload now comes from LegacyRequestHandlerSetter / LegacyNotificationHandlerSetter, named types with a documented call signature; a language-service probe confirms the 1.x call is reported as deprecated on both App and AppBridge and the 2.x forms are not. Runtime behaviour is unchanged (245 tests).

Also normalises the three README quickstart links to the lowercase quickstart.html slug typedoc emits; the capitalised one only resolves today because the docs deploy keeps old files.

[github-actions]

Preview

Preview deployments for this PR have been cleaned up.

[pkg-pr-new]

Open in StackBlitz

@modelcontextprotocol/ext-apps

npm i https://pkg.pr.new/@modelcontextprotocol/ext-apps@771

@modelcontextprotocol/server-basic-preact

npm i https://pkg.pr.new/@modelcontextprotocol/server-basic-preact@771

@modelcontextprotocol/server-basic-react

npm i https://pkg.pr.new/@modelcontextprotocol/server-basic-react@771

@modelcontextprotocol/server-basic-solid

npm i https://pkg.pr.new/@modelcontextprotocol/server-basic-solid@771

@modelcontextprotocol/server-basic-svelte

npm i https://pkg.pr.new/@modelcontextprotocol/server-basic-svelte@771

@modelcontextprotocol/server-basic-vanillajs

npm i https://pkg.pr.new/@modelcontextprotocol/server-basic-vanillajs@771

@modelcontextprotocol/server-basic-vue

npm i https://pkg.pr.new/@modelcontextprotocol/server-basic-vue@771

@modelcontextprotocol/server-budget-allocator

npm i https://pkg.pr.new/@modelcontextprotocol/server-budget-allocator@771

@modelcontextprotocol/server-cohort-heatmap

npm i https://pkg.pr.new/@modelcontextprotocol/server-cohort-heatmap@771

@modelcontextprotocol/server-customer-segmentation

npm i https://pkg.pr.new/@modelcontextprotocol/server-customer-segmentation@771

@modelcontextprotocol/server-debug

npm i https://pkg.pr.new/@modelcontextprotocol/server-debug@771

@modelcontextprotocol/server-lazy-auth

npm i https://pkg.pr.new/@modelcontextprotocol/server-lazy-auth@771

@modelcontextprotocol/server-map

npm i https://pkg.pr.new/@modelcontextprotocol/server-map@771

@modelcontextprotocol/server-pdf

npm i https://pkg.pr.new/@modelcontextprotocol/server-pdf@771

@modelcontextprotocol/server-scenario-modeler

npm i https://pkg.pr.new/@modelcontextprotocol/server-scenario-modeler@771

@modelcontextprotocol/server-shadertoy

npm i https://pkg.pr.new/@modelcontextprotocol/server-shadertoy@771

@modelcontextprotocol/server-sheet-music

npm i https://pkg.pr.new/@modelcontextprotocol/server-sheet-music@771

@modelcontextprotocol/server-system-monitor

npm i https://pkg.pr.new/@modelcontextprotocol/server-system-monitor@771

@modelcontextprotocol/server-threejs

npm i https://pkg.pr.new/@modelcontextprotocol/server-threejs@771

@modelcontextprotocol/server-transcript

npm i https://pkg.pr.new/@modelcontextprotocol/server-transcript@771

@modelcontextprotocol/server-video-resource

npm i https://pkg.pr.new/@modelcontextprotocol/server-video-resource@771

@modelcontextprotocol/server-wiki-explorer

npm i https://pkg.pr.new/@modelcontextprotocol/server-wiki-explorer@771

commit: 853c9f7