Python SDK 概览:用官方工具链构建 MCP 服务
Python SDK 不只是“一个库”,而是把 MCP 的 Server、Client、传输和开发工具链一起打包给你。
TypeScript SDK 现在正处在 v1.x 生产线和 v2 主线演进并存的阶段,理解这个版本格局比盲目开写更重要。
内容摘要
TypeScript SDK 是 MCP 官方在 JavaScript / TypeScript 生态里的核心实现。它的角色,和 Python SDK 很像,但当前有一个非常关键的现实背景:
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.2engines.node 都要求:>=20所以现在最该先搞清楚的,不是“先写哪段代码”,而是:
| 要素 | 作用 |
|---|---|
| 版本分层 | main 分支是 v2 pre-alpha;官方 README 明确说生产仍推荐 v1.x |
| 包拆分 | v2 主线把能力拆成 @modelcontextprotocol/server 和 @modelcontextprotocol/client |
| 多运行时支持 | 官方 README 说明它可运行在 Node.js、Bun、Deno |
| 中间件适配层 | 官方还提供 Node / Express / Hono 等薄适配包 |
| 文档入口 | v1 和 v2 的 API 文档是分开的,不能混着看 |
这个图的核心信息就一句话:现在 TypeScript SDK 不是“只有一条主线”,而是“生产线和演进线并存”。
main 分支 README 给出的安装方式是拆包的:
npm install @modelcontextprotocol/server
客户端则是:
npm install @modelcontextprotocol/client
并且还支持:
bun add @modelcontextprotocol/server
deno add npm:@modelcontextprotocol/server
这说明 v2 的一个明显方向是:把 Server、Client 和运行时适配层拆得更清楚。
官方 README 还列了几个可选 middleware:
@modelcontextprotocol/node@modelcontextprotocol/express@modelcontextprotocol/hono它们的定位不是增加新 MCP 功能,而是“薄适配”,帮你把 MCP 接进具体运行时或 Web 框架。
v1.x 分支 README 里的主包还是:
npm install @modelcontextprotocol/sdk zod
而且 README 明确写了:
zod 是 required peer dependencyzod/v4 导入zod v3.25+这类信息在生产项目里很关键,因为它直接影响你的依赖树和升级风险。
v1.x README 和主文档的核心思路是类似的:你会用 McpServer 或对应服务端 API 定义:
而 v2 主线 README 更强调:
也就是说,v1 更像“单包主入口”,v2 更像“拆层后的 monorepo 工具箱”。
如果你现在就要在 TypeScript 里真的做东西,比较稳的顺序通常是:
v1.x 分支和 v1 API docsmain 分支 README、docs/server.md、docs/client.md如果目标是“用 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 团队 |
| 认知门槛 | 中 | 更高,得先理解版本格局 | 中 |
核心区别:
| 误区 | 准确理解 |
|---|---|
| 以为 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 SDK 当前不是单线稳定状态。
如果你先入手装包,再回头看文档,很容易出现下面这种混乱:
main 分支 README所以正确顺序应该反过来:先判断你要走生产稳定线还是预研演进线,再决定包、文档和示例都看哪一套。
参考答案:
拆包的核心价值是职责更清楚。
很多项目只写 Server,不需要 Client;有些项目只写 Client,不需要 Server;还有些项目只是想把 Streamable HTTP 接到 Express 或 Hono 里。这些场景如果全绑在一个大包里,依赖会更重,边界也更模糊。
v2 的方向显然是在把这几层分开:
这对大项目和框架化使用是好事,但对刚入门的人来说,理解成本也确实更高。
参考答案:
关键不在“哪个更新”,而在“你承担得起多少不确定性”。
如果你的团队现在主要目标是稳定交付、快速上线、少踩版本坑,那更合理的路线通常是:
如果你的团队本身就在做 SDK、基础设施、中间件层,或者你明确希望跟随官方主线提前适配新的包结构和运行时支持,那可以更积极地试 v2。
换句话说:
这不是保守,而是把工程风险和学习成本放在正确的位置上。
v1.x README:https://github.com/modelcontextprotocol/typescript-sdk/blob/v1.x/README.md(查询日期 2026-04-11)@modelcontextprotocol/server:https://www.npmjs.com/package/@modelcontextprotocol/server(查询日期 2026-04-11)@modelcontextprotocol/client:https://www.npmjs.com/package/@modelcontextprotocol/client(查询日期 2026-04-11)优先展示同分类且标签更接近的内容,方便继续串联学习。
Python SDK 不只是“一个库”,而是把 MCP 的 Server、Client、传输和开发工具链一起打包给你。