系列：《从 Rule 到落地：AI 工程化实践》第 13 篇
标签：MCP · 实战 · dry-run · 工具设计
专栏：从小白到AI落地大师

系列：《从 Rule 到落地：AI 工程化实践》第 13 篇
标签：MCP · 实战 · dry-run · 工具设计
专栏：从小白到AI落地大师

序言

概念够了，动手。童鞋们最容易一上来列二十个工具，结果一个都观不透。本篇目标很克制：最小 MCP 服务器，三个工具演示列表、执行、健康检查。强调可运行与可观察，上线加固留给第 14 篇。

说句自嘲的：我的第一版 MCP 工具表像愿望清单，联调三天还在改 schema。后来砍到三个，反而两小时打通。少，是为了看见。

概念

本篇 MCP 的目标是可发现、可调用、可观察。Tool 三个就够完成演示闭环。dry-run，只演练不落真实副作用的默认安全模式——演示阶段请默认打开。健康检查，health 工具返回版本与依赖状态，让你知道进程是真活着还是僵尸微笑。

可以理解为：先搭一个能亮灯的电路，再谈配电房。灯都不亮，开关面板做再漂亮也是摆设。

问题在哪

最小实现常栽在三处。工具职责糊成一个 god-tool，参数爆炸，错误只丢堆栈给模型。模型看到堆栈会编故事，不会做决策。本地验证跳步：不列工具就调用，不看日志就怀疑协议。还有人默认实跑，演示改到真实数据——热闹完了才发现副作用。

举例

演示剧本：列出能力 → 跑一个无害动作 → 查看健康与版本。三工具注册表示意：

TOOLS={"health":health_handler,"list_fixtures":list_fixtures_handler,"run_safe_task":run_safe_task_handler,# default dry_run=True}

list_fixtures 只读，建立信任。run_safe_task 带参数的受限执行，默认 dry-run：

{"task":"regress","engine":"acme-adaptor-mock","dry_run":true}

health 返回版本、时间、依赖探测。错误返回约定：可机器解析的错误码，不要只丢堆栈。本地验证步骤固定：启动 → 列举工具 → 调用 → 看日志。虚构的 ops-gate-mcp 最小版就按这三板斧走，团队 onboarding 一天能接通，靠的不是天才，是剧本短。

自检

# 最小 MCP 自检 - [ ] 是否只有职责清晰的 3 个工具（或同量级）？ - [ ] run 类工具是否默认 dry-run？ - [ ] 错误是否结构化、含错误码？ - [ ] 是否走完启动→列举→调用→看日志？ - [ ] health 是否能反映版本与依赖状态？

两问。第一，关掉 dry-run 需要什么显式动作？若「什么都不做就实跑」，默认安全档就不存在。第二，客户端看到的错误是码还是小说？小说请改成码。

演示剧本请写成可勾选清单放进仓库。下一个人接通时，不应靠你现场口述。口述是单点故障，清单才是资产。

干跑成功后再谈实跑开关。实跑开关要显式、可审计、默关闭——这三件事比多写五个工具重要。

三个工具就够演示：fetch_log（读）、dry_run_adapt（写的假动作）、apply_adapt（真写，默认关）。演示日只点亮前两盏灯；第三盏灯接上鉴权与确认再开。工具愿望清单可以写在 backlog，别写进第一周的 manifest。

错误返回建议固定形状：{ "ok": false, "code": "...", "hint": "...", "correlation_id": "..." }。助手靠 code 分支，人靠 hint 排查，审计靠 correlation_id 串链。

演示脚本建议写成一键：起 MCP → 打fetch_log→ 打dry_run_adapt→ 打印 correlation_id → 故意让apply_adapt因缺确认而拒绝。观众看到「拒绝」比看到「成功改掉」更该鼓掌——那说明闸门在。

三个工具的命名要丑一点、具体一点，避免do_stuff。名字即文档，模糊名字会引诱助手乱调用。

读到这里，不妨立刻做一个五分钟动作：打开你们仓库，找到与本篇对应的那个目录（没有就新建），把文中最小示意落成真实文件名。文件在，讨论才有坐标；文件不在，下周还会从「我们觉得」开始。第 13 篇的验收不是「读完」，是「仓库里多了一份可指出的东西」。

举例加长：演示当日的「拒绝剧本」

主持人脚本：先成功 fetch_log，再成功 dry_run_adapt，最后调用 apply_adapt——期望返回ok=false, code=CONFIRM_REQUIRED。然后才人工确认，第二次 apply 成功。观众应记住第二次，而不是第一次被拒绝的尴尬；尴尬是教材。

演示脚本请写成「人也能点」的顺序：先health，再list_fixtures，再 dry-runrun_safe_task，最后才显式打开实跑。全程同一correlation_id。观众问「写操作在哪」，你能指到 T2 工具与确认板——这比工具数量更能证明你懂闸门。

思考

小结三句。最小 MCP 追求可发现、可调用、可观察。默认 dry-run 降低演示风险。错误要结构化，方便 Agent 决策。

可以理解为：三盏灯亮了，再谈配电与门禁。下篇升级到上线级：鉴权、熔断、T1 到 T4 风险闸门。

下篇预告：《上线级 MCP：鉴权、熔断、职责边界》——演示级直接上生产，就是裸奔登台。

觉得有用的话，欢迎点赞、留言晒你的三工具名单；有「工具愿望清单联调到崩溃」的经历，也欢迎自嘲区集合。

专栏：从小白到AI落地大师｜《从 Rule 到落地：AI 工程化实践》