MCP エレクトリック — OpenDSS

OpenDSSDirect.py を介して OpenDSS で中圧/低圧電気ネットワークをモデル化、シミュレーション、検査するための MCP サーバー。

このプロジェクトの目的は、MCP クライアントに高レベルの電気ツール（回路の作成、要素の追加、電力潮流の解決、短絡、事故、単線図の生成）を提供し、OpenDSS インタープリタへの直接的かつ無制限なアクセスを与えないことです。

ChatGPT/MCP による対話に加えて、このプロジェクトはアクティブな回路の技術ビューアとして機能する永続的な HTML ワークスペースを維持できます。HTML には2つ目のチャットボットは含まれず、モデル API も使用しません。ChatGPT は引き続き会話インターフェースであり、OpenDSS は引き続き電気エンジンであり、ワークスペースは状態と結果の構造化されたビューにすぎません。

状態: 教育用/実験用プロジェクトです。専門的な電気調査や、設計、保護協調、アークフラッシュ安全性のために検証されたソフトウェアの代わりにはなりません。

1. インストール

要件: Python 3.10 以上。

git clone https://github.com/NoeCalle/MCP-Electrico.git
cd MCP-Electrico

python -m venv venv

Windows:

venv\Scripts\activate
pip install -r requirements.txt

Linux/macOS:

source venv/bin/activate
pip install -r requirements.txt

クイック確認:

python -c "import opendssdirect; import mcp; import networkx; print('OK')"

Related MCP server: uam-analyst

2. MCP クライアントなしでのテスト

例では server.py の関数を直接インポートします:

python examples/hospital_basico.py
python examples/visualizar_hospital.py
python examples/campus_hospitalario.py
python examples/arc_flash_campus.py
python examples/unifilar_tecnico.py
python examples/workspace_hospital.py

unifilar_tecnico.py は unifilar_tecnico.svg と unifilar_tecnico.html を生成します。workspace_hospital.py は、埋め込まれた単線図、計算状態、モデルデータ、印刷/PDF および SVG ダウンロード用のボタンを備えた永続的な workspace_hospital.html を生成します。

回帰テストスイートを実行するには:

pip install -r requirements-dev.txt
python -m pytest -q

GitHub Actions は pytest を実行し、技術単線図と参照ワークスペースを生成し、各 PR で両方をアーティファクトとして保持します。

3. MCP クライアントへの接続

Windows での Claude Desktop の例:

{
  "mcpServers": {
    "opendss": {
      "command": "C:\\ruta\\MCP-Electrico\\venv\\Scripts\\python.exe",
      "args": ["C:\\ruta\\MCP-Electrico\\server.py"]
    }
  }
}

macOS/Linux では、venv の Python 実行可能ファイルと server.py への絶対パスを使用します。

4. 利用可能なツール

5. 永続的な HTML ワークスペース

ワークスペースはアクティブな回路に安定したパスを設定します。モデルまたはその表現を変更する MCP ツールは、そのファイルを自動的に再生成します。

概念的な例:

configurar_workspace(
    "workspace.html",
    titulo="Hospital — Sistema eléctrico",
    auto_regenerar=True,
)

crear_circuito("hospital", 22.9)
agregar_transformador(...)
agregar_linea(...)
agregar_carga(...)
ejecutar_flujo_potencia()

5.1 状態とリビジョン

ワークスペースは以下を区別します:

• EMPTY: 使用可能なモデルが存在しない;

• MODIFIED: 最後の解決後にモデルが変更された;

• SOLVED: 現在のリビジョンが解決済みリビジョンと一致する;

• ERROR: 関連する電気エラー/非収束が存在する。

model_revision、solved_revision、visual_revision が維持されます。電気的な変更は以前の調査を自動的に無効にします。視覚のみの変更は正しい解決を無効にしません。

各調査は計算されたリビジョンを保持し、valid フラグを公開します。これにより、履歴結果は現在のものとして提示されることなく追跡可能なままになります。

5.2 HTML とエクスポート

初期バージョンには以下が含まれます:

• 埋め込まれた SVG 単線図;

• バス、フィーダー、負荷、損失の概要;

• Datos タブ;

• 埋め込まれ、バージョン管理された JSON スナップショット;

• window.print() と印刷 CSS に基づく 印刷 / PDF ボタン;

• SVG ダウンロード ボタン;

• ファイルの再読み込み ボタン。

HTML は自己完結型であり、リモート依存関係を使用しません。ファイルは自動的に書き換えられますが、すでに開いているローカルタブは新しいバージョンを読み取るために更新する必要があります。ライブ更新のためのローカルサーバー/ウォッチは後のフェーズに残されています。

ガイドは docs/WORKSPACE.md にあり、完全なアーキテクチャ決定は docs/decisions/ADR-0001-workspace-persistente.md にあります。

6. 技術単線図 SVG

可視化は一般的なグラフの美学を避けます。レンダラーは電気モデルを解釈し、対応する場合にのみ物理バーを表示し、デフォルトでは純粋に論理的なバスを折りたたみます。

主な原則:

1. 秩序ある主エネルギー流;

2. 明確に階層化された物理バー;

3. 直交し秩序あるフィーダー;

4. ヘッダーでの保護;

5. 電源、変圧器、配電盤、モーター、ATS、UPS、発電機、接地の一貫したシンボル;

6. OpenDSS 内部名から独立したエンジニアリングラベル;

7. 区別可能な視覚保護: 遮断器、MCCB、ACB、ヒューズ、断路器;

8. クリーンな ingenieria モードと追加情報を含む diagnostico モード;

9. 縦または横の向き;

10. 開いた要素と無電圧バスを視覚的に区別。

例:

agregar_carga(
    "motor_bomba",
    "mcc_01",
    kw=75,
    kvar=30,
    kv=0.48,
    tipo_visual="motor",
)

configurar_alimentador_unifilar(
    "Line.f_critico",
    dispositivos=["ats", "ups"],
    fuente_alterna="Generator.ge_01",
    proteccion="mccb",
    conductor="3x50 mm2 Cu XLPE",
)

ejecutar_flujo_potencia()
generar_diagrama_unifilar("hospital.html", titulo="Hospital — Diagrama unifilar")

パスが .html で終わる場合、関連するベクター .svg も生成されます。完全な視覚仕様は docs/UNIFILAR_TECNICO.md にあります。

ATS と UPS は、現時点では表現上の注釈です。 これらは、OpenDSS が内部電子機器、転送、自立性、または故障寄与をすでにモデル化していると主張することなく、単線図が意図されたアーキテクチャを文書化するために役立ちます。これらの注釈はインピーダンスや電気結果を変更しません。

7. N-1 事故: 一貫した状態

simular_perdida_alimentador() は2つの動作モードを区別します。

restaurar=True の場合、要素が開かれ、OpenDSS が事故を解決し、結果がキャプチャされ、その後元の状態が正確に復元されて再解決されます。

restaurar=False の場合、要素は開いたままになり、回路は検査と可視化のために事故状態で解決されたままになります。

ワークスペースは、対応するモデルリビジョンとともに事故調査を記録します。

8. 重要負荷

critica=True とマークされた負荷はモデルのメタデータとして保持されます。事故中は、各重要負荷について、そのバス、pu 電圧、通電インジケータ、および無電圧の重要負荷のリストが返されます。

本質的に無電圧のバーと通電中のバーを区別するために使用される内部しきい値は、サービス品質の適合基準ではありません。

9. DSS エクスポート

obtener_netlist() は回路をエクスポートし、ディレクトリ、Master.dss、ファイル数、および生成された各 .dss ファイルの内容を返します。

10. アークフラッシュ: 範囲と安全性

estimar_arc_flash_lee() は、学習と桁数の推定のための Lee の簡略化方程式のみを実装します。

IEEE 1584-2018 の完全な経験モデルは実装しておらず、入射エネルギーを PPE カテゴリに変換しません。calcular_arc_flash() は互換性のあるエイリアスとして維持されます。

11. 短絡

dss.Bus.Isc() は実数成分と虚数成分を交互に返します。サーバーは各フェーザの大きさを明示的に計算します:

|I| = sqrt(Re(I)^2 + Im(I)^2)

ワークスペースと統合する場合、FaultStudy は調査として保持され、ビューアを再生成する前に電力潮流ソリューションが復元されます。これにより、永続的な単線図でソリューションモードが混在するのを防ぎます。

12. 発電機と UPS

agregar_generador_respaldo() は、OpenDSS の Generator オブジェクトを使用して発電機セットを表します。パワーエレクトロニクスベースの UPS は、同期発電機と同等のものとして提示されません。

13. アーキテクチャ

MCP-Electrico/
├── server.py
├── mcp_electrico/
│   ├── __init__.py
│   ├── core.py
│   ├── visualization.py
│   ├── visual_state.py
│   ├── visual_symbols.py
│   ├── workspace_state.py
│   └── workspace.py
├── docs/
│   ├── UNIFILAR_TECNICO.md
│   ├── WORKSPACE.md
│   └── decisions/
│       └── ADR-0001-workspace-persistente.md
├── examples/
│   ├── unifilar_tecnico.py
│   └── workspace_hospital.py
├── tests/
├── requirements.txt
└── requirements-dev.txt

• server.py: MCP ツールとオーケストレーション。

• core.py: 電気ロジックと OpenDSS 状態。

• visualization.py: トポロジ解釈、レイアウト、SVG レンダリング。

• visual_symbols.py: シンボルのベクターライブラリ。

• visual_state.py: 計算を変更しない視覚メタデータ。

• workspace_state.py: リビジョン、有効性、スナップショット契約。

• workspace.py: 永続的な HTML のレンダリング/自動生成。

14. 現在の制限事項

• いくつかの要素は正相シーケンスパラメータ R1/X1 を使用します;

• パラメータの出所を備えた技術ケーブルライブラリはまだ存在しません;

• R0/X0 またはインピーダンス行列の詳細なモデリングはありません;

• TCC 曲線や保護協調はありません;

• ATS/UPS は視覚的に文書化できますが、独自の詳細な電気モデルはまだありません;

• LoadShape、PV、Storage、コンデンサ、高調波、年間シミュレーションはありません;

• ワークスペースはプロセス再起動間でプロジェクトを永続化しません;

• 開いているローカル HTML は再生成を読み取るために手動更新が必要です;

• 電圧降下、フロー、短絡、事故の特定ビューはスナップショット v1 上で計画されていますが、まだワークスペースの一部ではありません;

• SVG は技術単線図であり、契約用 CAD 図面や完全な IEC/ANSI 規格ライブラリではありません;

• アークフラッシュは Lee による教育用の推定にすぎません。

ワークスペースの次のステップは、要素選択による視覚的インタラクションを組み込み、その後、このフェーズで定義されたスナップショット契約を壊すことなく、フローと電圧降下のオーバーレイを組み込むことです。