企业官网建设流程全解析

MCP TypeScript SDK 从 v1 迁移到 v2：5 步完成升级的完整实战指南

【免费下载链接】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 3，schema 必须来自zod ≥ 4.2.0，有缺口先补齐再动手。

用官方 codemod 一键改写 v1 代码

codemod（自动化代码迁移脚本）自带v1-to-v2规则，能机械完成所有映射固定的改名：import 路径、符号名、package.json依赖声明。它的规则源码在 packages/codemod/，这里只需要知道：能自动的它全做，剩下的留给你。

在包根目录运行 codemod

1. 确保git status干净，方便之后审查 diff
2. 在项目根目录执行（结尾的.很关键——真实项目的test/、scripts/也 import SDK，只指向./src会漏掉这些改写；它同时会重写package.json）：

npx @modelcontextprotocol/codemod@latest v1-to-v2 .

这一条命令原地完成所有@modelcontextprotocol/sdk/*导入、.tool()、McpError等旧 API 与 v2 依赖的改写。

3. 补一次格式化——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错误就消失了。

按运行时选对 transport

transport（传输层）是客户端与服务器交换消息的通道：本地 stdio 子进程或 HTTP 二选一。codemod 只会把StreamableHTTPServerTransport机械改名为 Node 版，具体用哪个要看部署环境：

// Node 运行时：handler 收 Node IncomingMessage import { NodeStreamableHTTPServerTransport } from '@modelcontextprotocol/node'; // Workers / Deno / Bun：handler 收发标准 Request / Response import { WebStandardStreamableHTTPServerTransport } from '@modelcontextprotocol/server';

判断规则一句话：收 Node 对象用前者，收 Web Standard 对象用后者。另外SSEServerTransport已从 v2 移除，个别仍必须走旧 HTTP+SSE 传输的客户端，可临时用 @modelcontextprotocol/server-legacy 里的冻结 v1 副本过渡。

错误处理改写为新类层次

v1 的单一McpError在 v2 拆成三类：ProtocolError（跨线的协议错误）、SdkError（本地 SDK 错误）、SdkHttpError（HTTP 传输错误）。codemod 会改类名，但每个catch该匹配哪个分支需要你判断：

// v1：超时在 McpError 上 if (error instanceof McpError && error.code === ErrorCode.RequestTimeout) { ... } // v2：超时是本地 SdkError，HTTP 状态码改放 .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 ===的状态码比较。

验证迁移成功：类型检查 + 进程内冒烟测试

跑类型检查与残留检索

1. tsc --noEmit（或项目构建），剩余报错按 官方迁移指南 的手动章节逐条处理
2. grep 确认没有 v1 包名残留，包括 lint、CI 里硬编码旧包名的规则：

grep -rn '@modelcontextprotocol/sdk' --include='*.ts' .

3. 若报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里共存，大项目不必一刀切：

1. 先添加需要的 v2 包（连带升到zod ^4.2.0），保留@modelcontextprotocol/sdk
2. 逐目录、逐包改写，每改一批先过一遍类型检查
3. 全库 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