SDK v2 migration mechanics (behavior-neutral, versionNegotiation: 'legacy')

[cliffhall]

Stack: SDK V2 + New Spec — 1 of 10 (foundation; do this first).

Migrate the codebase from @modelcontextprotocol/sdk@1.29 to SDK v2, keeping behavior identical against today's (legacy) servers. This is the behavior-neutral base that unblocks every other card in the stack: we're using SDK v2 underneath, with versionNegotiation: 'legacy' so nothing 2026-era goes on the wire yet.

Scope

• Package split: @modelcontextprotocol/sdk → @modelcontextprotocol/client (Client, transports, OAuth) + @modelcontextprotocol/core (public Zod schemas); stdio transport moves to @modelcontextprotocol/client/stdio (root barrel stays browser-safe). WebSocketClientTransport is removed.
• Run the codemod (npx @modelcontextprotocol/codemod@beta v1-to-v2 .) per client, then hand-fix the rest.
• Zod 3 → 4 (^4.2.0).
• Handlers take method strings, not schemas: client.setRequestHandler('elicitation/create', …). Spec methods drop result schemas from request()/callTool(); the raw "send request" path must pass an explicit ResultSchema from core.
• Error taxonomy rename: McpError → ProtocolError; new SdkError (string codes: RequestTimeout, ConnectionClosed, EraNegotiationFailed, …); StreamableHTTPError → SdkHttpError (.status). Unknown-tool calls now reject with -32602 instead of resolving isError: true.
• Elicitation mode discriminant: branch on params.mode === 'url' vs. form; ElicitResult.content values strictly string | number | boolean | string[].
• Protocol base class no longer exported; use client.fallbackRequestHandler for arbitrary inbound requests.
• Tasks note: requestor tasks currently ride client.experimental.tasks.* (inspectorClient.ts:listRequestorTasks). That surface changes under v2 — keep legacy tasks working here; the modern redesign is card 8.
• Set versionNegotiation: { mode: 'legacy' } explicitly so this card changes no wire behavior.

Key files

core/mcp/inspectorClient.ts, core/mcp/remote/**, core/auth/**, clients/web|cli|tui/package.json, everywhere importing @modelcontextprotocol/sdk/*.

Acceptance

• All three clients behave exactly as today against existing legacy servers.
• npm run ci green (format, lint, build, per-file ≥90 coverage, smoke, storybook).

Ref: specification/v2_new_spec_impact.md §8.1, §9.5(1).

[BobDickinson]

SDK v2 port — lessons from a spike

Notes from an exploratory port of Inspector to @modelcontextprotocol/client / server / core (legacy versionNegotiation, behavior-neutral). Intended as implementation context for the migration work tracked above.

---

Remove experimental tasks before the codemod

SDK v2 dropped the experimental tasks layer (client.experimental.tasks.*, task stores, built-in task RPC). Inspector still has a Tasks tab, client task handlers/state, test-server task fixtures, and integration tests on the old tasks/* wire.

On the spike we tried to keep that behavior with local shims. That was the wrong trade: a lot of code, handler typing problems, and an API the SDK and protocol are moving away from anyway. Modern tasks (io.modelcontextprotocol/tasks) are a separate follow-on.

Next time: strip the Tasks UI, client task paths, test-server task fixtures, and related tests first, then run the codemod on a smaller tree. If the goal is to get a clean "legacy" port, having that without the experimental tasks should be fine. We can implement the new tasks extension as part of the future 07-28-2026 work.

---

Form schemas: InspectorFormSchema + toFormSchema()

Inspector’s web form utilities define a local type called JsonSchemaType (clients/web/src/utils/jsonUtils.ts) — a subset tuned for what SchemaForm renders: enumNames, nullable, simple properties / items / oneOf, etc. It is not full Draft 2020-12 and it adds conveniences for the UI.

SDK v2 also exports a type named JsonSchemaType (from @modelcontextprotocol/client, via json-schema-typed). Same name, different type definition. After the port, protocol objects use the SDK type — e.g. Tool["inputSchema"] is the SDK’s JsonSchemaType, not Inspector’s. The JSON on the wire is often unchanged; TypeScript correctly refuses to assign one to the other.

On v1 this was mostly invisible: everything imported from @modelcontextprotocol/sdk and the local form type could coexist without many boundary collisions. The split packages and SDK’s stricter schema typing surface the clash everywhere a tool schema crosses from MCP types into the form layer (Tools/Apps screens, elicitation panels, toolOutputValidation for outputSchema).

The spike added cast helpers (asFormSchema, as unknown as JsonSchemaType) at those boundaries. Compiles, but merges two different type stories into one name.

Next time:

• Rename the local form type to InspectorFormSchema so the name collision with the SDK is obvious.
• Use SDK JsonSchemaType from @modelcontextprotocol/client anywhere you are modeling protocol/validation data.
• Add toFormSchema(...) — structural narrow from SDK schema fields to InspectorFormSchema | null, not a cast. Callers handle null when the form cannot render a shape.

Pick one canonical import for shared protocol symbols (client, not mixed with server).

---

MCP Apps: one ext-apps compat module

@modelcontextprotocol/ext-apps still peers on @modelcontextprotocol/sdk v1; published .d.ts files import v1 Client / Tool paths. After the port, Inspector uses v2 types from @modelcontextprotocol/client. Runtime is fine; TypeScript is not.

The spike scattered as unknown as at AppBridge and helper call sites.

Next time: a single compat module in core (bridge construction, UI resource URI from tool metadata, tool result forwarding), tested, with a note to delete when ext-apps#702 lands a v2 peer release.

---

Manifests — check every workspace

Inspector is fat-root + per-client node_modules (root postinstall installs each client). The codemod updates some manifests; verify all of them.

Location	Notes
Root	v2 split packages; keep ext-apps
clients/web, cli, tui	Each has its own manifest — only list packages that client imports. CLI often needs server + server-legacy for test-server vitest; web often client + core.
core/	No package.json; resolves from root
clients/launcher	Usually no SDK deps

After edits: npm install at root, grep for leftover @modelcontextprotocol/sdk, align lockfiles. Keep server, server-legacy, node external in CLI/runner bundles.

---

References

• typescript-sdk v1→v2 upgrade guide
• ext-apps#702