HYSYS MCP Server

Английский: MCP-сервер (Model Context Protocol), который позволяет Claude Code / Claude Desktop управлять Aspen HYSYS на естественном языке. 51 инструмент для чтения / сеансов / записи / построения технологических схем, ограниченный безопасным режимом (HYSYS_MCP_MODE), который по умолчанию доступен только для чтения. Только Windows (HYSYS COM), проверено на HYSYS V14. Полную документацию см. в разделах на японском ниже.

MCP-сервер (Model Context Protocol) для управления Aspen HYSYS на естественном языке через Claude Code / Claude Desktop.

MCP — это стандартный протокол для безопасного подключения внешних инструментов к ИИ-ассистентам (например, Claude). С помощью этого сервера Claude может читать значения потоков HYSYS и результаты моделирования, а также (только с вашего разрешения) редактировать модель.

Что это?

При работе с HYSYS неэффективно вручную управлять графическим интерфейсом, советуясь с ИИ. Этот сервер управляет HYSYS через COM Automation в Windows и позволяет только с помощью чата с ИИ:

• Просмотр и изменение значений потоков

• Автоматизация тематических исследований

• Мониторинг состояния сходимости в реальном времени

• Построение и редактирование технологической схемы

Версия Aspen Plus (brack101/AspenPlus-MCP-Server) уже существует, но версия HYSYS не была реализована (по состоянию на май 2026 года). Этот проект заполняет этот пробел.

Related MCP server: AspenPlus MCP Server

Возможности

• Чтение: получение потоков/оборудования/профилей колонн/компонентов/пакетов свойств/состояния сходимости, проверка материального баланса

• Управление сеансами: открытие, закрытие, сохранение кейсов, переключение между несколькими кейсами/экземплярами

• Запись (опционально): изменение условий потоков и параметров технологических операций, запуск решателя, настройка спецификаций колонн

• Построение технологической схемы (опционально): создание, подключение и удаление потоков/оборудования

• Безопасный режим: поэтапное управление от «только чтение» до «разрешить запись» с помощью одной переменной окружения

Всего предоставляется 51 инструмент (подробнее см. Предоставляемые инструменты).

Текущее состояние

Реализация и проверка на реальном оборудовании завершены (по состоянию на 2026-05-30).

• Выполнен рефакторинг на основе реестра + реализован шлюз режимов

• Офлайн-тесты: 67 passed / 2 skipped

• Проверены чтение, запись при построении, сквозной MCP и реальная модель на реальном оборудовании (HYSYS V14) (подробнее в Состояние проверки на реальном оборудовании)

О безопасном режиме

⚠️ Если вы хотите использовать безопасно, ничего настраивать не нужно. По умолчанию запускается режим default, ориентированный на чтение, и инструменты, изменяющие модель, не публикуются.

Переменная окружения HYSYS_MCP_MODE переключает «уровень побочных эффектов публикуемых инструментов». Каждый инструмент имеет тег read / session / write и в зависимости от режима исключается из списка (list_tools), а при вызове отклоняется до подключения к HYSYS.

• В режиме default по умолчанию инструменты записи, такие как set_stream / run / построение, не публикуются. Вы можете начать в безопасном состоянии «только просмотр и сохранение».

• Установите HYSYS_MCP_MODE=enhanced только когда вам нужна запись (Включение функций записи).

• Если задано недопустимое значение, запуск произойдет в безопасном режиме readonly.

Обзор архитектуры

┌─────────────────┐         ┌──────────────────────┐         ┌─────────────┐
│  Claude Code    │  MCP    │  HYSYS MCP Server    │   COM   │   HYSYS     │
│  (WSL or Win)   │ stdio   │  (Windows Python)    │  pywin32│  (Windows)  │
└─────────────────┘  <──>   └──────────────────────┘  <──>   └─────────────┘

• MCP-сервер работает на собственном Python для Windows и подключается к COM-объекту HYSYS.Application через pywin32.

• Связь с Claude Code / Claude Desktop осуществляется через stdio (даже если сам Claude Code находится в WSL, сервер вызывает Windows Python).

• Подробнее об архитектуре см. docs/ARCHITECTURE.md.

Установка

Требования

• Windows 10/11

• Aspen HYSYS V12 или новее (проверено на V14)

• Python 3.10+ (нативный Windows. Не работает с Python в WSL)

• pywin32

⚠️ HYSYS доступен только для Windows. Поскольку используется COM Automation, он не работает из Python в Linux/macOS или WSL (сам Claude Code может быть в WSL; только серверу нужен Windows Python).

Установка

# Windows PowerShell
cd path\to\hysys-mcp
python -m venv venv
.\venv\Scripts\Activate.ps1
pip install -e .

Настройка Claude Desktop / Claude Code

Добавьте в %APPDATA%\Claude\claude_desktop_config.json:

{
  "mcpServers": {
    "hysys": {
      "command": "C:\\path\\to\\hysys-mcp\\venv\\Scripts\\python.exe",
      "args": ["-m", "hysys_mcp.server"]
    }
  }
}

• Замените command на абсолютный путь к venv\Scripts\python.exe в вашем клоне.

• Поскольку в этой конфигурации HYSYS_MCP_MODE не указан, запуск произойдет в режиме default (чтение + сохранение) по умолчанию.

Включение функций записи

Чтобы изменить значения потоков, запустить решатель или построить технологическую схему, установите HYSYS_MCP_MODE=enhanced в env. Поскольку все настраивается только переменными окружения на стороне сервера, каждый пользователь может переключать режим в своем конфигурационном файле.

{
  "mcpServers": {
    "hysys": {
      "command": "C:\\path\\to\\hysys-mcp\\venv\\Scripts\\python.exe",
      "args": ["-m", "hysys_mcp.server"],
      "env": { "HYSYS_MCP_MODE": "enhanced" }
    }
  }
}

⚠️ Операции записи могут привести к зависанию HYSYS. Именно поэтому по умолчанию установлен безопасный режим default. Рекомендуется сначала попробовать чтение и переключаться на enhanced только когда возникает необходимость записи. Вы также можете заблокировать отдельные инструменты на стороне Claude Code с помощью permissions.deny (это локальная настройка пользователя и не входит в дистрибутив).

Предоставляемые инструменты

Реализован 51 инструмент. Режим публикации определяется тегом (О безопасном режиме).

Инструменты чтения (21)

hysys_list_streams hysys_get_stream hysys_list_unit_ops hysys_get_status hysys_list_column_specs hysys_get_column_profile hysys_balance_check hysys_get_stream_phys hysys_introspect hysys_list_components hysys_find_streams hysys_find_ops hysys_list_ports и др.

Инструменты сеанса (6)

hysys_open hysys_close hysys_reconnect hysys_list_instances → hysys_switch_instance hysys_set_active_case hysys_save

Инструменты записи (24)

hysys_set_stream hysys_set_unit_op_param hysys_run hysys_reset hysys_case_study hysys_set_column_spec и связанные hysys_column_run hysys_set_adjust_target hysys_call_method hysys_set_property и др.

Инструменты построения технологической схемы

Эквивалентно режиму enhanced (построение) в AspenPlus-MCP (добавлено 2026-05-30). Все имеют тег write, и по умолчанию выполняется пробный прогон с confirm=false (только просмотр выполняемых действий).

Предварительные условия: требуется кейс с определенными компонентами и Fluid Package. В пустом кейсе сам create_stream завершится ошибкой (спецификация HYSYS; AspenPlus-MCP также предполагает существующий кейс с компонентами/свойствами).

disconnect_stream не поддерживается в этой сборке HYSYS V14 COM (поскольку не существует API для очистки точки подключения). При выполнении возвращается supported:false и альтернативные методы (для переподключения используйте connect_stream, для удаления — delete_object, для полного отключения — GUI).

Для редактирования компонентов/реакций/Fluid Package не предусмотрено специальных инструментов из-за больших различий в окружении (доступно через hysys_call_method / hysys_set_property). Если тип или имя порта неизвестны, используйте hysys_find_ops / hysys_list_ports.

Состояние проверки на реальном оборудовании

Проверено на реальном оборудовании с HYSYS V14 2026-05-30 (только основные моменты; подробнее в docs/TODO.md).

• Офлайн: 67 passed / 2 skipped (можно запустить с помощью PYTHONPATH=src pytest и в системном Python WSL. Пропуски связаны с ограничениями среды без mcp/win32)

• Чтение: проверены connect / list_cases / list_streams / list_unit_ops и др. на реальном оборудовании

• Запись при построении: create_stream / create_unit_op / connect_stream / list_ports / delete_object — все успешно на реальном оборудовании, модель не повреждена (ноль остатков)

• Исчерпывающая проверка: охвачены энергетические потоки, типы оборудования mixer / heater / separator (=flashtank) / valve / cooler, подключение портов feed / product / energy

• Сквозной MCP: проверено server.call_tool → шлюз режимов → handler → реальный HYSYS (enhanced=51, default=27, при этом write-инструменты скрыты и отклоняются при вызове)

• Реальная модель: чтение полностью успешно на сходящейся реальной технологической модели (потоки 47 / операции 30); также выполнено create→delete изолированного объекта, модель не повреждена (47→47 / 30→30), Save не выполнялся

Скрипты воспроизведения находятся в scripts/ (live_probe.py / live_build_test.py / live_build_test_full.py / live_mcp_passthrough.py / live_prod_test.py).

Информация для разработчиков

Структура каталогов

src/hysys_mcp/
  registry.py      # ToolSpec(tool+handler+tag) / モードゲート / JSON 正規化 (mcp 非依存)
  server.py        # 薄い adapter: registry → list_tools / call_tool ディスパッチ
  tools/           # ドメイン別ツール定義
    connection.py  streams.py  unit_ops.py  columns.py
    solver.py      logical.py  fluid.py     generic.py
    build.py       # フローシート構築 (create/connect/delete/ports)
  hysys_client.py  # COM 層 (HYSYS.Application 操作。registry 層からは触らない)
tests/             # オフラインテスト (registry / basic)
scripts/           # 実機検証スクリプト
docs/              # ARCHITECTURE.md / TODO.md

server.py — это тонкий слой, делегирующий регистрацию и диспетчеризацию инструментов реестру. Поскольку registry.py не зависит от пакета mcp, его можно импортировать в средах без HYSYS (например, WSL), и модульные тесты уровня реестра выполняются. Конструкция перенесена из разделения компонентов AspenPlus-MCP.

Как добавить инструмент

Просто добавьте одну строку register(...) в tools/<domain>.py (старые громоздкие if/elif упразднены). Если нужна новая операция COM, добавьте метод в hysys_client.py.

Тестирование

# WSL/Linux でも registry 層のテストは回せる
PYTHONPATH=src pytest -q

Для реального тестирования (требующего HYSYS COM) запустите скрипты из scripts/ в виртуальном окружении Python в Windows.

Меры предосторожности

• HYSYS доступен только для Windows — не работает в Python в Linux/macOS/WSL.

• Операции записи могут привести к зависанию HYSYS — начинайте с режима default по умолчанию и переключайтесь на enhanced только при необходимости.

• Инструменты построения предполагают наличие кейса с определенными компонентами и Fluid Package — в пустом кейсе создание завершится ошибкой.

• disconnect_stream не поддерживается в этой сборке V14 COM — альтернативы см. выше.

Справочные материалы

• Aspen Plus MCP Server (brack101) — версия Aspen Plus, справочник по дизайну

• Aspen HYSYS Customization Guide (PDF, зеркало archive.org) — официальный справочник по COM Automation (AspenTech, V7.3). Оригинал распространяется на портале поддержки AspenTech

• Спецификация Model Context Protocol — стандарт MCP

Created: 2026-05-14