Agentic AI and End-to-End PCB Understanding

[avivsabilal29]

Agentic AI and End-to-End PCB Understanding

This document describes what KiCAD MCP Server exposes today, what is missing for agents to reason about a PCB from data alone, and a layered roadmap so autonomous or semi-autonomous agents can approach end-to-end comprehension of a design (schematic intent → physical copper → manufacturability → domain-specific checks such as RF).

It is intended for maintainers, contributors, and MCP client authors who want to extend the server or document limitations clearly on GitHub.

---

1. Terminology

Term	Meaning here
Agent	An LLM-driven client (e.g. Cursor, Claude) using MCP tools to read or edit KiCad projects.
End-to-end understanding	The agent can answer questions that depend on logical connectivity, physical geometry, design rules, and cross-domain constraints (signal integrity, RF, thermal, etc.) without manually parsing .kicad_pcb / .kicad_sch text unless the protocol explicitly exposes that.
Data gap	Information required for a correct answer that is not available through MCP tools in a structured form.

---

2. What the project already provides (strengths)

KiCAD MCP Server is strong at the traditional KiCad automation surface:

2.1 Project and lifecycle

• Open/save project, project metadata, board path resolution.
• Optional snapshot / export workflows.

2.2 Schematic (logical design)

• List components, nets, wires, labels.
• Structured netlist (generate_netlist): references, values, footprints, net → (component, pin) membership.
• Editing primitives (add/move components, wires, net labels) and sync schematic ↔ PCB.

2.3 PCB (board-level operations)

• Board extents, layer list, board info.
• Design rules read/write (global / class-level depending on implementation).
• DRC violations listing (with types such as clearance, silk, dangling items).
• Component placement, moves, routing helpers, zones, mounting holes (tool surface exists; exact coverage see TOOL_INVENTORY).

2.4 Libraries and manufacturing

• Footprint/symbol discovery, footprint info, BOM/position/Gerber exports, autorouter DSN/SES, etc.

2.5 Execution backends

• SWIG / headless: script drives pcbnew without UI.
• IPC / KiCad UI: tighter coupling to a running KiCad instance; capabilities and edge cases may differ from SWIG.

These capabilities support workflow automation, documentation, DRC triage, and high-level reasoning about what is on the board and how nets are named and connected in the schematic.

---

3. What is still missing (gaps vs. end-to-end understanding)

The following gaps limit an agent that must rely only on MCP (no ad-hoc file parsing):

3.1 Spatial copper model

Missing capability	Why it matters for agents
Per-net track/arc list with (start, end, width, layer)	Without this, the agent cannot compute lengths, symmetry, or proximity between nets (e.g. differential NFC loop segments).
Per-net via list with stack, drill, position	Return paths, stub analysis, and “dangling via” explanations need geometry.
Pad geometry tied to net + footprint instance	Bridging “U1 pin 5” to where on the board requires pad positions and net codes.

Today, answering “minimum lateral distance between net A and net B on F.Cu” typically requires parsing .kicad_pcb outside MCP or custom scripts.

3.2 Spatial relationships (queries, not just lists)

Missing capability	Example agent question
Minimum clearance between two nets (or net vs. zone)	“Are RED and BLACK always ≥ 0.2 mm metal-to-metal?”
Coupling / overlap summaries	“Does the GND pour intrude between this differential pair?”
Route topology	“Single continuous path vs. branches / stubs on this net.”

3.3 Zone (pour) semantics beyond “add zone”

• Filled polygon boundaries, islands, clearance to foreign nets, and keepout interaction are hard to infer from DRC text alone.
• Agents need either vector summaries or rasterized layer snippets with known scale.

3.4 Schematic ↔ PCB physical graph

• Netlist gives logical pins; the agent still needs a single graph: schematic pin ↔ PCB pad ↔ tracks ↔ vias ↔ zones.
• Without it, “trace this signal from IC to connector” is incomplete.

3.5 Stackup and controlled impedance

• Stackup (dielectric thickness, εr) may live in .kicad_pcb / project settings but is not surfaced as a single MCP response designed for SI tools.
• Impedance / Zo is not a small KiCad API wrapper: it requires models (microstrip, coplanar, etc.) and often external field solvers for accuracy.

3.6 3D / mechanical / thermal

• Exports exist; interpretable 3D collision or thermal resistance models are out of scope unless explicitly added.

3.7 Backend parity and truth source

• SWIG vs IPC may return different subsets or hit different bugs; agents need documented \_backend / capability flags so they know when a tool is authoritative.

---

4. Agentic AI perspective: how an agent should reason end-to-end

Think in layers of representation. Each layer can be implemented as one or more MCP tools returning versioned JSON.

Layer 0 — Session and scope

• Which project/board/schematic is active.
• Which backend (SWIG vs IPC) and whether geometry tools are supported.

Agent use: always establish scope before deep analysis.

Layer 1 — Logical design (already largely available)

• Components, symbols, values, footprints, netlist, ERC if exposed.
• Intent: “What should be connected?”

Agent use: BOM-style questions, connectivity, naming, power domains at a logical level.

Layer 2 — Physical placement

• Footprint positions, rotations, layers, courtyard outlines (optional).
• Intent: “Where are things?”

Agent use: assembly, connector orientation, mechanical clearance to board edge.

Layer 3 — Conductive geometry (major gap today)

• Tracks, arcs, vias, pads with coordinates and widths.
• Intent: “How is copper actually routed?”

Agent use: length matching intuition, stub detection, “show me all copper on net X,” lateral spacing, layer usage.

Layer 4 — Spatial queries (built on Layer 3)

• Min distance between nets, histogram of spacings, parallel run detection.
• Intent: “Are two nets dangerously close over a region?”

Agent use: NFC/critical pairs, creepage-like checks (not a substitute for certified high-voltage rules unless modeled).

Layer 5 — Zones and planes

• Zone definitions + simplified filled boundaries or “coverage ratio” per region.
• Intent: “How solid is the return path?”

Agent use: return path, shielding, thermal spokes, pour intrusion between sensitive traces.

Layer 6 — Design rules and DRC as structured facts

• Rules + violations with stable IDs, net names, and object handles (where possible).
• Intent: “Does the board pass manufacturability checks?”

Agent use: triage, explain violations, suggest fixes (still needs Layer 3 for “why here”).

Layer 7 — Domain adapters (optional, pluggable)

• RF / SI: export stackup + geometry to a calculator or external solver; ingest summarized S-parameters or Zo estimates.
• DFM: export to manufacturer API or gerber-level checks.

Agent use: “Is this NFC loop likely detuned?” — only after Layers 3–5 + domain tool.

End-to-end for an agent means: it can traverse Layer 1 → 7 inside the MCP contract, without smuggling in unpublished side channels—except where you explicitly document an external tool as part of the workflow.

---

5. Roadmap: concrete upgrades (prioritized)

Phase A — Geometry export (highest leverage)

1. get_net_geometry (or list_tracks filtered by net name / code)
   • Returns segments, arcs, width, layer, net, optional UUID.
2. list_vias_for_net / list_pads_for_component with nets and positions.
3. Unit tests on a small demo board committed to the repo.

Phase B — Spatial queries

1. min_clearance_between_nets(net_a, net_b, layers?)
   • Brute-force acceptable for named critical nets; optimize later.
2. Optional: parallel_run_stats for pair analysis (length of co-directional proximity).

Phase C — Zones and pour summaries

1. list_zones with polygon vertices (or bbox + hole count).
2. Optional raster preview (already partially explored elsewhere via board view tools).

Phase D — Physical connectivity graph

1. get_physical_path from (ref, pin) to (ref, pin) or to nearest net segment list.
2. Align naming with generate_netlist output.

Phase E — Stackup and impedance (explicitly “assistant” tier)

1. get_stackup as structured JSON from the board file.
2. Document that Zo is approximate unless integrated with a solver.

Phase F — Agent ergonomics

1. Stable JSON schema + schemaVersion field per tool response.
2. AGENT_PLAYBOOK.md: recommended tool order for “analyze net X,” “compare two nets,” “pre-fab checklist.”

---

6. Context budget and MCP tuning (token-aware design)

Richer MCP data (geometry, large netlists, full DRC dumps) must be paired with mechanisms that keep LLM context and client tool lists sustainable. Without this, token usage and “tool overload” errors grow quickly—not an MCP flaw, but a product design requirement for any bridge.

6.1 Reduce what the client advertises

Mechanism	Purpose
Router / discovery	Do not register every tool at once; agents discover categories or search first, then invoke specific tools (see ROUTER_ARCHITECTURE).
Minimal / “copilot-safe” profiles	Subset of tools + optional omission of resources/prompts for clients with strict limits.
Separate profiles	e.g. “agent” (light) vs “power user” (full) documented in client config.

6.2 Reduce payload per tool call

Mechanism	Purpose
Default = summary, detail = opt-in	e.g. statistics + bbox first; full segment lists only when requested.
Pagination	limit / offset or cursors on large lists (components, nets, tracks).
Mandatory filters	net_name, layer, reference_prefix, or spatial bbox before returning geometry.
detail levels	Enum such as minimal | standard | full on new heavy tools.

6.3 Offload bulk data from the chat transcript

Mechanism	Purpose
Write sidecar files	Large JSON/CSV under the project directory; MCP returns path, size, checksum—the agent reads slices only when needed.
MCP resources	URIs for on-demand reads instead of pasting megabytes into one tool result.

6.4 Client and workflow discipline

• Human-in-the-loop approval for expensive calls in some clients.
• Summarize exploration into a short “design decision” note so long threads do not carry full history forever.

6.5 Design contract for new tools (e.g. get_net_geometry)

When adding high-volume tools, specify from day one:

• safe defaults (max segments, default layer set),
• filters required for unbounded nets,
• optional “stats only” mode (total length, segment count, bounding box) without full polyline dumps.

---

7. Non-goals (be explicit on GitHub)

To avoid scope creep:

• Replacing KiCad’s internal DRC engine.
• Guaranteeing certified high-voltage or emissions compliance from MCP alone.
• Full 3D FEA or EM simulation inside this repository without external engines.

---

8. Summary

Question	Short answer
Is KiCAD MCP “enough” for agents today?	Enough for schematic logic, netlists, many edits, DRC lists, exports, and high-level PCB metadata.
Is it enough for spatial or RF reasoning from MCP data alone?	Not yet; agents must parse board files or use custom scripts unless new tools are added.
What unlocks end-to-end understanding?	Layered geometry + queries + physical graph, then optional domain adapters.
Is that hard?	Phase A–B is moderate for contributors familiar with KiCad’s Python API; accurate RF remains a separate, harder problem.

---

9. Related documents

• TOOL_INVENTORY — current tool surface
• ARCHITECTURE — server layout
• IPC_BACKEND_STATUS — IPC vs SWIG behavior
• ROADMAP — project roadmap (may be merged with Phase A–F above over time)

---

Contributions welcome: if you implement get_net_geometry or similar, link the PR here and update the Tool Inventory.

[mixelpixx]

So I am working on similarly focused stuff. I think that we need to break the tools up into groups (tool boxes) and each toolbox should have an agent / skills to help guide the LLM for proper use. I have been playing with adding both to each toolbox i create. and in one experiment I have our tool context window use down from 15K tokens down to 2k. I will probably start a thread on this over here -- so people can see what I am talking about - https://forum.orchis.ai/

I am also training (trying to) local LLM models to use the tool as well. I am going to start a run this weekend with a Qwen VL model to see if I can create a 'schematic agent' -- i have had good luck with training one on KiCAD usage docs, troubleshooting guides, and my own tool calls to the KiCAD MCP server. A lot of what I have tried has worked, but i am still refining.

[mixelpixx]

@avivsabilal29 here you go:

https://github.com/mixelpixx/Konnect

[avivsabilal29]

thank u sir, i will review and try it. Kudos!!