一个关键词如何找到244个工具：KiCAD MCP Server的search_tools发现机制与一次被回滚的架构设计-开发者社区

一个关键词如何找到244个工具：KiCAD MCP Server的search_tools发现机制与一次被回滚的架构设计

【免费下载链接】KiCAD-MCP-ServerKiCAD MCP is a Model Context Protocol (MCP) implementation that enables Large Language Models (LLMs) like Claude to directly interact with KiCAD for printed circuit board design.项目地址: https://gitcode.com/gh_mirrors/ki/KiCAD-MCP-Server

KiCAD MCP Server 是一个 Model Context Protocol（MCP）服务器，它让 Claude 等大语言模型能直接操作 KiCAD 完成电路板（PCB）设计。目前它在服务端注册了244 个工具，其中最巧妙的部分不是这些工具本身，而是一个搜索机制——当你只说"gerber"这样一个关键词时，search_tools就能从 244 个工具里帮你找到该调用的那一个。更有趣的是，这个项目还曾经把大部分工具"藏起来"以省上下文，结果被 AI 的"幻觉"逼着回滚了。本文带你看懂这套发现机制的设计、取舍与教训。

KiCAD MCP Server 是什么？给新手的一句话解释

简单说，它是一座"AI 与 KiCAD 之间的桥"：

你在对话框里用自然语言说"导出 Gerber 文件"、"加一个安装孔"；
MCP 服务器把这句话翻译成对 KiCAD 的具体工具调用；
工具由 Python 端真正执行，结果再返回给 AI 总结给你。

对使用者来说完全无感——你不需要知道任何工具名字，AI 会自己找到并调用。而"找到工具"这件事，就是本文的主角search_tools干的事。

📖 完整能力清单见 README.md，全部 244 个工具的机器生成目录在 docs/TOOL_INVENTORY.md。

为什么 244 个工具需要"发现机制"

MCP 协议下，所有工具的定义（名字、参数、JSON Schema）都会发给 AI 客户端。244 个工具意味着庞大的上下文。这就引出一个问题：

AI 怎么知道自己该调哪个工具？

两种情况：

常用工具：AI 已经见过它们的完整定义，直接按名字调用，无需搜索；
长尾工具：比如"导出 IPC-2581 文件"这种低频操作，AI 可能不确定工具名，需要按关键词检索。

KiCAD MCP Server 的答案是：给每个工具建一个"索引目录"，再提供 3 个只读的发现工具。

search_tools 的工作原理：一个"工具目录"

核心实现只有两个文件：

src/tools/registry.ts：工具注册表，把 244 个工具分成17 个类别（board、component、export、drc、schematic、library、routing、autoroute 等）；
src/tools/router.ts：注册search_tools、list_tool_categories、get_category_tools三个发现工具，它们只查目录、不执行任何操作。

以search_tools为例，调用方只需给一个query关键词。它的搜索逻辑（见 src/tools/registry.ts）会同时匹配三类文本：

直接工具（direct tools）的名称——这是 32 个高频"必备工具"，比如create_project、place_component，保证最核心的操作永远搜得到；
类别名和类别描述——搜 "gerber" 时，因为export类别的描述里写着 "Gerber, PDF, BOM, 3D models"，整个类别下的工具都会被带出；
工具名本身——子串匹配，比如搜 "export" 会命中export_gerber、export_bom等。

返回值是一段简单的 JSON，告诉 AI"找到几个、叫什么、在哪个类别，直接按名字调用即可"：

{ "query": "gerber", "count": 4, "matches": [ { "category": "export", "tool": "export_gerber", "description": "..." } ], "note": "Call a matching tool directly by name with its own parameters." }

这里有一个值得新手注意的细节：注册表里"分类工具"和"直接工具"故意有 7 个重叠（最常用的原理图操作既常驻可见、也可被搜索到），而且统计总数时必须去重——否则标题里的数字就会虚高。src/tools/registry.ts 中的getDistinctToolNames()专门处理这件事。

目前184 个工具已被索引，其余 60 个"未索引"工具照样能用（直接按名字调用即可），只是暂时搜不到。项目用测试把 60 这个数字"冻结"住，只许减少不许增加——见 tests-ts/registry-completeness.test.ts。

三个发现工具的分工

工具	作用	适合场景
`list_tool_categories`	列出 17 个类别及每个类别的工具数	"这个服务器都能干什么？"
`get_category_tools`	展开某个类别下的全部工具	"导出类工具有哪些？"
`search_tools`	按关键词跨类别搜索	"gerber 相关的工具在哪？"

三者都不执行任何动作，纯粹是"目录浏览"。实现见 src/tools/router.ts。

一次被回滚的架构设计：省 Token 的"网关"为什么失败了

这部分是本文的重点。项目早期（2025 年 12 月）实现过一个"路由器网关"设计，完整方案记录在 docs/ROUTER_ARCHITECTURE.md，实施状态存档在 docs/archive/ROUTER_IMPLEMENTATION_STATUS.md：

原始设计（三层结构）：

🟢直接工具（12 个）：最高频操作，常驻可见；
🟡路由器工具（4 个）：比现在多一个execute_tool，所有被隐藏的工具必须"先搜索、再经它统一执行"；
🔴被隐藏的工具（110+ 个）：不发给 AI，目的是把上下文从约 40K token 压到 12K，节省约 70%。

账面上很漂亮。实际跑起来却踩了一个 AI 特有的坑：

工具被隐藏后，AI 从未见过它们的真实参数定义，于是开始凭空编造工具 schema（幻觉）——把不存在的参数发给execute_tool，调用自然失败。

回滚过程分两步，原因都写在代码注释里（src/tools/router.ts）：

2026-03-11（3d9497e）：禁用网关。提交记录写道："间接执行导致 Claude 通过 search_tools/execute_tool 幻觉出工具 schema，所有工具改为直接注册、立即可见"；
2026-05-03（963a39c）：彻底删除execute_tool，只保留 3 个只读发现工具。

关键教训：这是一次"正确性优先于省 Token"的权衡，而不是烂尾功能——间接执行让模型发明了它从没见过的 schema，而直接注册不会。

项目如何保证"旧坑不再被踩"

回滚后还有一个隐患：search_tools的返回文案里可能仍写着"请调用 execute_tool"——这类话是给 AI 读的，过期指令会把模型引向一个已不存在的工具，而且这个回归持续了两个版本才被发现。

项目的解法是"对着运行时输出做断言"：测试 tests-ts/no-stale-tool-references.test.ts 用假服务器拦截三个发现工具的处理器，真正执行一遍，检查返回给客户端的文本里绝不能出现execute_tool。有意思的是它刻意不 grep 源码——因为router.ts文件头注释里合法地记载着这段历史，检查源码会误伤解释性文字。

新手速览：这套机制怎么用

实际使用时你完全不需要手动调用任何发现工具，直接自然语言提问即可：

你：把这个板子的 Gerber 文件导出到 ./output/ AI 内部动作：search_tools("gerber") → 定位 export_gerber → 直接调用 → 返回结果

如果你是想给这个项目做贡献、或想深入理解 MCP 服务器设计，推荐阅读顺序：

docs/ROUTER_ARCHITECTURE.md——完整的设计史（开头有"历史文档"警告，务必读到 Status 一节）；
docs/TOOL_INVENTORY.md——244 个工具的完整目录，每个工具标注了"Essential / 类别 / 未索引"的发现方式；
src/tools/registry.ts 与 src/tools/router.ts——全部核心逻辑，两个文件即可读完。

总结：一个小机制背后的工程智慧

KiCAD MCP Server 的search_tools用一个关键词就能穿透 244 个工具，靠的是"注册表索引 + 类别描述匹配 + 必备工具直通"三层设计；而它被回滚的"网关"方案则给所有做 MCP 服务的开发者上了一课：省上下文不能以牺牲模型对工具的真实认知为代价。

这套机制的精华浓缩成三条：

🔍 发现工具只做"只读目录"，所有工具都直接注册、按名可调用——搜索是索引，不是闸门；
🧠 模型看不见的工具，模型就会幻想它的参数——间接执行是幻觉之源；
🛡️ 面向 AI 的响应文本要像 API 一样被测试保护，防止过期指令悄悄回归。

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

一个关键词如何找到244个工具：KiCAD MCP Server的search_tools发现机制与一次被回滚的架构设计