schematic-mcp: Instructions file for Codex

AGENTS.md

This file gives coding agents and human contributors the project rules that matter most when changing schematic-mcp.

Project goal

schematic-mcp is a hardware-context server for AI agents. It converts EDA schematics into a deterministic, format-neutral component/pin/net model and exposes that model through MCP.

The project is not trying to become a general-purpose KiCad GUI automation layer or an autorouter. The long-term direction is read-oriented hardware context, cross-EDA adapters, electrical reasoning, and firmware ↔ schematic validation.

Architecture

• src/schematic_mcp/parsers/ — EDA-specific adapters. New formats should terminate in the canonical model rather than leak format-specific behavior into MCP tools.
• src/schematic_mcp/models.py — canonical data structures.
• src/schematic_mcp/graph.py — deterministic graph/query helpers over the canonical model.
• src/schematic_mcp/workspace.py — current loaded schematic and filesystem boundary enforcement.
• src/schematic_mcp/server.py — MCP tools/resources and CLI transport setup.
• examples/ — synthetic or explicitly redistributable fixtures only.
• tests/ — behavior and regression tests.

Read docs/architecture.md before making parser/model changes.

Required development loop

From a clean checkout:

python -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"
pytest
python -m build

On Windows, use the appropriate virtual-environment activation command instead of source.

Every behavior change should add or update tests. Parser bugs should be reduced to the smallest safe fixture that reproduces the issue.

Electrical correctness invariants

1. Never invent connectivity. If the file does not provide enough information to resolve a connection, preserve an unknown state or emit a warning.
2. Do not infer internal IC connectivity. trace_signal follows resolved schematic nets only.
3. Keep parser behavior deterministic. The same file should produce the same canonical model without an LLM call.
4. Preserve ambiguity. Duplicate labels, ambiguous pin names, unsupported constructs, and unresolved hierarchy should be surfaced explicitly rather than silently normalized away.
5. Prefer exact source evidence. When adding future confidence-based adapters such as PDF parsing, attach confidence/source metadata rather than presenting uncertain results as exact net connectivity.