MCP TypeScript SDK v2 完整升级变化说明

MCP v2 的发布，可以说是这套协议生态里一次真正意义上的架构级大改。不光是版本号从 1 跳到 2，连底层的包结构、协议层能力、API 设计都做了大幅调整。当前处于 2.0.0-beta.2 预发布阶段，配合的是全新 2026-07-28 协议规范，计划在 2026-07-28 正式稳定发布。整体来看，这次升级覆盖了包结构重构、协议能力升级、API 重构、构建/运行时、破坏性变更、迁移工具六大模块，同时还能兼容旧版 2025 协议客户端——这算是个比较友好的过渡方案。

一、包架构彻底拆分（最大破坏性变更）

v1 时代那个单一的 @modelcontextprotocol/sdk 包，这次彻底废弃了。取而代之的是一套模块化、按需安装的独立包体系。这么做的好处很直接：每个项目只用装自己真正需要的部分，整体体积也能降下来。

具体拆分成了三大类：

1. 核心基础包
   • @modelcontextprotocol/client：仅客户端实现
   • @modelcontextprotocol/server：仅服务端实现
   • @modelcontextprotocol/core：协议类型、通用 Schema、底层编解码

2. 框架适配适配器
   • @modelcontextprotocol/express / @modelcontextprotocol/fastify：Web 框架适配器
   • @modelcontextprotocol/node：原生 Node http 兼容层
   • @modelcontextprotocol/server-legacy：旧版 OAuth 兼容服务

3. 工具包
   • @modelcontextprotocol/codemod：v1→v2 自动化迁移脚本

安装变更

如果你之前是这么装的：

# v1
npm install @modelcontextprotocol/sdk

现在得改成按角色来装：

# v2 服务端
npm install @modelcontextprotocol/server @modelcontextprotocol/express

# v2 客户端
npm install @modelcontextprotocol/client

二、构建产物：同时支持 ESM + CommonJS

beta.2 版本新增了双构建输出，这个改动主要解决了 Node.js 项目中 CJS 导入报错的老问题。具体来说：

1. 每个包同时输出 ESM（.mjs + .d.mts）和 CJS（.cjs + .d.cts）两种格式。
2. package.json 的 exports 字段配置了 require 条件，这样用 require() 加载也能正常工作。
3. 统一了文件后缀规范，比如 core 从 .js 改为 .mjs，但对外导入路径不变，所以对开发者来说感知不大。

三、协议层：适配全新 2026-07-28 MCP 规范（核心新能力）

v2 的协议层升级是这次改版的核心亮点。它原生支持新版协议，同时还能兼容 2025 旧协议客户端——这意味着一个服务可以同时处理两代协议的请求，迁移过程可以逐步进行。

1. 无状态 HTTP 架构（核心升级）

服务端不再依赖会话亲和性，水平扩展时不需要共享任何会话存储。会话本身变成了可选特性，只有在业务真正需要时才启用。另外新增了 Mcp-Method 和 Mcp-Name 请求头，路由时不需要解析 body 就能知道该往哪走，性能上是个不错的优化。

2. 多轮交互请求 MRTR（Multi Round-Trip Requests）

这个特性很有意思：工具执行中途可以主动向用户索要输入，而不用像之前那样一直靠长连接阻塞等待。具体实现是工具返回 InputRequiredResult 来中断执行，等待用户输入。配套的 requestState 密封存储机制内置了 HMAC-SHA256 签名工具 createRequestStateCodec，带 TTL 防篡改，安全性上考虑得比较周全。

3. 缓存标准化

tools/list、resources/read 这类接口现在会自动携带 ttlMs、cacheScope 缓存字段，默认值是 ttlMs:0, private。服务端可以全局配置，也可以针对单个资源设置缓存策略，灵活性不错。

4. 协议编解码分层

按协议版本分离了 WireCodec，新旧协议的字段可以隔离处理。比如 resultType 这个字段只存在于 2026 协议的 wire 层，上层业务类型里完全看不到它。对于不兼容的协议方法，直接返回 -32601 方法不存在错误，处理逻辑很清晰。

5. JSON Schema 升级至 Draft 2020-12

默认使用 Ajv2020 进行校验，严格支持 $defs、prefixItems、unevaluatedProperties 这些新特性。如果还在用旧 Draft-07，可以手动降级配置，给了开发者一定的选择空间。

四、SDK API 全面重构

1. 统一跨运行时 Web 标准接口

createMcpHandler() 现在返回的是 Web 标准接口 { fetch, close, notify, bus }，原生支持 Node、Bun、Deno、Workers 等运行时。旧版 .node(req, res) 接口被废弃，Node 环境需要通过 toNodeHandler 做适配转换。另外本地服务启动变得极简，一行 serveStdio() 就能拉起 stdio 服务。

2. 标准化上下文 ctx（替代 v1 模糊 extra 参数）

所有工具/资源处理器现在都接收强类型 ctx，内置了日志、进度上报、请求取消、用户输入询问（elicitation）等能力。还可以通过 ctx.mcpReq.requestState() 读取原始协议信封和多轮交互状态，比 v1 那个模糊的 extra 参数清晰太多了。

3. Schema 解耦：支持任意 Standard Schema 库（告别强制 Zod）

v1 强制内置 Zod，v2 完全解耦了。现在支持 Zod v4、ArkType、Valibot（搭配 @valibot/to-json-schema），甚至可以直接传入原生 JSON Schema，完全不需要第三方库。内部虽然仍使用 Zod，但对外 API 不再有 Zod 依赖。

4. 服务注册 API 更名

v1 的 .tool() 改成了 .registerTool()，资源、提示词也统一成了 registerXXX 风格，命名更规范了。

5. 错误码标准化

资源不存在统一返回 -32602 Invalid Params，兼容新旧协议。新增强类型错误类 ResourceNotFoundError，携带 uri 元数据，方便上层捕获和处理。协议层会自动映射新旧错误码，保证客户端兼容性。

五、类型与数据校验破坏性变更

1. 返回内容强制必填
   ：CallToolResult.content 不再默认空数组，缺失直接抛出 -32602 校验错误。v1 会静默填充空数组，这个行为差异需要特别注意。

2. 结构化内容放宽+自动文本序列化
   ：structuredContent 支持非对象根类型；服务端会自动补充文本序列化内容，向下兼容旧客户端。

3. 废弃 Task 内置类型
   ：任务相关词汇移出主协议，改为扩展规范，相关类型标记为 @deprecated。

4. 入参 _meta 不再自动删除
   ：自定义处理器现在可以读取请求元数据，但会过滤协议保留字段。

六、迁移配套工具：codemod 自动转换

官方提供了一键迁移脚本，可以处理绝大多数机械修改：

npx @modelcontextprotocol/codemod@beta v1-to-v2 .

• 包导入路径替换（@modelcontextprotocol/sdk → server/client/core）
• API 改名 .tool() → registerTool()
• 基础类型导入路径迁移

• 自定义 Zod Schema 逻辑、HTTP 服务适配代码
• 旧版 Task 业务逻辑、OAuth 鉴权代码
• 项目构建配置（ESM/CJS 双模式适配）

七、运行时与兼容性

1. 最低 Node 版本提升至 Node 20+。
2. 同时支持 ESM / CommonJS 双模式，兼顾新旧项目。
3. 向后兼容承诺：v1.x 至少维护 6 个月安全补丁。
4. 完整通过 MCP 一致性测试套件（除 Task 扩展待稳定版补齐）。

八、其他配套优化

1. 全新官方文档与可 CI 验证示例，10 分钟快速上手教程。
2. 新增独立 server-legacy 包处理 OAuth 旧兼容逻辑，支持 RFC9207 iss 颁发者校验。
3. stdio 传输增加进程探测能力，兼容 Rust MCP 等第三方服务端。
4. 完善可观测性：适配器层统一错误捕获钩子 onerror，便于日志监控。

九、升级风险总结

1. 强破坏性
   ：包完全拆分，导入路径全变，必须修改依赖与 import。

2. 行为变更
   ：校验更严格（content 必填、Schema 2020 强校验），原有不规范代码会直接报错。

3. 协议收益
   ：无状态水平扩容、工具中途询问用户、HTTP 缓存、多运行时部署。

4. 迁移成本
   ：codemod 覆盖 70% 机械改动，剩余业务协议、鉴权、自定义 schema 需要手动适配。