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<T>()

3. Schema 与库解耦：任意 Standard Schema 库皆可使用（不再绑定 Zod）

v2 实现彻底解耦，改变了 v1 强制内置 Zod 的做法：

• 支持 Zod v4、ArkType、Valibot（搭配 @valibot/to-json-schema）
• 第三方库不是必需项，原生 JSON Schema 可以直接传入
• 对外 API 已不依赖 Zod，尽管内部仍在使用 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. MCP 一致性测试套件已完整通过，仅 Task 扩展需要等稳定版补齐

八、其他相关优化

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

九、升级风险归纳

1. 强破坏性：包被完全拆分，所有导入路径均发生变化，依赖与 import 必须修改
2. 行为变更：原有不规范代码会直接报错，因为校验收紧，包括 content 必填与 Schema 2020 强校验
3. 协议收益：部署覆盖多个运行时，HTTP 可缓存，工具能在中途询问用户，并可无状态水平扩容
4. 迁移成本：机械改动中的 70% 可交给 codemod，业务协议、鉴权及自定义 schema 的剩余部分仍需手动适配