企业官网建设流程全解析

MCP TypeScript SDK 从 v1 到 v2 迁移完整指南：codemod 自动化升级

【免费下载链接】typescript-sdkThe official TypeScript SDK for Model Context Protocol servers and clients项目地址: https://gitcode.com/GitHub_Trending/ty/typescript-sdk

MCP（Model Context Protocol）TypeScript SDK 是构建 MCP 服务器与客户端的官方实现，v2 将原先单一的 sdk 包拆成 client、server、core 与框架适配包。本文面向仍在使用 v1 的团队，给出从单包升级到 v2 分包的完整迁移流程与验证方法，全程由 codemod 主导机械改写、人工补齐语义变更。

背景与收益

先说清楚为什么要动、动了能拿到什么。v1 把客户端、服务器、传输、鉴权全部打进同一个@modelcontextprotocol/sdk包，不管你的场景多小都要为整体体积和 API 面积买单。v2 按职责拆分成@modelcontextprotocol/client、@modelcontextprotocol/server、@modelcontextprotocol/core与框架适配包（/node、/express、/hono、/fastify），同时引入了方法字符串注册、结构化的ctx上下文与 Standard Schema 校验。

迁移后你能拿到三样东西：只安装真正用到的包，浏览器 / Workers 与 Node 的运行时差异由分包边界消化；导入路径、错误类、注册 API 全部语义化，读代码不用猜版本；升级某一部分不再牵动全局，测试、脚本、fixtures 都能独立迭代。

迁移路线图

下表给出一眼看懂的全局路径，细节见下文分步说明。

| 阶段 | 关键动作 | 产出/结果 | | 依赖切换 | 运行 codemod 改写导入与 package.json | 源码与依赖切到 v2 分包 | | 人工补齐 | 处理 codemod 标记点与语义改写 | 传输、错误、ctx 适配完成 | | 收尾验证 | 类型检查、格式化、跑完整测试 | 通过 CI，具备发布条件 |

迁移前检查清单

动手前逐项确认，能避开绝大多数返工：

1. Node 版本：确认运行时为 Node 20+；v2 为 ESM 优先但附带 CommonJS 构建，import与require都能原生解析。
2. 引用盘点：全局搜索@modelcontextprotocol/sdk，务必覆盖test/、scripts/、fixtures，别只盯src/。
3. 工作区边界：monorepo 成员需各自声明实际导入的 v2 包，先划清每个成员的依赖边界再开跑。
4. Zod 范围：确认package.json里 zod 声明范围 ≥^4.2.0，v2 不再支持 zod@3，这是最容易静默翻车的点。

核心迁移步骤

以下三步按顺序执行：先让 codemod 跑完机械改写，再人工补齐它判断不了的部分，最后用类型检查收尾。

第一步：运行 codemod 完成机械改写

codemod 会按固定映射自动处理导入路径、符号重命名（如McpError→ProtocolError）、setRequestHandler方法字符串化，并改写最近的package.json。在项目根目录执行，命令如下（把.换成你的项目根路径，通常就是.）：

npx @modelcontextprotocol/codemod@latest v1-to-v2 . grep -rn '@mcp-codemod-error' .

务必在项目根目录（.）而非./src运行，否则test/、scripts/里的引用会被漏改；第二条命令用来定位所有需要你人工处理的标记点。

第二步：补齐 codemod 改不了的语义变更

codemod 只能改「映射固定」的代码，传输选型、错误分支选择、ctx属性这些需要判断的改写会留成标记点。以服务器注册为例，v1 的可变参.tool()在 v2 改为显式配置对象的registerTool，schema 走 Standard Schema：

server.registerTool('greet', { description: 'Greet a user', inputSchema: z.object({ name: z.string() }) }, async ({ name }) => ({ content: [{ type: 'text', text: `Hi ${name}` }] }));

这里的inputSchema必须是实现 Standard Schema 的 schema（如 Zod v4），zod@3 会静默失败——先升级 zod 再注册，细节参考 v1 到 v2 官方迁移指南。

第三步：类型检查与格式化收尾

codemod 只重写 AST 不重排格式，残留的编译错误要靠tsc定位，改完再统一格式化。执行：

tsc --noEmit npx prettier --write 'src/**/*.ts'

类型检查全绿后再跑格式化，最后执行完整测试确认行为无回归，这一步是发布前的最后一道闸。

验证与排错

本节把「怎么确认迁好了」和「踩坑了怎么查」分开处理，前者是清单，后者是速查表。

上线验证清单

1. 功能：跑完整测试套件，确认工具列表、调用结果、未知工具的报错与迁移前一致。
2. 性能：对比新旧构建的初始化耗时与打包体积，确认分包后增长在可接受范围。
3. 兼容性：用 Node 20+ 分别跑 ESM 与 CommonJS 入口，确认import和require均可解析。
4. 协议：确认客户端与服务端协商到同一协议版本，避免跨版本握手失败。

常见问题速查

| 现象 | 可能原因 | 解决方案 | | 安装报 not found | 私有 / 企业 registry 未同步@modelcontextprotocolscope | 指向公共 registry 或让镜像同步该 scope | | 编译报 TS2307 / 导入解析失败 | 依赖仍含 v1 路径，或 monorepo 成员未声明新包 | 按 codemod 输出清单补齐依赖，grep 确认无残留 v1 包 | | 注册成功但tools/list报错 | zod 低于 4.2，缺~standard.jsonSchema| 升级 zod^4.2.0，或用fromJsonSchema传原始 JSON Schema |

总结

把 codemod、类型检查、测试这三道关卡纳入 CI，你的 v2 升级就能长期保持干净。完成基础迁移后，可继续参考 2026-07-28 协议支持指南 采用新版协议特性。迁移顺利，祝升级愉快。

【免费下载链接】typescript-sdkThe official TypeScript SDK for Model Context Protocol servers and clients项目地址: https://gitcode.com/GitHub_Trending/ty/typescript-sdk