Track migration to MCP SDK v2 (2026-07-28 protocol revision) / 规划迁移到 MCP SDK v2

[ctrlcakepro]

Context

The MCP ecosystem shipped its largest spec revision since launch on
2026-07-28, together with major (v2) releases of the TypeScript, Python,
Go, and C# SDKs. This repo currently depends on @modelcontextprotocol/sdk ^1.29.0 (v1 line) and speaks only the stdio transport via
server.connect(new StdioServerTransport()) in src/server.mjs.

Current state

• Transport: stdio only, launched as a local child process (.mcp.json).
• API surface: McpServer + registerTool (config-object form) for all
  10 tools; no usage of sampling, elicitation, roots, or tasks.
• SDK: @modelcontextprotocol/sdk v1.30.0 installed.

Two separable work items

1. Mechanical SDK v1 → v2 package migration (low risk, has an official
   codemod: npx @modelcontextprotocol/codemod@latest v1-to-v2 .)

   • Package split: @modelcontextprotocol/sdk → @modelcontextprotocol/server
     (+ /stdio subpath), /core, /node, etc.
   • Wrap raw inputSchema Zod shapes in z.object(...) (codemod handles
     this automatically for registerTool/registerPrompt/registerResource).
   • Update package.json dependencies and re-run tests/node/mcp-stdio.test.mjs
     plus the Python test suite.

2. Opting into the 2026-07-28 wire protocol (serveStdio() instead of
   server.connect(new StdioServerTransport())) — lower priority. The
   headline benefits of this revision (stateless core for load-balanced
   HTTP deployments, header-based routing, cacheable list responses,
   MRTR replacing sampling/elicitation) target remote, multi-instance HTTP
   servers. This project is a single-instance local stdio tool and uses
   none of sampling/elicitation/roots/tasks today, so item 2 buys little
   in its current architecture.

Suggested plan

• Do (1) as routine maintenance, on its own branch, verified against the
  existing test suite.
• Defer (2) unless/until this project grows an HTTP/remote transport, or
  the v1.x SDK line is formally sunset (currently still receiving patches;
  deprecated 2025-era features carry a 12-month minimum deprecation window).

References

• https://blog.modelcontextprotocol.io/posts/2026-07-28/
• https://ts.sdk.modelcontextprotocol.io/v2/migration/upgrade-to-v2.html
• https://ts.sdk.modelcontextprotocol.io/v2/migration/support-2026-07-28.html

---

背景

MCP 生态在 2026-07-28 发布了自协议诞生以来幅度最大的一次规范修订,同时
TypeScript、Python、Go、C# 四个官方 SDK 都发布了各自的 v2 大版本。本仓库
目前依赖的是 @modelcontextprotocol/sdk ^1.29.0(v1 系列),且只使用 stdio
传输(src/server.mjs 中 server.connect(new StdioServerTransport()))。

项目现状

• 传输方式:仅 stdio,以本地子进程方式拉起(见 .mcp.json)。
• API 用法:全部 10 个工具都用 McpServer + registerTool(配置对象写法);
  未使用 sampling、elicitation、roots、tasks 这几个能力。
• SDK 版本:实际安装的是 @modelcontextprotocol/sdk v1.30.0。

两件可以拆开做的事

1. SDK v1 → v2 包迁移(机械性改动,风险低)——官方提供了自动化 codemod:
   npx @modelcontextprotocol/codemod@latest v1-to-v2 .

   • 包拆分:@modelcontextprotocol/sdk → @modelcontextprotocol/server
     (含 /stdio 子路径)、/core、/node 等。
   • 把裸露的 inputSchema Zod shape 包一层 z.object(...)(codemod 会对
     registerTool/registerPrompt/registerResource 自动处理)。
   • 更新 package.json 依赖,并重跑 tests/node/mcp-stdio.test.mjs 和
     Python 测试套件。

2. 正式协商到 2026-07-28 协议版本(把 server.connect(new StdioServerTransport()) 换成 serveStdio())——优先级更低。这次修订
   的核心卖点(无状态内核便于负载均衡的 HTTP 部署、按 header 路由、list
   结果可缓存、MRTR 取代 sampling/elicitation)针对的是远程、多实例 HTTP
   部署场景。本项目是单实例本地 stdio 工具,且目前完全没用到
   sampling/elicitation/roots/tasks,第 2 项在当前架构下收益很有限。

建议的推进方式

• 第 1 项作为常规维护尽早排期,单独开分支,靠现有测试套件验证。
• 第 2 项先搁置,除非项目未来发展出 HTTP/远程传输能力,或者 v1.x SDK 分支
  被正式官宣停止维护(目前仍在持续发补丁;被弃用的 2025 时代特性至少有
  12 个月的过渡期)。

参考资料

• https://blog.modelcontextprotocol.io/posts/2026-07-28/
• https://ts.sdk.modelcontextprotocol.io/v2/migration/upgrade-to-v2.html
• https://ts.sdk.modelcontextprotocol.io/v2/migration/support-2026-07-28.html