Skip to content

chore: migrate to MCP TypeScript SDK v2#122

Merged
mattzcarey merged 3 commits into
mainfrom
chore/mcp-sdk-migration
Jul 1, 2026
Merged

chore: migrate to MCP TypeScript SDK v2#122
mattzcarey merged 3 commits into
mainfrom
chore/mcp-sdk-migration

Conversation

@mattzcarey

@mattzcarey mattzcarey commented May 14, 2026

Copy link
Copy Markdown
Contributor

Summary

Migrate from @modelcontextprotocol/sdk v1 to the v2 packages, pinned to the
2.0.0-beta.1 release candidate. Rebuilt on top of current main (which
refactored the tool code into src/tools/*).

  • Drop @modelcontextprotocol/sdk; add @modelcontextprotocol/server@2.0.0-beta.1
    (dep) and @modelcontextprotocol/client@2.0.0-beta.1 (devDep, tests only).
  • Repoint imports to the @modelcontextprotocol/server root export
    (WebStandardStreamableHTTPServerTransport, McpServer, Tool/CallToolResult
    types). The Web Standard transport still exists in v2 with the same options, so
    src/index.ts is a behavior-preserving import change.
  • Low-level non-Code-Mode handlers use method strings
    (setRequestHandler('tools/list' | 'tools/call', …)); the request-schema
    exports were removed in v2.
  • Wrap registerTool inputSchema/outputSchema in z.object(…) for the v2
    Standard Schema API.
  • Mirror v2's wire output in the precomputed non-Code-Mode artifacts: JSON Schema
    dialect 2020-12 (was draft-07) and drop execution.taskSupport (v2 omits it
    for non-task tools). Kept byte-identical to the SDK-generated tools per
    tests/non-codemode.test.ts.
  • No manual @cfworker/json-schema dependency: 2.0.0-beta.1 bundles the Workers
    validator and auto-selects it on the workerd export condition.

See MIGRATION_TRACKER.md for the full decision log.

Validation

  • npm run check — format, lint, typecheck, and 261 tests pass (incl. the e2e
    suite that drives the real worker through the full Streamable HTTP transport,
    tool dispatch, and a real Worker Loader isolate call against 2.0.0-beta.1).
  • npm run deploy — deployed to staging; worker boots in 107 ms with no
    bundle/boot errors.
Worker:     cloudflare-api-mcp-staging
URL:        https://staging.mcp.cloudflare.com
Version ID: a3ff901c-61ca-4e6f-bfc1-008b66b5fef8

Deployed-worker smoke checks: /.well-known/oauth-protected-resource200,
/.well-known/oauth-authorization-server200, unauthenticated POST /mcp
401. (A full authenticated round-trip against the staging endpoint needs a
token valid on the staging Cloudflare API; that path is covered by the e2e suite.)

Notes

  • 2.0.0-beta.1 is <3 days old, so installing it locally requires overriding the
    min-release-age npm setting for the intentional install.
# Conflicts:
#	package-lock.json
#	package.json
#	src/index.ts
#	src/server.ts
Replace @modelcontextprotocol/sdk v1 with the v2 packages
@modelcontextprotocol/server and @modelcontextprotocol/client, pinned to
2.0.0-beta.1, re-applied on top of the refactored main (src/tools/*).

- Repoint imports to @modelcontextprotocol/server root export (WebStandard
  transport, McpServer, Tool/CallToolResult types).
- Low-level non-codemode handlers use method strings
  (setRequestHandler('tools/list'|'tools/call', ...)) since the request
  schema exports were removed.
- Wrap registerTool input/output schemas in z.object(...) for the v2
  Standard Schema API.
- Mirror v2 wire output in the precomputed artifacts: JSON Schema dialect
  2020-12 (was draft-07) and drop execution.taskSupport (v2 omits it).
- Drop the manual @cfworker/json-schema dep (bundled by the beta validator).
- Point the test Client import at @modelcontextprotocol/client.

npm run check passes (261 tests); deployed to staging (boots in 107ms).
@mattzcarey mattzcarey merged commit b782f48 into main Jul 1, 2026
5 checks passed
@mattzcarey mattzcarey deleted the chore/mcp-sdk-migration branch July 1, 2026 11:27
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

1 participant