第五篇　接入 WorkBuddy、联调排错与发布上线

本章导读

服务器写完了，但「能跑」和「能用」是两件事。这一篇解决最后一段路：

一个真实的比例

按经验，一个 MCP 服务器项目的时间分布大约是这样：

• 写业务逻辑：20%；
• 把接口描述与错误文案打磨到模型能稳定选对、读懂：30%；
• 联调排错（含各种客户端差异）：30%；
• 安全加固与上线准备：20%。

也就是说，80% 的工作在「写完之后」。这一篇讲的就是那 80%。

学完这一篇你会得到什么

1. 能独立写出一份不会踩坑的 ~/.workbuddy/mcp.json（含 stdio 与远程 HTTP 两种形态）；
2. 遇到「工具不出现 / 连接失败 / 调用 400 / 模型选错工具」时，有一套固定的排查顺序，而不是瞎试；
3. 有一份可以直接贴进团队仓库的上线检查清单；
4. 知道怎么把服务器分发给别人（uvx / npm / 私有仓库 / 统一配置下发）。

一个心态提醒

MCP 的报错信息分散在三处：服务器自己的日志（stderr）、客户端的连接状态、以及协议层的响应。排错效率低，往往是因为只看了一处。5.2 节会教你把三处串起来看。

下一节：先把服务器接进 WorkBuddy。