KiCad AI — локальная среда Cursor → MCP → KiCad

1. What is this?

Рабочая среда для AI-assisted engineering в KiCad: LLM через MCP создаёт и правит настоящие .kicad_sch / .kicad_pro, проверяет связность, гоняет ERC/DRC и BOM через официальный kicad-cli. SKiDL — опциональный Python-слой; KiCad остаётся источником истины.

Это не генератор картинок и не mock. Схему можно открыть в KiCad 10.

Related MCP server: KiCad MCP Server

2. Architecture

Cursor Agent  --stdio MCP-->  kicad-ai (whitelist + backup + logs)
                                |                         |
                                v                         v
                         kicad-sch-api 0.5.6          kicad-cli 10.0.6
                                |                     ERC / DRC / netlist
                                +-----> projects/**  (source of truth)

                         SKiDL 2.3.0  --> skidl_lab/  (blocks, tests, generated netlists)
                                          never overwrites projects/*.kicad_sch

• Schematic engine: пакет kicad-sch-api (реальный S-expression parser/writer).

• ERC / DRC / BOM / netlist / sch upgrade: C:\Program Files\KiCad\10.0\bin\kicad-cli.exe.

• SKiDL 2.3.0 (KICAD10): блоки и Python ERC в skidl_lab/ (не пакетный каталог skidl/, чтобы не перекрыть PyPI).

• Stock kicad-sch-mcp не подключён напрямую: у него нет whitelist путей.

Отклонённые альтернативы и будущие слои: docs/architecture.md.

3. Requirements

Проверено на этой машине:

• Windows 10 x64

• KiCad 10.0.6 (C:\Program Files\KiCad\10.0\)

• Python 3.12 через uv (системный 3.14 не используется)

• uv 0.12.x

• Git

4. Installation

В PowerShell из корня репозитория:

cd C:\Cursor_Projects\MCP_KiCad
.\scripts\setup.ps1

Эквивалент вручную:

uv sync --group dev
uv run doctor

5. Configuration

Скопируйте .env.example в .env только если автоопределение KiCad не сработало.

Переменные:

• KICAD_AI_WORKSPACE — корень workspace (Cursor задаёт сам)

• KICAD_EXE, KICAD_CLI, KICAD_SYMBOL_DIR, KICAD_FOOTPRINT_DIR — ручные пути

• KICAD_AI_BACKUP_KEEP — сколько backup хранить (по умолчанию 10)

• KICAD_AI_LOG_LEVEL — INFO / DEBUG

6. Cursor MCP setup

Файл .cursor/mcp.json запускает .venv/Scripts/python.exe -m kicad_ai.mcp.server (быстрее и совместимо с Cursor; MCP 1.x).

1. Откройте этот folder как workspace Cursor.

2. Cursor Settings → MCP → включите сервер kicad.

3. Подтвердите tools.

4. Проверка: uv run doctor должен показать [OK] MCP configuration.

Ручной запуск (обычно не нужен):

uv run start-mcp
.\scripts\start-mcp.ps1

7. Creating first project

Скажите агенту:

Создай проект контроллера насоса в projects/user/pump-controller

Агент должен вызвать create_project, затем добавлять символы из библиотек KiCad, соединять пины, сохранить, прогнать ERC.

Пример из репозитория:

uv run kicad-ai example

создаёт projects/examples/mcp-test/ (12V → предохранитель → R-78E5.0-0.5 → 5V + LED). Рядом лежит тестовая плата mcp-test.kicad_pcb (не для производства). kicad-ai example с overwrite перезапишет каталог, после этого плату нужно собрать снова скриптом из §11.

8. Working with existing projects

1. list_projects / load_schematic

2. get_schematic_info + inspect_connectivity

3. Предложить изменение

4. save_schematic (backup создаётся автоматически)

5. validate_project (ERC + DRC; нет PCB → DRC SKIPPED)

6. Показать summary

Проекты пользователя кладите в projects/user/. Каталог projects/ в .gitignore — схемы и платы не попадают в git, только локально. Не пишите вне workspace: MCP это запретит.

9. Backup and rollback

Перед перезаписью существующей схемы MCP копирует проект в backups/<name>/YYYY-MM-DD_HHMMSS/. Старые копии чистятся (последние 10).

.\scripts\backup-project.ps1 projects\examples\mcp-test
uv run kicad-ai backup projects\examples\mcp-test

Откат: tool restore_backup или копирование папки backup обратно в project dir.

10. Validation

uv run doctor
uv run kicad-ai validate projects\examples\mcp-test
uv run pytest -v
.\scripts\open-kicad.ps1

Doctor проверяет KiCad, Python 3.12, uv, Git, kicad-sch-api, SKiDL, .cursor/mcp.json, workspace.

validate гоняет настоящий kicad-cli sch erc и kicad-cli pcb drc. Если .kicad_pcb нет, DRC = SKIPPED (не PASS).

Python-тесты: tests/test_electrical.py (KiCad ERC/DRC/netlist) и skidl_lab/tests/ (SKiDL ERC). SKiDL не пишет схему проекта.

11. PCB

MCP не создаёт .kicad_pcb: ни автоматически после схемы, ни по запросу из Cursor. create_project пишет только .kicad_pro + .kicad_sch. Tool run_drc / validate_project при отсутствии платы возвращают SKIPPED (это не PASS и не проверка разводки).

У примеров уже есть тестовые платы (smoke для DRC и 2D/3D render, не Gerber). Пересборка только через pcbnew KiCad 10:

& "C:\Program Files\KiCad\10.0\bin\python.exe" scripts\build_mcp_test_pcb.py
uv run kicad-ai validate projects\examples\mcp-test

& "C:\Program Files\KiCad\10.0\bin\python.exe" scripts\build_oxy_pcb.py
uv run kicad-ai validate projects\oxy\oxy
uv run kicad-ai render-pcb projects\oxy\oxy
uv run kicad-ai render-3d projects\oxy\oxy

mcp-test: F1, U1, R1, D1, 40×26 мм. oxy: F1, J1/J2 (XH2.54), R1, D1, 55×30 мм, GND/GNDA разведены.

Готовую к производству плату MCP не соберёт. Нормальный путь для своих проектов — KiCad GUI:

uv run kicad-ai open projects\examples\mcp-test\mcp-test.kicad_pro

1. PCB Editor (если файла платы нет, KiCad создаст пустой *.kicad_pcb).

2. Update PCB from Schematic (F8) — футпринты и нетлист со схемы, не разводка.

3. Контур, расстановка, дорожки, полигоны, крепёж — руками в pcbnew.

4. DRC в PCB Editor, затем снова uv run kicad-ai validate … (DRC уже не SKIPPED).

Update PCB from Schematic — не «плата на печать». Gerber / drill / Pick & Place в этой среде не реализованы. Не просите агента имитировать их.

12. skidl_lab

skidl_lab/ — опциональный Python-слой на SKiDL 2.3.0 (KICAD10). Каталог назван skidl_lab, а не skidl: имя skidl занято пакетом PyPI (import skidl vs import skidl_lab).

KiCad-файлы в projects/ остаются источником истины. SKiDL не перезаписывает .kicad_sch / .kicad_pcb / .kicad_pro. Нетлисты только в skidl_lab/generated/.

MCP: list_skidl_blocks, run_skidl_erc, export_skidl_netlist (отказ, если путь в projects/ или расширение .kicad_sch).

uv run kicad-ai skidl-erc led_indicator
uv run kicad-ai skidl-erc rail_12v_5v

13. Visualization

Картинки строятся из .kicad_sch / .kicad_pcb через kicad-cli, не через AI/Blender/скриншот.

uv run python scripts/render_project.py projects\examples\mcp-test
uv run kicad-ai render-schematic projects\examples\mcp-test
uv run kicad-ai render-pcb projects\examples\mcp-test
uv run kicad-ai render-3d projects\examples\mcp-test

Выход (gitignore): renders/<project>/schematic|pcb|3d/ и renders/render_report.json.

Темы light / dark (dark — presentation invert чёрной туши, геометрия та же). Виды схемы: full и имена из render.yaml (power, indicator, …) — SKIPPED, если на листе нет указанных reference. DPI: preview 150 / docs 300 / large 600. Кадрирование SVG по bounding box + render.margin в миллиметрах (по умолчанию 15, чтобы не резать labels и не оставлять пустой лист).

Авторендер после validation выключен (automation.render_after_validation: false). Устаревший PNG не показывается: *.meta.json хранит source_hash, при изменении схемы рендер пересобирается.

Нет .kicad_pcb — PCB/3D не симулируются. 3D-модели отсутствуют → WARNING, пайплайн продолжается.

14. Troubleshooting

См. docs/troubleshooting.md. Логи: logs/kicad-ai-YYYYMMDD.log (каждая строка начинается с времени). Traceback не скрывается.

15. Example prompts for LLM

1. Создай проект projects/user/pump-controller с входом 12V, предохранителем и DC-DC 5V.

2. Прочитай projects/examples/mcp-test и перечисли компоненты и цепи.

3. Добавь в mcp-test конденсатор 100nF на выход 5V, сохрани backup и покажи connectivity.

4. Найди в библиотеках KiCad символ предохранителя, не создавай новый.

5. Соедини выход U1 с net VOUT_5V через label, не считая пересечение проводов соединением.

6. Прогони validate_project по текущей схеме, объясни ERC и статус DRC (PASS/FAIL/SKIPPED).

7. Сгенерируй BOM CSV для mcp-test.

8. Добавь защиту от обратной полярности (диод) на вход 12V, не меняя существующие reference.

9. Покажи dangling pins и неподключённые power pins.

10. Сделай backup mcp-test, затем откати последнее изменение.

11. Прогони SKiDL ERC для блока led_indicator; не пиши из SKiDL в projects/.

12. Плату проекта не генерируй через MCP. Для mcp-test тестовый .kicad_pcb уже есть; для своих плат — KiCad GUI и Update PCB from Schematic.

13. Покажи схему mcp-test (render_schematic), не генерируй картинку нейросетью.

14. Покажи плату mcp-test в 2D и 3D (render_pcb, render_pcb_3d). Если у проекта нет .kicad_pcb — SKIPPED, без фейковой картинки.

Команды Windows:

uv sync
uv run doctor
uv run start-mcp
uv run pytest -v
uv run kicad-ai example
uv run kicad-ai validate projects\examples\mcp-test
uv run kicad-ai skidl-erc led_indicator
uv run python scripts/render_project.py projects\examples\mcp-test
uv run kicad-ai open projects\examples\mcp-test\mcp-test.kicad_pro