--- title: "TypeScript SDK 概览：主线在演进，生产默认看 v1.x" wiki: mcp category: "SDK" slug: typescript-sdk-overview url: https://learnagent.wiki/mcp/cards/typescript-sdk-overview tags: ["MCP", "TypeScript SDK", "Node.js", "Streamable HTTP", "SDK"] last_updated: 2026-04-11 reading_time: 10 --- > TypeScript SDK 是 MCP 官方在 JavaScript / TypeScript 生态里的核心实现。它的角色，和 Python SDK 很像，但当前有一个非常关键的现实背景： # TypeScript SDK 概览：主线在演进，生产默认看 v1.x ## 基础概念 TypeScript SDK 是 MCP 官方在 JavaScript / TypeScript 生态里的核心实现。它的角色，和 Python SDK 很像，但当前有一个非常关键的现实背景： **截至 2026-04-11，官方 `typescript-sdk` 仓库 `main` 分支 README 仍明确写着：主线是 v2，当前处于 pre-alpha；生产环境仍推荐使用 v1.x。** 这句话非常重要，因为如果你只看 `main` 分支示例，很容易误以为： - “这就是我现在该直接用的稳定接口” 但官方自己给出的版本判断不是这样。 我又核了 npm registry 的真实发行状态： - `@modelcontextprotocol/server` 最新版本：`2.0.0-alpha.2` - `@modelcontextprotocol/client` 最新版本：`2.0.0-alpha.2` - 二者 `engines.node` 都要求：`>=20` 所以现在最该先搞清楚的，不是“先写哪段代码”，而是： 1. 你是在看 v1.x 还是 v2 主线资料 2. 你是做生产项目还是做试验 / 迁移预研 ### 核心要素 | 要素 | 作用 | |------|------| | **版本分层** | `main` 分支是 v2 pre-alpha；官方 README 明确说生产仍推荐 v1.x | | **包拆分** | v2 主线把能力拆成 `@modelcontextprotocol/server` 和 `@modelcontextprotocol/client` | | **多运行时支持** | 官方 README 说明它可运行在 Node.js、Bun、Deno | | **中间件适配层** | 官方还提供 Node / Express / Hono 等薄适配包 | | **文档入口** | v1 和 v2 的 API 文档是分开的，不能混着看 | ### 现在最重要的不是 API，而是版本判断 ```mermaid graph TD A["我要用 TypeScript SDK 做 MCP"] --> B{"目标是什么？"} B -->|"生产项目"| C["优先看 v1.x 文档和分支"] B -->|"预研 / 学 v2 方向"| D["看 main 分支和 v2 文档"] C --> E["关注稳定接口和迁移成本"] D --> F["关注拆包、新中间件、v2 架构"] ``` ### v1 和 v2 的官方格局 ```mermaid graph LR A["v1.x"] --> B["@modelcontextprotocol/sdk"] A --> C["官方 README 仍作为生产推荐线"] D["v2 main"] --> E["@modelcontextprotocol/server"] D --> F["@modelcontextprotocol/client"] D --> G["middleware packages"] D --> H["官方标注为 pre-alpha"] ``` 这个图的核心信息就一句话：**现在 TypeScript SDK 不是“只有一条主线”，而是“生产线和演进线并存”。** ## 基础用法 ### 如果你看的是 v2 主线 `main` 分支 README 给出的安装方式是拆包的： ```bash npm install @modelcontextprotocol/server ``` 客户端则是： ```bash npm install @modelcontextprotocol/client ``` 并且还支持： ```bash bun add @modelcontextprotocol/server deno add npm:@modelcontextprotocol/server ``` 这说明 v2 的一个明显方向是：**把 Server、Client 和运行时适配层拆得更清楚。** ### v2 主线还提供哪些适配包 官方 README 还列了几个可选 middleware： - `@modelcontextprotocol/node` - `@modelcontextprotocol/express` - `@modelcontextprotocol/hono` 它们的定位不是增加新 MCP 功能，而是“薄适配”，帮你把 MCP 接进具体运行时或 Web 框架。 ### 如果你看的是 v1.x 生产线 `v1.x` 分支 README 里的主包还是： ```bash npm install @modelcontextprotocol/sdk zod ``` 而且 README 明确写了： - `zod` 是 **required peer dependency** - SDK 内部从 `zod/v4` 导入 - 但兼容 `zod` v3.25+ 这类信息在生产项目里很关键，因为它直接影响你的依赖树和升级风险。 ### 一个最小能力长什么样 v1.x README 和主文档的核心思路是类似的：你会用 `McpServer` 或对应服务端 API 定义： - tools - resources - prompts - transports 而 v2 主线 README 更强调： - split packages - examples/ - docs/server.md 与 docs/client.md 也就是说，**v1 更像“单包主入口”，v2 更像“拆层后的 monorepo 工具箱”。** ### 当前最稳的学习路径 如果你现在就要在 TypeScript 里真的做东西，比较稳的顺序通常是： 1. 先判断你是不是生产项目 2. 生产项目优先看 `v1.x` 分支和 v1 API docs 3. 预研 v2 时再看 `main` 分支 README、`docs/server.md`、`docs/client.md` 4. 不要把 v1 包名、v2 包名和示例代码混用 ## 同类工具对比 如果目标是“用 TS/JS 构建 MCP 能力”，几条路线大致可以这样看： | 维度 | TypeScript SDK v1.x | TypeScript SDK v2 main | Python SDK | |------|---------------------|------------------------|------------| | 当前生产稳定性 | **更稳** | 预发布，官方标注 pre-alpha | 稳定主线更明确 | | 包结构 | 较集中，`@modelcontextprotocol/sdk` | 拆成 server / client / middleware | 以 `mcp` 包为中心 | | 运行时生态 | Node.js 为主 | Node.js、Bun、Deno 都强调 | Python | | 最适合谁 | 现在就要上线的 TS 团队 | 做迁移预研或跟进主线演进的人 | Python 团队 | | 认知门槛 | 中 | 更高，得先理解版本格局 | 中 | 核心区别： - **TS SDK v1.x**：现在更像生产默认线。 - **TS SDK v2 main**：现在更像下一代主线，适合预研和跟进。 - **Python SDK**：当前生产叙事更统一，没有这么强的“主线分叉感”。 ## 常见误区 | 误区 | 准确理解 | |------|----------| | 以为 main 分支 README 就等于“当前生产最佳实践” | 不对。官方自己在 README 里写了：v2 仍是 pre-alpha，生产仍推荐 v1.x | | 以为 npm 上有 `@modelcontextprotocol/server` 最新包，就说明 v2 已稳定 | 不对。最新发布目前仍是 `2.0.0-alpha.2`，alpha 本身就说明不是稳定 GA | | 以为 v1 和 v2 只是文档排版不同 | 不是。包结构、入口设计、适配层思路都发生了变化 | | 以为 TypeScript SDK 只支持 Node.js | 不对。官方 v2 README 明确写了 Node.js、Bun、Deno | | 以为 middleware 包就是“功能扩展层” | 官方强调它们是 thin adapters，不该承载新的业务逻辑或协议功能 | | 以为学习 TypeScript SDK 时可以随便混看 v1 和 v2 示例 | 这是最容易踩坑的地方，尤其包名和导入方式很容易混乱 | ## 优劣势分析 | 优势 | 劣势 | |------|------| | **官方能力覆盖完整**：Server、Client、transports、middleware、examples 都很全 | **当前版本格局复杂**：v1 生产线和 v2 演进线并存，认知成本明显更高 | | **JS/TS 生态强**：很适合 Web 服务、Node 侧网关、框架适配 | **新手最容易踩版本坑**：尤其看到 main 分支就直接抄代码 | | **v2 拆层方向清晰**：server/client/middleware 分工更明确 | **v2 仍是 pre-alpha**：现在还不能把“未来方向”直接当“当前稳定答案” | | **多运行时支持有潜力**：Node、Bun、Deno 兼容面广 | **生产决策需要更多判断**：不是“安装一个包就完了”，得先选版本线 | | **examples 和 docs 体系较完整**：官方给了 runnable examples 和 server/client 文档 | **迁移成本真实存在**：已有 v1 项目不能假设无痛切 v2 | ## 思考题
初级：为什么现在写 TypeScript MCP 项目时，第一步不是“npm install 什么”，而是“先判断看哪条版本线”？ **参考答案：** 因为 TypeScript SDK 当前不是单线稳定状态。 如果你先入手装包，再回头看文档，很容易出现下面这种混乱： - 安装了 v2 alpha 包 - 却看的是 v1 文档 - 或者看了 `main` 分支 README - 却在项目里还沿用 v1 的包名和代码结构 所以正确顺序应该反过来：先判断你要走生产稳定线还是预研演进线，再决定包、文档和示例都看哪一套。
中级：为什么官方 v2 要把 TypeScript SDK 拆成 `server`、`client` 和 middleware，而不是继续做一个“大一统包”？ **参考答案：** 拆包的核心价值是职责更清楚。 很多项目只写 Server，不需要 Client；有些项目只写 Client，不需要 Server；还有些项目只是想把 Streamable HTTP 接到 Express 或 Hono 里。这些场景如果全绑在一个大包里，依赖会更重，边界也更模糊。 v2 的方向显然是在把这几层分开： - 协议能力分层 - 运行时适配分层 - 应用逻辑和框架 glue code 分层 这对大项目和框架化使用是好事，但对刚入门的人来说，理解成本也确实更高。
进阶：如果你今天要给团队定一条 TypeScript MCP 技术路线，应该怎么决定是继续用 v1.x，还是开始试 v2？ **参考答案：** 关键不在“哪个更新”，而在“你承担得起多少不确定性”。 如果你的团队现在主要目标是稳定交付、快速上线、少踩版本坑，那更合理的路线通常是： - 生产继续用 v1.x - 单独开一个预研分支试 v2 如果你的团队本身就在做 SDK、基础设施、中间件层，或者你明确希望跟随官方主线提前适配新的包结构和运行时支持，那可以更积极地试 v2。 换句话说： - **交付优先**：v1.x - **预研优先**：v2 main / alpha 这不是保守，而是把工程风险和学习成本放在正确的位置上。
## 参考资料 1. MCP TypeScript SDK 官方仓库（main 分支）：（查询日期 2026-04-11） 2. MCP TypeScript SDK main README：（查询日期 2026-04-11） 3. MCP TypeScript SDK `v1.x` README：（查询日期 2026-04-11） 4. npm `@modelcontextprotocol/server`：（查询日期 2026-04-11） 5. npm `@modelcontextprotocol/client`：（查询日期 2026-04-11） --- *Source: https://learnagent.wiki/mcp/cards/typescript-sdk-overview* *Markdown mirror of https://learnagent.wiki, served as text/markdown for LLM ingestion.*