1. 项目概述：一次面向未来的协议层重构
如果你最近在捣鼓AI Agent或者想让你的大模型应用能“看见”和“操作”更多外部工具，那你大概率已经接触过MCP（Model Context Protocol）了。简单来说，MCP就是一个让AI模型（比如Claude、GPTs）安全、标准化地调用外部数据和工具的协议。而TypeScript SDK，就是我们这些开发者用来快速构建MCP服务器（Server）或客户端（Client）的脚手架和工具箱。
这次v2版本的升级，远不止是修几个Bug或者加几个API那么简单。从我拿到早期预览版开始折腾，到最终正式版发布后在实际项目中迁移，整个过程感觉更像是一次协议层的“地基重打”。官方把这次升级称为“MCP 2.0”，SDK的版本号直接从v1跳到了v2，这本身就说明了变化的剧烈程度。核心目标非常明确：让协议更健壮、类型更安全、开发体验更接近现代TypeScript工程的最佳实践。对于已经用v1构建了生产级MCP服务器的团队，升级是必然选择，因为这是协议演进的方向；对于新入局的开发者，直接从v2开始则是幸运的，可以避开不少早期设计上的“坑”。
2. 核心变化总览：从“能用”到“好用且可靠”
在深入细节之前，我们先从高处俯瞰一下v2带来的主要变化。这些变化可以归结为三个核心方向：协议规范化、类型系统强化和开发者体验提升。
2.1 协议与传输层的标准化加固
MCP v1协议在设计上相对宽松，这给了早期探索者灵活性，但也带来了互操作性的隐患。v2协议在传输层和消息格式上做了大量加固工作。
首先，SSE（Server-Sent Events）传输方式成为了标准且强制的选择。在v1中，虽然SSE是主流，但协议层没有严格限定。v2明确规定了通信必须基于SSE，这消除了传输层的不确定性，使得客户端和服务器的实现可以更专注在业务逻辑上。SSE作为一种基于HTTP长连接的轻量级推送技术，非常适合MCP这种由服务器主动向客户端推送工具列表、资源内容变更的场景。相比于WebSocket，SSE更简单，天然支持HTTP/2，并且在连接中断后具备自动重连机制，提升了连接的鲁棒性。
其次，消息格式和错误处理被极大规范化。v1中的一些模糊地带，比如未定义行为的处理、错误响应的格式，在v2中都有了明确的规范。例如，所有服务器响应的JSON结构现在都必须包含严格的jsonrpc: “2.0”字段，这向JSON-RPC 2.0规范靠拢，使得协议本身更易于被其他标准的JSON-RPC工具理解和调试。错误对象现在有了更详细的分类和错误码，比如INVALID_PARAMS、METHOD_NOT_FOUND、INTERNAL_ERROR等，这让客户端能更精准地识别问题所在，而不是面对一个笼统的“出错了”。
2.2 类型系统的革命：从“松散”到“精确”
对于TypeScript开发者而言，v2 SDK在类型安全上的提升是最令人兴奋的部分。v1的类型定义虽然存在，但很多时候是“any”或者宽泛的联合类型，类型体操玩得不够彻底。v2彻底重构了类型系统，其核心是引入了泛型（Generics）的深度应用，以实现端到端的类型安全。
现在，当你定义一个工具（Tool）时，你可以为其输入参数（inputSchema）定义一个精确的Zod模式（Schema）。SDK会利用TypeScript的泛型，将这个模式推断出的类型，一路传递到工具处理函数（handler）的参数中。这意味着，在你的handler函数里，parameters的类型不再是any或Record<string, unknown>，而是与你定义的JSON Schema完全匹配的强类型对象。编辑器可以提供完美的自动补全和类型检查，将许多运行时错误提前到了编译时。
// v2 示例：强类型的工具定义 import { z } from “zod”; import { Server } from “@modelcontextprotocol/sdk/server/index.js”; import { Tool } from “@modelcontextprotocol/sdk/types.js”; const server = new Server( { name: “my-server”, version: “1.0.0” }, { capabilities: { tools: {} } } ); const getWeatherSchema = z.object({ city: z.string().describe(“The name of the city”), unit: z.enum([“celsius”, “fahrenheit”]).optional().default(“celsius”), }); // `Tool` 类型现在能正确推断出基于 schema 的参数类型 const getWeatherTool: Tool<typeof getWeatherSchema> = { name: “get_weather”, description: “Get current weather for a city”, inputSchema: getWeatherSchema, }; server.setRequestHandler( { method: “tools/call” }, async (request) => { // 这里，`request.params.arguments` 的类型被推断为 `{ city: string; unit?: “celsius” | “fahrenheit” }` const { city, unit } = request.params.arguments; console.log(`Fetching weather for ${city} in ${unit}`); // ... 实际业务逻辑 return { content: [{ type: “text”, text: `It’s 22 degrees ${unit} in ${city}.` }], }; } );这种变化极大地提升了开发效率和代码可靠性。你不再需要写大量的类型断言（as）或防御性检查，TypeScript成了你构建MCP服务器时最得力的助手。
2.3 包结构与API的现代化重构
v2 SDK的包结构进行了重新组织，更清晰，也支持了更好的Tree-shaking。
- 包名与入口点：核心包仍然是
@modelcontextprotocol/sdk。但内部模块的导入路径发生了变化，更加符合ES模块标准。例如，现在通常从@modelcontextprotocol/sdk/server/index.js导入Server类。这种显式的子路径导入，配合现代打包工具，能更有效地移除未使用的代码。 - 初始化与配置：创建
Server和Client的构造函数参数变得更加结构化。以前一些零散的配置项现在被整合到清晰的对象中，比如服务器的能力声明（capabilities）现在是一个独立且必需的结构体，你必须明确声明你的服务器支持tools、resources、prompts中的哪些功能。 - 废弃与新增API：一些v1中不推荐使用的或设计不佳的API被移除或替换。同时，引入了一些新的辅助函数和类，用于处理更复杂的场景，比如资源订阅的通知、提示模板的渲染等。整个API的设计思路是让常见任务更简单，同时为高级用例提供明确的扩展点。
3. 迁移指南与实操详解
将现有的v1项目升级到v2，需要系统性地修改代码。以下是一个循序渐进的迁移实操流程。
3.1 依赖更新与安装
首先，更新你的package.json中的依赖项。
{ “dependencies”: { “@modelcontextprotocol/sdk”: “^2.0.0” // 确保是 2.x 版本 // Zod 现在几乎是强依赖，用于定义 schema “zod”: “^3.22.0” } }运行npm install或yarn install进行安装。请注意，由于v2是重大升级，可能会存在不兼容的变更，建议先在项目的独立分支上进行操作。
3.2 服务器（Server）代码重构
这是迁移工作的核心部分。我们假设你有一个v1的服务器，它提供了几个工具和资源。
步骤一：导入路径更新将你文件中所有来自@modelcontextprotocol/sdk的导入语句更新为新的路径。常见的变更包括：
import { Server } from “@modelcontextprotocol/sdk/server/index.js”;import { Tool } from “@modelcontextprotocol/sdk/types.js”;- 工具、资源、提示等相关类型都从
types.js导出。
步骤二：重构服务器实例化v1中可能相对简单的初始化过程，在v2中需要更明确的配置。
// v1 风格 (示例) // const server = new Server(‘my-server’, ‘1.0.0’); // v2 风格 import { Server } from “@modelcontextprotocol/sdk/server/index.js”; const server = new Server( { name: “my-server”, version: “1.0.0”, }, { // 必须明确声明能力 capabilities: { tools: {}, // 表示支持工具 resources: {}, // 表示支持资源 // prompts: {}, // 如果不支持提示，则不要声明 }, } );步骤三：使用Zod定义强类型Schema这是提升类型安全的关键。为你每个工具的输入参数创建Zod Schema。
import { z } from “zod”; const searchWebSchema = z.object({ query: z.string().min(1).describe(“Search keywords”), limit: z.number().int().positive().max(50).optional().default(10), }); const calculateSchema = z.object({ expression: z.string().describe(“Mathematical expression to evaluate”), });步骤四：重新定义工具列表工具的定义方式发生了变化，现在需要将Schema与工具描述绑定。
import { Tool } from “@modelcontextprotocol/sdk/types.js”; const tools: Tool[] = [ { name: “search_web”, description: “Search the web for information”, inputSchema: searchWebSchema, // 关联 Zod Schema }, { name: “calculate”, description: “Evaluate a mathematical expression”, inputSchema: calculateSchema, }, ]; // 将工具列表告知服务器 server.setRequestHandler({ method: “tools/list” }, async () => ({ tools, }));步骤五：重写工具调用处理器这是受益最大的部分。处理器中的参数现在有了精确的类型。
server.setRequestHandler( { method: “tools/call” }, async (request) => { // 1. 根据工具名路由到不同的处理逻辑 if (request.params.name === “search_web”) { // 2. TypeScript 知道这里的 arguments 类型是 searchWebSchema 推断出的类型 const { query, limit } = request.params.arguments; // 3. 执行搜索逻辑，无需手动验证 query 是否为字符串，limit 是否在范围内 const results = await performSearch(query, limit); return { content: [{ type: “text”, text: `Search results for “${query}”: ...` }], }; } if (request.params.name === “calculate”) { const { expression } = request.params.arguments; const result = safeEvaluate(expression); // 你自己的安全计算函数 return { content: [{ type: “text”, text: `${expression} = ${result}` }], }; } // 4. 如果工具名未匹配，抛出规范化的错误 throw new Error(JSON.stringify({ code: -32601, message: `Method not found: ${request.params.name}`, })); } );步骤六：处理资源（Resources）资源相关的API也有类似升级。定义资源模板和内容提供器时，类型也更安全了。
// 定义资源模板 const resources: ResourceTemplate[] = [ { uri: “file:///logs/{date}”, name: “Log file by date”, description: “Server log for a specific date”, mimeType: “text/plain”, }, ]; server.setRequestHandler({ method: “resources/list” }, async () => ({ resources, })); // 资源读取处理器 server.setRequestHandler( { method: “resources/read” }, async (request) => { const { uri } = request.params; // 解析URI，获取日期参数等 const logContent = await readLogFile(uri); return { contents: [{ uri, mimeType: “text/plain”, text: logContent, }], }; } );3.3 客户端（Client）代码调整
如果你也使用了SDK的客户端部分（例如，自己编写一个测试客户端或中间件），同样需要调整。
// v2 客户端示例 import { Client } from “@modelcontextprotocol/sdk/client/index.js”; const client = new Client( { name: “test-client”, version: “1.0.0”, }, new StdioClientTransport({ command: “node”, args: [“path/to/your/server.js”], }) ); await client.initialize(); const { tools } = await client.listTools(); console.log(“Available tools:”, tools); // 调用工具，参数类型也是安全的 const result = await client.callTool({ name: “search_web”, arguments: { query: “MCP v2 changes”, limit: 5, // 如果传 limit: “five”，TypeScript 会报错 }, }); console.log(result.content);3.4 构建与启动脚本
确保你的启动脚本（通常是package.json中的scripts）指向正确的入口文件。由于导入路径变成了显式的.js扩展名（即使你写的是.ts，构建后也是.js），在开发时如果使用TS-Node或类似工具，可能需要配置模块解析。在生产环境中，确保你构建后的JS文件能正确找到这些子路径模块。
一个常见的package.json脚本配置如下：
{ “scripts”: { “build”: “tsc”, “start”: “node ./dist/index.js”, “dev”: “tsx watch ./src/index.ts” // 使用 tsx 等工具进行开发时热重载 } }注意：v2 SDK强烈推荐甚至要求与构建工具链（如ESBuild、Vite、Webpack）良好配合，以利用其Tree-shaking特性。如果你的项目是纯CommonJS（
require），可能会遇到一些挑战，建议逐步迁移到ES模块（import/export）。
4. 深度解析：为什么需要这些破坏性变更？
理解这些变化背后的原因，能帮助我们在迁移时做出更合理的决策，并更好地利用新特性。
4.1 协议标准化是生态繁荣的前提
MCP的野心是成为AI模型与外部世界交互的“USB-C接口”。一个松散、有多种实现的协议无法承担这个重任。v1版本作为探索阶段的产物，允许快速实验，但当像Anthropic、Cursor、Windsurf这样的主流IDE和平台开始集成MCP时，互操作性问题就被放大了。
强制使用SSE，定义了严格的错误码和消息格式，这些举措都是为了确保任何遵循MCP 2.0协议的服务器，都能在任何兼容的客户端上无缝工作。这降低了集成成本，让开发者可以专注于工具本身的价值，而不是兼容性调试。这类似于Web API领域的OpenAPI Specification（Swagger）所起的作用，为机器可读的接口描述奠定了基础。
4.2 类型安全是大型项目与团队协作的基石
在v1中，构建一个简单的MCP服务器很快捷。但当工具数量增加到几十个，输入输出结构变得复杂时，维护成本急剧上升。一个工具的参数变更，需要手动检查所有调用它的地方，极易出错。
v2通过Zod Schema + 泛型的组合，将接口契约中心化且机器可校验。Schema是唯一的真相来源（Single Source of Truth），它同时服务于：
- 运行时验证：Zod可以在服务器启动或请求时校验数据。
- 编译时类型：TypeScript利用它提供全链路的类型提示和检查。
- 自动文档生成：Schema本身是结构化的，未来可以轻松用于生成API文档。
这对于团队协作尤为重要。后端开发者修改了工具Schema，前端或AI应用开发者在调用时立即能在IDE中看到类型错误，而不是等到运行时才发现传参不对。
4.3 面向未来的设计：可扩展性与性能
新的包结构和API设计考虑了未来的扩展。将能力（Capabilities）显式化，使得服务器可以声明自己支持哪些协议特性（如“资源变更通知”、“提示模板变量”），客户端可以据此进行适配。这种设计模式为协议后续增加新功能（如身份验证、流式响应、二进制数据传输）预留了空间，而无需再次进行破坏性更新。
ES模块优先的导出方式，配合现代打包工具，可以显著减少最终部署包的体积。对于一个可能被集成到轻量级IDE插件或边缘环境中的MCP服务器来说，每一KB的体积都值得关注。
5. 常见问题与避坑指南实录
在实际迁移和开发v2服务器的过程中，我遇到了一些典型问题，这里记录下来供大家参考。
5.1 类型推断不工作或报错
问题：在工具处理器中，request.params.arguments的类型仍然是any或unknown。排查：
- 检查
Tool类型是否正确使用了泛型。确保你是从@modelcontextprotocol/sdk/types.js导入的Tool类型。 - 检查
inputSchema是否直接传递了Zod Schema对象，而不是它的类型。应该是inputSchema: mySchema，而不是inputSchema: typeof mySchema或inputSchema: z.infer<typeof mySchema>。 - 确保
server.setRequestHandler用于tools/call的方法签名正确。第二个参数应该是异步函数，其参数request的类型应由SDK内部推断。
解决方案示例：
// 正确做法 import { Tool } from “@modelcontextprotocol/sdk/types.js”; import { z } from “zod”; const mySchema = z.object({ /* … */ }); const myTool: Tool<typeof mySchema> = { name: “my_tool”, inputSchema: mySchema, // 直接传递 schema 实例 }; // 在 handler 中，arguments 类型会被正确推断5.2 客户端连接失败或初始化错误
问题：使用v2 SDK的客户端连接v1服务器，或反之，无法正常工作。原因：v1和v2协议不兼容。这是最主要的破坏性变更。解决：
- 升级服务器：目标服务器必须升级到支持MCP 2.0协议的版本（即使用v2 SDK或等效实现）。
- 检查传输方式：确保客户端使用的传输方式（如Stdio、SSE）与服务器端匹配。v2服务器默认期望基于SSE的通信，但通过
StdioServerTransport等方式也支持stdio传输，这通常用于本地调试。 - 查看初始化参数：客户端的
initialize()方法可能需要传递额外的能力协商参数，请参考最新文档。
5.3 Zod Schema定义过于复杂导致序列化问题
问题：定义了一个非常复杂的嵌套Zod Schema，在tools/list响应中，inputSchema字段序列化后的JSON过于庞大，甚至可能包含循环引用导致错误。注意：inputSchema在协议中是需要通过网络传输的JSON Schema。Zod对象本身有.shape等属性，直接JSON.stringify可能有问题。解决：SDK内部应该已经处理了Zod Schema的序列化。但如果你需要手动操作，应使用Zod的.describe()方法或将其转换为JSON Schema对象。通常，你只需要将Zod Schema实例直接赋值给inputSchema，SDK会负责后续处理。
// 通常只需这样写，SDK 会处理转换 const schema = z.object({ user: z.object({ id: z.number(), name: z.string(), }), tags: z.array(z.string()), }); const tool: Tool<typeof schema> = { name: “complex_tool”, inputSchema: schema, // 直接赋值，没问题 };5.4 如何处理可选参数和默认值？
问题：在Zod Schema中定义了可选参数或默认值，但在处理器中不确定如何安全地使用它们。最佳实践：
- 使用
.optional()定义可选参数。 - 使用
.default(value)定义默认值。这是最推荐的方式，因为它确保了即使在调用者未提供该参数时，处理器内也能获得一个确定的值。 - 在处理器中，你可以放心地使用解构赋值，因为Zod在解析参数时已经应用了默认值。
const schema = z.object({ requiredParam: z.string(), optionalParam: z.string().optional(), // 类型是 string | undefined paramWithDefault: z.number().default(10).optional(), // 实际上总会有一个值，至少是10 }); // 在 handler 中 const { requiredParam, optionalParam, paramWithDefault } = request.params.arguments; console.log(optionalParam); // 可能是 undefined console.log(paramWithDefault); // 一定是 number，如果用户没传，就是 105.5 资源URI模板的匹配与解析
问题：在resources/read处理器中，如何解析像file:///logs/{date}这样的URI模板中的变量？解决：SDK通常不会帮你自动解析模板变量。你需要自己编写一个简单的解析函数，从传入的完整URI中提取出变量值。
import { URL } from ‘url’; server.setRequestHandler( { method: “resources/read” }, async (request) => { const uri = request.params.uri; // 示例：解析 file:///logs/2023-10-01 if (uri.startsWith(“file:///logs/”)) { const date = uri.replace(“file:///logs/”, “”); // 验证 date 格式，读取对应日志文件 const content = await readLogByDate(date); return { contents: [{ … }] }; } // 处理其他 URI 模式… throw new Error(`Resource not found: ${uri}`); } );对于更复杂的模板匹配，可以考虑使用像path-to-regexp这样的库。
6. 性能优化与高级模式
当你的MCP服务器需要处理高并发或复杂逻辑时，以下几点优化建议可能会有所帮助。
6.1 工具处理器的异步优化
确保你的工具处理器（handler）是充分异步化的，避免阻塞事件循环。对于耗时的操作（如网络请求、大文件读取、复杂计算），使用async/await，并考虑设置合理的超时。
server.setRequestHandler( { method: “tools/call” }, async (request) => { // 使用 Promise.race 设置超时 const timeoutPromise = new Promise((_, reject) => setTimeout(() => reject(new Error(“Tool execution timeout”)), 30000) ); const executionPromise = (async () => { // 你的实际业务逻辑 await someLongRunningTask(); })(); try { await Promise.race([executionPromise, timeoutPromise]); return { content: [{ type: “text”, text: “Done” }] }; } catch (error) { // 处理超时或其他错误 return { content: [{ type: “text”, text: `Error: ${error.message}` }], isError: true, }; } } );6.2 利用资源订阅（Notifications）减少轮询
MCP v2协议支持资源变更通知。如果你的资源内容会频繁变化（如日志尾随、股票价格、实时数据），不要依赖客户端不断调用resources/read来轮询。相反，实现resources/subscribe和resources/unsubscribe处理器，并在资源变化时主动向客户端发送notifications/resources/updated通知。
这能极大减少不必要的请求，提升效率，并提供更实时的体验。实现此功能需要服务器维护订阅状态列表，并在数据源变化时遍历列表发送通知。
6.3 结构化内容（Content）的返回
工具调用和资源读取的返回值中，content字段是一个数组。除了简单的{ type: “text”, text: “…” }，你还可以返回更丰富的内容。
- 多格式内容：同一个信息，可以同时返回文本和图像格式。
return { content: [ { type: “text”, text: “这是数据的文本描述。” }, { type: “image”, data: “base64EncodedData…”, mimeType: “image/png” }, ], }; - 引用（Annotations）：在文本内容中，可以嵌入引用（如指向某个资源的URI），让客户端能够进行交互。
return { content: [{ type: “text”, text: “请查看详细报告。”, annotations: [{ type: “resource”, resourceUri: “file:///reports/2024-Q1.pdf”, start: 4, // “详细报告”这几个字的位置 end: 8, }], }], };
善用这些结构化内容，可以构建出体验远胜于纯文本交互的智能工具。
从v1到v2的升级，初期确实需要投入一些迁移成本，尤其是对于已有复杂项目的团队。但长远来看，这次升级所带来的协议稳定性、开发体验的飞跃以及为未来生态打下的坚实基础，让这些投入变得非常值得。我的建议是，新项目毫不犹豫地选择v2；对于老项目，制定一个渐进式的迁移计划，可以从工具较少、结构较简单的服务开始，逐步享受强类型和规范化带来的红利。整个MCP生态正在快速成熟，跟上协议的步伐，意味着你的工具能在更广阔的平台中被更可靠地使用。
完全指南：从语法到实战配置)
