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 会启动自己的无头 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. 验证无头部分

按顺序调用，确认每个都返回 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 不应意外继承套接字监听器。

工具

无头（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， 也不要在共享会话上运行它。

贡献

欢迎提交 Issue 和拉取请求，尤其是来自 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 安装。