MCP TypeScript SDK 的 modelcontextprotocol 包该装哪个server、client 与 HTTP 适配器怎么选【免费下载链接】typescript-sdkThe official TypeScript SDK for Model Context Protocol servers and clients项目地址: https://gitcode.com/GitHub_Trending/ty/typescript-sdk开始使用 MCP TypeScript SDKv2时第一个容易卡住的点是安装npm 上发布的不是单一的modelcontextprotocol/sdk而是九个modelcontextprotocol/*包。装错包比如新项目引入迁移用的server-legacy或漏装HTTP 部署时没装框架适配器都会让第一步就跑不起来。这篇文章给出按使用位置选包的方法先确定你写的是协议哪一侧再决定是否需要 HTTP 适配器并给出每个选择对应的安装命令和验证方式。先确定你要装的是 server 还是 clientmodelcontextprotocol/server和modelcontextprotocol/client是几乎所有项目的起点按你构建的协议位置二选一npm install modelcontextprotocol/server # expose tools, resources, prompts npm install modelcontextprotocol/client # connect to servers and call them暴露工具tools、资源resources、提示prompts的程序装 server 包。一个进程同时扮演两侧例如自带调试客户端的服务端项目就两个都装。连接并调用已有服务器的程序装 client 包。Client加一个 transport 就是一个完整的 MCP 客户端。v1 时代的单个modelcontextprotocol/sdk包不再用于新项目v1 导入路径如modelcontextprotocol/sdk/server/mcp.js的深路径在 v2 包中不会解析需要用modelcontextprotocol/codemod重写。完整的九个包以及什么时候才轮到它们除 server/client 两个起点外文档给出的发布集合是包什么时候装modelcontextprotocol/node用 Node 内置http提供 HTTP 服务时IncomingMessage/ServerResponse适配modelcontextprotocol/expressExpress 框架上提供 HTTP 服务时与express一起装modelcontextprotocol/fastifyFastify 框架上提供 HTTP 服务时与fastify一起装modelcontextprotocol/honoHono 框架上提供 HTTP 服务时与hono一起装modelcontextprotocol/core只有当你要自己校验原始 JSON-RPC 报文时网关、代理、日志管道modelcontextprotocol/server-legacyv1 部署逐步迁移到 v2 时冻结的 v1 SSE 传输与 OAuth 授权服务器助手modelcontextprotocol/codemod命令行工具把 v1 导入和调用点改写成 v2 形式判断规则HTTP 适配器按需选装且最多装一个。createMcpHandler来自modelcontextprotocol/server本身就输出 web-standard 的(Request) PromiseResponsehandler适配器只是把它接到具体运行时或框架上是薄封装不增加 MCP 行为。所以框架选哪个就装哪个适配器不要为了备用多装。core只在处理原始 wire JSON 时直接导入。server和client都不导出 Zod schema对应的 TypeScript 类型随两者自带如果你只调用registerTool和callToolcore只是作为它们的传递依赖存在无需显式安装。server-legacy和codemod不属于新项目二者都只服务于 v1 迁移。包名之外还有一个结构点每个包的根入口都是运行时中立的——其模块图不会触碰浏览器或 Cloudflare Workers 打包器无法解析的 Node 内置模块。会启动子进程的代码一律放在./stdio子路径后面显式导入才进入你的依赖树// Runs anywhere: browsers, Workers, Node. import { Client } from modelcontextprotocol/client; // Spawns a child process — Node-only, so it lives behind the subpath. import { StdioClientTransport } from modelcontextprotocol/client/stdio;modelcontextprotocol/server/stdio是服务端对应物导出serveStdio和StdioServerTransport。前提与安装文档要求Node.js 20 或更高——所有modelcontextprotocol/*包都要求 Node 20OAuth 客户端助手依赖globalThis.cryptoNode 20 起该全局始终存在。SDK 只发布 ES modules所以项目里typemodule是必须的。以服务端为例从零建项目mkdir weather cd weather npm init -y npm pkg set typemodule npm install modelcontextprotocol/server zod tsx mkdir srctsx用于直接运行 TypeScript免去构建步骤zod是工具 schema 的依赖工具 schema 遵循 Standard SchemaZod v4、Valibot、ArkType 等均可。SDK 本身跑在 Node.js、Bun 和 Deno 上README 给出的等价安装命令bun add modelcontextprotocol/server # 或 deno add npm:modelcontextprotocol/serverclient 侧同理modelcontextprotocol/client与 server 包分开发布单独安装。装完 serverstdio 跑通并验证最小可运行的 server 来自上面这一条安装通过两个导入路径根入口拿McpServer./stdio子路径拿serveStdio见 docs/get-started/first-server.mdimport { McpServer } from modelcontextprotocol/server; import { serveStdio } from modelcontextprotocol/server/stdio; import * as z from zod/v4; const server new McpServer({ name: greeting-server, version: 1.0.0 }); server.registerTool( greet, { description: Greet someone by name, inputSchema: z.object({ name: z.string() }) }, async ({ name }) ({ content: [{ type: text, text: Hello, ${name}! }] }) ); void serveStdio(() server); console.error(server running on stdio);注意日志用console.errorstdout 是 JSON-RPC 协议通道serveStdio拥有它一条console.log就会把无法被 JSON-RPC 解析的行混进流里。运行与验证npx tsx src/index.tsstdio 服务启动后不会继续输出——它在 stdin 上等待客户端发起对话属预期现象CtrlC停止。文档给出的直接验证方式是 MCP Inspector它自己启动你的命令并经 stdio 连接见 docs/serving/stdio.mdnpx modelcontextprotocol/inspector npx tsx src/index.ts在打开的浏览器页签里点ConnectTools页签会列出工厂注册的全部工具选择greet、填入参数并运行结果里的 text 块就是模型调用该工具时会收到的内容。装完 client连接并验证client 包的最小形态是Client加一个 transport。stdio 场景下connect()会自己把服务器命令作为子进程启动经其 stdin/stdout 走 JSON-RPC 并完成initialize握手——不要自己先启动服务器脚本见 docs/get-started/first-client.mdimport { Client } from modelcontextprotocol/client; import { StdioClientTransport } from modelcontextprotocol/client/stdio; const client new Client({ name: my-first-client, version: 1.0.0 }); const transport new StdioClientTransport({ command: npx, args: [tsx, src/index.ts] }); await client.connect(transport); const { tools } await client.listTools(); for (const tool of tools) { console.log(tool.name, —, tool.description); } await client.close();用npx tsx src/client.ts运行。验证判据脚本打印出服务器注册的工具名与描述文档示例输出为greet — Greet someone by name这类一行且结尾close()之后脚本自行退出、不必CtrlC——close()会关闭生成的服务器 stdin 并在进程不退出时将其终止。如果出现spawn npx ENOENT说明command不在PATH上属环境问题而非 SDK 问题。远端服务器走 HTTP 时transport 换成StreamableHTTPClientTransport从modelcontextprotocol/client根入口导入取服务器 MCP 端点 URL面向只有旧版 HTTPSSE 传输的服务器才用SSEClientTransport兜底——详见 docs/clients/connect.md。需要对外提供 HTTP 端点加装一个框架适配器当目标是一个端点、多个客户端连接时同一份服务器工厂改经 Streamable HTTP 提供见 docs/serving/http.md。此时在 server 包之外加装一个适配器且必须与你的框架配套# Node.js HTTP (IncomingMessage/ServerResponse) Streamable HTTP transport: npm install modelcontextprotocol/node # Express integration: npm install modelcontextprotocol/express express # Fastify integration: npm install modelcontextprotocol/fastify fastify # Hono integration: npm install modelcontextprotocol/hono hono以 Express 为例docs/serving/express.md一条安装行加一个文件即可import { createMcpExpressApp } from modelcontextprotocol/express; import { toNodeHandler } from modelcontextprotocol/node; import { createMcpHandler, McpServer } from modelcontextprotocol/server; import * as z from zod/v4; const handler createMcpHandler(() { const server new McpServer({ name: notes, version: 1.0.0 }); server.registerTool(add-note, { description: Append a note, inputSchema: z.object({ text: z.string() }) }, async ({ text }) ({ content: [{ type: text, text: Saved: ${text} }] })); return server; }); const app createMcpExpressApp(); const node toNodeHandler(handler); app.all(/mcp, (req, res) void node(req, res, req.body)); app.listen(3000);结构要点createMcpHandler接收工厂每个 HTTP 请求构建一个全新的McpServer工厂内注册工具/资源/提示不要在工厂外对共享实例注册createMcpExpressApp已替你配好express.json()和本地回环绑定下的Host/Origin校验防 DNS rebinding绑定0.0.0.0时需要改用createMcpExpressApp({ host: 0.0.0.0, allowedHosts: [api.example.com] })明确允许的域名req.body作为toNodeHandler的第三个参数传入避免适配器重复读取 Express 已消费的请求流。用npx tsx server.ts启动后向端点 POST 一个tools/list请求验证curl -s -X POST http://127.0.0.1:3000/mcp \ -H Content-Type: application/json \ -H Accept: application/json, text/event-stream \ -d {jsonrpc:2.0,id:1,method:tools/list}响应是一个携带tools/list结果的 SSEmessage事件文档示例event: message data: {result:{tools:[{name:add-note,description:Append a note,inputSchema:{type:object,$schema:https://json-schema.org/draft/2020-12/schema,properties:{text:{type:string}},required:[text]}}]},jsonrpc:2.0,id:1}看到add-note出现在tools数组里即端点已通。纯node:http无框架或 web-standard 运行时Cloudflare Workers、Deno、Bun 的export default handler的挂载方式见 docs/serving/http.md 与 docs/serving/web-standard.md。安装后常见的三个报错及对应检查docs/troubleshooting.md 中与前两个选择直接相关的条目TS2589: Type instantiation is excessively deep and possibly infinite——依赖树里存在两份zod。用npm ls zod或pnpm why zod/yarn why zod列出所有副本对齐到同一个 Zod 4 版本传递依赖固定了另一份时用包管理器的 override 字段npm/pnpm 用overridesYarn 用resolutions如zod: ^4.2.0。npm ls zod只剩一个版本后该错误随之消失。ReferenceError: crypto is not defined——进程运行在 Node 18 或更早的运行时代码路径上。所有modelcontextprotocol/*包要求 Node 20无法升级时需在触碰 SDK 前从node:crypto给globalThis.crypto补上 polyfill。SyntaxError: Unexpected token ... is not valid JSONstdio 场景——某处你的代码或依赖向 stdout 写了非协议行。改为console.error输出日志报错中引用的 token 通常是那条杂散行的首字符可借此定位写入点。选型结论按文档给出的规则收束写暴露工具/资源/提示的程序 →modelcontextprotocol/server写连接并调用服务器的程序 →modelcontextprotocol/client两侧都做就都装经 HTTP 对外服务 → 在上述基础上按所用框架加装且只装一个适配器node/express/hono/fastify框架工厂如createMcpExpressApp已默认启用 localhost 下的 Host/Origin 校验core留给自己处理原始 wire JSON 的代码server-legacy、codemod留给 v1 迁移不进新项目迁移路径见 docs/migration/upgrade-to-v2.md。后续路径stdio 服务可以注册进 VS Code、Claude Code、Cursor 等真实宿主docs/get-started/real-host.md更完整的可运行示例在 examples/README.md每个目录是一组自验证的客户端/服务端配对。【免费下载链接】typescript-sdkThe official TypeScript SDK for Model Context Protocol servers and clients项目地址: https://gitcode.com/GitHub_Trending/ty/typescript-sdk创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考