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

MCP v2 是一次架构级大改版，配套全新 2026-07-28 MCP 协议规范，计划 2026-07-28 正式稳定发布，当前处于 2.0.0-beta.2 预发布阶段；整体分为包结构重构、协议能力升级、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 自动化迁移脚本

安装方式变化

# v1npm install @modelcontextprotocol/sdk# v2 服务端npm install @modelcontextprotocol/server @modelcontextprotocol/express# v2 客户端npm install @modelcontextprotocol/client

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

beta.2 新增双构建输出，解决 Node 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()

3. 任意 Standard Schema 库均可使用：Schema 与 Zod 强制依赖解除

从 v1 的 Zod 强制内置，转变为 v2 的完全解耦：

• 支持 Zod v4、ArkType、Valibot（搭配 @valibot/to-json-schema）
• 无须第三方库，可直接传入原生 JSON Schema
• 内部依旧使用 Zod，但外部 API 不再依赖 Zod

4. 服务注册 API 更名

• v1 .tool() → v2 .registerTool()
• 资源、提示词统一 registerXXX 风格 API

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 .

codemod 可自动处理：

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

以下内容需要手动修改：

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

七、运行时及兼容性

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

八、其他配套改进

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

九、升级风险汇总

1. 强破坏性：包被彻底拆分且导入路径全部变化，依赖和 import 均须修改
2. 原有不规范代码将因行为变化直接报错：content 必填，Schema 2020 执行强校验，整体校验更严格
3. 工具执行期间可询问用户，并获得多运行时部署、HTTP 缓存及无状态水平扩容等协议收益
4. 业务协议、鉴权和自定义 schema 的适配仍需手动完成；迁移中的机械改动有 70% 可由 codemod 覆盖