如何为KiCAD MCP Server开发一个新MCP工具从Zod Schema到pcbnew实现的5步完整教程【免费下载链接】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 是一个让 Claude 等大语言模型通过 MCPModel Context Protocol直接操作 KiCAD 进行 PCB 设计的开源服务器。掌握它的工具开发流程你就能为这个 200 工具的 MCP 服务添加自己的新能力。本文用 5 个步骤带你从 Zod Schema 定义走到 pcbnew Python 实现完成一个新 MCP 工具的开发。先看懂架构一次工具调用的完整链路在动手前先用 30 秒理解 KiCAD MCP Server 的分层设计这是写出正确代码的前提AI 助手Claude 等 │ MCP 协议JSON-RPC 2.0 / STDIO ▼ TypeScript MCP 服务器src/—— 注册工具、校验参数 │ 以 JSON 通过 stdin 下发命令 ▼ Python 接口层python/kicad_interface.py—— 命令路由 │ pcbnew SWIG API 或 KiCAD IPC API ▼ KiCAD 9.0开发一个新工具本质就是打通这四层的 5 个动作。完整架构说明见官方文档docs/ARCHITECTURE.md。 建议先把仓库克隆到本地git clone https://gitcode.com/gh_mirrors/ki/KiCAD-MCP-Server下文所有路径均相对于仓库根目录。第 1 步用 Zod Schema 定义你的新工具TypeScript 层每个工具对应src/tools/下的一个文件通过server.tool()注册。它的四个参数依次是工具名、描述、Zod 参数 Schema、处理函数。以项目中的create_project工具为范本src/tools/project.tsserver.tool( create_project, // 1. 工具名AI 靠它调用 Create a new KiCAD project, // 2. 描述AI 靠它判断何时用 { // 3. Zod Schema参数即文档 path: z.string().describe(Project directory path), name: z.string().describe(Project name), }, async (args: { path: string; name: string }) { // 4. 处理函数把参数转发给 Python 层 const result await callKicadScript(create_project, args); return { content: [{ type: text, text: JSON.stringify(result, null, 2) }] }; }, );开发要点工具名用蛇形命名snake_case与 Python 端命令名保持一致如my_new_tool。描述要写给 AI 看说清楚这个工具做什么、什么时候该用它这直接决定大模型能否正确选用它。每个参数都加.describe()Zod 的 describe 会进入工具 Schema成为 AI 理解参数的说明书可选参数用.optional()。处理函数几乎不用写业务逻辑统一通过callKicadScript(命令名, 参数)把活交给 Python 层这是本项目的核心约定。新建一个src/tools/my-tools.ts导出一个registerMyTools(server, callKicadScript)函数即可。第 2 步把新工具登记进注册表KiCAD MCP Server 有一个工具注册表 src/tools/registry.ts它把 200 多个工具分成 15 个类别board、component、export、schematic 等供search_tools等发现类工具检索。新工具有两种登记方式方式 A加入某个类别适合大多数工具。在对应类别的tools数组中加上工具名例如 registry.ts 的 board 类别{ name: board, description: Board configuration: layers, mounting holes, zones, visualization, tools: [add_layer, ..., my_new_tool], }方式 B加入常显清单directToolNamesregistry.ts#L286-L330。这个清单里的工具始终对客户端可见适合高频核心操作。注意即使忘了登记工具本身依然能按名字被直接调用只是更难被 AI 发现——测试 tests-ts/registry-completeness.test.ts 会冻结未登记工具数防止这个数字增长。第 3 步在 src/server.ts 挂载注册函数TypeScript 层的所有工具注册都集中在 src/server.ts 的registerAll()方法中server.ts#L322-L352。你需要做两件事// 顶部导入你的注册函数 import { registerMyTools } from ./tools/my-tools.js; // registerAll() 内调用它 registerMyTools(this.server, this.callKicadScript.bind(this));callKicadScript由服务器类注入负责把命令排队、写进 Python 子进程的 stdin并处理超时与请求关联server.ts#L856-L888——你不需要自己关心进程通信细节。第 4 步用 pcbnew 实现 Python 端处理器Python 层遵循命令类模式每个工具命令对应python/commands/下一个模块里的一个方法。4.1 编写命令实现。参照 python/commands/project.py 中create_project的写法class ProjectCommands: Handles project-related KiCAD operations def create_project(self, params: Dict[str, Any]) - Dict[str, Any]: Create a new KiCAD project board pcbnew.BOARD() board.GetTitleBlock().SetTitle(params[name]) # ... 使用 pcbnew API 操作 PCB ... return {success: True, message: Created, data: {...}}约定俗成的返回值结构是{success: bool, message: str, ...其他数据}。4.2 在主入口登记命令路由。python/kicad_interface.py 是 Python 层主入口它从 stdin 读取 JSON 命令再按名字路由到处理器。项目里维护了一张命令名 → 方法的分发映射表kicad_interface.py#L544例如get_project_info: self.project_commands.get_project_info,把你的新命令加进这张表如my_new_tool: self.my_commands.my_new_tool整条链路就通了AI 调用my_new_tool→ TypeScript 校验参数 →callKicadScript下发 JSON → Python 路由到你的方法 → 结果原路返回。 后端选择SWIG / IPC由 python/kicad_api/factory.py 自动完成工具作者无需处理。第 5 步构建、测试并验证npm run build # 编译 TypeScript 层 pytest -v # 运行 Python 测试套件tests/ 目录180 个测试文件推荐的验证流程先跑现有测试确认没有破坏注册表完整性检查registry-completeness、no-stale-tool-references等 TS 测试为新命令补一个 Python 测试tests/下每个命令基本都有对应测试文件如 tests/test_create_project_paths.py照着写即可在 MCP 客户端手动试调重新加载服务器后让 AI 调用你的新工具检查返回的success与message是否符合预期。5 步速查清单步骤文件做什么1src/tools/ 新建文件server.tool() Zod Schema 定义工具2src/tools/registry.ts加入类别或directToolNames3src/server.tsimport 并调用注册函数4python/commands/ python/kicad_interface.pypcbnew 实现 命令路由登记5构建 测试npm run build、pytest、客户端实调写在最后KiCAD MCP Server 的工具开发模型非常清晰TypeScript 层只管协议与参数Python 层只管PCB 业务中间用callKicadScript一条 JSON 命令解耦。看懂 src/tools/project.ts 和 python/commands/project.py 这一对样板文件再对照 docs/ARCHITECTURE.md 的 Adding a New Tool 章节你就可以为这个 MCP 服务开发出任意新的 KiCAD 操作工具了。【免费下载链接】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），仅供参考