内容
# KiCad 库生成器 — MCP 服务器
> 使用 AI 为 **任何元件** 生成可用于生产的 KiCad 10 库（符号 + 焊盘 + 3D 模型）。
> 支持 **Claude Desktop**、**ChatGPT** 和 **Gemini**。
---
## 为什么存在
每个 PCB 工程师都知道痛苦：需要的元件在 KiCad 的库中不存在。你要么花费 2-3 小时从头开始建立一个焊盘，要么从 Ultra Librarian / SnapMagic 下载并希望焊盘尺寸是正确的。
它们往往不正确。在开发过程中测试的实际 RF 模块中，Ultra Librarian 的 IPC-7351C 估计值产生的焊盘 **面积比数据手册推荐的焊盘图案小 28%**。这是一个可靠的焊接连接和现场故障之间的区别。
该工具是在花费两周时间硬着头皮制作 KiCad 10 库后创建的，使用 Claude、数据手册像素测量、RF 禁区验证和一轮又一轮的 DRC/ERC 修复。在此过程中学习的所有规则现在都硬编码在此，您无需再向 AI 解释一次。
---
## 功能
### 核心差异 — 基于图像的焊盘测量
从 **数据手册焊盘图案图像** 读取焊盘尺寸（像素 → 毫米），而非 IPC-7351C 文本估计。每个测量值都与图纸中的所有数字标注进行交叉检查。
```
Ultra Librarian（IPC 估计）：0.559 × 2.007 mm ← 错误
制造商图纸（图像）： 0.600 × 2.400 mm ← 正确
面积差异：28%
```
### JLCPCB 优先工作流
在生成任何内容之前，检查 JLCPCB 的数据库（约 70 万种现货零件，通过 [jlcsearch](https://jlcsearch.tscircuit.com)）：
- **基本/首选零件**，有验证的焊盘 → 重用它，节省时间
- **扩展零件** → 下载并验证焊盘尺寸与数据手册对比
- **不在 JLCPCB / RF 模块 / 自定义焊盘图案** → 从数据手册生成
- 自动解决 LCSC 3D 模型下载 URL
### 6 个领域中的 24 个 MCP 工具
| 领域 | 工具 |
|---|---|
| **库生成** | `generate_full_library`、`generate_kicad_symbol`、`generate_kicad_footprint`、`generate_3d_model`、`package_kicad_library` |
| **测量和查找** | `measure_datasheet_drawing`、`get_component_info`、`get_available_packages` |
| **JLCPCB 集成** | `lookup_jlcpcb_part`、`find_jlcpcb_alternatives`、`get_jlcpcb_3d_model` |
| **验证** | `validate_kicad_library`、`check_schematic_erc`、`check_placement_clearance` |
| **高级焊盘** | `generate_thermal_pad_features`、`generate_multi_unit_symbol`、`calculate_ipc_pad_dimensions`、`get_ipc_footprint_name` |
| **生产输出** | `generate_bom`、`generate_cpl`、`add_supplier_properties`、`generate_accuracy_report`、`generate_power_symbols`、`generate_library_release` |
### 验证 — 20 个 DRC + 12 个 ERC 检查（IPC-7351C）
**焊盘 DRC（FP001-FP020）：**
courtyard 存在，courtyard 包围所有焊盘，fab 层存在，silkscreen 清晰，焊盘重叠，IPC-2221 电压清晰，THT 环形环（A/B/C 类），NPTH 铜禁止，热焊盘糊减少，pin-1 标记，silkscreen 上有参考，fab 层上有值，BGA NSMD 焊盘尺寸，`*.Cu` 上的 RF 禁区，禁区无填充块，模型块多行，`.pretty` 文件夹中的焊盘，SMD 糊层，焊盘编号顺序，安装孔 NPTH。
**符号 ERC（SY001-SY012）：**
pin 号唯一性，焊盘属性前缀，有源零件上的电源引脚，检测未连接的电源，GPIO 为双向，passive 引脚类型，参考前缀正确，存在描述，存在数据手册 URL，无 forbidden token，NC 引脚标记为 `no_connect`，引脚与焊盘双射。
### KiCad 10 规则硬编码 — 修复 8 个已知错误
| 错误 | 修复 |
|---|---|
| `(justify center)` 在 `fp_text` 中无效 | 忽略 — 中心文本不需要 justify 字段 |
| `generator_version` 导致解析错误 | 永远不会写入 |
| 单行模型块静默失败 | 强制多行模板 |
| `*.Cu` 中的 keepout 导致 DRC 错误 | 从不生成填充块 |
| 焊盘属性缺少库前缀 | 格式：`LibraryName:FootprintName` |
| 仅 `F.Cu` 上的 RF 禁区 | 始终写入为 `*.Cu` |
| `inverted` 引脚类型无效 | 重新映射到 `input` |
| `not_connected` 引脚类型无效 | 重新映射到 `no_connect` |
### 输出到 `~/Desktop/KiCad-Libraries`
所有生成的 文件都放在桌面上 — 立即可见。文件内容也会内联返回到 AI 响应中，以便您无需打开文件管理器即可检查。
---
## 支持的元件类型
无源元件（0201-2512），ICs（QFN，QFP，SOP，DIP，LGA，BGA，WLCSP），MCUs，RF/WiFi/BT/Zigbee/Thread 模块，连接器（USB-C，RJ45，JST，卡边缘），晶体管（SOT23，TO252），二极管，晶体，运算放大器（多单元），门阵列，电源模块，安装孔，测试点，基准点。
内置 IPC 焊盘图案适用于 0201、0402、0603、0805、1206、1210、2010、2512。
56 个前缀规则（U、R、C、L、J、Q、D、Y、FB、F、RV、H、TP、SW、K、T...）。
用于 JLCPCB 装配的 42 项 CPL 旋转校正表。
---
## 支持的 AI 客户端
| 客户端 | 传输方式 | 使用方法 |
|---|---|---|
| **Claude Desktop** | stdio | `install/install.sh` 自动配置 |
| **ChatGPT** | HTTP | `python server.py --http` → 指向 `http://localhost:8000/mcp` |
| **Gemini CLI** | HTTP | `python server.py --http` → `gemini --mcp http://localhost:8000/mcp` |
| **任意 MCP 客户端** | stdio / HTTP | 相同的服务器，两种传输方式 |
---
## 快速开始
### 要求
- Python 3.11 或 3.12（3.13 也可用）
- 与 pyenv、conda、homebrew、系统 Python 兼容
- KiCad 10（用于导入生成的库）
### 安装 — Mac / Linux
```bash
git clone https://github.com/yourname/kicad-mcp-server.git
cd kicad-mcp-server
bash install/install.sh
```
该脚本：
1. 自动检测 Python（通过 pyenv → conda → homebrew → PATH 解析）
2. 将依赖项安装到确切的 Python 中
3. 运行 80 个验证测试
4. 用正确的绝对 Python 路径编写 `claude_desktop_config.json`
然后 **完全退出 Claude Desktop（Mac 上为 Cmd+Q）**，等待 5 秒钟，然后重新打开。
### 安装 — Windows
```powershell
git clone https://github.com/yourname/kicad-mcp-server.git
cd kicad-mcp-server
powershell -ExecutionPolicy Bypass -File install\install.ps1
```
### 验证
在 Claude Desktop 中，询问：
> *"你有多少个 KiCad 工具？"*
预期响应：**24 个工具**。
### 可选 — 3D 模型生成（CadQuery）
```bash
pip install cadquery
```
如果没有 CadQuery，服务器提供 JLCPCB/LCSC 模型下载 URL 而不是生成 STEP 文件。对于大多数零件，这实际上更好（制造商模型与生成的近似值）。
---
## 使用示例
### 为任意元件生成库
```
"为 RC0603FR-07100KL 10kΩ 电阻器生成 KiCad 10 库。
首先检查 JLCPCB。"
```
该工具检查 JLCPCB，发现它是一个 0603 封装的基本零件，建议重用他们的焊盘，并生成具有所有供应商属性的符号。
### 从数据手册图像生成
```
"为此 RF 模块生成 KiCad 10 焊盘。
我将上传焊盘图案图 — 使用像素测量进行焊盘尺寸测量。"
```
上传数据手册中的图 8.3。该工具测量像素坐标，转换为毫米，与所有标注进行交叉检查，应用 RF 禁区规则，并生成验证的焊盘。
### 从头开始生成完整的库
```
"为 STM32F103C8T6 生成完整的 KiCad 10 库。
JLCPCB 零件编号 C8734。封装：LQFP48。"
```
返回：`.kicad_sym` + `.kicad_mod` 在 `.pretty` 文件夹中 + STEP 3D 模型 URL + BOM CSV + CPL CSV，带有旋转校正 + 准确性报告 + 导入说明。
### 查找更便宜的 JLCPCB 替代品
```
"查找 AMS1117-3.3 SOT223 LDO 的更便宜的 JLCPCB 替代品。"
```
搜索具有相同封装的基本/首选零件，按库存排序，并为每个零件建议重用。
---
## 项目结构
```
kicad-mcp-server/
├── server.py # MCP 服务器 — 24 个工具，单个 stdio 入口点
├── requirements.txt
├── README.md
│
├── tools/ # 每个功能区域一个文件
│ ├── symbol_gen.py # .kicad_sym 生成
│ ├── footprint_gen.py # .kicad_mod + 禁区 + 模型块
│ ├── model_gen.py # CadQuery STEP 生成
│ ├── validator.py # kiutils DRC/ERC 验证
│ ├── image_measure.py # 像素 → 毫米，从数据手册图纸
│ ├── component_lookup.py # 零件编号 → 元件数据
│ ├── jlcpcb_lookup.py # JLCPCB/LCSC API + 重用决策
│ ├── bom_cpl.py # BOM CSV，CPL CSV，旋转校正
│ ├── thermal_pad.py # QFN/LGA 的糊网 + 过孔阵列
│ ├── multi_unit_symbol.py # 多单元符号（运算放大器，门）
│ ├── ipc_land_pattern.py # IPC-7351C A/B/C 类焊盘计算器
│ ├── erc_checks.py # 引脚冲突，PWR_FLAG，网络连接
│ ├── accuracy_report.py # Markdown 签收报告 + 库差异
│ ├── library_metadata.py # IPC 命名，版本控制，审查清单
│ └── packager.py # ZIP 与 .pretty 文件夹 + README
│
├── rules/ # 所有规则为 Python 常量
│ ├── kicad10_rules.py # KiCad 10 语法规则，已知错误，3D 约定
│ └── ipc_rules.py # IPC-7351C DRC/ERC 检查，焊盘形状，庭院
│
├── tests/
│ └── test_rules.py # 80 个测试 — 全部离线
│
└── install/
├── install.sh # Mac/Linux 安装程序（处理 pyenv/conda/homebrew）
├── install.ps1 # Windows PowerShell 安装程序
├── start_server.py # .mcpb 的引导程序（venv + 依赖项安装）
└── manifest.json # Claude Desktop 扩展 manifest
```
---
## 导入到 KiCad 10
生成库后：
**符号：**
`Preferences → Manage Symbol Libraries → Add Existing → select .kicad_sym file`
**焊盘：**
`Preferences → Manage Footprint Libraries → Add Existing → select .pretty FOLDER`
⚠️ 选择 **文件夹**（`LibraryName.pretty`），而不是单个 `.kicad_mod` 文件。
**3D 模型：**
将 `.step` 文件放在焊盘的模型属性中显示的路径上，
或设置 `KICAD6_3DMODEL_DIR` 环境变量。
---
## JLCPCB 装配工作流
1. 生成库 → 使用您的 LCSC 零件编号 `generate_full_library`
2. 检查 JLCPCB 重用建议和证据
3. 生成 BOM → `generate_bom`，使用所有零件的 LCSC 号码
4. 生成 CPL → `generate_cpl`（自动应用旋转校正）
5. 将 Gerbers + BOM + CPL 上传到 JLCPCB
6. **在确认之前目视检查 pin-1 方向** 在 JLCPCB 装配预览中
步骤 6 无法自动化 — 这是一个 30 秒的视觉检查，捕获任何剩余的旋转偏移。
---
## 依赖项
| 包 | 用途 | 必须 |
|---|---|---|
| `mcp>=1.0.0` | MCP 协议（FastMCP） | 是 |
| `kiutils>=0.4.0` | KiCad 文件解析器 — KiCad 使用的相同解析器 | 是 |
| `pdfplumber>=0.9.0` | PDF 数据手册文本提取 | 是 |
| `pytest>=7.0.0` | 测试运行器 | 开发 |
| `cadquery` | STEP 3D 模型生成 | 可选 |
---
## 运行测试
```bash
python3 -m pytest tests/test_rules.py -v
```
80 个测试，全部离线。涵盖每个 KiCad 10 错误、IPC 规则、JLCPCB 决策和元件分类。测试在 Python 3.11、3.12、3.13 上通过。
---
## 故障排除
| 问题 | 修复 |
|---|---|
| "无法连接到 MCP 服务器" | 重新运行 `bash install/install.sh` — 用正确的 Python 路径重写配置 |
| "Uvicorn 在 8000 上运行" 在终端中 | 旧的 server.py 带有重复的 `__main__` 块 — 替换为最新的 |
| 重启后无工具 | 完全退出 Claude Desktop（Cmd+Q），而不仅仅是关闭窗口 |
| `FastMCP()` 得到意外的关键字参数 'version' | 旧的 server.py — 替换为最新的（删除 `version=` 和 `description=` 参数） |
| pyenv / conda Python 未找到 | 运行 `bash install/install.sh` — 自动检测实际二进制 |
| 测试失败 | `python3 -m pip install -r requirements.txt` 然后重试 |
| 输出文件不可见 | 检查 `~/Desktop/KiCad-Libraries/` |
---
## 背景
该项目源于为实际的 PCB 设计构建自定义 KiCad 10 库 — RF 模块、自定义连接器和标准 KiCad 库中没有涵盖的 IC。通过与 Claude 的合作，揭示了许多可重复使用的规则：如何从数据手册图像中读取焊盘图案，如何正确应用 RF 禁区，哪些 KiCad 10 语法错误导致静默失败，以及如何使用 kiutils 验证所有内容。
与其每次都解释这些规则，不如将它们硬编码到这个 MCP 服务器中。每个规则、每个修复、每个验证检查都是从实际设计会话中学到的。
---
## 路线图
- [ ] 发布到 PyPI（`uvx kicad-library-generator` 一键安装）
- [ ] KiCad 插件管理器集成（直接在 KiCad 中运行）
- [ ] 扩展已知元件数据库，添加更多验证的数据手册条目
- [ ] JLCPCB 旋转校正自动检测，从零件预览中
- [ ] 多页面数据手册导航，用于具有复杂焊盘图案的元件
---
## 许可证
MIT — 见 [LICENSE](LICENSE)
---
## 贡献
PR 欢迎，尤其是：
- `tools/component_lookup.py` 中的新条目 `KNOWN_COMPONENTS` 字典（验证的数据手册值）
- `tools/bom_cpl.py` 中的新 JLCPCB CPL 旋转校正 `JLCPCB_ROTATION_CORRECTION`
- `rules/kicad10_rules.py` 中的其他 KiCad 10 语法错误修复
对于每个新的元件条目，请包括数据手册图纸参考、测量的焊盘尺寸和标注交叉检查。
