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

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-sdkMCPModel Context ProtocolTypeScript 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具备发布条件 |迁移前检查清单动手前逐项确认能避开绝大多数返工Node 版本确认运行时为 Node 20v2 为 ESM 优先但附带 CommonJS 构建import与require都能原生解析。引用盘点全局搜索modelcontextprotocol/sdk务必覆盖test/、scripts/、fixtures别只盯src/。工作区边界monorepo 成员需各自声明实际导入的 v2 包先划清每个成员的依赖边界再开跑。Zod 范围确认package.json里 zod 声明范围 ≥^4.2.0v2 不再支持 zod3这是最容易静默翻车的点。核心迁移步骤以下三步按顺序执行先让 codemod 跑完机械改写再人工补齐它判断不了的部分最后用类型检查收尾。第一步运行 codemod 完成机械改写codemod 会按固定映射自动处理导入路径、符号重命名如McpError→ProtocolError、setRequestHandler方法字符串化并改写最近的package.json。在项目根目录执行命令如下把.换成你的项目根路径通常就是.npx modelcontextprotocol/codemodlatest v1-to-v2 . grep -rn mcp-codemod-error .务必在项目根目录.而非./src运行否则test/、scripts/里的引用会被漏改第二条命令用来定位所有需要你人工处理的标记点。第二步补齐 codemod 改不了的语义变更codemod 只能改「映射固定」的代码传输选型、错误分支选择、ctx属性这些需要判断的改写会留成标记点。以服务器注册为例v1 的可变参.tool()在 v2 改为显式配置对象的registerToolschema 走 Standard Schemaserver.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 v4zod3 会静默失败——先升级 zod 再注册细节参考 v1 到 v2 官方迁移指南。第三步类型检查与格式化收尾codemod 只重写 AST 不重排格式残留的编译错误要靠tsc定位改完再统一格式化。执行tsc --noEmit npx prettier --write src/**/*.ts类型检查全绿后再跑格式化最后执行完整测试确认行为无回归这一步是发布前的最后一道闸。验证与排错本节把「怎么确认迁好了」和「踩坑了怎么查」分开处理前者是清单后者是速查表。上线验证清单功能跑完整测试套件确认工具列表、调用结果、未知工具的报错与迁移前一致。性能对比新旧构建的初始化耗时与打包体积确认分包后增长在可接受范围。兼容性用 Node 20 分别跑 ESM 与 CommonJS 入口确认import和require均可解析。协议确认客户端与服务端协商到同一协议版本避免跨版本握手失败。常见问题速查| 现象 | 可能原因 | 解决方案 | | 安装报 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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考