feat!: migrate to MCP SDK v2

[gnapse]

Warning

This is a breaking change.

Summary

• migrate the MCP server and transports to the split MCP TypeScript SDK v2 packages
• register tools and prompts with Standard Schema objects
• preserve MCP Apps metadata using native v2 registration while ext-apps remains typed against SDK v1
• update token-footprint measurement and public setup documentation
• add a regression test that requires JSON Schema 2020-12 on every advertised tool schema

Why

SDK v1 emits explicit draft-07 tool schemas. Some MCP clients reject those schemas because they validate tools as JSON Schema 2020-12. SDK v2 emits 2020-12 schemas natively, so this fixes the compatibility issue without a schema-rewriting workaround.

This is a breaking library change because getMcpServer now returns the v2 McpServer type and the peer dependencies move from @modelcontextprotocol/sdk to @modelcontextprotocol/server and @modelcontextprotocol/node.

Verification

• 47 input schemas and 46 output schemas advertise JSON Schema 2020-12
• all 93 schemas compile with an Ajv 2020-12 validator
• npm test: 74 files, 1180 tests passed
• npm run check
• npm run type-check
• npm run test:executable

[doistbot]

This PR migrates the MCP server and transports to the split MCP TypeScript SDK v2 packages, registering tools and prompts with Standard Schema objects, preserving MCP Apps metadata, and adding a regression test requiring JSON Schema 2020-12 on every advertised tool schema.

Few things worth tightening:

• The new normalizeAppToolMeta in mcp-helpers.ts duplicates the _meta resource-URI normalization already present in token-footprint.test.ts; exporting the production function and reusing it in the test would prevent the two copies from drifting apart.

I also left one optional follow-up note in the details below.

Optional follow-up note (1)

• src/mcp-helpers.ts:185: normalizeAppToolMeta re-implements the same ui.resourceUri/ui/resourceUri fill-in logic that normalizeAppUiMeta in src/token-footprint.test.ts already hand-rolls (that test's comment now points at registerTool). Two copies of one normalization can drift, which would make the token-footprint measurement over- or under-count. Export normalizeAppToolMeta (or move it to a shared util) and have the test reuse it instead of mirroring it.

_{Share Feedback • Review Logs}

[henningmu]

Nice 👏

[scottlovegrove]

Just so we're aware, switching to the v2 SDK means we are now using the new MCP specification https://blog.modelcontextprotocol.io/posts/2026-07-28/. This is probably fine, but could be worth double checking.

It was on my list of things to do to look at the new spec and see what changes (if any) there could be for us with this.

[gnapse]

Just so we're aware, switching to the v2 SDK means we are now using the new MCP specification https://blog.modelcontextprotocol.io/posts/2026-07-28/. This is probably fine, but could be worth double checking.

It was on my list of things to do to look at the new spec and see what changes (if any) there could be for us with this.

I checked this more closely. SDK v2 supports the 2026 spec, but this PR does not enable it: we still use server.connect(...) with the existing HTTP and stdio transports, and I verified locally that it negotiates the 2025 protocol, including all older supported revisions. Moving to the 2026 protocol would require a separate change to createMcpHandler or serveStdio.

I'm now running a few more checks, including a locally-built version of ai.todoist.net/mcp that is wired to this new package, so I can run the full stack of the web-based MCP server, to make sure it works well with clients such as Claude Cowork or Codex. If all that goes well, I'll merge and update the web-based MCP server running in production.

[doist-release-bot]

🎉 This PR is included in version 13.0.0 🎉

The release is available on:

• npm package (@latest dist-tag)
• GitHub release

Your semantic-release bot 📦🚀