尧图网页设计 
一个关键词如何找到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-ServerKiCAD MCP Server 是一个 Model Context ProtocolMCP服务器它让 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.ts2026-03-113d9497e禁用网关。提交记录写道间接执行导致 Claude 通过 search_tools/execute_tool 幻觉出工具 schema所有工具改为直接注册、立即可见2026-05-03963a39c彻底删除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 一样被测试保护防止过期指令悄悄回归。【免费下载链接】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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 一个关键词如何找到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-ServerKiCAD MCP Server 是一个 Model Context ProtocolMCP服务器它让 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.ts2026-03-113d9497e禁用网关。提交记录写道间接执行导致 Claude 通过 search_tools/execute_tool 幻觉出工具 schema所有工具改为直接注册、立即可见2026-05-03963a39c彻底删除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 一样被测试保护防止过期指令悄悄回归。【免费下载链接】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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考