acp-mcp-agent

Обзор

MCP-сервер, который позволяет LLM-агенту управлять ANSYS Composite Pre [ACP(Pre)] — читать пакет слоёв, изменять углы укладки волокон и количество слоёв, проверять технологические правила и экспортировать расчётную модель и определения композита.

Он общается с ACP двумя способами, и разница важна:

agent ─┬─ acp_*      ──► PyACP ──► acp_grpcserver.exe   headless, batch / optimisation
       └─ acp_gui_*  ──► TCP 47800 ──► ACP-Pre GUI      live, visible on screen

PyACP запускает собственную headless-сессию ACP и не может подключиться к уже запущенному окну ACP-Pre. Поэтому существует второй путь: небольшой сокет-слушатель, работающий внутри встроенного Python в GUI, который выполняет правки модели в главном потоке wx. Углы меняются, и вьюпорт перерисовывается у вас на глазах.

Эти две сессии независимы. acp_gui_* редактирует модель, открытую в GUI; acp_* редактирует headless-модель. Выберите одну на задачу и оставайтесь в ней.

Область охвата — верхняя половина цикла работы с композитами. Решение и постобработка остаются там, где они уже работают:

acp-mcp-agent (lay-up) ──► analysis model ──► Mechanical (BC / mesh / solve)
                       ──► composite defs ──► PyDPF-Composites

Related MCP server: ansys-aedt-mcp

Живое демо

Требования

ANSYS — не pip-пакет. ansys-acp-core запускает gRPC-сервер ACP из локальной установки ANSYS; без неё здесь ничего не работает.

Мост для GUI не требует установки: он работает внутри собственного встроенного Python ACP-Pre (3.10 в протестированной 2026 R1) и использует только стандартную библиотеку плюс wx, которые ACP-Pre уже предоставляет.

Пути

Ничто в этом репозитории не содержит машинно-зависимых путей, вкомпилированных в код. Одна переменная окружения хранит расположение:

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

Структура репозитория

acp_mcp.py              the MCP server - 15 tools, stdio transport
acp_gui_bridge.py       socket listener that runs INSIDE ACP-Pre
acp_gui_autoload.py     tiny loader, embedded in a model for a persistent bridge
install_autoload.py     embeds the loader in the open model, one call
mcp_config.example.json client registration template
requirements.txt
probes/
  00_probe_pyacp.py     stage 1: what this PyACP install actually exposes
  gui_probe.py          GUI console API exploration
  gui_probe2.py         deeper GUI console API dump
docs/
  pyacp_api_report.txt  reference probe output (yours lands in probes/)
  gui_probe2_out.txt    reference GUI console dump, 2026 R1
  acp-scripting-notes.md   undocumented ACP behaviour worth knowing

Настройка с нуля

1. Установите Python-часть

git clone https://github.com/aalperakiss/acp-mcp-agent.git
cd acp-mcp-agent
pip install -r requirements.txt

Доставлено в виде zip-архива, а не репозитория? Распакуйте его где угодно, cd в папку и выполните строку pip install — здесь ничего не зависит от git, а пути в этом README относительны к корню папки.

Используйте один интерпретатор и запомните его абсолютный путь — venv, Anaconda, что угодно — но это должен быть именно тот интерпретатор, который вы указали в конфигурации клиента. Сервер, который «не может найти mcp», почти всегда означает второй Python.

2. Проверьте вашу установку ANSYS

python probes\00_probe_pyacp.py

Только проверка сессии: если launch_acp() здесь не сработает, всё остальное не имеет значения. Отчёт попадает в probes\pyacp_api_report.txt; docs\pyacp_api_report.txt — эталон с машины разработки, сохранённый для сравнения. Затем укажите модель:

python probes\00_probe_pyacp.py C:/path/to/your.acph5

PyACP переименовал несколько методов между релизами, поэтому acp_mcp.py разрешает каждую операцию во время вызова из словаря CANDIDATES в начале файла. Сравните отчёт пробы с CANDIDATES, PLY_ANGLE_ATTRS и PLY_COUNT_ATTRS и добавьте недостающие реальные имена — одно место, одна правка.

Нужен .acph5? Откройте ACP-Pre и выберите File → Save As. Наличие открытого ACP-Pre само по себе не помогает PyACP.

3. Зарегистрируйте сервер в вашем клиенте

Конфигурация Claude Desktop находится в %APPDATA%\Claude\claude_desktop_config.json. Вставьте запись acp из mcp_config.example.json внутрь существующего объекта mcpServers, рядом с тем, что уже там есть. Не заменяйте файл. Следите за запятыми и удваивайте каждый обратный слэш (или используйте прямые слэши).

Затем полностью закройте клиент — включая системный трей — и откройте заново. Список инструментов фиксируется при запуске; работающий клиент никогда не увидит новый сервер.

Быстрая проверка без клиента:

npx @modelcontextprotocol/inspector python acp_mcp.py

4. Проверьте headless-часть

Вызывайте по порядку, убеждаясь, что каждый возвращает JSON, а не Error:

1. acp_import_model

2. acp_get_layup

3. acp_set_ply_angles — измените один слой, затем перечитайте пакет

4. acp_check_layup_rules — нарушения на реальной модели — это нормально

5. acp_update_and_export

6. acp_save_for_gui — откройте результат в ACP-Pre и посмотрите глазами

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

5. Запустите живой GUI-мост

Откройте ACP-Pre с моделью, откройте консоль Python и вставьте одну строку:

exec(open('<repo>/acp_gui_bridge.py').read())

Вы должны увидеть:

[acp_gui_bridge] listening on 127.0.0.1:47800

Теперь acp_gui_status от агента возвращает pong: true и имя открытой модели. Оттуда acp_gui_set_ply_angles перерисовывает вьюпорт в реальном времени.

Слушатель живёт в процессе ACP-Pre. Закройте ACP-Pre — и он исчезнет: вставьте строку снова или сделайте его постоянным, как описано ниже.

6. Постоянный мост (необязательно)

Встройте автозагрузчик в модель как объект Script, чтобы ACP-Pre запускал слушатель сам. В консоли ACP-Pre:

import os
os.environ['ACP_BRIDGE_PATH'] = '<repo>/acp_gui_bridge.py'
exec(open('<repo>/install_autoload.py').read())

Затем сохраните модель. Три вещи делают это безопасным, а не безрассудным:

• Загрузчик встроен, мост — нет. Объект Script хранит исходный код как строку, поэтому встраивание всего моста отправило бы слушатель на каждую машину, открывающую файл. Вместо этого загрузчик читает мост с диска; нет файла — нет слушателя, одна напечатанная строка.

• Он идемпотентен. Режим always срабатывает при каждом model.update(), включая обновление, которое сам мост запускает после правки слоя. Защита на sys._acp_bridge не даёт ему повторно привязать порт 47800 во время запроса.

• Он сам получает db. Объекты Script выполняются с пустыми глобалами — нет db, нет model. Загрузчик достаёт пространство имён консоли через __main__.

Скрипты выполняются при обновлении модели, а не при открытии файла, поэтому install_autoload.py запускает одно обновление, чтобы немедленно поднять слушатель. Чтобы удалить его позже, установите model.scripts['acp_agent_bridge'].active = False и сохраните.

Всё же держите отдельную копию общих моделей с включённым агентом. Объект Script невидим при проверке проекта, и коллега, открывающий ваш .acph5, не должен случайно унаследовать сокет-слушатель.

Инструменты

Headless (PyACP)

Сначала проектный вектор, экспорт один раз: инструменты set_* не обновляют и не экспортируют.

Живой GUI (сокет-мост)

Для рутинных правок предпочитайте типизированные инструменты acp_gui_exec; свободный инструмент предназначен для исследования и разовых задач.

acp_gui_add_ply принимает список углов и добавляет по одному слою на запись, в порядке укладки. Материал и ориентированный набор выделения наследуются от существующего слоя (по умолчанию последнего в группе, или copy_from), потому что create_modeling_ply требует ссылки на объекты, которые агент не может удерживать. Группа вообще без слоёв, следовательно, не может быть заполнена отсюда — создайте первый слой в ACP-Pre.

Углы привязываются к 0, ±15, ±30, ±45, ±60, 90 по умолчанию. Отключите привязку явно, когда нужны промежуточные ориентации.

Устранение неполадок

Известные пробелы

• acp_check_layup_rules сводит всё в один стек. Для многорегиональных деталей перед тем, как полагаться на него на реальной геометрии, требуется группировка по OSS.

• Создание слоёв существует только в интерактивном GUI (acp_gui_add_ply). Головные инструменты acp_* по-прежнему только редактируют существующие слои, поэтому модель, управляемая через PyACP, должна изначально создаваться с достаточным запасом слоёв.

• Инструмента удаления слоя пока нет. Деактивируйте слой, задав acp_gui_set_ply_counts равным 0.

• Масса не выводится инструментом экспорта; путь к атрибуту слишком сильно различается между релизами, чтобы его угадывать. Добавьте его, когда ваш отчёт-проба покажет реальный путь.

• Проверено только на одном релизе ANSYS. Механизм CANDIDATES существует потому, что более старые и более новые релизы будут отличаться.

• Тестов нет. Путь верификации — это проба плюс ручная последовательность инструментов из шагов 4 и 5.

• Цикл оптимизации не запущен. Остаются открытыми три решения: вызывает ли оптимизатор ACP напрямую или через MCP, выполняется ли расчёт в пакетном режиме или через Mechanical MCP, и какой набор критериев отказа задаёт ограничение. Заложите бюджет на суррогатную модель — одна оценка — это один полный расчёт, а 200 таких — это минимум рабочий день.

Примечание по безопасности

Мост прослушивает только 127.0.0.1 и не имеет аутентификации. acp_gui_exec выполняет произвольный Python внутри ACP-Pre. Всё, что может достичь этого порта на машине, обладает той же мощью. Не привязывайте его к 0.0.0.0 и не запускайте в общей сессии.

Участие в разработке

Приветствуются issues и pull request'ы, особенно отчёты-пробы с релизов ANSYS, отличных от 2026 R1, — это самый быстрый способ заполнить CANDIDATES. Приложите сгенерированный probes/pyacp_api_report.txt и укажите релиз.

Вклад принимается на условиях Apache License 2.0 (см. раздел 5 лицензии). CLA не требуется.

Лицензия

Apache License 2.0 — см. LICENSE и NOTICE.

ANSYS, ACP, Composite PrepPost, Mechanical и Workbench являются товарными знаками ANSYS, Inc. Этот проект — независимая интеграция и не аффилирован с ANSYS, Inc., не одобрен и не поддерживается ею. Никакое ПО или документация ANSYS здесь не распространяются; требуется лицензированная локальная установка ANSYS.