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. 告别强制 Zod：Schema 解耦后可用任意 Standard Schema 库

从 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. MCP 一致性测试套件已完整通过，Task 扩展将在稳定版补齐

八、其他相关优化

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

九、汇总升级风险

1. 强破坏性：依赖与 import 必须调整，因为包被彻底拆开，导入路径也全部改变
2. 行为变更：原有不规范代码会直接报错，原因是校验趋严，包括 content 必填和 Schema 2020 强校验
3. 协议收益：涵盖多运行时部署、HTTP 缓存、工具中途询问用户以及无状态水平扩容
4. 迁移成本：机械改动有 70% 可由 codemod 覆盖；手动适配仍用于自定义 schema、鉴权和剩余业务协议