MCP Server 开发者起步包

这个 pack 写给谁

你在 Claude Code / Cursor / Codex CLI 里用 MCP server 已经一阵子了。现在你想自己写一个 — 把内部 API、私有 CRM、自定义工具封成 MCP server，让所有支持 MCP 的 agent 都能调用。这是生产侧的起步包；如果你只想装现成的 server，看姊妹包 MCP Server Stack。

这十个工具覆盖完整闭环：选一门你已经在写的语言的 SDK，用更高层的框架脚手架起项目跳过样板代码，开着 MCP Inspector 实时调试，最后发布到 registry 让别人的 agent 能自动发现和安装。

推荐安装顺序

1. MCP Inspector — 第一个装。MCP server 的官方 Web 调试 UI，可以连任何 server（stdio 或 HTTP）、列出 tool、发测试调用、看原始 JSON-RPC 报文。整个开发过程都开着这个标签页。不用 Inspector 调 MCP server 等于不用 DevTools 写网页。
2. Microsoft MCP — 官方 TypeScript SDK — Node 这边的官方 SDK。定义了 Server 类、传输层（stdio / HTTP）、带类型的 RequestHandler。想要完整控制权或者写参考样例就用这个。
3. MCP Python SDK — Python 官方 SDK。形状和 TS 那个一致：Server、stdio_server、request handler。如果你的工具本体已经在用 Python 生态（数据 / ML / 爬虫），选 Python。
4. FastMCP — Python 框架 — MCP 界的 Flask（相对 Werkzeug）。装饰器式，样板代码大幅减少。@mcp.tool() 套在普通函数上就是个 server。90% 的 Python MCP server 用这个；只有需要细粒度传输层控制才往下掉到裸 SDK。
5. FastMCP — TypeScript 框架 — Node 这边同理念。server.addTool({ name, parameters, execute }) 就完事。需要时和官方 TS SDK 混着用。
6. mcp-go — Build MCP Servers in Go — Go SDK。延迟敏感或者要单二进制部署就选它（serverless 冷启动、嵌入 CLI、Docker scratch image）。
7. Build Your Own MCP Server — Step-by-Step Guide — 第一次提交前先读的教程。讲 JSON-RPC 帧格式、tool 发现、错误信封、三种传输层。省半天读 spec 的时间。
8. Claude 官方 Skill: mcp-builder — Anthropic 官方的 Claude skill，专门用来脚手架 MCP server。插到 Claude Code 里，描述你要的 tool，它会写出 SDK 样板（manifest、request handler、类型存根）。第一个 server 用起来很爽；写到第三个会发现自己想绕过它。
9. Smithery — MCP Server Registry & Installer — 事实标准的 registry。发布到这里之后你的 server 就能 npx smithery install your-server 装，和几百个其他 server 一起列出。必看。
10. awesome-mcp-servers — MCP 目录索引 — GitHub 上人工维护的精选索引。server 稳定之后 PR 进去。受众和 Smithery 不一样（开发者在 GitHub 上浏览 vs agent 自动发现），两边都做。

它们怎么协同

选 SDK：     Microsoft TS  ─┐
             MCP Python    ──┼─▶  框架脚手架
             mcp-go        ─┘     │
                                  ├─ FastMCP Python
                                  ├─ FastMCP TypeScript
                                  └─ Claude mcp-builder skill
                                          │
                                          ▼
                                  MCP Inspector
                                  (实时调试 + 测试调用)
                                          │
                                          ▼
                                   发布
                                  ├─ Smithery registry
                                  └─ awesome-mcp-servers PR

SDK → 框架 → Inspector → registry 四步闭环就是全部工作。多数翻车（agent 找不到你的 tool / tool 调用挂死 / schema 校验失败）都来自跳过 Inspector。别跳过 Inspector。

你会遇到的取舍

• 裸 SDK vs FastMCP — 裸 SDK = hello-world 80 行代码、传输层和中间件完全自己控制。FastMCP = 12 行、装饰器式、有主见。从 FastMCP 起步，只有撞墙才掉到裸 SDK（自定义鉴权、自创非 stdio 传输层）。
• TypeScript vs Python vs Go — TS 参考样例最多，原生支持 MCP 的 agent host 生态也最大。如果你的工具本体已经是 Python（pandas / sklearn / scrapy）选 Python。Go 适合单二进制部署和紧延迟。
• Smithery vs awesome-mcp-servers — Smithery 机器可读（agent 自动安装），awesome-mcp-servers 人类可读（开发者在 GitHub 上翻）。漏斗不同 — 两边都提交。
• mcp-builder skill vs 自己手写 — Skill 适合第一个 server（生成正确的样板）。它生成的模式到第三个 server 你就想自己改了，预期会被你淘汰。

常见踩坑

• stdio 传输层的 buffer 问题 — 永远别往 stdout 写日志。日志走 stderr，stdout 给 JSON-RPC 帧用。混着写会静默破坏每一条消息。
• Tool schema 漂移 — manifest 里 tool 的输入 schema 必须和 handler 实际期望的一致。MCP Inspector 会立刻暴露不匹配；不用 Inspector 你会花几小时纳闷为啥 agent 传 query 而 handler 读 q。
• 长时间 tool 不发进度 — MCP 支持进度通知。如果你的 tool 超过 5 秒，要发进度，否则 host 会以为挂死直接超时。
• shutdown 时忘了清理 — 持资源的 handler（DB 连接、文件锁）需要 on_shutdown 清理。Inspector 抓不到，生产环境才会暴露。
• server 还没稳定就提交 Smithery — 版本抖动会破坏每个 pin 你 server 的 agent 的安装。先打真正的 v1.0.0 tag，再发布。