kicad-mcp: Instructions file for Claude Code

CLAUDE.md — kicad-mcp project constitution

This file is the durable operating agreement for building kicad-mcp. Read it every session. It is a distilled rulebook; the full spec is in PLAN.md. When the two conflict, PLAN.md wins and you should flag the conflict.

Read first, every session

1. HANDOFF.md — START HERE. The current goal, what's done, and what to do next (making the MCP genuinely usable on real boards). Session-to-session baton.
2. PLAN.md — master execution plan (architecture, pinned stack, repo layout §4, phases §8).
3. docs/rules/hartley-rules.md, docs/rules/philslab-rules.md — the rule catalogs the review engine encodes.
4. docs/rules/CHANGES.md — corrections verified against the source videos; severity and sourcing fixes you MUST honor.

Current status

• Phase: ALL PHASES 0–6 complete and green (2026-07-04). Lint (ruff) + 179 pytest pass (2 GUI tests auto-skip without a GUI; they PASSED against live KiCad 9.0.8). 45 tools + 4 router tools, 4 prompts, 23 review rules across 10 families. Three adversarial multi-agent reviews run (Phase 0/1, Phase 2, Phase 4–6): 6 + 12 + 20 = 38 confirmed findings, ALL fixed. Highlights fixed: path-traversal guard, UTF-8 encoding, span-based plane detection (L-shaped boards), DEC-1 connector FP, R5 abutting-zone tolerance; and Phase 4–6: diff-pair bare-P/N mis-pairing (VIN/VIP false pair + USB_DP/DM miss), atomic schematic write (temp+os.replace — a failed edit now leaves the original byte-identical), C4 cross-segment overlap accumulation, microstrip prop delay 5.8→6.1 ps/mm, TaskStore locked snapshots + atexit shutdown, sqlite URI escaping, router double-wrap unwrap.
  • Phase 0: repo scaffold, pyproject.toml (hatchling, pinned stack), FastMCP bootstrap (kicad_mcp/server.py), config.py (KICAD_MCP_*), backend factory + capability router with graceful degradation (backends/{base,cli,sexpr,ipc,factory}.py), kicad-cli discovery (mac/win/linux + override), path confinement + shell=False subprocess helpers, CI (.github/workflows/ci.yml, 3 OSes × py3.10–3.13), get_server_status diagnostics tool.
  • Phase 1: project discovery/info/create (tools/project.py), S-expr read layer — components (kicad-skip), stackup + board info (sexpdata) — cli wrappers for ERC/DRC (normalized JSON), netlist, BOM, gerbers, drill, STEP, pos, SVG, 3D render, and export_fab_package (gerbers+drill+BOM+CPL zip). 17 tools registered. Nets via cli kicadxml netlist + trace_net.
  • Phase 2 — review engine v1 (kicad_mcp/review_engine/): normalized DesignModel (stackup + copper-layer role inference from zones, footprints/pads with absolute positions, tracks/vias/zones, net classification, geometry helpers), Rule/Finding/registry/report framework, and 11 cited rules across 5 families — stackup (K1/K2/K5/K6), grounding (G1/G2), return_path (R5, geometric trace-over-gap via point-in-polygon), decoupling (DEC-1 proximity), dfm (RTE-2/RTE-3/DFM-4). Tools review_design/review_topic/set_design_context + review_board prompt. 20 tools total. Golden fixtures in tests/fixtures/review/ (generator generate_review_fixtures.py) with must-trigger + must-not-trigger + anti-myth (90° corners → 0 findings) tests. Heuristic rules (G2, DEC-1) softened to WARNING to limit false positives, documented inline.
  • Phase 3 — live editing via IPC (backends/ipc.py, tools/board_edit.py, tools/routing.py): kipy connection mgmt with per-PID socket discovery (each KiCad process serves its own /tmp/kicad/api-<pid>.sock; we probe all and prefer one with an open board), commit() context manager (begin→push, drop on exception = single undo step), move/rotate footprint (rotate must assign via the orientation setter — the getter returns a copy), route_trace (polyline), add_via, route_differential_pair (mitered offset_polyline), add_zone (PolygonWithHoles), refill_zones, save_board. 30 tools total. Verified live against KiCad 9.0.8: moved/rotated R2, routed traces + diff pair, via, GND zone, refill, save → re-parsed the saved file (all edits present) → rendered headless (edits visible). Graceful errors when GUI down (all non-GUI tests still pass headless). NOT yet done (deferred to Phase 6 polish): place NEW footprint from a library via IPC (needs the symbol/footprint definition pipeline), netclass management tools.
  • Phase 4 — review engine v2: +5 families, 23 rules total. transmission (F2 critical-length keyed off set_design_context rise time, F4 intra-pair skew in picoseconds), crosstalk (C4 aggressor-near-diff-pair via segment proximity + 3×H), smps (PWR-3 FB-near-SW), subcircuits (XTL-1, STM-1 NRST=WARNING, STM-2, STM-6, USB-2, MIX-2 — schematic-connectivity via model.schematic from the netlist), connectors (CON-1, ESD-1). Explicit anti-myth test (test_antimyth.py) asserts no rule mentions a myth term. New golden fixtures highspeed_4layer {F2,F4,C4}, smps_4layer {PWR-3}.
  • Phase 5 — schematic edit + libraries: transactional write pipeline in sexpr.py (edit_schematic: flag gate + lock check → mutate → re-parse rollback on corruption → ERC report with delta), set_symbol_property/duplicate_symbol (clone, not lib injection — safer). backends/library.py: ranked symbol/footprint search over installed KiCad libs (exact>prefix>substring), JLCPCB SQLite search (jlcparts schema, actionable error when KICAD_MCP_JLCPCB_DB unset).
  • Phase 6 — advanced + polish: async TaskStore (tasks.py, thread pool) + get_task_status/list_tasks/cleanup_tasks; tool router (tools/router.py, 14 categories, list_tool_categories/get_category_tools/search_tools/execute_tool, completeness enforced by test); review/DRC history (history.py, .kicad-mcp/history.jsonl); Freerouting (backends/freerouting.py, async via task queue); prompts plan_stackup/debug_emi/prepare_fab; docs/architecture.md.
  • Rip-up / delete routing (2026-07-24): added rip_up_nets(nets) and rip_up_footprint(reference) to backends/ipc.py + tools/routing.py. Closes the delete-copper gap: the server could create tracks/vias but never remove them, and move_footprint stranded old copper. rip_up_nets validates names against board.get_nets(), collects get_tracks()+get_vias() on those nets (tracks/vias ONLY — never pads/zones), board.remove_items(victims) inside one commit() (single undo, rollback on error). rip_up_footprint scopes to the part's local pad nets (fanout ≤ 2 footprints), skipping shared GND/power nets so a plane is never torn up (include_shared=True to override). Both use KiCad-9-safe get_tracks()/get_vias() — NOT get_items_by_net/get_connected_items, which are kipy 0.7 / KiCad 10.0.1+ only (verified via versionadded annotations). 8 new fake-board unit tests + 1 requires_kicad_gui route-then-rip-up test. router.py routing category now lists both. 49 tools now.
  • v1.0 release prep + deferred gaps (2026-07-04): closed two gaps — duplicate_footprint (IPC proto-copy of a placed footprint; KiCad 9 IPC has NO library-instantiation API, verified) and get_netclasses (IPC read of netclass constraints), both verified live against KiCad 9.0.8. 47 tools at that point. Release: version → 0.1.0 (pyproject + __init__ + server.json in sync), CHANGELOG.md, docs/example.md (STM32 review→fix→export walkthrough), .github/workflows/release.yml (PyPI Trusted Publishing on tag), server.json (MCP registry manifest), PUBLISHING.md. Built + twine-checked the wheel/sdist and smoke-installed the wheel in a clean venv (version 0.1.0, 47 tools, kicad-mcp console entry point present). NOT published (outward-facing, needs the maintainer's PyPI/registry credentials — see PUBLISHING.md).
• Remaining honest gaps (documented, not blockers): placing a NEW footprint/symbol from a LIBRARY — KiCad 9 IPC exposes no library-instantiation API and there is no schematic IPC at all, so duplicate_footprint/duplicate_symbol clone existing parts instead; DSN export is not available via kicad-cli in KiCad 9 so autoroute_board needs a GUI-exported .dsn; the tool router does not hide routed tools — a deliberate NON-goal (true hiding needs a FastMCP tool-visibility feature and 47 tools is manageable; forcing a dispatch-registry would add fragility for marginal benefit); JLCPCB/Freerouting exercised against a synthetic DB / interface only; cross-OS (uvx on Linux/Windows) only via CI so far, not a live KiCad smoke on those OSes.
• Next action: publish (maintainer runs PUBLISHING.md: tag v0.1.0 → PyPI Trusted Publishing, then mcp-publisher for the registry) and do a live uvx kicad-mcp + KiCad 9 smoke on Linux and Windows. The project is feature-complete against PLAN §8 and meets the §11 v1.0 definition of done.
• Machine note: ~/Library/Preferences/kicad/9.0/kicad_common.json had api.enable_server flipped to true for the live smoke (backup: kicad_common.json.kicad-mcp.bak). Leave enabled for IPC work.
• Smoke test: KICAD_MCP_SEARCH_PATHS=$(pwd)/tests/fixtures ./.venv/bin/python -m kicad_mcp then call get_server_status; or run ./.venv/bin/python -m pytest -q.
• Keep this section current. Update it at the end of every session with the phase reached and what is left.