# ANSYS MCP Local Server

**❗本项目目前处于测试阶段**

面向 ANSYS 2024 R2 的本地 stdio MCP 服务，覆盖 Fluent、Mechanical 和
PyAnsys Geometry，并内置 Fluent MCP-to-TUI journal 记录。

## 主要改进

- 所有失败返回 `isError=true`、稳定错误码和恢复建议。
- 每个工具同时返回文本与 `structuredContent`。
- 连接现有 GUI 与 MCP 自行启动的实例采用不同生命周期策略。
- ANSYS 同步调用在线程中执行，并按产品会话串行化。
- Mechanical 对空模型返回分层 readiness，不再把集合越界当作状态。
- 网格方法、载荷方向和单位均进入实际 IronPython 脚本。
- 原始 TUI/IronPython 需要 `confirm_unsafe=true`。
- Fluent journal 只记录成功执行的操作，且每个新会话自动清空历史。
- 提供 Pydantic 输入约束、MCP annotations、输出 schema 和单元测试。

## 安装

建议使用 Python 3.11-3.13：

```powershell
cd D:\build\ansys-mcp
py -3.13 -m venv .venv
.\.venv\Scripts\python.exe -m pip install -e ".[test]"
```

确认 ANSYS 路径：

```powershell
$env:AWP_ROOT242 = "C:\Program Files\ANSYS Inc\v242"
```

注册到 Codex：

```powershell
.\scripts\install_codex.ps1 -InstallSkill
```

注册到 Claude Code：

```powershell
.\scripts\install_claude.ps1 -InstallSkill
```

安装脚本在目标 MCP 或 skill 已存在时会停止，不会自动删除或覆盖。

## 启动与检查

直接启动 stdio 服务：

```powershell
.\.venv\Scripts\python.exe -u .\server.py
```

运行测试：

```powershell
.\.venv\Scripts\python.exe -m pytest
```

## Mechanical GUI 连接

1. 在 Workbench 中双击分析系统的 `Model` 单元并等待模型树加载。
2. 打开 Mechanical 的 Scripting 窗口。
3. 执行 `scripts/mechanical_start_grpc.py`。
4. 使用返回端口调用 `mechanical_launch`。

连接结果中的关键字段为：

```json
{
  "transport_connected": true,
  "scripting_ready": true,
  "project_open": true,
  "model_available": true,
  "analysis_count": 1
}
```

如果只有 transport 为 true，应先打开 Model 单元，而不是继续调用网格或求解工具。

## 生命周期规则

- 无端口调用 `*_launch`：MCP 启动实例，`*_exit` 会关闭它。
- 指定端口连接：MCP 仅附加，`*_exit` 默认只断开本地句柄。
- 只有显式传入 `shutdown_attached=true` 才会关闭附加的 Fluent/Mechanical。
- 已有活动会话时重新连接需要 `replace=true`。

## 新增工具

`mechanical_get_mesh_settings` 只读返回全局网格尺寸、物理与求解器偏好、
自适应尺寸、增长率、曲率以及节点/单元计数等当前版本可读取属性。

## Skill 联动

完整 skill 位于 `skills/ansys-fluent-tui-guide`。服务端映射实现在
`ansys_mcp/tui_mapper.py`，不依赖把 skill Python 文件加入 `sys.path`，因此
skill 文档更新不会破坏 MCP 协议进程。`fluent_get_script` 返回 journal，
`fluent_get_mapping_report` 返回结构化历史。报告中的 `reproducible=false`
或非空 `unmapped_operations` 表示 journal 是 partial，不能宣称完整复现；
当前材料设置和 UDF 加载/挂接会被明确记录为未映射。

## 安全说明

`mechanical_script` 和 `fluent_tui` 可以执行任意产品脚本，属于高风险工具。
高层工具仍可能修改或求解当前模型；执行前应确认连接的是正确实例，并保留工程副本。

远程 Fluent 附加默认禁止。非回环地址必须同时设置 `allow_remote=true`、
`allow_insecure_remote=true` 并提供密码。该路径使用不安全 gRPC，仅应用于可信网络；
优先通过安全隧道映射到本机回环地址。

## 兼容性

依赖范围锁定到本项目验证过的 MCP/PyAnsys 次版本。ANSYS 产品 API 仍会因
安装版本、许可和模块不同而变化；真实产品集成测试需要在对应 ANSYS 环境中运行。