# ansys-scdmdoc-mcp

![ANSYS SpaceClaim MCP](docs/assets/circular-pattern-hero.png)

用 MCP 更快找到 SpaceClaim 的 Python 建模命令。

## 你是否遇到过这些问题？

在 SpaceClaim 中进行几何建模时，很多操作并不是“知道功能名称”就能直接写出 Python：

- 不知道“几何体命名”“共享拓扑”“圆周阵列”等功能对应哪个命令；
- 除了打开脚本录制器，不知道还有什么方法可以获取可用脚本；
- 官方提供了 CHM 帮助文档，但 CHM 只是汇总了大量 HTML 页面；
- API 文档通常以 C#/.NET 签名为主，类型、命名空间、参数和返回值不容易理解；
- 即使搜到了一个方法，也很难判断它能否组合成真正可运行的 SCDM Python 脚本。

如果不是经验非常丰富的 SpaceClaim 二次开发用户，直接阅读 CHM 往往需要花费大量时间。

## 我们的解决方法：用 MCP 做 SpaceClaim API 助手

MCP（Model Context Protocol，模型上下文协议）是一种让 AI 应用安全调用外部工具和数据源的标准协议。它可以把本地的文档、数据库、代码工具或业务服务，以结构化工具的形式提供给 AI。

在本项目中，MCP 连接的是用户电脑上 ANSYS SpaceClaim/SCDM 安装目录中的官方 API CHM。AI 不需要凭记忆猜命令，而是可以通过 MCP：

1. 搜索官方 SpaceClaim API 文档；
2. 读取对应的类、方法或属性说明；
3. 根据你的建模意图整理相关 API；
4. 返回一段带有证据边界的 SCDM Python 候选代码；
5. 在需要时继续生成有顺序的几何建模步骤。

这样可以把“翻阅大量 CHM 页面”变成“用自然语言快速定位命令”，减少 SpaceClaim 几何建模中的试错时间。

![MCP setup and search flow](docs/assets/setup-flow.svg)

## 两种主要使用方式

### 方式一：直接向 MCP 提问功能对应的命令

当你只知道想实现什么功能，但不知道 SpaceClaim 命令时，可以直接描述目标。

例如：

```text
SpaceClaim 中如何给几何体创建命名选择？
```

```text
SpaceClaim 中如何创建共享拓扑？请给出相关 API 和 Python 候选。
```

```text
先创建一个 0° 的实体，再用圆周阵列每隔 60° 生成共 6 个实体，最后合并，应该使用哪些命令？
```

MCP 会优先检索官方 CHM 中的相关 API，例如：

```text
Pattern.CreateCircular
CircularPatternData
Combine.Merge
```

然后返回命令含义、官方文档页面、参数信息和可进一步验证的 Python 候选。

这种方式适合：

- 查询某个 SpaceClaim 功能对应的 API；
- 了解一个命令需要哪些输入；
- 快速比较多个可能的建模方法；
- 让 AI 帮你把多个 API 组织成建模步骤。

### 方式二：提供完整建模输入，让 AI 按参数复现

如果你已经有明确的建模任务，可以把输入参数、几何约束、参考图片和目标结果一起提供给 AI，让它按照这些信息生成复现脚本。

建议提供：

- 几何尺寸和单位；
- 点、线、面、轴、坐标系等基准信息；
- 阵列数量、角度、间距和旋转方向；
- 拉伸、倒角、圆角、布尔运算等操作顺序；
- 命名选择、共享拓扑或装配关系要求；
- 输入图片、草图、截图或目标几何示意图；
- 最终验收标准，例如实体数量、角度、尺寸和输出文件。

例如：

```text
请根据下面的参数和图片复现一个空天飞机外形：

- 单位：mm
- 机身长度：1200
- 翼展：900
- 左右结构对称
- 发动机舱沿机身轴线布置
- 需要创建命名选择：Fuselage、LeftWing、RightWing、Engine
- 最后检查实体数量和命名是否正确
```

这种方式适合：

- 根据图片或已有设计复现几何体；
- 生成参数化建模脚本；
- 把复杂建模任务拆分成可验证的阶段；
- 对已有 SpaceClaim 脚本进行补全、重构或排错。

## 这个 MCP 提供什么工具？

| 工具 | 用途 |
| --- | --- |
| `search_api` | 搜索官方 CHM 中的类、方法、属性、事件和几何关键词 |
| `get_doc` | 读取搜索结果对应的单个官方 API 页面 |
| `find_python_command` | 根据自然语言建模意图返回 API 关联的 Python 候选 |
| `get_geometry_recipe` | 将几何任务整理为有顺序的建模步骤 |

示例意图：

```text
圆周阵列 6 个，每隔 60 度，生成后合并
```

该意图会关联圆周阵列和合并操作，并返回：

```python
Pattern.CreateCircular(...)
Combine.Merge(...)
```

## 安装与首次配置

要求：Windows、Node.js 18+，以及本机已经安装 ANSYS SpaceClaim/SCDM。

```powershell
git clone <your-github-repository-url>
cd ansys-scdmdoc-mcp
npm ci
npm run setup
node server.mjs
```

首次执行 `npm run setup` 会打开本地浏览器配置页。配置页提供两种选择：

1. 根据 `AWP_ROOT<number>` 自动检测；
2. 手动输入 `SpaceClaim.exe` 的应用程序路径。

在自动检测模式下，程序会扫描当前环境变量中所有版本化的 AWP_ROOT，并通过下拉框让用户选择。例如：

```text
AWP_ROOT241
AWP_ROOT251
AWP_ROOT261
```

点击确认后，程序会验证所选版本对应的官方 CHM 是否存在。如果验证失败，会显示：

```text
无法根据 AWP 确定环境变量的路径，无法确定 SpaceClaim 的路径
```

并禁用自动检测，只允许用户手动输入 `SpaceClaim.exe` 路径。

配置保存在：

```text
%LOCALAPPDATA%\ansys-scdmdoc-mcp\config.json
```

程序不会把用户电脑上的 ANSYS 安装路径写入代码或 README。手动模式保存的是应用程序路径，CHM 会从对应的 SCDM 安装目录自动查找。

## 路径和文档来源

路径解析优先级如下：

1. 显式 `SCDM_CHM`；
2. 首次配置保存的 AWP 或 SpaceClaim 路径；
3. 所有可用 `AWP_ROOT<number>` 中版本号最高者；
4. 通用 `AWP_ROOT` + `SCDM_API_VERSION`。

首次读取 CHM 时，程序使用 Windows 的 `hh.exe` 将帮助文档解包到用户缓存目录，并建立搜索索引：

```text
%LOCALAPPDATA%\ansys-scdmdoc-mcp\cache
```

项目只查询用户本机的官方 CHM，不在仓库中分发或保存 ANSYS 专有文档。

## 如何理解返回结果？

本项目明确区分三类证据：

- `official-doc`：来自官方 SpaceClaim CHM 的页面、类型、方法或属性；
- `inferred`：根据官方 API 签名和建模意图推导出的 Python 候选；
- `runtime-verified`：已经在目标 SpaceClaim/SCDM 安装中实际执行，并检查过模型结果。

尤其要注意：CHM 中常见的是 C#/.NET 签名。它可以证明 API 文档存在，但不能单独证明某段 IronPython 代码已经运行成功。因此，MCP 返回的 Python 代码仍应在目标 SCDM 版本中执行验证。

## 真实几何验收案例

项目提供了一个真实 SpaceClaim 验收脚本：[spaceclaim-circular-repeat-smoke.py](scripts/spaceclaim-circular-repeat-smoke.py)。它不是简单地循环 `Copy` 和 `Move.Rotate`，而是验证完整的圆周阵列与合并流程：

```text
创建 0° 基体
    ↓
Pattern.CreateCircular
    ↓
CircularPatternData：6 个实例、360° 总角度
    ↓
检查 0/60/120/180/240/300°
    ↓
Combine.Merge
    ↓
最终 1 个合并实体
```

验收必须同时检查：

- 阵列实体数量为 6；
- 角度间隔为 60°；
- 覆盖完整 360°；
- `Combine.Merge` 成功；
- 合并后的实体数量为 1；
- 模型文件和 `status=PASS` 结果文件都是本次运行新生成的。

MCP 查询成功、缓存建立成功或 SpaceClaim 进程返回码为 0，都不能单独替代真实几何验收。

## 开发与测试

```powershell
npm ci
npm test
npm run smoke
```

如果需要在本机验证真实 CHM：

```powershell
$env:SCDM_RUN_REAL_CHM_TEST = "1"
npm test
```

真实 SpaceClaim 几何验收需要目标电脑安装有效的 ANSYS SpaceClaim/SCDM，并且输出文件应保存到仓库之外的临时目录。

## 发布和版权边界

发布到 GitHub 前，请确认以下内容没有被提交：

- ANSYS 或 SpaceClaim CHM 文件；
- CHM 解包后的 HTML、HHK、HHC 文件；
- 用户本地缓存和索引；
- SpaceClaim 模型和运行日志；
- 用户配置、凭据和机器专属安装路径。

本项目只发布 MCP 实现、测试和说明文档，不发布 ANSYS 专有文档。ANSYS、SpaceClaim、SCDM 及相关产品名称属于各自权利人。本项目不代表 ANSYS 官方，也不声明与 ANSYS 存在授权或隶属关系。

项目代码使用 MIT License，详见 [LICENSE](LICENSE)。