如何为KiCAD MCP Server开发一个新MCP工具：从Zod Schema到pcbnew实现的5步完整教程-开发者社区

如何为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-Server

KiCAD MCP Server 是一个让 Claude 等大语言模型通过 MCP（Model 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.ts）：

server.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：加入常显清单directToolNames（registry.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 步速查清单

步骤	文件	做什么
1	src/tools/ 新建文件	`server.tool()`+ Zod Schema 定义工具
2	src/tools/registry.ts	加入类别或`directToolNames`
3	src/server.ts	import 并调用注册函数
4	python/commands/ + python/kicad_interface.py	pcbnew 实现 + 命令路由登记
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 操作工具了。

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