MCP TypeScript SDK 从 v1 迁移到 v25 步完成升级的完整实战指南【免费下载链接】typescript-sdkThe official TypeScript SDK for Model Context Protocol servers and clients项目地址: https://gitcode.com/GitHub_Trending/ty/typescript-sdk老版本的 MCP TypeScript SDK v1 代码在新 v2 包上编译不过手动改写又太慢本文用官方 codemod 加少量手动修改5 步完成迁移并用进程内冒烟测试验证整条链路你可以直接照着敲。升级前先确认这 3 件事v2 要求Node.js 20而迁移工具会直接在原文件上改写代码——工作区有未提交内容时你分不清哪些改动是工具做的。先跑一遍检查node -v git status npm ls zod这三条命令分别确认运行时版本、干净的工作区、以及 Zod 版本。v2 不再支持 Zod 3schema 必须来自zod ≥ 4.2.0有缺口先补齐再动手。用官方 codemod 一键改写 v1 代码codemod自动化代码迁移脚本自带v1-to-v2规则能机械完成所有映射固定的改名import 路径、符号名、package.json依赖声明。它的规则源码在 packages/codemod/这里只需要知道能自动的它全做剩下的留给你。在包根目录运行 codemod确保git status干净方便之后审查 diff在项目根目录执行结尾的.很关键——真实项目的test/、scripts/也 import SDK只指向./src会漏掉这些改写它同时会重写package.jsonnpx modelcontextprotocol/codemodlatest v1-to-v2 .这一条命令原地完成所有modelcontextprotocol/sdk/*导入、.tool()、McpError等旧 API 与 v2 依赖的改写。补一次格式化——codemod 只重写语法树不重排格式npx prettier --write .检索遗留标记codemod 对识别到但不敢安全改写的代码会原地留一个mcp-codemod-error注释例如/* mcp-codemod-error WebSocketClientTransport removed in v2. Use StreamableHTTPClientTransport or StdioClientTransport. */用一条命令找出所有要手动处理的点位注释本身就写明了修复方向grep -rn mcp-codemod-error .codemod 不会替你做的 2 处手动修改 以下两项占剩余类型报错的大头改完它们大部分tsc错误就消失了。按运行时选对 transporttransport传输层是客户端与服务器交换消息的通道本地 stdio 子进程或 HTTP 二选一。codemod 只会把StreamableHTTPServerTransport机械改名为 Node 版具体用哪个要看部署环境// Node 运行时handler 收 Node IncomingMessage import { NodeStreamableHTTPServerTransport } from modelcontextprotocol/node; // Workers / Deno / Bunhandler 收发标准 Request / Response import { WebStandardStreamableHTTPServerTransport } from modelcontextprotocol/server;判断规则一句话收 Node 对象用前者收 Web Standard 对象用后者。另外SSEServerTransport已从 v2 移除个别仍必须走旧 HTTPSSE 传输的客户端可临时用 modelcontextprotocol/server-legacy 里的冻结 v1 副本过渡。错误处理改写为新类层次v1 的单一McpError在 v2 拆成三类ProtocolError跨线的协议错误、SdkError本地 SDK 错误、SdkHttpErrorHTTP 传输错误。codemod 会改类名但每个catch该匹配哪个分支需要你判断// v1超时在 McpError 上 if (error instanceof McpError error.code ErrorCode.RequestTimeout) { ... } // v2超时是本地 SdkErrorHTTP 状态码改放 .status if (error instanceof SdkError error.code SdkErrorCode.RequestTimeout) { ... } if (error instanceof SdkHttpError) console.log(error.status);注意一个静默坑v1 里写的e.code 401这种鸭子类型判断会悄悄失效——SdkHttpError上 HTTP 状态码的新家叫.status记得全库 grep 一遍.code 的状态码比较。验证迁移成功类型检查 进程内冒烟测试跑类型检查与残留检索tsc --noEmit或项目构建剩余报错按 官方迁移指南 的手动章节逐条处理grep 确认没有 v1 包名残留包括 lint、CI 里硬编码旧包名的规则grep -rn modelcontextprotocol/sdk --include*.ts .若报TS2589: Type instantiation is excessively deep说明依赖树里存在两份 zod——用npm ls zod确认只剩一个版本必要时用overrides强制去重进程内冒烟测试最后一步别起 HTTP 服务直接用进程内客户端打到你部署的同一个 handler 上const handler createMcpHandler(createServer); const transport new StreamableHTTPClientTransport(new URL(http://test.local/mcp), { fetch: (url, init) handler.fetch(new Request(url, init)) }); const client new Client({ name: smoke, version: 1.0.0 }, { versionNegotiation: { mode: auto } }); await client.connect(transport); const result await client.callTool({ name: apply-discount, arguments: { price: 80, percent: 25 } }); assert.deepStrictEqual(result.structuredContent, { total: 60 });transport 从不真正拨号每个请求都在进程内直达handler.fetch——能断言工具返回值说明连接、协商、调工具、校验结果的整条链路都通了接线细节见 docs/testing.md。若连接远端旧服务时报ERA_NEGOTIATION_FAILED是两侧没找到共同协议版本把versionNegotiation换成mode: auto对照 docs/troubleshooting.md 的逐字报错条目定位。项目太大分阶段迁移v1 与 v2 包名不同两个版本可以在同一个package.json里共存大项目不必一刀切先添加需要的 v2 包连带升到zod ^4.2.0保留modelcontextprotocol/sdk逐目录、逐包改写每改一批先过一遍类型检查全库 grep 确认无人再引用后删除 v1 依赖注意一条边界规则v1 代码构造的对象和 v2 的类互相instanceof不通过两侧只能共享线上格式切分点选在进程或 transport 边界上。逐成员的操作细节见 迁移指南的分阶段章节。收尾按上面的流程走完你的 MCP TypeScript SDK 代码已经跑在 v2 上工具与 schema 校验全部就位。下一步建议看 support-2026-07-28.md 接入多轮往返请求卡住时先用 troubleshooting 的逐字报错条目自查再按 CONTRIBUTING.md 的入口向社区提问。想快速核对效果可以照 examples/ 里的自验证客户端/服务端示例对跑一遍。【免费下载链接】typescript-sdkThe official TypeScript SDK for Model Context Protocol servers and clients项目地址: https://gitcode.com/GitHub_Trending/ty/typescript-sdk创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考