acp-mcp-agent

개요

LLM 에이전트가 ANSYS Composite Pre [ACP(Pre)] 를 구동할 수 있게 해주는 MCP 서버입니다. 적층(lay-up)을 읽고, 섬유 각도와 층 수를 변경하고, 제조 규칙을 확인하고, 해석 모델과 복합재 정의를 내보낼 수 있습니다.

ACP와 두 가지 방식으로 통신하며, 그 차이가 중요합니다:

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

PyACP는 자체 헤드리스 ACP 세션을 시작하며, 실행 중인 ACP-Pre 창에 연결할 수 없습니다. 따라서 두 번째 경로가 존재합니다: GUI 내장 Python에서 실행되는 작은 소켓 리스너가 wx 메인 스레드에서 모델 편집을 실행합니다. 각도가 변경되고 뷰포트가 실시간으로 다시 그려집니다.

두 세션은 독립적입니다. acp_gui_*는 GUI에 열린 모델을 편집하고, acp_*는 헤드리스 모델을 편집합니다. 작업당 하나를 선택하고 그곳에 머무르세요.

범위는 복합재 루프의 상류 절반입니다. 해석 및 후처리는 이미 잘 작동하는 곳에 남아 있습니다:

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는 로컬 ANSYS 설치에서 ACP gRPC 서버를 시작합니다. 설치가 없으면 여기서 아무것도 실행되지 않습니다.

GUI 브리지는 설치가 필요 없습니다. ACP-Pre 자체 내장 Python(테스트된 2026 R1에서 3.10)에서 실행되며, 표준 라이브러리와 ACP-Pre가 이미 제공하는 wx만 사용합니다.

경로

이 저장소의 어떤 것에도 머신별 경로가 컴파일되어 있지 않습니다. 하나의 환경 변수가 위치를 전달합니다:

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를 열고 파일 → 다른 이름으로 저장을 선택하세요. ACP-Pre가 열려 있다고 해서 PyACP에 도움이 되지는 않습니다.

3. 클라이언트에 서버 등록

Claude Desktop 구성은 %APPDATA%\Claude\claude_desktop_config.json에 있습니다. mcp_config.example.json의 acp 항목을 기존 mcpServers 객체 안에 이미 있는 것과 함께 붙여넣으세요. 파일을 교체하지 마세요. 쉼표에 주의하고, 모든 백슬래시를 두 번 쓰거나(또는 슬래시를 사용) 하세요.

그런 다음 클라이언트를 완전히 종료(시스템 트레이 포함)하고 다시 여세요. 도구 목록은 시작 시 고정됩니다. 실행 중인 클라이언트는 새 서버를 절대 볼 수 없습니다.

클라이언트 없이 기본 확인:

npx @modelcontextprotocol/inspector python acp_mcp.py

4. 헤드리스 절반 검증

순서대로 호출하고, 각각 Error: 대신 JSON을 반환하는지 확인하세요:

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를 열 때 실수로 소켓 리스너를 상속받지 않아야 합니다.

도구

헤드리스 (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는 ACP-Pre 내부에서 임의의 Python을 실행합니다. 해당 머신의 포트에 도달할 수 있는 모든 것은 동일한 권한을 가집니다. 0.0.0.0에 바인딩하지 말고, 공유 세션에서 실행하지 마세요.

기여

이슈와 풀 리퀘스트를 환영합니다. 특히 2026 R1 이외의 ANSYS 릴리스에서의 프로브 보고서를 환영합니다 — 그것이 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 설치가 필요합니다.