feat: MCP v2 (draft) (decomposed by #4475)

[KKonstantinov]

Don' merge this, decompose it into individual, testable issues via #4475

Migrate the TypeScript reference servers (everything, filesystem, sequentialthinking) to the v2 MCP TypeScript SDK.

Note

Do not merge this. Goal of PR is to remain open and be updated through beta, stable. See Roadmap section below.

Roadmap

• Initial alpha draft
• Review // @mcp-codemod-error comments
• Update to beta (legacy era MCP on modern interfaces)
• Update to stable - backwards compatible with legacy era MCP clients; enabling Modern stateless MCP will need maintainers support

Description

Migrates the TypeScript reference servers — everything, filesystem, and sequentialthinking — from the v1 monolithic SDK (@modelcontextprotocol/sdk@^1.29.0) to the v2 scoped packages (@modelcontextprotocol/server, @modelcontextprotocol/node, @modelcontextprotocol/core; 2.0.0-alpha.3). The Python servers are untouched.

The bulk of the migration was produced automatically by the SDK's v1-to-v2 codemod, then finished by hand for the cases the codemod flags as manual.

What the migration covers:

• Imports — @modelcontextprotocol/sdk/* → the scoped v2 packages; StreamableHTTPServerTransport → NodeStreamableHTTPServerTransport (from @modelcontextprotocol/node).
• Registration API — .tool() / .prompt() / .resource() → .registerTool() / .registerPrompt() / .registerResource() with config objects and z.object(...) (Standard Schema) input schemas.
• Request-handler context — the flat extra parameter → the nested v2 ctx (ctx.mcpReq.send, ctx.mcpReq.id, ctx.mcpReq._meta, ctx.sessionId, ctx.http?.authInfo, …).
• Tests — hand-built mock request-handler contexts in the everything suites reshaped from the flat v1 shape ({ sendRequest, requestId, _meta }) to the v2 nested shape ({ mcpReq: { send, id, _meta } }).

All three transports — stdio, SSE, and Streamable HTTP — are retained (SSE via a legacy-transport dependency).

Note: these depend on v2 alpha packages (2.0.0-alpha.x). Intended to land once the v2 SDK is released, or to be merged as a preview/draft.

Server Details

• Server: everything (primary), filesystem, sequentialthinking
• Changes to: dependencies (SDK v1 → v2), tool / prompt / resource registration APIs, the request-handler context, and the servers' test suites. The set of tools / resources / prompts exposed over the wire is unchanged.

Motivation and Context

v2 is a redesign of the TypeScript SDK: scoped, runtime-neutral packages (client / server / core), a restructured request-handler context, Standard-Schema tool inputs, and consolidated error types. Migrating the reference servers keeps them building against the shipping API, exercises the v2 surface end-to-end, and validates the automated v1-to-v2 codemod against a real, non-trivial codebase.

How Has This Been Tested?

• npm test (vitest) passes for every migrated server — 266 tests green total:
  • everything — 5 files / 105 tests (tools 59, plus prompts, resources, registrations, server)
  • filesystem — 7 files / 147 tests
  • sequentialthinking — 1 file / 14 tests
• Type-check (tsc) and build pass.
• Manual LLM-client smoke test — connect over stdio / Streamable HTTP and exercise a few tools (please confirm before submitting).

Breaking Changes

No client-facing configuration change: the servers launch the same way (stdio | sse | streamableHttp) and expose the same tools / resources / prompts. The requirements inherited from SDK v2 are Node.js ≥ 20 (v1's Node 18 support is dropped) and ESM-only. Anyone importing a server as a library must move to the v2 package names.

Types of changes

• Bug fix (non-breaking change which fixes an issue)
• New feature (non-breaking change which adds functionality)
• Breaking change (Node 20+ / ESM-only; SDK v1 → v2 internal API migration)
• Documentation update (server AGENTS.md / docs/* refreshed for v2)

Checklist

• I have read the MCP Protocol Documentation
• My changes follows MCP security best practices
• I have updated the server's README accordingly (README not touched; docs/* and AGENTS.md were updated)
• I have tested this with an LLM client (please confirm)
• My code follows the repository's style guidelines (run the server's prettier/lint over the migrated output before submitting — codemod output can need formatting cleanup)
• New and existing tests pass locally (266/266 across the three migrated servers)
• I have added appropriate error handling (existing handling preserved by the migration)
• I have documented all environment variables and configuration options (no new env vars / config introduced)

Additional context

• The migration is largely mechanical (codemod-driven). Manual finishing was concentrated in test doubles (mock request-handler contexts) and a few features not carried over in v2.
• The codemod emits advisory diagnostics for the manual cases (e.g. context objects forwarded to helpers, destructured contexts, and hand-built v1 mock contexts in tests), which guided the hand-edits.
• Suggested reviewer focus: the reshaped test mocks in src/everything/__tests__/* and the transport wiring under src/everything/transports/*.

[igorsaevets]

Two things landed after this PR was last updated (2026-07-07) that move the roadmap forward.

1. v2 is stable. @modelcontextprotocol/{core,server,node}@2.0.0 were published 2026-07-27T23:55:22Z, so the 2.0.0-alpha.3 pin here (2026-06-25) is now five prereleases plus the stable release behind. Protocol revision 2026-07-28 shipped the following day.

2. The last roadmap box — "enabling Modern stateless MCP will need maintainers support" — may be a smaller decision than it reads. I migrated a published stdio server end to end this week, and the thing that surprised me is that the installed SDK version does not select the era. The entry point does. The v2 migration guide says it outright: "Nothing in v2 puts a 2026-07-28 byte on the wire by default." A Server handed to a StdioServerTransport keeps serving the 2025 era at any SDK version, so the dependency bump alone leaves the reference servers exactly where they are today.

The whole change is at the entry point:

// 2025 era only, whatever the installed SDK version is
const server = new Server(/* ... */);
await server.connect(new StdioServerTransport());

// both eras; era pinned per connection from the opening message
serveStdio(() => buildServer(), { legacy: 'serve' });

legacy: 'serve' is the part that bears on "backwards compatible with legacy era MCP clients" — it keeps the initialize handshake answering rather than replacing it, so existing clients are unaffected.

Measured on a real published package with raw JSON-RPC frames, deliberately not the client SDK, so the evidence does not depend on the library under test. One process per arm, because the era is pinned per connection and you cannot exercise two eras down one pipe:

opening message	0.1.2 (pre-migration, from npm)	0.2.0 (after)
server/discover + 2026-07-28 claim in _meta	-32601 Method not found	OK — returns supportedVersions, capabilities, resultType, ttlMs, cacheScope
server/discover, no version claim	-32601	-32601
initialize (2025-11-25)	OK	OK — still answers protocolVersion: "2025-11-25"

Row 2 is not a regression, and this is the part I would flag for whoever writes the test expectations in #4475: the spec classifies a message carrying no version claim in _meta as a 2025-era opening, so -32601 is the correct answer in both columns. I first read that as the migration having failed and went looking for a bug in the server, when the bug was in my probe.

One side effect that may matter for reference servers specifically: dropping the monolithic v1 SDK took that package from 117 production dependencies to 26, because the v1 bundle pulls an HTTP and OAuth stack into a server that only speaks stdio.

Probe script, if it is useful for the decomposition's test expectations: https://github.com/igorsaevets/page2ai-mcp/blob/main/scripts/probe-protocol.mjs — node scripts/probe-protocol.mjs node dist/index.js, and point it at the previously published version for the control arm. Two caveats I hit while producing the table above, since they would bite anyone reproducing it: on Windows npx needs the shell (Node refuses .cmd since the CVE-2024-27980 mitigation), and a cold npx download will outrun a fixed startup delay — both failures surface as "no response", which is indistinguishable from a server that ran and stayed silent. The script now waits for the readiness banner instead.

Happy to pick up one of the scoped sub-issues once #4475 is decomposed, if that is useful.