MCP Электрический — OpenDSS

MCP-сервер для моделирования, симуляции и инспекции электрических сетей СН/НН с помощью OpenDSS через OpenDSSDirect.py.

Цель проекта — предоставить MCP-клиенту высокоуровневые электрические инструменты — создание цепей, добавление элементов, решение потока мощности, короткое замыкание, аварийные режимы и генерацию однолинейных схем — без предоставления прямого и неограниченного доступа к интерпретатору OpenDSS.

Помимо диалога через ChatGPT/MCP, проект может поддерживать постоянное HTML-рабочее пространство, которое выступает в качестве технического просмотрщика активной цепи. HTML не содержит второго чат-бота и не использует 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 генерирует постоянный workspace_hospital.html со встроенной однолинейной схемой, состоянием расчёта, данными модели и кнопками для печати/PDF и загрузки SVG.

Для запуска набора регрессионных тестов:

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

GitHub Actions запускает pytest, генерирует техническую однолинейную схему и эталонное рабочее пространство и сохраняет оба как артефакты в каждом PR.

3. Подключение к MCP-клиенту

Пример для Claude Desktop в Windows:

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

В macOS/Linux используйте исполняемый файл Python из venv и абсолютный путь к 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;

• сводку по шинам, фидерам, нагрузкам и потерям;

• вкладку Данные;

• встроенный и версионированный JSON-снимок;

• кнопку Печать / PDF, основанную на window.print() и CSS для печати;

• кнопку Скачать SVG;

• кнопку Перезагрузить файл.

HTML самодостаточен и не использует удалённых зависимостей. Файл перезаписывается автоматически, но уже открытая локальная вкладка должна быть обновлена, чтобы прочитать новую версию. Локальный сервер/наблюдатель для обновления в реальном времени остаётся на более поздний этап.

Руководство находится в docs/WORKSPACE.md, а полное архитектурное решение — в docs/decisions/ADR-0001-workspace-persistente.md.

6. Техническая однолинейная схема SVG

Визуализация избегает эстетики общего графа. Рендерер интерпретирует электрическую модель, чтобы показывать физические шины только там, где это уместно, и по умолчанию сворачивает чисто логические шины.

Основные принципы:

1. упорядоченный основной поток энергии;

2. чётко иерархизированные физические шины;

3. ортогональные и упорядоченные фидеры;

4. защита в начале линии;

5. согласованная символика для источника, трансформатора, щита, двигателя, ATS, UPS, генератора и земли;

6. инженерные подписи, независимые от внутреннего имени OpenDSS;

7. различимые визуальные защиты: breaker, 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() различает два режима работы.

С restaurar=True элемент открывается, OpenDSS решает аварию, результаты фиксируются, а затем точно восстанавливается исходное состояние и решение выполняется снова.

С restaurar=False элемент остаётся открытым, и цепь остаётся решённой в аварийном состоянии для инспекции и визуализации.

Рабочее пространство регистрирует исследование аварии вместе с ревизией модели, которой оно соответствует.

8. Критические нагрузки

Нагрузки, помеченные как critica=True, сохраняются как метаданные модели. Во время аварии для каждой критической нагрузки возвращаются её шина, напряжения в о.е., индикатор наличия напряжения и список критических нагрузок без напряжения.

Внутренний порог, используемый для различения практически обесточенной шины от шины с напряжением, не является критерием соответствия качеству обслуживания.

9. Экспорт DSS

obtener_netlist() экспортирует цепь и возвращает каталог, Master.dss, количество файлов и содержимое каждого сгенерированного файла .dss.

10. Arc Flash: область применения и безопасность

estimar_arc_flash_lee() реализует только упрощённое уравнение Ли для обучения и оценки порядка величины.

Не реализует полную эмпирическую модель IEEE 1584-2018 и не преобразует энергию инцидента в категорию СИЗ. calcular_arc_flash() сохраняется как совместимый псевдоним.

11. Короткое замыкание

dss.Bus.Isc() возвращает чередующиеся действительные и мнимые компоненты. Сервер явно вычисляет величину каждого фазора:

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

При интеграции с рабочим пространством FaultStudy сохраняется как исследование, а затем перед регенерацией просмотрщика восстанавливается решение потока мощности. Это предотвращает смешение режимов решения в постоянной однолинейной схеме.

12. Генераторы и UPS

agregar_generador_respaldo() представляет дизель-генератор через объект Generator OpenDSS. 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, накопителей, конденсаторов, гармоник или годового моделирования;

• рабочее пространство не сохраняет проект между перезапусками процесса;

• открытый локальный HTML требует ручного обновления для чтения регенерации;

• специальные представления падения напряжения, потока, КЗ и аварий запланированы на основе снимка v1, но пока не входят в рабочее пространство;

• SVG — это техническая однолинейная схема, а не контрактный CAD-план или полная нормативная библиотека IEC/ANSI;

• Arc Flash — это лишь образовательная оценка по Ли.

Следующим шагом рабочего пространства будет включение визуального взаимодействия с выбором элементов, а затем наложения потока и падения напряжения без нарушения контракта снимка, определённого на этом этапе.