typescript-sdk
modelcontextprotocol/typescript-sdk加载项目详情…
本应用为开源项目，仅供学习研究，请遵守其开源协议。
微信扫码咨询客服
POMOAI — 让开源 AI 即刻运行
加载项目详情…
本应用为开源项目，仅供学习研究，请遵守其开源协议。
想象一下：你刚给 AI 下达了"查一下上海今天的天气，再帮我发封邮件"的任务。话音刚落，AI 就已经调动了天气 API 和邮件系统，两件事几乎同时完成，没有任何额外的配置，没有插件适配的烦恼。
这听起来理所当然，但背后其实是一场持续多年的"巴别塔困境"。每一个 AI 应用想调用外部工具，都得像学一门新语言一样，重新适配一遍。Model Context Protocol（MCP） 的出现，正在终结这个混乱局面。
图1：MCP 官方标志 — Model Context Protocol 正在成为 AI 工具互联的事实标准
2024年11月25日，Anthropic 发布了 Model Context Protocol，随即被 Claude Desktop 率先采用。但很少有人注意到，这个协议的灵感其实来自一个老前辈——Language Server Protocol（LSP）。
LSP 在 2016 年由 Red Hat、Microsoft 和 Codenvy 联合推出，旨在让 IDE 能够用统一的协议连接任何编程语言的语言服务器。在此之前，每个 IDE 每支持一门新语言，都要重新实现一遍语法解析、智能提示等功能。LSP 出现后，一套协议打天下，VS Code 因此得以在短短几年内成为宇宙最强IDE。
MCP 的思路如出一辙：与其让每个 AI 应用和每个工具、数据源逐一对接，不如定义一个标准协议，让双方只需说普通话就能互联互通。Anthropic 将这一理念引入 AI 领域，推出了 MCP。如今 Claude、ChatGPT、Cursor、VS Code、Zed、Replit 等主流平台均已采纳 MCP 作为标准扩展机制。
modelcontextprotocol/typescript-sdk 是 MCP 协议的 TypeScript 官方实现库，定位为开发者的首选 SDK。
从架构上看，MCP 采用了经典的 Client-Server 模型，传输层支持两种方式：
图2：MCP 核心架构 — Host 应用（如 Claude Desktop）通过 Client 连接 MCP Server，获取工具（Tools）、资源（Resources）和提示（Prompts）
MCP 协议基于 JSON-RPC 2.0 规范，所有消息均为 JSON 格式，通过传输层序列化传输。协议层定义了四大核心能力：
| 能力 | 说明 |
|---|---|
| Tools | AI 可以调用的函数/工具，如查数据库、发送邮件 |
| Resources | AI 可以读取的数据/文件，如本地文件、API 响应 |
| Prompts | 预定义的提示模板，可被 AI 直接调用 |
| Sampling | AI 主动请求二次推理（向 Host 申请更多 token 或更高模型） |
typescript-sdk 是一个采用 pnpm monorepo 管理的大规模 TypeScript 项目，主分支代码总量约 890 个文件，分为以下核心包：
@modelcontextprotocol/server — 构建 MCP Server
这是 SDK 的核心包，用于构建 MCP 服务器。典型用法只需几行代码：
import { McpServer } from '@modelcontextprotocol/server';
import { StdioServerTransport } 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}!` }] })
);
const transport = new StdioServerTransport();
await server.connect(transport);
Server 端支持注册工具（registerTool）、资源（registerResource）、提示（registerPrompt），并通过中间件机制支持日志记录、进度报告和请求取消。
@modelcontextprotocol/client — 构建 MCP Client
Client 包提供了连接 Server 的能力，支持 stdio 和 Streamable HTTP 两种传输方式。它还内置了完整的 OAuth 2.0 认证流程，支持 Bearer Token、Machine Auth 等多种认证模式，以及 Middleware 机制，允许开发者拦截和修改请求/响应。
Middleware 包 — 框架集成
| 包名 | 说明 |
|---|---|
@modelcontextprotocol/node | Node.js Streamable HTTP 传输适配器 |
@modelcontextprotocol/express | Express 框架集成 |
@modelcontextprotocol/hono | Hono 框架集成 |
这些中间件包极为轻量，仅做传输适配，不引入额外业务逻辑。开发者可以自由选择自己熟悉的 Web 框架来托管 MCP Server。
TypeScript SDK 的另一大亮点是引入了 Standard Schema 规范来验证工具的输入输出 Schema。这意味着你不再被 Zod 绑定，可以自由选择 Zod v4、Valibot 或 ArkType。
同一个 Schema 定义，可以同时用于运行时验证和类型推导，实现一次定义、多处使用，大幅降低了开发者的维护成本。
SDK 在 examples/ 目录下提供了超过 30 个完整可运行的示例，涵盖：
图3：MCP Inspector — 官方调试工具，可查看 Server 的所有工具、资源和提示，并直接测试调用
typescript-sdk 真正做到了 Write Once, Run Anywhere：同一套 SDK 代码，无需任何修改，即可在 Node.js、Bun 和 Deno 上运行。这得益于项目对各运行时 API 差异的充分抽象，通过 shim 层抹平了 process、globalThis、EventTarget 等 API 在不同运行时中的差异。
SDK 同时支持 npm / pnpm / bun / deno 四种安装方式。
截至目前，MCP 已成为 AI 工具互联领域增长最快的协议标准之一。GitHub 上已有数千个社区贡献的 MCP Server 实现，覆盖数据库查询、文件操作、API 调用等各类场景。
图4：Claude Desktop 中的 MCP 工具连接界面 — 点击即用，无需代码配置
从行业视角看，MCP 的意义不仅在于降低开发者的接入成本，更在于它正在形成一种 AI 工具互联的普通话。就像当年 REST API 让 Web 服务之间的调用标准化一样，MCP 正在让 AI 智能体与各类工具、数据源的连接走向标准化。
当前 SDK 处于 v2 beta 阶段（2.0.0-alpha.0），预计 2026 年 7 月 28 日随新版 MCP 规范同步发布正式版。v1.x 仍为生产推荐版本，且至少在未来 6 个月内持续获得 bug 修复和安全更新。
MCP 仍然年轻，v2 规范尚未完全稳定，API 可能在正式版发布前发生变化。对于追求稳定性的企业用户，建议继续使用 v1.x 分支。此外，SDK 对浏览器环境（Browser）的支持仍处于早期阶段，shimsBrowser.ts 尚未完全成熟。
从协议层面看，MCP 目前不支持双向流式通信（Server 主动向 Client 推送大量数据），在需要实时数据流的场景中仍有局限。尽管已有 Sampling 和 Elicitation 等机制弥补，但距离完整的双向通信仍有差距。
一句话总结：modelcontextprotocol/typescript-sdk 是连接 AI 智能体与外部工具/数据源的标准桥梁，通过 TypeScript SDK 将复杂的 MCP 协议封装为简洁的 API，开发者只需几行代码即可为自己的 AI 应用构建起完整的工具生态。