# ANSA MCP MVP

这是一个最小可用版 ANSA MCP。它采用 GUI bridge + 文件 IPC 的形式，让 MCP Client 通过外部 `ansa-mcp-server` 向 ANSA 内部插件发送 JSON 命令。

当前 MVP 聚焦：

- `ping`
- `check_ansa_connection`
- `execute_script`
- `get_capabilities`
- `get_model_info`
- `geometry_inventory`
- `import_file`
- `list_faces`
- `face_properties`
- `select_faces_by_query`
- `preview_selection`
- `delete_faces`
- `autosave_model`
- `restore_model`
- `save_model_as`
- `check_mesh_quality`
- `export_solver_deck`
- `batch_benchmark_test`
- `read_last_log`

暂不包含求解器运行、META 后处理或浏览器 Viewer。

## 架构

```text
MCP Client
  -> ansa_mcp.server
  -> %USERPROFILE%\.ansa-mcp\commands\cmd_<id>.json
  -> ANSA 内部 ansa_mcp.plugin
  -> %USERPROFILE%\.ansa-mcp\results\<id>.json
  -> MCP Client
```

所有 command/result 文件使用 `.tmp` + `os.replace()` 原子写入。每次调用都会写入独立 run 目录，便于复盘。

## 安装

```powershell
cd /d D:\ansa-mcp
python -m venv .venv
.\.venv\Scripts\python -m pip install -e .
```

如果只想运行基础单元测试，不需要安装 MCP SDK：

```powershell
cd /d D:\ansa-mcp
$env:PYTHONPATH = "D:\ansa-mcp\src"
python -m unittest discover -s tests
```

## 启动 MCP Server

```powershell
cd /d D:\ansa-mcp
$env:ANSA_MCP_HOME = "$env:USERPROFILE\.ansa-mcp"
.\.venv\Scripts\python -m ansa_mcp.server
```

也可以使用安装后的入口：

```powershell
ansa-mcp-server
```

## 在 ANSA 中加载插件

在 ANSA Script Editor 或 Python Console 中执行：

```python
exec(open(r"D:\ansa-mcp\scripts\load_plugin_in_ansa.py").read())
ansa_mcp_loop()
```

`ansa_mcp_loop()` 是阻塞轮询模式。停止方式：

```python
ansa_mcp_stop()
```

或在 `%USERPROFILE%\.ansa-mcp\stop.flag` 创建停止文件。

## ANSA v25.1.0 noGUI 验证方式

本机已验证 ANSA v25.1.0 可以通过 `-exec load_script` 启动插件轮询：

```powershell
$env:ANSA_MCP_HOME = "$env:USERPROFILE\.ansa-mcp"
& "C:\Program Files (x86)\BETA_CAE_Systems\ansa_v25.1.0\ansa64.bat" `
  -exec "load_script:'D:\ansa-mcp\scripts\start_plugin_loop_in_ansa.py'" `
  -nogui
```

上面的命令会阻塞运行，直到创建 `stop.flag`：

```powershell
New-Item -ItemType File -Force -Path "$env:USERPROFILE\.ansa-mcp\stop.flag"
```

外部验证命令：

```powershell
$env:ANSA_MCP_HOME = "$env:USERPROFILE\.ansa-mcp"
$env:PYTHONPATH = "D:\ansa-mcp\src"
D:\miniconda\envs\geo\python.exe -c "from ansa_mcp import server; print(server.tool_check_ansa_connection()); print(server.tool_get_capabilities()); print(server.tool_get_model_info())"
```

已验证环境：

- ANSA: `25.1.0`
- ANSA Python: `3.11.9`
- `current_deck`: `1`

## MCP Client 配置示例

见 [examples/mcp_config.example.json](examples/mcp_config.example.json)。

## 工具说明

### `ping`

检查 MCP server 自身是否运行。

### `check_ansa_connection`

读取 `status.json` 并向 ANSA 插件发送 `ping`。如果 ANSA 插件未运行，会返回明确错误。

### `execute_script`

在 ANSA Python 环境中执行脚本。当前版本主要用于调试和探索。稳定工作流应优先使用高层工具。

### `get_capabilities`

返回插件版本、Python 版本、ANSA API 是否可用、当前 deck 等信息。

### `get_model_info`

返回当前模型摘要。实体类型跨 deck 可能存在差异，失败项会进入 `warnings`。

### `geometry_inventory`

返回更宽的几何/实体清单，用于诊断导入后为什么没有 `FACE`。当前会统计 parts、faces、macros、cons、points、curves、surfaces、volumes、nodes、shells、solids、elements、materials、properties 等。

### `import_file`

打开或导入模型/几何文件。用户给外部路径时，server 会先复制到 `ANSA_MCP_HOME\imports`，再让 ANSA 打开该副本。

### `list_faces`

列出当前 ANSA 模型中的 `FACE` 实体，返回 face id、name、type。用于让 Codex 在删除前先明确可操作对象。

### `face_properties`

返回 `FACE` 的几何选择属性，包括 area、center、bbox、normal、perimeter_count。支持按 `area`、`center_z`、`max_z` 等字段排序，用于自然语言选面前的候选筛选。

### `select_faces_by_query`

基于 `face_properties` 执行常见自然语言式选面，当前支持最大面、最小面、顶面、底面、法向 +Z、法向 -Z、靠近指定点等查询，并返回候选 face id、选择理由和分数。

### `preview_selection`

删除前预览候选 face id 和选择理由。该工具不修改模型，返回 `requires_confirmation=true`，用于让用户确认后再调用 `delete_faces`。

### `delete_faces`

按 face id 删除 `FACE` 实体，并可选保存副本。推荐流程是先 `list_faces`，再按明确 id 删除。

### `autosave_model`

在 `ANSA_MCP_HOME\autosaves` 下保存带时间戳的当前模型副本，用于破坏性操作前回退。

### `restore_model`

重新打开一个已有模型文件，通常用于恢复 `autosave_model` 生成的副本。

### `save_model_as`

把当前 ANSA 模型另存到 `ANSA_MCP_HOME` 下。输出路径会被限制在工作区内。

### `check_mesh_quality`

执行基础质量检查，当前包括实体数量、free nodes 和 intersections。后续可扩展更细的单元质量阈值。

### `export_solver_deck`

导出 solver deck 到 `ANSA_MCP_HOME` 下。当前支持 `NASTRAN`、`ABAQUS`、`LSDYNA`、`ANSYS` 的受控封装。空模型导出可能返回非零 ANSA code，但只要写出非空文件，工具会返回 artifact 并在 `warnings` 中记录 return code。

### `batch_benchmark_test`

批量导入指定目录下的 `.step/.stp/.igs/.iges/.ansa/.bdf/.nas/.inp` 文件，记录导入状态、实体统计、最大面、顶面等诊断结果，并输出 JSON/CSV 报告到 `ANSA_MCP_HOME\reports`。

### `read_last_log`

返回最近一次 run 目录中的 `result.json`。

## 安全边界

- 外部 MCP server 不直接 import `ansa`。
- ANSA API 只在 ANSA 内部插件中调用。
- 输出路径默认限制在 `ANSA_MCP_HOME` 下。
- `execute_script` 默认脚本长度上限为 64 KB。
- 每次调用都会记录 run 目录。

## 下一步

- 验证 ANSA batch/noGUI 启动参数后增加 batch runner。