Circuitarium MCP

Circuitarium MCP

MCP 対応アシスタント向けのローカル電子回路ツールです。CRUMB の セーブファイルと Logisim-evolution プロジェクトをサポートしています。

Circuitarium を使うと、MCP ホストは、静的解析を稼働中のシミュレーターであるかのように装うことなく、回路ファイルを調査できます。CRUMB のネットをたどり、BOM を作成し、電気的ルールチェックを実行し、Logisim プロジェクトを解析できます。また、必要に応じて Logisim-evolution に真理値表の作成やテストベクトルの実行を依頼できます。

リリース 0.3.1 には、22 個のツール、9 個の読み取り専用リソース、4 個のワークフロープロンプトが含まれています。このサーバーは特定のモデルに依存しません。Codex、Claude Code/Desktop、VS Code、LM Studio、Jan、またはその他のローカル MCP ホストがモデルを提供し、stdio 経由で Circuitarium を起動します。Circuitarium 自体には、OpenAI、Anthropic、またはローカルモデルの API キーは不要です。

クイックスタート

必要なもの：

• Node.js 22 以降
• ローカルの stdio サーバーを起動できる MCP クライアント
• クライアントにアクセスさせたい回路ファイルだけを含む専用フォルダー

Windows、macOS、Linux は CI で確認しています。CRUMB の解析と静的な Logisim ツールには、シミュレーターも Java も必要ありません。

ターミナルからローカルの stdio サーバーをインストールして起動するには、次を実行します。

npx -y [email protected]

対話型ターミナルでは、簡潔なステータスパネルが表示されます。通常の使用では、MCP クライアントが同じコマンドを実行し、stdio 経由でサーバーへの接続を維持します。

1. MCP クライアントに Circuitarium を追加する

ほとんどのクライアントで、同じコマンド、引数、環境変数を指定します。

Command: npx
Arguments: -y [email protected]
Environment:
  CIRCUITARIUM_MCP_ROOT=/absolute/path/to/circuit-workspace

初回起動時は、npm がパッケージをダウンロードするため、時間がかかる場合があります。2 回目以降の起動では、通常 npm のキャッシュが使われます。

パスは、モデルが利用できる .cru、.circ、.vec、.txt ファイルを格納する、必要最小限のフォルダーに置き換えてください。ホームディレクトリやドライブのルートを指定しないでください。

コピーして使える設定ファイル：

• Codex
• Claude Code
• VS Code
• LM Studio
• Jan

プラットフォーム別の例やローカルモデルに関する案内は、クライアント設定ガイドをご覧ください。スターターワークスペースの手順では、合成 CRUMB フィクスチャ 1 つと全加算器の Logisim プロジェクトを隔離されたフォルダーにコピーするため、最初のテストでソースチェックアウトの残りのファイルにアクセスする必要はありません。サーバーを追加した後、クライアントを再起動するか再読み込みしてください。

Claude Desktop のユーザーは、代わりに circuitarium-mcp-0.3.1.mcpb を直接ダウンロードし、ローカルバンドルとして開くこともできます。インストーラーでは回路ワークスペースの指定を求められ、Logisim JAR と Java の設定を任意で追加できます。 リリースページ には、チェックサムと対応する npm tarball も含まれています。

2. シミュレーターをインストールせずに回路を試す

接続済みのクライアントに次の内容を貼り付けてください。

Use Circuitarium. Call electronics_capabilities. Create the built-in breadboard-led fixture as demo/first-led.cru without overwriting anything, analyze it, and run crumb_check_design. Explain which findings are static inferences rather than simulation results.

クライアントから、合成ファイルの作成を承認するよう求められる場合があります。このツールは既存のパスへの上書きを拒否します。再度実行する場合は、既存のファイルを分析するか、新しい名前を選んでください。

正常に接続されると、小さな合成ファイルが作成され、ブレッドボードと LED が認識され、2 件の端子未接続の警告が報告されます。このフィクスチャは独自に作成されたもので、安全に再配布できます。CRUMB のアセットではありません。

3. ターミナルからランチャーを確認する

次のコマンドで、サーバーセッションを開かずに公開済みランチャーを確認できます。

npx -y [email protected] --help
npx -y [email protected] --version
npx -y [email protected] doctor --smoke

npx -y [email protected] のみのコマンドを実行して待機状態になったように見える場合、サーバーは想定どおりに動作しています。標準入力で MCP ホストを待機中です。Ctrl+C を押し、ホスト自身にコマンドを起動させてください。

ターミナルデモを見ると、ソースチェックアウトのコマンドランナーが合成フィクスチャを検査し、BOM を作成して、ネットリストをエクスポートする様子を確認できます。公開パッケージでは、上記の MCP サーバー、ヘルプ、バージョン、doctor コマンドが提供されています。

「MCP Inspector」のデモを見ると、独立した MCP クライアントでサーバーを実行する様子を確認できます。または、再現可能な 22 ツールのホスト検証と、そのサニタイズ済みの証拠レポートをご覧ください。

できること

分野	現在の機能
一般的な電子工学	利用可能なバックエンドの検出、移植可能な実験記述の検証、回路に関する主張の検証に必要な証拠の計画
CRUMBLE / CRUMB	Unity 時代の .cru セーブデータの検出、検査、検証、比較、BOM とネットリストの作成、導電性ネットの追跡、対応 IC のピン配置の照会、静的な電気チェックの実行
Logisim-evolution	.circ プロジェクトの検出と検査、意図的に部分的な中立ネットリストのエクスポート、コンポーネント統計、真理値表、テストベクトルの任意実行
モデル間の作業	ワークスペース相対のプロジェクト参照と生バイトの SHA-256 ダイジェストを保持し、別のモデルが同じアーティファクトを読み取っていることを確認可能にする

CRUMBLE（Circuit Representation & Universal Model Bridge for Laboratory Electronics）は、Circuitarium に組み込まれた、CRUMB 専用の非公式な連携機能です。シミュレーターに依存しないツールは、今後のアダプターに CRUMB 固有の前提が持ち込まれないようにします。

現在の機能は、中立的な electronics_* ツール 3 個、crumb_* ツール 13 個、logisim_* ツール 6 個で構成されています。すべてのツール結果では、パッケージのバージョンに関係なく、electronics.mcp/0.2 の結果コントラクトが使用されます。

静的解析と実行時の実行

操作	シミュレーターまたは Java が必要ですか？	確認できる内容
すべての crumb_* ツール	いいえ	保存された Unity 時代の .cru ファイルから推定される事実です。稼働中の CRUMB の動作を示すものではありません
logisim_list_projects、logisim_analyze_design、logisim_export_netlist	いいえ	保存された .circ の構造と、明示的に部分的な中立表現です
logisim_component_stats	Java 21 と、ユーザーが指定した Logisim 4.1.0 の all-JAR	選択したプロジェクトと回路が、制限されたサブプロセス内で読み込まれたことです
logisim_truth_table、logisim_run_test_vector	Java 21 と、ユーザーが指定した Logisim 4.1.0 の all-JAR	厳密に指定されたプロジェクトダイジェストに対する、制限された動作上の証拠です。ライブ GUI セッションではありません
リソースとプロンプト	いいえ	ガイダンスとワークフローテンプレートのみです。プロジェクトの読み取りやシミュレーターの実行は行いません

互換性と正直な制限事項

対象	ステータス	境界
CRUMB 1.3.5、Unity 時代の .cru 形式	実験的サポート	crumb.unity/1.3.5 における、静的かつバージョン固定のファイル解析
Godot 時代の CRUMB 2.x	未サポート	個別のエビデンスプロファイルと、管理された保存ファイルのコーパスが必要です
CRUMB のライブ制御またはシミュレーション	未実装	実行、一時停止、ステップ実行、信号読み取り、GUI ブリッジには対応していません
任意の CRUMB 編集	未実装	公開されている書き込みツールは、5 種類の固定された合成フィクスチャのうち 1 つを作成するだけです
Logisim-evolution 4.1.0 の静的解析	実験的サポート	クリーンルームでの .circ 解析。中立ネットリストの解析は明示的に部分対応です
Logisim-evolution 4.1.0 の実行	オプション	上限付きの単発 JAR サブプロセス。ライブ GUI セッションには対応していません

CRUMB の電気ルールチェックは、推定したネット接続と保存されたコンポーネント値に基づいて動作します。電源の短絡、認識された 1 つの電源の両方のレールに LED が直接接続されている状態、保存値から過剰な消費電力が示唆される抵抗の直接接続、一部の未接続端子や IC 電源ピンを検出できます。直列経路の追跡、極性の証明、一般的な回路動作の計算、実機の認証は行いません。

警告

Circuitarium は実験的な教育用ソフトウェアであり、安全認証ツールではありません。商用電源電圧、バッテリーの充電、医療、自動車、生命の安全、高エネルギー、規制関連の作業において、Circuitarium の出力だけを頼りにしないでください。結果が重要な場合は、信頼できるコンポーネントの資料、適切な測定、有資格のエンジニアによるレビューを利用してください。

ファイル解析はローカルで行われますが、MCP ホストが返されたデータをクラウドモデルに送信する場合があります。埋め込みファームウェアのソースコードはデフォルトで省略され、バイナリ EEPROM の内容が返されることはありませんが、それでも秘密情報のない限定的なワークスペースを使用してください。信頼モデルの詳細については、セキュリティポリシーをお読みください。

オプションの Logisim ランタイム

3 つの静的 Logisim ツールは Java なしで動作します。コンポーネントの統計、真理値表、テストベクトルを有効にするには、次の手順を行います。

1. Java 21 以降をインストールします。
2. 公式の logisim-evolution-4.1.0-all.jarをダウンロードします。
3. JAR のパスを MCP ホストの設定に追加します。

CIRCUITARIUM_LOGISIM_JAR=/absolute/path/to/logisim-evolution-4.1.0-all.jar
CIRCUITARIUM_JAVA=java

java がすでに Java 21 以降を参照している場合、CIRCUITARIUM_JAVA は省略可能です。ヘッドレスの Linux マシンでは、テストベクトルの実行に X11 ディスプレイも必要です。Xvfb で対応できます。

信頼できる JAR のみを使用してください。Circuitarium は自己申告のバージョンが 4.1.0 であることを検証しますが、その応答によってファイルや公開元が認証されるわけではありません。ランタイムツールは、ユーザーごとの Logisim の Java 設定を更新する場合があり、オペレーティングシステムのサンドボックスではありません。

リポジトリには、最初のランタイムテスト用に独自に作成した 全加算器のプロジェクトとベクトルが含まれています。Circuitarium は Logisim-evolution をバンドルしたりダウンロードしたりしません。セットアップ、Linux に関する注意事項、エビデンスレベル、サブプロセスの保護策については、Logisim アダプターガイドを参照してください。

一般的なワークフロー

CRUMB の保存ファイルを確認する

1. electronics_capabilities を呼び出します。
2. パスが不明な場合は crumb_list_projects を呼び出します。プロジェクトには、要求され、文書化されたファイルおよび集計の上限内であればダイジェストが含まれます。それ以外の場合は、省略された理由が結果に記載されます。
3. view: "summary" を指定して crumb_analyze_design を呼び出します。
4. 質問に応じて、crumb_export_netlist、crumb_trace_net、crumb_check_design、crumb_bom のみを使用します。

静的な検出結果は、引き続きファイル形式からの推定です。Circuitarium は、CRUMB が実行中かどうかや、回路がどのように動作するかを監視しません。

Logisim プロジェクトを検証する

1. logisim_list_projects を呼び出し、次に logisim_analyze_design を呼び出します。
2. logisim_export_netlist は部分的な静的証拠として扱い、変換による損失を示すマーカーを確認します。
3. オプションのランタイムが利用可能な場合は、対象の回路を正確に選択し、logisim_truth_table または logisim_run_test_vector を呼び出します。
4. 主張の検証に複数種類の証拠が必要な場合や、残っている不足事項を明示的に列挙する場合は、electronics_plan_verification を使用します。

別のモデルに作業を引き継ぐ

引き継ぎには projectRef、projectDigest、backendId、adapterVersion、compatibilityProfile を含めます。引き継ぎを受けるモデルは、最初の読み取り時に記録されたダイジェストを expectedProjectDigest として渡してください。バイト列が変更されている場合、Circuitarium は古い結論を黙って再利用せず、PROJECT_STATE_CONFLICT を返します。

モデル間引き継ぎの例を参照してください。

ツールリファレンス

全 22 ツール

中立的な電子工学ツール

ツール	目的
electronics_capabilities	呼び出し可能なバックエンド、制限事項、推奨ワークフローを報告します
electronics_validate_experiment	実行したとは主張せず、移植可能な実験の記述を検証します
electronics_plan_verification	回路に関する明示的な主張を検証するための証拠計画を作成します

CRUMBLE ツール

ツール	目的
crumb_component_catalog	バージョン固定された CRUMB コンポーネントカタログを返します
crumb_analyze_design	.cru セーブデータの範囲を限定したセマンティックビューを読み取ります
crumb_compare_designs	いずれも変更せず、ダイジェストで保護された 2 つのセーブデータを比較します
crumb_inspect_design	形式レベルの簡潔なインベントリを返します
crumb_validate_design	XML 構造と既知の不変条件を確認します
crumb_generate_fixture	上書きを行わず、固定された合成フィクスチャを 1 つ作成します
crumb_list_projects	ワークスペース内の .cru ファイルと、範囲を限定したアーティファクトメタデータを検出します
crumb_get_component	1 つのコンポーネントと、オプションで範囲を限定したソースウィンドウを取得します
crumb_bom	認識されたコンポーネントを部品表にまとめます
crumb_ic_reference	バージョン固定された IC パッケージとピンレジストリを照会します
crumb_export_netlist	ジャンパーを統合した、推定に基づく静的ネットをエクスポートします
crumb_trace_net	1 つの端子について、ページ分割された導通経路の証拠を生成します
crumb_check_design	対象範囲を指定して静的な電気ルールチェックを実行します

Logisim-evolution ツール

ツール	目的
logisim_list_projects	ワークスペース内の .circ ファイルを検出します
logisim_analyze_design	プロジェクト、回路、コンポーネント、Pin、Clock、配線の構造を静的に調査します
logisim_export_netlist	明示的に部分的な座標ベースの中立ネットリストをエクスポートします
logisim_component_stats	設定された JAR に回路を読み込ませ、インベントリを作成します
logisim_truth_table	範囲を限定した組み合わせ論理の真理値表を評価します
logisim_run_test_vector	ワークスペース内のベクターを実行し、構造化された失敗情報を返します

9 つのリソースは、機能メタデータ、互換性プロファイル、合成サンプルのメタデータ、電気的レビューとデジタルテストのガイダンス、中立的なコンポーネントプロファイルのスキーマ、およびバージョン固定されたコンポーネントカタログを提供します。ユーザーが呼び出す 4 つのプロンプトは次のとおりです。

• review-circuit-design
• compare-crumb-designs
• verify-logisim-design
• handoff-circuit-project

リソースとプロンプトは、それ自体ではプロジェクトを読み取ったり、シミュレーターを実行したりしません。これらの MCP 機能を公開しないクライアントでも、22 個のツールはすべて利用できます。コントラクトリファレンスには、リソース URI、プロンプト引数、結果エンベロープ、エラー、出力上限、ツールスキーマが正確に記載されています。

貢献

Circuitarium はまだ初期段階にあり、小規模で十分な根拠のある改善が役立ちます。 取り組みやすい内容としては、クライアントのセットアップ修正、合成テスト回路、 出典を明記したコンポーネントプロファイル、パーサーのエッジケース、 条件を管理した互換性の観察結果、対象を絞ったロードマップの作業などがあります。

アダプターや公開コントラクトを変更する前に、 貢献ガイド、 アーキテクチャ、 出典管理ポリシーをお読みください。質問や初期段階の設計案は ディスカッションでお寄せください。 再現可能なバグ、対象を絞った機能リクエスト、条件を管理した相互運用性の 根拠は、課題トラッカーにお寄せください。

git clone https://github.com/Craftiee/circuitarium-mcp.git
cd circuitarium-mcp
npm ci
npm run lint
npm run check

動作の変更には npm run test:coverage、パッケージやランチャーの変更には npm run package:check、Logisim のランタイム変更には npm run logisim:e2e を 使用してください。Logisim の E2E テストには Java 21 と、別途用意した 4.1.0 の all-JAR が必要です。

フィクスチャは小規模な合成データで、独自に作成され、再配布しても問題のないものにしてください。 非公開の回路、ファームウェア、シミュレーターのバイナリ、抽出したアセット、 サードパーティ製の回路設計は提出しないでください。代わりに、最小限の合成データで 再現例を作成してください。脆弱性は公開の課題ではなく、 GitHub の非公開脆弱性報告を通じて報告してください。 すべての貢献者は行動規範に従う必要があります。

ドキュメント

ドキュメント	用途
クライアントのセットアップ	ホスト固有のインストール、サブスクリプション／API、ローカルモデル
CRUMBLE ガイド	現在の CRUMB の対象範囲と根拠プロファイル
Logisim ガイド	JAR のセットアップ、ランタイムの根拠、安全性、Linux に関する注記
MCP コントラクト	正確なツール、リソース、プロンプト、エンベロープ、制限
アーキテクチャ	アダプターの境界とシミュレーターに依存しない設計
出典管理	根拠のカテゴリと再配布のルール
ロードマップ	リリース済みのマイルストーンと計画中の作業
変更履歴	リリース履歴

プライバシーポリシー

Circuitarium は stdio 経由でローカル実行され、テレメトリはなく、メンテナーが管理するサービスに 回路ファイルを送信しません。ただし、選択した MCP ホストやモデルプロバイダーは、 各自の規約に基づいてツールの引数や結果を処理する場合があります。ホストにワークスペースへの アクセスを許可する前に、プライバシーポリシー全文をお読みください。

プロジェクトの状況とライセンス

Circuitarium MCP は実験的なコミュニティソフトウェアであり、 Apache License 2.0のもとで公開されています。バージョン 0.3.1 は npmおよび GitHub リリースで入手でき、 そのメタデータは公式 MCP Registryに掲載されています。 サポートについては、SUPPORT.mdをご覧ください。研究や教育で利用する場合は、 CITATION.cffを使ってこのプロジェクトを引用できます。

Circuitarium MCP、CRUMBLE、Logisim-evolution アダプターは、独立した非公式の相互運用性に関する取り組みです。 CRUMB、Logisim-evolution、またはそれらの開発者とは提携しておらず、承認や後援も受けていません。 このリポジトリには、CRUMB または Logisim-evolution のシミュレーターコード、バイナリ、抽出したアセット、 ロゴ、バンドルされたサードパーティ製の回路設計は含まれていません。製品名および標章は、 それぞれの所有者に帰属します。