Skip to content

feat!: move to MCP TypeScript SDK v2 - #296

Merged
mattpodwysocki merged 3 commits into
mainfrom
feat/mcp-sdk-v2
Oct 23, 2026
Merged

feat!: move to MCP TypeScript SDK v2#296
mattpodwysocki merged 3 commits into
mainfrom
feat/mcp-sdk-v2

Conversation

@mattpodwysocki

@mattpodwysocki mattpodwysocki commented Oct 21, 2026

Copy link
Copy Markdown
Contributor

Part of #245.

Moves us from @modelcontextprotocol/sdk 1.x to the v2 SDK packages (@modelcontextprotocol/server and /core 2.3.1) and ext-apps 2.0.3. v2 is where new MCP features land, including the SDK's Skills extension support (typescript-sdk#2818), which #295 wants to switch to once it merges.

What changed

Most of this is the official codemod (npx @modelcontextprotocol/codemod v1-to-v2 .): import paths, method-string setRequestHandler, RequestHandlerExtra to ServerContext, extra.authInfo to ctx.http?.authInfo. On top of that:

  • SDK patch replaced. v2 fails a tool call when structuredContent doesn't match the output schema or is missing, which is what we patched v1 to stop. v2 takes any Standard Schema, so lenientOutputSchema wraps each tool's Zod schema: tools/list still publishes the real schema, validation only warns. Text-only results from a tool with an output schema get structuredContent: {}. patches/ is now empty.
  • publishJsonSchema2020 is a deprecated no-op. v2 publishes 2020-12 itself. Kept because hosted's adapter calls it.
  • OptimizationV2Tool removed. Never registered, and built on the experimental tasks API that v2 drops.
  • Test auth contexts fixed. About 20 tests built the request context in the v1 { authInfo } shape, so the token never reached the code under test. That includes the checks that a secret sk. token never gets embedded in the map page. They now use { http: { authInfo } }, so those checks actually run.
  • Patch tests replaced. The old ones called tool.run() directly and never touched the SDK. The new ones make a real tools/call through McpServer and fail without the wrapper.
  • @modelcontextprotocol/client and /node are dev deps only (tests, evals harness, dev HTTP server).

Clients

Nothing changes for clients. It still negotiates 2025-11-25, and the MCP Apps wire protocol is the same in ext-apps 2.x, so render_map_tool renders as before. Adopting the 2026-07-28 protocol revision is separate work under #245.

Heads up

  • Hosted has to move in the same release. installTo(server) needs a v2 McpServer, so hosted-mcp-server needs its own v2 PR (adapter plus the auth context shape) before it picks up this version.
  • Test-only type errors. Test files aren't typechecked in CI, and main already has 207 errors there. This adds about 367, nearly all from v2 typing structuredContent loosely. Nothing fails because of them; happy to clean up in a follow-up.

Testing

  • npm test: 96 files, 1080 tests passing
  • npm run lint: 0 errors
  • npm run build: ESM and CJS both build; the CJS dist installs all 32 tools on a v2 McpServer
  • stdio smoke test against the built server: handshake (2025-11-25), all 30 default tools with 2020-12 schemas, prompts, completions, resources, the MCP Apps UI resource (text/html;profile=mcp-app), logging and a bbox_tool call

🤖 Generated with Claude Code

@mattpodwysocki @claude
feat!: move to MCP TypeScript SDK v2 (#245)
2838aef 
Swaps @modelcontextprotocol/sdk 1.x for the v2 packages
(@modelcontextprotocol/server and /core, plus /client and /node for tests
and scripts). Ran the official v1-to-v2 codemod, then:

- Replace the SDK output-validation patch with lenientOutputSchema, a
  Standard Schema wrapper that keeps the real schema in tools/list but only
  warns on a mismatch. Tools that return text only get structuredContent {}.
- Make publishJsonSchema2020 a deprecated no-op, since v2 publishes JSON
  Schema 2020-12 natively. Kept for hosted's adapter.
- Remove OptimizationV2Tool, which was never registered and used the
  experimental tasks API that v2 drops.
- Move test request contexts to the v2 shape (http.authInfo) so the token
  checks actually run.
- Replace the patch tests, which never went through the SDK, with tests
  that make a real tools/call.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@mattpodwysocki mattpodwysocki added the enhancement New feature or request label Oct 21, 2026
@mattpodwysocki
mattpodwysocki requested a review from a team as a code owner October 21, 2026 19:19
@mattpodwysocki @claude
docs: add PR number to CHANGELOG
7212f80 
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This was referenced Oct 21, 2026
Merged
Merged
Open
Merged
ctufts
ctufts previously approved these changes Oct 23, 2026
View reviewed changes
@mattpodwysocki
Merge remote-tracking branch 'origin/main' into feat/mcp-sdk-v2
3481d8b 
# Conflicts:
#	src/utils/versionUtils-cjs.cjs
#	src/utils/versionUtils-cjs.d.cts
@mattpodwysocki
mattpodwysocki merged commit 7b39175 into main Oct 23, 2026
5 checks passed
@mattpodwysocki mattpodwysocki mentioned this pull request Oct 26, 2026
Merged
mattpodwysocki added a commit to mapbox/mcp-devkit-server that referenced this pull request Oct 26, 2026
@mattpodwysocki @claude
feat!: move to MCP TypeScript SDK v2 (#142)
bf1752d 
* feat!: move to MCP TypeScript SDK v2

Swaps @modelcontextprotocol/sdk 1.x for the v2 packages
(@modelcontextprotocol/server and /core, plus /client for tests) and
ext-apps 2.0.3, same as mapbox/mcp-server#296. Ran the official
v1-to-v2 codemod, then:

- Replace the SDK output-validation patch with lenientOutputSchema, a
  Standard Schema wrapper that keeps the real schema in tools/list but only
  warns on a mismatch. Tools that return text only get structuredContent {}.
- Register prompt argument schemas as z.object(), since v2 deprecates raw
  shapes.
- Move test request contexts to the v2 shape (http.authInfo) so the token
  checks actually run.
- Add tests that make a real tools/call through McpServer.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* docs: add PR number to CHANGELOG

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
mattpodwysocki added a commit to mapbox/mcp-docs-server that referenced this pull request Oct 26, 2026
@mattpodwysocki @claude
feat!: move to MCP TypeScript SDK v2 (#46)
27fb899 
* feat!: move to MCP TypeScript SDK v2

Swaps @modelcontextprotocol/sdk 1.x for @modelcontextprotocol/server 2.3.1
(and @modelcontextprotocol/client as a dev dependency for the scripts and
tests), same as mapbox/mcp-server#296. The v1-to-v2 codemod did the
imports and context types. No tool has an output schema, so v2's strict
output validation doesn't apply.

Adds a test that installs every tool and resource on a real v2 McpServer,
since the tool tests call run() directly and never touch the SDK.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* docs: add PR number to CHANGELOG

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* test: typecheck tests in CI

Adds npm run typecheck (tsc over src and test) as a CI step, fixes the
one error it found, and sets noEmit in tsconfig.test.json so tsc can't
write .js files next to the sources.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* chore: bump MCP TypeScript SDK to 2.4.0

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
mattpodwysocki added a commit that referenced this pull request Oct 26, 2026
@mattpodwysocki @claude
test: fix all test type errors and typecheck tests in CI (#298)
e8c0c99 
* feat!: move to MCP TypeScript SDK v2 (#245)

Swaps @modelcontextprotocol/sdk 1.x for the v2 packages
(@modelcontextprotocol/server and /core, plus /client and /node for tests
and scripts). Ran the official v1-to-v2 codemod, then:

- Replace the SDK output-validation patch with lenientOutputSchema, a
  Standard Schema wrapper that keeps the real schema in tools/list but only
  warns on a mismatch. Tools that return text only get structuredContent {}.
- Make publishJsonSchema2020 a deprecated no-op, since v2 publishes JSON
  Schema 2020-12 natively. Kept for hosted's adapter.
- Remove OptimizationV2Tool, which was never registered and used the
  experimental tasks API that v2 drops.
- Move test request contexts to the v2 shape (http.authInfo) so the token
  checks actually run.
- Replace the patch tests, which never went through the SDK, with tests
  that make a real tools/call.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* docs: add PR number to CHANGELOG

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* test: fix all test type errors and typecheck tests in CI

Follow-up to #296. Adds structuredOf/textOf/resourceTextOf test helpers,
fixes the ~450 errors tsconfig.test.json reported (about 200 already on
main, the rest from SDK v2's open structuredContent type), adds noEmit to
tsconfig.test.json and runs `npm run typecheck` in CI.

Fixes tests the errors exposed: the zod 4 tuple traversal that never looked
inside arrays, a structured-content test importing a nonexistent file, a
stale directions input shape, and a SimplifyTool comparison that couldn't
fail.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* docs: add PR number to CHANGELOG

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
This was referenced Oct 26, 2026
Open
Open
mattpodwysocki added a commit to mapbox/mcp-devkit-server that referenced this pull request Oct 26, 2026
@mattpodwysocki @claude
test: fix all test type errors and typecheck tests in CI (#143)
2ac064f 
* feat!: move to MCP TypeScript SDK v2

Swaps @modelcontextprotocol/sdk 1.x for the v2 packages
(@modelcontextprotocol/server and /core, plus /client for tests) and
ext-apps 2.0.3, same as mapbox/mcp-server#296. Ran the official
v1-to-v2 codemod, then:

- Replace the SDK output-validation patch with lenientOutputSchema, a
  Standard Schema wrapper that keeps the real schema in tools/list but only
  warns on a mismatch. Tools that return text only get structuredContent {}.
- Register prompt argument schemas as z.object(), since v2 deprecates raw
  shapes.
- Move test request contexts to the v2 shape (http.authInfo) so the token
  checks actually run.
- Add tests that make a real tools/call through McpServer.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* docs: add PR number to CHANGELOG

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* test: fix all test type errors and typecheck tests in CI

Adds npm run typecheck (tsc over src and test) as a CI step. Fixes the
247 errors it found: content/resource/prompt text reads go through
helpers that narrow the block type, StyleBuilderTool tests use the
schema's input type, and a bare src/ import is made relative. Sets
noEmit in tsconfig.test.json.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* docs: add PR number to CHANGELOG

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
This was referenced Oct 26, 2026
Merged
Merged
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@ctufts ctufts ctufts approved these changes

Assignees

No one assigned

Labels

enhancement New feature or request

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

2 participants

@mattpodwysocki @ctufts