feat: MCP v2 (draft)

[KKonstantinov]

Migrate @upstash/context7-mcp to MCP TypeScript SDK v2

Summary

This PR migrates the packages/mcp server (@upstash/context7-mcp) from the MCP
TypeScript SDK v1 (@modelcontextprotocol/sdk) to v2
(@modelcontextprotocol/server + @modelcontextprotocol/node).

It is a mechanical, behavior-preserving migration — no tool logic, prompts, transport
wiring, or runtime behavior changed. The bulk of it was produced by the official
@modelcontextprotocol/codemod and then reviewed by hand.

Why v2

v2 replaces the single monolithic @modelcontextprotocol/sdk package with a set of
focused, ESM-only packages:

• @modelcontextprotocol/server — the runtime-neutral server API (McpServer,
  stdio transport, shared types).
• @modelcontextprotocol/node — the Node.js HTTP transport
  (NodeStreamableHTTPServerTransport).

The result is a smaller dependency surface, a cleaner public API, and first-class
support for non-Node runtimes. v1 is being superseded, so new work should target v2.

What changed (high level)

Area	Before (v1)	After (v2)
Dependencies	@modelcontextprotocol/sdk	@modelcontextprotocol/server + @modelcontextprotocol/node
Imports	deep paths under @modelcontextprotocol/sdk/...	the two new packages
Tool input schemas	raw Zod shape { query: z.string() }	wrapped z.object({ query: z.string() })
Low-level handlers	setRequestHandler(ListPromptsRequestSchema, …)	setRequestHandler("prompts/list", …)
HTTP transport	StreamableHTTPServerTransport	NodeStreamableHTTPServerTransport

Two concrete illustrations:

// Tool schemas now use Standard Schema — raw shapes are wrapped in z.object()
inputSchema: z.object({
  query: z.string().describe("…"),
  libraryName: z.string().describe("…"),
}),

// Low-level handlers take a method string instead of a Zod request schema
server.server.setRequestHandler("prompts/list", async () => ({ prompts: [] }));
server.server.setRequestHandler("resources/list", async () => ({ resources: [] }));
server.server.setRequestHandler("resources/templates/list", async () => ({ resourceTemplates: [] }));

What did NOT change

• Tool names, descriptions, annotations, and arguments.
• The Express/Streamable-HTTP and stdio serving logic.
• Auth, JWT handling, session store, and API-call code.
• The zod dependency (already ^4.4.3; v2's Standard Schema requirement is satisfied
  by Zod v4).

How this was produced

Generated with the official MCP v1→v2 codemod and reviewed by hand:

npx @modelcontextprotocol/codemod packages/mcp/src

Verification

All package checks pass after the migration:

• ✅ typecheck (tsc --noEmit)
• ✅ build (tsc)
• ✅ test (vitest run) — 12/12 passing
• ✅ lint (eslint .)

Before merging

• v2 is currently pre-release (2.0.0-alpha.3). The dependency pins reflect that.
  Recommend merging once v2 reaches a stable release and re-pinning to the GA version.
• The minimumReleaseAgeExclude: ['@modelcontextprotocol/*'] entry added to
  pnpm-workspace.yaml exempts the SDK packages from this repo's 7-day
  minimumReleaseAge gate so the pre-release versions can be installed. It can be
  removed once the depended-on v2 release is older than that window.

Roadmap

• Initial alpha draft
• 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 context7 maintainers support

[enesgules]

We do use a stateful implementation with Redis currently which we should get rid of with this PR right?

[enesgules]

Pushed an update that moves the migration to the SDK's stateless serving model (per the 2026-07-28 migration guide):

• Bumped @modelcontextprotocol/server / @modelcontextprotocol/node to 2.0.0-beta.4 (roadmap's beta step).
• HTTP: replaced the hand-wired per-request transport + Redis session store with createMcpHandler + toNodeHandler. 2025-era clients are served through the built-in stateless legacy fallback; the 2026-07-28 era is served natively. No more Mcp-Session-Id, no session state anywhere. responseMode: 'sse' preserves the immediate-header-flush behavior long-running tools rely on.
• stdio: server.connect(transport) → serveStdio(factory).
• Tool-arg alias rewriting now happens on the parsed HTTP body / a wrapped stdio onmessage instead of a transport hook.
• Deleted sessionStore.ts, redis.ts, and the @upstash/redis dependency.

Net −133 lines. Verified: typecheck, build, lint, 46/46 tests, plus end-to-end smoke tests of both transports (legacy initialize handshake, sessionless tools/list, tools/call with hallucinated arg aliases, GET → 405).

[fahreddinozcan]

P1 (functional regression): the auth sign-in nudge is dead on the 2026-07-28 era

maybeElicitAuthSignIn uses push-style server.server.elicitInput(...). The 2026-07-28 revision removes the server-to-client request channel, so on a modern-era request the SDK throws MethodNotSupportedByProtocolVersion locally before anything reaches the wire. The .catch(() => {}) swallows it, so there is no crash, but modern stdio clients silently stop getting the nudge.

Note: on the HTTP path this nudge was already inert in both old and new code. getClientCapabilities() is initialize-scoped, and stateless HTTP serves each tools/call on a fresh McpServer that never ran initialize, so the getClientCapabilities()?.elicitation guard never passes there. In practice this feature only ever worked on 2025-era stdio.

• Reference: support-2026-07-28.md > Multi-round-trip requests and the appendix behavior matrix row "Server to client requests".
• Options: rewrite as an in-band return inputRequired({ inputRequests: { id: inputRequired.elicit({...}) } }) (one code path serves both eras via the legacy shim), or accept it as 2025-only and document it. The inputRequired form is blocking rather than fire-and-forget, so a soft nudge does not map cleanly, worth a design decision rather than a mechanical swap.

[fahreddinozcan]

P2 (fragility, not a bug): modern stdio identity relies on an untyped beta surface

The stdio factory sets server.server.oninitialized = () => server.server.getClientVersion(). On 2026-pinned connections oninitialized never fires and getClientVersion() returns undefined (no initialize runs there), so that branch is dead code on the modern era. It is correctly compensated by the new envelopeClientInfo(toolCtx) path (I confirmed the envelope populates clientInfo on modern requests).

The concern: ctx.mcpReq.envelope is typed Partial<RequestMetaEnvelope> where RequestMetaEnvelope is {} in beta, so the as Record<...> cast is load-bearing. A beta bump could change the envelope shape with no compile error and no test catching it.

• Reference: support-2026-07-28.md > Server over stdio / long-lived connections ("On 2026-pinned connections, getClientCapabilities() / getClientVersion() return undefined").
• Suggestion: add a unit test asserting envelopeClientInfo extracts { ide, version } from a CLIENT_INFO_META_KEY envelope, so a shape change fails loudly.

[fahreddinozcan]

P4 (functional gap): SEP-2243 standard headers are not allow-listed for CORS

Enabling modern-era serving means 2026-07-28 Streamable HTTP clients send the SEP-2243 standard headers Mcp-Method and Mcp-Name on every request, and createMcpHandler validates them against the body (I hit exactly this in testing: the request was rejected 400 until both headers were present). The CORS Access-Control-Allow-Headers list allows MCP-Protocol-Version but not Mcp-Method / Mcp-Name, so a browser-based modern client making a credentialed cross-origin call fails the preflight. Non-browser clients (Node, native IDEs) do not preflight and are unaffected. This is new surface: 2025-era clients never sent these headers.

• Reference: support-2026-07-28.md > Mcp-Param-* and standard headers (SEP-2243).
• Fix: add Mcp-Method, Mcp-Name to Access-Control-Allow-Headers. Browser clients skip Mcp-Param-* mirroring, so those dynamically named headers are not required.