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 包，这次彻底废弃了。取而代之的是一套模块化、按需安装的独立包体系。这么做的好处很直接：每个项目只用装自己真正需要的部分，整体体积也能降下来。
具体拆分成了三大类：
核心基础包
@modelcontextprotocol/client：仅客户端实现@modelcontextprotocol/server：仅服务端实现@modelcontextprotocol/core：协议类型、通用 Schema、底层编解码
框架适配适配器
@modelcontextprotocol/express/@modelcontextprotocol/fastify：Web 框架适配器@modelcontextprotocol/node：原生 Node http 兼容层@modelcontextprotocol/server-legacy：旧版 OAuth 兼容服务
工具包
@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 导入报错的老问题。具体来说：
- 每个包同时输出 ESM（
.mjs+.d.mts）和 CJS（.cjs+.d.cts）两种格式。 package.json的exports字段配置了require条件，这样用require()加载也能正常工作。- 统一了文件后缀规范，比如
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 元数据，方便上层捕获和处理。协议层会自动映射新旧错误码，保证客户端兼容性。
五、类型与数据校验破坏性变更
- ：
返回内容强制必填
CallToolResult.content不再默认空数组，缺失直接抛出-32602校验错误。v1 会静默填充空数组，这个行为差异需要特别注意。 - ：
结构化内容放宽+自动文本序列化
structuredContent支持非对象根类型；服务端会自动补充文本序列化内容，向下兼容旧客户端。 - ：任务相关词汇移出主协议，改为扩展规范，相关类型标记为
废弃 Task 内置类型
@deprecated。 - ：自定义处理器现在可以读取请求元数据，但会过滤协议保留字段。
入参
_meta不再自动删除
六、迁移配套工具：codemod 自动转换
官方提供了一键迁移脚本，可以处理绝大多数机械修改：
npx @modelcontextprotocol/codemod@beta v1-to-v2 .
codemod 自动处理的内容包括：
- 包导入路径替换（
@modelcontextprotocol/sdk→server/client/core） - API 改名
.tool()→registerTool() - 基础类型导入路径迁移
需要手动修改的部分：
- 自定义 Zod Schema 逻辑、HTTP 服务适配代码
- 旧版 Task 业务逻辑、OAuth 鉴权代码
- 项目构建配置（ESM/CJS 双模式适配）
七、运行时与兼容性
- 最低 Node 版本提升至 Node 20+。
- 同时支持 ESM / CommonJS 双模式，兼顾新旧项目。
- 向后兼容承诺：v1.x 至少维护 6 个月安全补丁。
- 完整通过 MCP 一致性测试套件（除 Task 扩展待稳定版补齐）。
八、其他配套优化
- 全新官方文档与可 CI 验证示例，10 分钟快速上手教程。
- 新增独立
server-legacy包处理 OAuth 旧兼容逻辑，支持 RFC9207iss颁发者校验。 - stdio 传输增加进程探测能力，兼容 Rust MCP 等第三方服务端。
- 完善可观测性：适配器层统一错误捕获钩子
onerror，便于日志监控。
九、升级风险总结
- ：包完全拆分，导入路径全变，必须修改依赖与 import。
强破坏性
- ：校验更严格（content 必填、Schema 2020 强校验），原有不规范代码会直接报错。
行为变更
- ：无状态水平扩容、工具中途询问用户、HTTP 缓存、多运行时部署。
协议收益
- ：codemod 覆盖 70% 机械改动，剩余业务协议、鉴权、自定义 schema 需要手动适配。
迁移成本
