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

作者：袖梨 2026-07-29

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 自动化迁移脚本

安装方式变化

# v1npm 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）

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 元数据
为了维持客户端兼容，协议层会对新旧错误码进行自动映射

五、数据校验及类型的不兼容变更

返回内容不再允许缺省CallToolResult.content 不再自动使用空数组，字段缺失会直接抛出 -32602 校验错误；v1 的处理则是静默补上空数组。
放宽结构化内容并自动完成文本序列化structuredContent 根类型可以不是对象；为了让旧客户端继续兼容，服务端会自动补上文本序列化内容。
Task 内置类型被废弃；主协议不再放置任务相关词汇，而由扩展规范承接，相关类型标记 @deprecated。
入参 _meta 自定义处理器现在能够读取请求元数据，不会再被自动删除；过滤范围只包括协议保留字段。