ansa-tcp-bridge（中文使用说明）

一个自托管的 MCP 服务器，把 AI 客户端（WorkBuddy / Claude / Copilot / Cursor …）连到 BETA CAE Systems ANSA 上。它通过 ANSA 原生的 IAPConnection（TCP）协议连到 「listener 模式」的 ANSA（-listenport 9999），把约 49 个 ANSA 前处理操作封装成 MCP 工具；也可以绕过 MCP，直接在 Python 里把任意 ANSA 脚本发到 ANSA 执行。

1. 整体架构

AI 客户端 (WorkBuddy / Claude / …)
        │  MCP (stdio)
        ▼
  ansa-tcp-bridge  (FastMCP，本仓库)
        │  TCP :9999  (ANSA 原生 IAP 协议)
        ▼
  ANSA  (以 -listenport 9999 启动的 listener)

桥本身只是一个很薄的 Python 进程：它从 <ANSA安装目录>/scripts/RemoteControl/ansa/ 导入 ANSA 自带的 AnsaProcessModule.py 来"说"IAP 协议，再把每次工具调用拼成一段 Python 片段发给 ANSA，由 ANSA 自己在它的解释器里执行并返回 dict[str, str]。

Related MCP server: Ansys MCP Server

2. 前置条件

3. 快速开始（三步）

步骤 1 — 启动 ANSA listener

⚠️ 重要：见第 6 节"坑①"，ANSA_SCRIPTS_PATH 必须指向 D 盘真实安装路径， 写错（如写成 C 盘）会导致桥在启动时把导入错误缓存住，后续所有调用都连不上。

REM 方式 A（推荐，不动你正在用的 GUI ANSA）
D:\ansa-tcp-bridge\start_listener_only.bat

REM 方式 B（手动，等价）
"D:\Program Files (x86)\BETA_CAE_Systems\ansa_v25.1.4\ansa64.bat" -nolauncher -listenport 9999 -foregr -b

启动后 ANSA 没有 GUI 窗口（这是对的）。它只会开一个被最小化到任务栏的控制台窗口， 最后一行通常是 Code generation completed.，然后就安静地等命令——这是健康状态，不是卡死，别关它。

确认端口已起：

netstat -an | findstr ":9999"
REM 应看到  TCP  127.0.0.1:9999  LISTENING

步骤 2 — 启动 MCP 桥

D:\ansa-tcp-bridge\run_mcp.bat

run_mcp.bat 内部等价于（注意 ANSA_SCRIPTS_PATH 是 D 盘）：

set "ANSA_SCRIPTS_PATH=D:\Program Files (x86)\BETA_CAE_Systems\ansa_v25.1.4\scripts"
set "ANSA_PORT=9999"
set "PYTHONPATH=D:\ansa-tcp-bridge"
"C:\Users\Admin\.workbuddy\binaries\python\envs\ansa-tcp\Scripts\python.exe" -m mcp_server.server

可用 CLI 参数（mcp_server.server）：

步骤 3 — 在客户端里调用

WorkBuddy 侧把 ansa-tcp 加进 MCP 配置（见第 5 节），然后直接调用 ping_ansa 验证连通性即可。

4. 启动 listener 的三种方式（含注意事项）

可选：给 ansa_listener.bat 传一个模型路径作参数，启动时自动打开 （如 ansa_listener.bat "J:\path\to\model.ansa"）。

停止 listener：taskkill /F /IM ansa_win64.exe

5. WorkBuddy MCP 客户端配置

编辑 C:\Users\Admin\.workbuddy\mcp.json，加入：

{
  "mcpServers": {
    "ansa-tcp": {
      "command": "C:\\Users\\Admin\\.workbuddy\\binaries\\python\\envs\\ansa-tcp\\Scripts\\python.exe",
      "args": ["-m", "mcp_server.server"],
      "env": {
        "PYTHONPATH": "D:\\ansa-tcp-bridge",
        "ANSA_SCRIPTS_PATH": "D:\\Program Files (x86)\\BETA_CAE_Systems\\ansa_v25.1.4\\scripts",
        "ANSA_PORT": "9999"
      }
    }
  }
}

注意：WorkBuddy 客户端不会自动重启已退出的服务进程。若 listener 崩了， 需在客户端里"信任/重连"该连接器，或手动重启 listener 再确认 9999 端口恢复。

6. 两种调用方式

方式 A — 通过 MCP 工具（49 个，见第 7 节）

客户端直接调 ping_ansa / open_model / mesh_shells / apply_connectors 等。 好处是结构化、可被 AI 直接编排；缺点是工具集是固定的子集。

方式 B — 直接 Python 桥（call.py 模式，最强大）

绕过 MCP，自己写一段 Python，用 bridge_client.AnsaBridge 把任意 ANSA 脚本发到 ANSA 执行。这样可以调用 MCP 工具没有覆盖的 API（如 connections.ReadConnections、 connections.RealizeConnections、base.GetEntityCardValues 等），做复杂批量操作。

最小模板（call.py）：

import sys, os
os.environ["ANSA_SCRIPTS_PATH"] = r"D:\Program Files (x86)\BETA_CAE_Systems\ansa_v25.1.4\scripts"
sys.path.insert(0, r"D:\ansa-tcp-bridge")
from mcp_server.bridge_client import AnsaBridge

bridge = AnsaBridge(host="localhost", port=9999)

# 要发给 ANSA 执行的脚本：必须定义 def main(): 并返回一个 dict
script = r'''
def main():
    import ansa
    from ansa import base
    faces = base.CollectEntities(0, None, "FACE", False)
    return {"n_faces": str(len(faces)), "ok": "true"}
'''

ret = bridge.run_script(script)   # 执行
print(ret)

运行：ansa-tcp\Scripts\python.exe call.py

要点：

• 发给 ANSA 的脚本里函数名必须是 main（除非你传 function_name=）， 且必须 return 一个 dict。

• 见下方"坑②"：返回 dict 的值必须是字符串，否则桥会报 unsupported 返回类型。

• 示例批量脚本见 run_midsurface.py（批量抽取中面）。

7. 工具清单（49 个）

会话与文件 I/O（9） ping_ansa open_model new_model save_model save_model_as export_nastran export_lsdyna export_step run_python_script_in_ansa

实体查询与编辑（18） count_entities list_entities get_entity set_entity_fields create_entity delete_entities search_entities_by_name get_bounding_box get_node_coordinates change_element_type create_part create_set add_to_set get_model_summary list_model_includes calc_element_mass calc_shell_area calc_solid_volume

质量检查（9） check_intersections check_penetrations check_free_nodes run_quality_check count_failed_elements check_geometry check_sharp_edges check_rigid_dependencies calc_mesh_quality

网格（5） mesh_shells mesh_volume set_shell_mesh_params delete_mesh run_batch_mesh

连接（3） apply_connectors check_connections list_connectors （点焊 / 螺栓 / 铆接 / 缝焊）

视口可见性（5） show_only show_also hide near neighb

8. 踩坑与排错（实战经验，重点看）

诊断命令速查：

netstat -an | findstr ":9999"     REM 看端口是否 LISTENING
tasklist | findstr "ansa_win64"   REM 看 ANSA 进程是否存活

9. 目录结构

D:\ansa-tcp-bridge\
├── README.md                 # 本文件
├── ansa_listener.bat         # 标准 listener 启动器（会先杀所有 ANSA！）
├── start_listener_only.bat   # 只起 listener，不杀已有 ANSA（推荐）
├── run_mcp.bat               # 启动 MCP 桥
├── run_midsurface.py         # 示例：批量抽取中面脚本
├── pyproject.toml            # 包定义（mcp[cli]>=1.0）
├── mcp_server\
│   ├── server.py             # FastMCP 入口，注册 49 个工具
│   ├── bridge_client.py      # AnsaBridge：IAP 连接 + run_script / run_file
│   ├── ansi_scripts.py       # 生成发给 ANSA 的 Python 片段
│   └── tools\                # 各类工具实现
│       ├── session.py  entities.py  checks.py
│       ├── mesh.py  connections.py  visibility.py
├── output\                   # 运行产物（生成的 .ansa 等）
└── diag_out\                 # 诊断输出

10. 典型工作流示例（本仓库实战）

以"打开模型 → 载入 3mm 网格标准 → 重划网格 → 导入连接 XML → 生成 FE 表示"为例：

1. open_model 打开 initial.ansa；

2. set_shell_mesh_params + mesh_shells 载入 mesh_ftrd_3mm.ansa_mpar / mesh_3mm.ansa_qual 并重划到 3mm；

3. 方式 B（run_python_script_in_ansa 或 call.py）调用 connections.ReadConnections("XML", path) 导入 connections_to_insert.xml；

4. 同样用方式 B 调用 connections.RealizeConnections(...) 生成 FE 表示；

5. 对未成功的连接先修连通性再二次 realize；

6. save_model_as 落盘（注意坑⑦，保存后确认无 .lock 残留）。

提示：ANSA 25 的 FE 点焊模式常为 SpotweldPoint_RBE3-HEXA-RBE3，且 DoNotMove='y' 时投影失败不允许微移，落在部件交界带（缺第二层板 / 引用了不存在的 Part）的连接会 无法生成 FE 表示——这是数据固有边界问题，与重划网格无关。

License

MIT。ANSA 是 BETA CAE Systems International AG 的商业产品；本项目为独立的社区工具， 与 BETA CAE Systems 无关、未获其背书。