SDK难度 2⏱ 12 分钟概念
01Python SDK 概览：用官方工具链构建 MCP 服务
Python SDK 不只是“一个库”，而是把 MCP 的 Server、Client、传输和开发工具链一起打包给你。
MCPPython SDKFastMCPMCPServerSDK
更新于 2026-04-11python-sdk-overview
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、传输和开发工具链一起打包给你。