schematic-mcp

AI-agent-friendly system for building electrical schematics: an MCP server exposes a high-level, semantic API (components, pins, nets) so an LLM never has to touch coordinates, wires, or .kicad_sch internals directly.

AI Agent → MCP / high-level API → semantic schematic model → validation/ERC
    → automatic layout → SVG and/or KiCad schematic

See schematic_mcp_requirements.md for the full spec and SKILL.md for agent rules.

Status

• Stage 1 done: minimal semantic model (Component, Pin, Net, Schematic) with JSON save/load, in schematic/model.py.

• Stage 2 done: KiCad symbol library import backed by SKiDL (schematic/library.py: search_components / get_component_pins / instantiate) and structural validation + basic ERC (schematic/validation.py: validate / run_erc). Tested against real official KiCad symbol libraries vendored in tests/fixtures/kicad-symbols/ (Device, MCU_Espressif, Sensor_Current).

• Stage 3 done: naive auto layout (schematic/layout.py, one row of boxes, no overlap), an SVG renderer (schematic/renderer.py) that draws component boxes with pin numbers/names and net-name labels next to each pin — no drawn wires yet, connectivity is shown via labels (see requirements section 11); and a CLI (cli/main.py: search, validate, render).

• Stage 4 done: MCP server (mcp_server/server.py) exposing the full section 8 tool list — library lookup, schematic lifecycle, connections, layout hints, validation/ERC, SVG output — over stdio. The stateful logic lives in mcp_server/tools.py::SchematicSession (one active schematic per session), framework-free so it's tested directly without an MCP client. set_placement_hint / set_pin_side / group_components store intent on the model already.

• Stage 5 done: auto_layout now honors left_of/right_of placement hints (topological reorder of the row; other relations are still ignored, a real 2D layout is stage 7 territory if needed). New schematic/routing.py draws an actual orthogonal wire between two components when they land as immediate neighbors and it's a 2-endpoint net with pins facing each other — otherwise still a net label, since routing around an intervening box is real routing-algorithm work (deferred). set_pin_side/group_components are still stored-but-unconsumed.

• Stage 6 done: .kicad_sch export (schematic/exporters/kicad.py), reusing SKiDL's own schematic generator rather than hand-rolling a KiCad file writer — it already draws real classical symbols with correct geometry (section 4/19's stated preference). Only works for components sourced from a real library symbol via add_component; raises KicadExportError on a hand-authored/invented component or one that doesn't resolve, rather than silently producing a broken file. examples/esp32_ina226.json can't export (its ESP32/INA226 pins are hand-authored placeholders, not real symbols) — see examples/build_rc_filter.py for a small schematic built entirely from real library parts that does. Needed vendoring power.kicad_sym too (SKiDL's schematic generator loads it unconditionally).

  Also fixed a real bug found while building that RC filter example: ComponentLibrary.instantiate() defaulted reference to the bare library ref_prefix ('R' for every resistor) instead of component_id — so adding a second resistor without an explicit reference= produced a false duplicate_reference ERC error on a perfectly valid schematic.

MVP is now complete end-to-end (search → add → connect → validate/ERC → SVG / KiCad export) via both the CLI and the MCP server. What's left is optional polish: stage 7 (ELK-based 2D layout + general wire routing) is explicitly "only if this isn't good enough" territory in the spec, not committed to.

Development

python3 -m pip install --user --break-system-packages -e ".[dev]"
PYTHONPATH=. python3 -m pytest

# CLI
PYTHONPATH=. python3 -m cli.main search resistor
PYTHONPATH=. python3 -m cli.main validate examples/esp32_ina226.json
PYTHONPATH=. python3 -m cli.main render examples/esp32_ina226.json -o out.svg
PYTHONPATH=. python3 -m cli.main export-kicad examples/rc_filter.json -o out.kicad_sch

# MCP server (stdio)
PYTHONPATH=. python3 -m mcp_server.server