schematic-mcp

MCP を介した AI エージェント向けハードウェア回路図コンテキスト。

schematic-mcp を使用すると、MCP 互換エージェントがハードウェア回路図をスクリーンショットや長大なテキストブロックとして扱うのではなく、構造化された電気データとして検査できるようになります。

ステータス: V0.1 / alpha。最初のアダプタは、最新の KiCad .kicad_sch ファイルを対象としています。

存在理由

ファームウェアを記述する AI コーディングエージェントは、次のような回答を必要とすることがよくあります:

• どの ESP32 ピンが SENSOR_OUT に接続されていますか?

• U4.GPIO12 には何が接続されていますか?

• この I2C ネットを共有しているデバイスはどれですか?

• MCU 上のすべてのピンと解決されたネットは何ですか?

• ファームウェアが想定している GPIO マップは、実際に回路図と一致していますか?

サーバーは EDA ファイルを決定論的に解析し、正規のコンポーネント/ピン/ネットモデルを構築し、そのモデルを MCP ツールとリソースを通じて公開します。

設計原則は保守的です。接続性を確信を持って解決できない場合は、電気的接続をでっち上げるのではなく、警告を表示します。

設計の焦点

schematic-mcp は、意図的にファイル駆動型のハードウェアコンテキストレイヤーであり、汎用の EDA GUI 自動化サーバーではありません。通常の KiCad の読み取り/クエリワークフローでは、KiCad アプリケーションを実行する必要はありません。EDA 固有のアダプタは正規の電気グラフを生成しますが、エージェント向けの MCP コントラクトはフォーマットに依存しません。

これにより、このプロジェクトはエディタ/IPC 自動化を補完するものになります。エディタツールは対話的な設計変更に役立ちますが、schematic-mcp は、コーディングエージェント、CI システム、および将来のクロス EDA アダプタが利用できる決定論的なハードウェアファクトに焦点を当てています。ファームウェア ↔ 回路図の検証は、最初の具体的なユースケースです。

プロジェクトの境界とエコシステムの論拠については、docs/project-positioning.md を参照してください。

Related MCP server: mcp-kicad-sch-api

V0.1 の機能

• 最新の KiCad .kicad_sch S 式ファイルを解析します

• コンポーネント、リファレンス、値、ライブラリ ID を読み取ります

• ライブラリのピン形状を回路図座標に解決します

• マルチユニットシンボルのアクティブな KiCad ユニットでピンを選択します

• ワイヤ、ラベル、ジャンクションから接続性を構築します

• 名前付きネットと匿名ネットを解決します

• 1 つのコンポーネントまたはピンを検査します

• ピンを同じ電気ネット上のすべてのエンドポイントにトレースします

• コンパクトな MCU ピンマップを生成します

• 物理ピン番号またはシンボリックピン名で、ファームウェアのピン期待値を回路図ネットと比較します

• 現在の正規モデルを MCP リソースとして公開します

• SCHEMATIC_MCP_ROOT または --root でファイルシステムアクセスを制限します

• stdio または Streamable HTTP 経由でローカルに実行します

• GitHub Actions での自動化されたパーサー、グラフ、ファイルシステム境界テスト

MCP ツール

リソース:

• schematic://current/summary

• schematic://current/model

GitHub からのインストール

Python 3.10 以降が必要です。最初のパッケージレジストリリリースが公開されるまで、現在の main ブランチを GitHub から直接インストールできます:

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

再現可能な本番環境での使用では、ピン留めされていない開発ブランチを追跡するのではなく、リリースタグまたはコミットを固定してください。最初のパッケージリリースは issue #8 で追跡されています。

開発用のインストール

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

このプロジェクトは、公式 MCP Python SDK の安定版 v2 系を使用しています。

実行

ローカル stdio

schematic-mcp

または:

python -m schematic_mcp

環境変数を設定せずに、読み取り可能なファイルを制限できます:

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

同梱のフィクスチャを試す

リポジトリには、デモやテストに安全な小さな合成 KiCad 回路図が含まれています:

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

次に、MCP 互換クライアントは次を呼び出すことができます:

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

この例では、U1.1 が SENSOR_OUT に解決され、U2.1 が別のエンドポイントとして表示されるはずです。examples/README.md を参照してください。

ファームウェア ↔ 回路図検証デモ

2 つ目の合成例は、コーディングエージェントがソースコードだけでは安全に検出できないハードウェアバグを示しています。ファームウェアは意図的に SENSOR_INT と LED_STATUS の GPIO 割り当てを入れ替えていますが、回路図は正しい電気的マッピングを維持しています。

決定論的なローカルデモを実行します:

python examples/demo_firmware_validation.py

examples/firmware_with_pin_bug.c から単純な GPIO コントラクトを抽出し、examples/esp32_firmware_validation.kicad_sch を解析して、2 つの一致と 2 つの不一致を報告します。

MCP を介すると、同じ比較は次のようになります:

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

完全なエージェントワークフローと期待される結果については、docs/firmware-validation-demo.md を参照してください。

Streamable HTTP

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

MCP エンドポイントは http://127.0.0.1:8000/mcp で利用できます。デフォルトのホストはループバックのみです。認証されていない開発サーバーをパブリックインターネットに直接公開しないでください。

MCP Inspector の場合:

mcp dev src/schematic_mcp/server.py

MCP クライアント設定の例

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

次に、エージェントは次を呼び出すことができます:

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

ファイルシステムのセキュリティ

デフォルトでは、ローカルサーバーはそのプロセスがアクセスできるパスを開くことができます。完全には信頼できないエージェントの場合は、SCHEMATIC_MCP_ROOT を設定するか、許可されたプロジェクトディレクトリに --root を渡します。許可されたルートの外側に解決されるパスを含め、その外側のファイルを開こうとすると拒否されます。

脆弱性の報告と展開のガイダンスについては、SECURITY.md を参照してください。

現在の制限事項

V0.1 は意図的に小規模です。階層的な子シートは検出されますが、まだシート間の 1 つのグラフに再帰的にマージされていません。特殊なマルチユニット/ライブラリ構造とサードパーティの KiCad エクスポートには、より広範な互換性フィクスチャが引き続き必要です。バスセマンティクスはまだ再構築されていません。PDF、Altium、EasyEDA はまだ実装されていません。

trace_signal は解決されたネット接続のみを追跡します。IC 内の個別のピンが電気的に接続されているとは想定しません。validate_pinmap は明示的な期待マッピングを比較します。任意のファームウェアフレームワークからの自動抽出は、まだコアパーサーの一部ではありません。

ロードマップ

• V0.2 — 階層的な KiCad プロジェクトグラフと、よりリッチなバス/ネットセマンティクス

• V0.3 — 信頼性メタデータを備えた PDF/ベクター回路図アダプタ

• V0.4 — Altium および EasyEDA アダプタ

• V0.5 — データシートコンテキストと電気ルール推論

• V0.6 — フレームワーク固有のファームウェア抽出 (ESP-IDF/Arduino/Zephyr) と CI ピンコントラクトチェック

• 後日 — PCB、BOM、ガーバー、製造コンテキスト

長期的な目標は、ベンダーに依存しないAI エージェント向けハードウェアコンテキストサーバーです。

コントリビューション

ハードウェアエンジニア、組み込み開発者、EDA ユーザーは、最小限の互換性フィクスチャ、パーサーのエッジケース、テスト、実際のエージェントワークフローを提供することで、最も貢献できます。

CONTRIBUTING.md から始めてください。コーディングエージェントとメンテナは、アーキテクチャの不変条件、安全上の制約、期待される開発ループについて、AGENTS.md もお読みください。明示的な公開許可がない限り、独自の顧客回路図を提供しないでください。

便利なメンテナ/プロジェクトドキュメント:

• AGENTS.md — コーディングエージェントとメンテナのルール

• docs/project-positioning.md — プロジェクトの境界とエコシステムの価値

• docs/architecture.md — パーサー/モデル/MCP アーキテクチャ

• docs/firmware-validation-demo.md — ファームウェア ↔ 回路図の不一致デモ

• examples/README.md — 実行可能な合成フィクスチャ

• CHANGELOG.md — リリース履歴

• SECURITY.md — セキュリティポリシー

• docs/oss-readiness.md — パブリック採用と OSS プログラムの準備状況チェックリスト

ライセンスと帰属

Apache License 2.0 の下でライセンスされています。商用利用、変更、再配布は、ライセンス条件に基づいて許可されています。再配布の際は、Apache-2.0 で要求される該当する著作権、ライセンス、NOTICE 情報を保持する必要があります。

LICENSE と NOTICE を参照してください。

元々は SYANKOR の下で開発されました。