schematic-mcp

Hardware-Schaltplankontext für KI-Agenten über MCP.

schematic-mcp ermöglicht es MCP-kompatiblen Agenten, Hardware-Schaltpläne als strukturierte elektrische Daten zu untersuchen, anstatt sie als Screenshots oder lange Textblöcke zu behandeln.

Status: V0.1 / Alpha. Der erste Adapter zielt auf moderne KiCad-.kicad_sch-Dateien ab.

Warum es das gibt

Ein KI-Codieragent, der Firmware schreibt, benötigt oft Antworten wie:

• Welcher ESP32-Pin ist mit SENSOR_OUT verbunden?

• Was ist mit U4.GPIO12 verbunden?

• Welche Geräte teilen sich dieses I2C-Netz?

• Was sind alle Pins und aufgelösten Netze auf dem MCU?

• Stimmt die vom Firmware angenommene GPIO-Zuordnung tatsächlich mit dem Schaltplan überein?

Der Server parst die EDA-Datei deterministisch, erstellt ein kanonisches Komponenten-/Pin-/Netzmodell und stellt dieses Modell über MCP-Tools und -Ressourcen bereit.

Das Designprinzip ist konservativ: Wenn die Konnektivität nicht sicher aufgelöst werden kann, wird eine Warnung ausgegeben, anstatt eine elektrische Verbindung zu erfinden.

Designfokus

schematic-mcp ist bewusst eine dateigetriebene Hardware-Kontextschicht, kein Allzweck-EDA-GUI-Automatisierungsserver. Normale KiCad-Lese-/Abfrage-Workflows erfordern keine laufende KiCad-Anwendung. EDA-spezifische Adapter erzeugen einen kanonischen elektrischen Graphen, während der agentenorientierte MCP-Vertrag formatneutral bleibt.

Das macht das Projekt komplementär zur Editor-/IPC-Automatisierung: Editor-Tools sind wertvoll für interaktive Designänderungen, während sich schematic-mcp auf deterministische Hardware-Fakten konzentriert, die Codieragenten, CI-Systeme und zukünftige Cross-EDA-Adapter konsumieren können. Firmware-↔-Schaltplan-Verifikation ist ein erster konkreter Anwendungsfall.

Siehe docs/project-positioning.md für die Projektgrenzen und die Ökosystem-These.

Related MCP server: mcp-kicad-sch-api

V0.1-Funktionen

• Moderne KiCad-.kicad_sch-S-Expressionsdateien parsen

• Komponenten, Referenzen, Werte und Bibliotheks-IDs lesen

• Bibliotheks-Pin-Geometrie in Schaltplan-Koordinaten auflösen

• Pins nach der aktiven KiCad-Einheit für Symbole mit mehreren Einheiten auswählen

• Konnektivität aus Drähten, Beschriftungen und Verbindungspunkten aufbauen

• Benannte und anonyme Netze auflösen

• Eine Komponente oder einen Pin untersuchen

• Einen Pin zu allen Endpunkten im selben elektrischen Netz verfolgen

• Kompakte MCU-Pin-Zuordnungen erzeugen

• Firmware-Pin-Erwartungen mit Schaltplan-Netzen nach physischer Pin-Nummer oder symbolischem Pin-Namen vergleichen

• Das aktuelle kanonische Modell als MCP-Ressourcen bereitstellen

• Dateisystemzugriff mit SCHEMATIC_MCP_ROOT oder --root einschränken

• Lokal über stdio oder Streamable HTTP ausführen

• Automatisierte Parser-, Graph- und Dateisystemgrenzen-Tests in GitHub Actions

MCP-Tools

Ressourcen:

• schematic://current/summary

• schematic://current/model

Installation von GitHub

Python 3.10+ ist erforderlich. Bis zur ersten Paket-Registry-Veröffentlichung kann der aktuelle main-Zweig direkt von GitHub installiert werden:

python -m pip install "git+https://github.com/vonpanda/schematic-mcp.git"
schematic-mcp --help

Für reproduzierbare Produktionsnutzung sollte ein Release-Tag oder Commit gepinnt werden, anstatt einem ungepinnten Entwicklungszweig zu folgen. Die erste verpackte Veröffentlichung wird in Issue #8 verfolgt.

Installation für die Entwicklung

git clone https://github.com/vonpanda/schematic-mcp.git
cd schematic-mcp
python -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"
pytest

Das Projekt verwendet die stabile v2-Linie des offiziellen MCP-Python-SDKs.

Ausführen

Lokales stdio

schematic-mcp

oder:

python -m schematic_mcp

Sie können lesbare Dateien einschränken, ohne eine Umgebungsvariable zu setzen:

schematic-mcp --root /absolute/path/to/your/hardware-projects

Das enthaltene Beispiel ausprobieren

Das Repository enthält einen kleinen synthetischen KiCad-Schaltplan, der für Demos und Tests sicher ist:

schematic-mcp --root "$PWD/examples"

Dann kann ein MCP-kompatibler Client aufrufen:

open_schematic("minimal.kicad_sch")
schematic_summary()
list_components()
trace_signal("U1", "1")

Das Beispiel sollte U1.1 auf SENSOR_OUT auflösen und U2.1 als weiteren Endpunkt zeigen. Siehe examples/README.md.

Firmware-↔-Schaltplan-Validierungsdemo

Ein zweites synthetisches Beispiel demonstriert einen Hardwarefehler, den ein Codieragent allein aus dem Quellcode nicht sicher erkennen kann. Die Firmware vertauscht absichtlich die GPIO-Zuweisungen von SENSOR_INT und LED_STATUS, während der Schaltplan die korrekte elektrische Zuordnung beibehält.

Führen Sie die deterministische lokale Demo aus:

python examples/demo_firmware_validation.py

Sie extrahiert den einfachen GPIO-Vertrag aus examples/firmware_with_pin_bug.c, parst examples/esp32_firmware_validation.kicad_sch und meldet zwei Übereinstimmungen und zwei Abweichungen.

Über MCP ist derselbe Vergleich:

open_schematic("esp32_firmware_validation.kicad_sch")
validate_pinmap(
  "U1",
  {
    "GPIO8": "I2C_SDA",
    "GPIO9": "I2C_SCL",
    "GPIO12": "LED_STATUS",
    "GPIO13": "SENSOR_INT"
  }
)

Siehe docs/firmware-validation-demo.md für den vollständigen Agenten-Workflow und das erwartete Ergebnis.

Streamable HTTP

schematic-mcp --transport streamable-http --host 127.0.0.1 --port 8000

Der MCP-Endpunkt ist unter http://127.0.0.1:8000/mcp verfügbar. Der Standard-Host ist nur auf Loopback beschränkt; setzen Sie einen nicht authentifizierten Entwicklungsserver nicht direkt dem öffentlichen Internet aus.

Für den MCP Inspector:

mcp dev src/schematic_mcp/server.py

Beispiel-MCP-Clientkonfiguration

{
  "mcpServers": {
    "schematic": {
      "command": "uv",
      "args": ["--directory", "/absolute/path/to/schematic-mcp", "run", "schematic-mcp"],
      "env": {"SCHEMATIC_MCP_ROOT": "/absolute/path/to/your/hardware-projects"}
    }
  }
}

Dann kann ein Agent aufrufen:

open_schematic("board/main.kicad_sch")
get_component("U4")
get_mcu_pinmap("U4")
trace_signal("U4", "12")

Dateisystemsicherheit

Standardmäßig kann ein lokaler Server Pfade öffnen, die für seinen Prozess zugänglich sind. Für Agenten, denen Sie nicht vollständig vertrauen, setzen Sie SCHEMATIC_MCP_ROOT oder übergeben Sie --root an ein erlaubtes Projektverzeichnis. Versuche, Dateien außerhalb davon zu öffnen, werden abgelehnt, einschließlich Pfade, die außerhalb des erlaubten Stammverzeichnisses aufgelöst werden.

Siehe SECURITY.md für Schwachstellenmeldung und Bereitstellungsrichtlinien.

Aktuelle Einschränkungen

V0.1 ist bewusst klein. Hierarchische Unterseiten werden erkannt, aber noch nicht rekursiv zu einem blattübergreifenden Graphen zusammengeführt. Ungewöhnliche Multi-Unit-/Bibliothekskonstrukte und Drittanbieter-KiCad-Exporte benötigen noch breitere Kompatibilitäts-Fixtures. Bus-Semantik wird noch nicht rekonstruiert. PDF, Altium und EasyEDA sind noch nicht implementiert.

trace_signal folgt nur aufgelöster Netz-Konnektivität; es nimmt nicht an, dass separate Pins innerhalb eines ICs elektrisch verbunden sind. validate_pinmap vergleicht eine explizite erwartete Zuordnung; automatische Extraktion aus beliebigen Firmware-Frameworks ist noch nicht Teil des Kernparsers.

Roadmap

• V0.2 — Hierarchischer KiCad-Projektgraph und reichere Bus-/Netz-Semantik

• V0.3 — PDF-/Vektor-Schaltplanadapter mit Konfidenzmetadaten

• V0.4 — Altium- und EasyEDA-Adapter

• V0.5 — Datenblatt-Kontext und elektrische Regelbegründung

• V0.6 — Framework-spezifische Firmware-Extraktion (ESP-IDF/Arduino/Zephyr) und CI-Pin-Vertragsprüfungen

• Später — PCB, BOM, Gerber und Fertigungskontext

Das langfristige Ziel ist ein herstellerneutraler Hardware-Kontextserver für KI-Agenten.

Mitwirken

Hardware-Ingenieure, Embedded-Entwickler und EDA-Nutzer können am meisten helfen, indem sie minimale Kompatibilitäts-Fixtures, Parser-Edge-Cases, Tests und reale Agenten-Workflows beitragen.

Beginnen Sie mit CONTRIBUTING.md. Codieragenten und Maintainer sollten auch AGENTS.md lesen, um Architektur-Invarianten, Sicherheitsbeschränkungen und den erwarteten Entwicklungszyklus zu verstehen. Bitte tragen Sie niemals proprietäre Kundenschaltpläne bei, es sei denn, Sie haben die ausdrückliche Erlaubnis, sie zu veröffentlichen.

Nützliche Maintainer-/Projektdokumente:

• AGENTS.md — Regeln für Codieragenten und Maintainer

• docs/project-positioning.md — Projektgrenzen und Ökosystemwert

• docs/architecture.md — Parser-/Modell-/MCP-Architektur

• docs/firmware-validation-demo.md — Firmware-↔-Schaltplan-Abweichungsdemo

• examples/README.md — ausführbare synthetische Fixtures

• CHANGELOG.md — Versionshistorie

• SECURITY.md — Sicherheitsrichtlinie

• docs/oss-readiness.md — Checkliste für öffentliche Adoption und OSS-Programme

Lizenz und Namensnennung

Lizenziert unter der Apache License 2.0. Kommerzielle Nutzung, Modifikation und Weiterverbreitung sind unter den Lizenzbedingungen erlaubt. Weiterverbreitungen müssen anwendbare Urheberrechts-, Lizenz- und NOTICE-Informationen gemäß Apache-2.0 bewahren.

Siehe LICENSE und NOTICE.

Ursprünglich entwickelt unter SYANKOR.