Schematic PDF to JSON

Precision-first conversion of vector PDF circuit schematics into an evidence-preserving SchematicIR JSON document. The project includes a Python conversion engine, command-line interface, MCP server, reusable Codex skill, and validation tools.

This project deliberately prefers missing uncertain content over emitting plausible but incorrect electrical information. A result marked needs_review must not be treated as a verified netlist.

Architecture

1. PDF parsing — extracts native text, vector paths, styles, coordinates, source IDs, and evidence.

2. Primitive recognition — identifies conservative wire, component, pin, junction, label, and network-flag candidates.

3. Connectivity recovery — applies explicit endpoint, T-junction, junction marker, and evidence-backed named-net rules.

4. JSON output — emits validated SchematicIR, unresolved issues, topology checks, and a deterministic hash.

Each conversion preserves all four stages as separate JSON artifacts.

Related MCP server: KiCAD Schematic Manipulation MCP Server

Install

Python 3.11 or newer is required.

python -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install -e ".[test]"

Command line

schematic-pdf inspect "D:\path\drawing.pdf"
schematic-pdf convert "D:\path\drawing.pdf" --output output\artifacts
schematic-pdf validate "D:\path\schematic.final.json"

The conversion output contains:

job-.../
├── layer1/raw.json
├── layer2/semantic.json
├── layer3/connectivity.json
├── layer4/schematic.final.json
└── manifest.json

MCP server

Start the stdio server with:

schematic-pdf-mcp

Available tools:

• inspect_schematic_pdf

• convert_schematic_pdf

• validate_schematic_ir

The server exposes schematic://schema/current and staged artifacts through schematic://jobs/{job_id}/{stage}. Restrict readable local paths with SCHEMATIC_PDF_ALLOWED_ROOTS; set SCHEMATIC_PDF_ARTIFACT_ROOT to control the artifact destination.

Example MCP configuration:

{
  "mcpServers": {
    "schematic-pdf": {
      "command": "schematic-pdf-mcp",
      "env": {
        "SCHEMATIC_PDF_ALLOWED_ROOTS": "D:\\schematics",
        "SCHEMATIC_PDF_ARTIFACT_ROOT": "D:\\schematic-output"
      }
    }
  }
}

Accuracy and validation

The final JSON contains source evidence and explicit issues for unresolved content. Schema validity and topology validity are independent of recognition completeness. Important policies include:

• no inferred connection at a four-way crossing without explicit evidence;

• no invented pin numbers, reference-designator suffixes, or net names;

• ambiguous part-number-like text is omitted and reported for review;

• recognition changes must keep 100% precision on registered real-PDF regression samples.

Run the automated suite:

python -m pytest

Run the EasyEDA-backed precision regression after placing authorized local sample PDFs and truth exports at the paths registered in the script:

python scripts\run_precision_regression.py

For a genuinely unseen PDF, lock the conversion before reading EDA truth:

python scripts\blind_validate_pdf.py lock "Test_PDF_SCH\new.pdf"
python scripts\blind_validate_pdf.py compare `
  "output\blind\job-...\blind-lock.json" `
  "output\accuracy\new.easyeda-ground-truth.json"

Test schematics, EasyEDA truth exports, and generated artifacts are excluded from the repository because they may contain proprietary circuit designs.

Codex skill

The reusable skill is in skill/convert-schematic-pdf. It defines the precision-first workflow, acceptance order, validation policy, MCP contract, and current limitations.

Current limitations

• Native vector PDFs are the primary supported input.

• Raster OCR and raster primitive recognition are not implemented.

• Hidden pin numbers and ambiguous symbol identity remain unresolved.

• Long-distance value/label association is intentionally conservative.

• Human review is still required whenever blocking issues remain.

License

MIT