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

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

安装变更

bash 复制代码

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

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

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

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() → v2 .registerTool()
资源、提示词统一 registerXXX 风格 API

5. 错误码标准化

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

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

返回内容强制必填 CallToolResult.content 不再默认空数组，缺失直接抛出 -32602 校验错误，v1 会静默填充空数组。
结构化内容放宽+自动文本序列化 structuredContent 支持非对象根类型；服务端自动补充文本序列化内容向下兼容旧客户端。
废弃 Task 内置类型任务相关词汇移出主协议，改为扩展规范，相关类型标记 @deprecated。
入参 _meta 不再自动删除自定义处理器可读取请求元数据，仅过滤协议保留字段。

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

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