symbolic

An MCP server that generates KiCad 10 schematic symbols from a datasheet, with consistent pin grouping (power top, ground bottom, related signals grouped left/right) and KLC-compliant layout. Also includes a parametric IPC-7351B footprint and 3D-model generator for parts with no matching official footprint.

The server does the mechanical work: fetching a datasheet, enforcing a closed pin-classification taxonomy, deterministic layout math, IPC-7351B land-pattern and parametric STEP model math, writing .kicad_sym/.kicad_mod/.step files, and rendering previews for human review. Reading the datasheet and proposing what each pin does and what the package dimensions are, including finding the datasheet URL by part number via web search, is left to whichever AI client drives the server (e.g. Claude Code). See PLAN.md for the design rationale and the closed pin-group vocabulary in .agents/skills/generate-symbol/references/pin-taxonomy.md.

Requirements

• Python 3.12+
• uv
• KiCad 10 installed, specifically kicad-cli on your PATH. Used to render preview SVGs and to validate generated symbols against the real KiCad parser.

Setup

uv sync

This creates .venv/ and installs both runtime and dev dependencies from uv.lock.

Running the server

The server speaks standard MCP over stdio. It's meant to be launched by an MCP client, not run standalone in a terminal you type into.

uv run symbolic

Connecting it to any MCP client

The server works with any harness that supports MCP. It speaks plain stdio MCP and uses the standard mcpServers config format. A project-level .mcp.json is included; Claude Code, Codex, and Cline pick it up directly.

{
  "mcpServers": {
    "symbolic": {
      "command": "uv",
      "args": ["--directory", "/absolute/path/to/symbolic", "run", "symbolic"]
    }
  }
}

No path is needed: uv finds pyproject.toml by walking up from its working directory, and clients that install a project-level .mcp.json spawn the server from the project root. If your harness spawns stdio servers from an arbitrary cwd, add "--directory", "/absolute/path/to/symbolic" before "run" (a per-machine edit, since the config format has no path variables). Harnesses that read a different config path (Cursor, VS Code, Claude Desktop's claude_desktop_config.json, ...) take the same JSON snippet there.

Note: pi has no built-in MCP client. It picks up the skill below from .agents/skills/, but driving the tools requires an MCP extension.

Skills for any harness

The generate-symbol skill lives in .agents/skills/ (the standard Agent Skills location, discovered by pi, Codex, and other spec-compliant harnesses) and is symlinked from .claude/skills/ for Claude Code. One source of truth for every harness.

Tools

Tool	Purpose
get_pin_taxonomy	Returns the closed pin functional-group taxonomy to classify pins against
fetch_datasheet	Fetches raw datasheet text (PDF or HTML) from a URL
validate_pin_classification	Validates AI-proposed pin classifications against the taxonomy
layout_symbol	Deterministic KLC-based pin placement for a validated pin list
find_footprint	Matches a package hint against KiCad's own local footprint libraries, ranked candidates only, never auto-picks
generate_footprint	Generates an IPC-7351B land pattern (pads + courtyard) from a datasheet package spec, for packages with no confident find_footprint match
render_footprint_preview	Renders the generated land pattern to SVG plus a pad table for human review
write_kicad_sym	Writes/appends the generated symbol to a .kicad_sym library file
write_kicad_footprint	Writes the approved footprint as a .kicad_mod into a .pretty dir plus its generic parametric 3D model as .step
render_preview	Renders the symbol to SVG plus a plain-text pin table for human review

Typical flow: AI finds a datasheet URL (e.g. via its own web search) → fetch_datasheet → (AI reads it, proposes pins) → validate_pin_classification → layout_symbol → find_footprint → render_preview (review both together) → write_kicad_sym.

When find_footprint comes up empty (or the user wants a footprint regardless), the AI reads the datasheet's mechanical-drawing section and proposes a package spec → generate_footprint → render_footprint_preview (same review gate) → write_kicad_footprint. Generated footprints reference their 3D model through the ${SYMBOLIC_3DMODEL_DIR} KiCad path variable (set it once in Preferences → Configure Paths, or pass a custom variable name to write_kicad_footprint).

Using generated footprints in other EDA tools

The output is KiCad-native, but it imports elsewhere:

• Altium Designer: the Import Wizard (File » Import Wizard, KiCad Design Files type) accepts .kicad_mod files directly and converts them to .PcbLib. The companion .step model imports natively (Place → 3D Body, or the component's 3D-model properties). This is the practical path until the planned direct .PcbLib writer (PLAN.md, "Altium support") exists.
• Other tools: any EDA that reads KiCad footprints or STEP works the same way. The STEP model is format-neutral, and the land-pattern IR (package_spec.py/ipc7351.py) is EDA-neutral, so a direct writer for another tool needs a new serializer, not new math.

See the generate-symbol skill for the step-by-step workflow an AI client should follow through these tools (available to Claude Code via the .claude/skills/ symlink described above).

Development

uv run pytest                      # full test suite
uv run pytest tests/test_layout.py # a single test file
uv run mypy                        # strict type checking
uv run ruff check .                # lint

Tests that shell out to real kicad-cli (symbol rendering/validation) are skipped automatically if it isn't on PATH. Generated STEP models are validated in tests by round-tripping through OCCT (the cadquery dev dependency, the same STEP kernel KiCad uses for import). The CAD stack is a test-only dependency, never a server runtime one.

Project status

KiCad symbol generation, footprint matching, and parametric footprint/3D-model generation. No .step sourcing from the web, no direct Altium binary writing (import via Altium's KiCad Import Wizard instead), no standalone CLI. See PLAN.md's "Deferred" section for what's intentionally not here yet.