不会还有人一上来就做二十个工具吧？三个工具够演示闭环 | 最小 MCP 实战

系列《从 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_runTrue}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——期望返回okfalse, codeCONFIRM_REQUIRED。然后才人工确认第二次 apply 成功。观众应记住第二次而不是第一次被拒绝的尴尬尴尬是教材。演示脚本请写成「人也能点」的顺序先health再list_fixtures再 dry-runrun_safe_task最后才显式打开实跑。全程同一correlation_id。观众问「写操作在哪」你能指到 T2 工具与确认板——这比工具数量更能证明你懂闸门。思考小结三句。最小 MCP 追求可发现、可调用、可观察。默认 dry-run 降低演示风险。错误要结构化方便 Agent 决策。可以理解为三盏灯亮了再谈配电与门禁。下篇升级到上线级鉴权、熔断、T1 到 T4 风险闸门。下篇预告《上线级 MCP鉴权、熔断、职责边界》——演示级直接上生产就是裸奔登台。觉得有用的话欢迎点赞、留言晒你的三工具名单有「工具愿望清单联调到崩溃」的经历也欢迎自嘲区集合。专栏从小白到AI落地大师《从 Rule 到落地AI 工程化实践》