# creo_mcp_server (dream_creo_mcp)

让 AI Agent 通过 [MCP](https://modelcontextprotocol.io) 直接在 **正在运行的 Creo Parametric 5** 里建模和改模型。

- **建模**:新建零件/装配,拉伸、旋转、扫描、孔、圆角、倒角、抽壳、阵列、基准面……
- **修改与查询**:经 [CREOSON](http://www.simplifiedlogic.com/creoson) 改尺寸、参数、特征、族表、图纸,读取模型信息,导出 STEP/PDF
- **看结果**:切换视图、截图返回给 Agent,让它自己检查

> 版本 **1.1.1**,在 Creo 5.0.0.0 + Windows 上验证。变更见 [CHANGELOG](CHANGELOG.md)。

---

## 工作原理

```
AI Agent (Grok / OpenCode / Claude / Cursor / Kiro / VS Code ...)
   │ stdio MCP
   ▼
dream-creo-mcp (Python)
   ├── CREOSON HTTP (localhost:9056) ──► J-Link ──► Creo 5     改尺寸/参数/导出等
   └── 请求文件 + mapkey 触发 ─────────► DreamFeatureApp ──► Creo 5   建新特征
                                          (Creo 内加载的 OTK Java 插件)
```

Creo 5 上用元素树建特征只对 Creo 自己加载的程序开放,外部连接(CREOSON 的方式)拿不到。所以建模由 Creo 内的 Java 插件完成,MCP 服务器经 CREOSON 的 `interface/mapkey` 触发它,通过 `%LOCALAPPDATA%\dream_creo_mcp\ipc` 交换请求和结果。

---

## 环境要求

| 项 | 要求 |
| --- | --- |
| 系统 | Windows |
| Creo | Creo Parametric 5.0(自带 JRE 1.8,插件运行在它上面,不用另装 Java) |
| CREOSON | [CreosonSetup](https://github.com/SimplifiedLogic/creoson/releases) 已安装,连上 Creo 并监听 `localhost:9056` |
| Python | 3.11 或更高 |

---

## 安装(三步)

### 1. 安装 Python 包

任选一种:

```powershell
# pipx(推荐,独立环境)
pipx install git+https://github.com/JaikenWong/creo_mcp_server.git

# 或者普通 pip / 虚拟环境
python -m pip install git+https://github.com/JaikenWong/creo_mcp_server.git
```

装好后有一个命令 `dream-creo-mcp`。

### 2. 安装 Creo 插件

```powershell
dream-creo-mcp install-plugin
```

它把插件复制到 `%LOCALAPPDATA%\dream_creo_mcp\plugin\`,并在那里生成 `creotk.dat`。然后在 Creo 里:
「工具」→「辅助应用程序」→「注册」→ 选上面那个 `creotk.dat` → 选中 `DreamFeatureApp` →「启动」。

**想让插件随 Creo 自动启动**:加上 Creo 的「起始位置」目录(Creo 启动时的工作目录):

```powershell
dream-creo-mcp install-plugin --start-dir "C:\Users\Public\Documents"
```

目录里已有 `creotk.dat` 时会先备份成 `creotk.dat.bak` 再追加,不会覆盖其他应用。也可以在 `config.pro` 里加一行 `toolkit_registry_file <creotk.dat 路径>`。

升级包之后重新运行 `install-plugin`,再在 Creo 里停止、启动一次插件。

### 3. 检查

先打开 Creo 和 CREOSON,启动插件,然后:

```powershell
dream-creo-mcp doctor
```

每一项都会显示 OK 或 FAIL,失败的项会给出修复方法。全部 OK 就可以接入 Agent 了。

---

## 接入 Agent

直接生成对应 Agent 的配置,复制粘贴即可:

```powershell
dream-creo-mcp config grok        # 也可以是 opencode / claude / cursor / kiro / vscode
```

生成的配置里,命令就是当前安装的 Python:`<python> -m dream_creo_mcp`。

**单次工具调用超时请设到 180 秒以上**(再生、装配、导出可能较慢)。Grok 和 OpenCode 的配置已经带上了这一项。

### 工具分组与环境变量

| 环境变量 | 作用 |
| --- | --- |
| `DREAM_MCP_TOOLS` | `modeling`(默认):28 个工具,说明文字少,Agent 更快;`all`:全部 41 个 |
| `CREOSON_URL` | 默认 `http://localhost:9056/creoson`,只接受本机回环地址 |
| `DREAM_FEATURE_IPC` | 插件交换目录,默认 `%LOCALAPPDATA%\dream_creo_mcp\ipc`(插件和服务器要一致) |
| `DREAM_CREO_TEMPLATES` | Creo 模板目录;默认根据 Creo 自带 JRE 自动找到 `Common Files\templates` |
| `CREOSON_SPECS_DIR` | 可选,用别的 CREOSON jsonSpecs 目录代替包内自带的 |

---

## 工具清单

### 建模(经 DreamFeatureApp 插件)

| 工具 | 说明 |
| --- | --- |
| `model_new` / `model_open` / `model_save` / `model_close` | 新建(零件,或 `kind=asm` 装配)、打开、保存、关闭;有未保存改动的模型拒绝关闭,除非 `confirm=DISCARD_CHANGES` |
| `model_info` | 特征列表、尺寸、轴、包围盒、体积 |
| `measure` | 两个面/边/轴/点之间的最小距离,平面或直线之间的夹角 |
| `extrude` | 拉伸:加材料/切除,盲孔、对称、贯穿 |
| `revolve` | 旋转:草图中用中心线 `CL` 作轴 |
| `sketch_curve` / `sweep` | 草绘曲线;沿曲线或边扫描恒定截面 |
| `hole` | 直孔,线性或同轴放置;`flip` / `both_sides` 控制方向 |
| `round` / `chamfer` | 圆角 / 等距倒角(按 `edge:N`);`tangent_chain=true` 自动带上相切相连的边 |
| `shell` | 抽壳,可指定开口面 |
| `datum_plane` | 偏移或成角度基准面 |
| `pattern` | 绕轴或沿方向阵列 |
| `find_geometry` | 按法向、类型、所属特征查找面和边,或用 `near=[x,y,z]` 找离某点最近的,返回 `surface:N` / `edge:N` |
| `view_set` | 切到 front / back / top / bottom / left / right / iso(也认中文:俯视、右视、轴测……)并自动适配窗口 |
| `preview_image` | 截图并作为图片返回;可同时切视图,默认隐藏基准 |
| `delete_feature` / `undo` | 删除特征(`confirm=DELETE_FEATURE`)/ 撤销最近一步(`confirm=UNDO`) |
| `feature_suppress` / `feature_resume` | 压缩 / 恢复特征 |
| `feature_xml_export` / `feature_xml_create` | 进阶:导出特征的元素树 XML,改完再建出来(适用于不带草图的特征) |

**草图语法**(`sketch` 参数,命令用 `;` 分隔,单位 mm)。推荐加 `coords=model`,每个点写成模型坐标 `x y z`,工具会投影到草图平面上,画在哪个面都一样:

| 命令 | 含义 |
| --- | --- |
| `M p` | 新环起点 |
| `L p` | 直线到 p |
| `A3 p m` | 经过点 m 的圆弧到 p(不用管顺逆时针) |
| `A p c ccw\|cw` | 绕圆心 c 的圆弧到 p |
| `Z` | 闭合当前环 |
| `C c r` | 整圆 |
| `CL p q` | 中心线(旋转轴) |

例:绕 Y 轴旋转出 r20×h40 的圆柱:`coords=model`,`CL 0 0 0 0 1 0; M 0 0 0; L 20 0 0; L 20 40 0; L 0 40 0; Z`

不写 `coords` 时是 1.0 的草图坐标:点写成 `x y`,FRONT 上就是模型 X/Y,其他面上的方向见结果里的 `sec_location`。实体特征的环必须闭合,旋转必须有且只有一条 `CL`,不满足时在调用 Creo 之前就会报错。

坐标系:FRONT 为 XY 面(法向 +Z),TOP 为 XZ 面(法向 +Y),RIGHT 为 YZ 面(法向 +X)。

**特征尺寸自动命名**:建特征时给了 `feature_name`,尺寸会被命名为 `<名字>_DEPTH`、`<名字>_DIAMETER`、`<名字>_RADIUS`、`<名字>_ANGLE`……草图尺寸是 `<名字>_S1`、`_S2`……结果里的 `dims` 列出全部尺寸,之后可以直接 `dimension_edit` 按名字改,比如把 `BOX_DEPTH` 改成 60。

**结果里的检查信息**:每个特征都返回 `volume_change`;孔、切除这类特征没有改变体积时会带 `warning: no_effect`,一般是打到了空处,可以用 `flip=true` 重试。

### 修改与查询(经 CREOSON)

默认分组只带 `dimension_edit`、`list_dimensions`、`model_export`;其余要 `DREAM_MCP_TOOLS=all`。

| 工具 | 说明 |
| --- | --- |
| `dimension_edit` | 批量改尺寸,默认改完再生一次并返回包围盒 |
| `parameter_edit` | 参数增删改(`PTC_WM_` 系统参数默认拒绝) |
| `feature_edit` | 压缩、恢复、重命名、删除特征,特征参数 |
| `file_edit` | 再生、保存、单位、材料、关系式、擦除等 |
| `familytable_edit` / `drawing_edit` / `note_edit` / `layer_edit` | 族表、工程图、注释、层 |
| `model_edit` | 装配(无约束时封装放置)、导入、mapkey(需 `RUN_MAPKEY`) |
| `model_export` | 导出 STEP/IGES/STL、PDF、3D PDF、图片 |
| `model_snapshot` | 活动模型快照:尺寸、包围盒、质量属性、特征、Windchill 检出状态 |
| `list_dimensions` / `list_parameters` / `list_features` | 列表查询 |
| `function_help` / `creoson_call` | 查 CREOSON 函数说明 / 调任意 CREOSON 函数 |

### 返回与错误

成功时 `ok: true` 加上结果。失败时统一为:

```json
{"ok": false, "error": {"code": "feature_failed", "message": "...", "hint": "下一步该怎么做"}}
```

常见 `code`:`invalid_arguments`、`feature_failed`、`model_not_in_session`、`model_in_session`、`unsaved_changes`、`confirm_required`、`creo_blocked`(Creo 在等用户关对话框)、`creoson_unreachable`、`plugin_not_running`。

### 安全约定

- **不会自动保存**。只有 `model_save` 或 `file_edit action=save` 会写盘。
- 破坏性操作必须带精确确认令牌(如 `DELETE_FEATURE`);选择器为空或通配 `*` 时需要 `ALL_*` 令牌。
- CREOSON 地址只允许本机回环;`sessionId` 不会返回给模型。
- 修改未检出的 Windchill 模型时,结果里会带"只存在于当前会话"的警告。

---

## 使用示例

对 Agent 说(尺寸、方向写清楚成功率最高):

> 在 D:\demo 新建零件 flange。用旋转做一个法兰:底盘直径 80、厚 10,中间轮毂直径 30、总高 30,Y 轴向上。中心打一个 φ10 通孔,在半径 28 处打一个 φ6 螺栓孔并绕中心轴阵列 6 个,最后给轮毂顶部外缘倒 R2 圆角。切到轴测视图截图给我看。

> 在 D:\demo 新建零件 box,拉伸一个 120×80×40 的长方体,顶面四条边倒角 3,然后去掉顶面抽壳,壁厚 2。

> 在 FRONT 面画一条路径:竖直向上 60,半径 20 圆弧转向右,再水平 40;沿它扫一个直径 10 的圆做成管子。

---

## 从源码开发

```powershell
git clone https://github.com/JaikenWong/creo_mcp_server.git
cd creo_mcp_server
python -m venv .venv
.venv\Scripts\python -m pip install -e ".[test]"
.venv\Scripts\python -m pytest                       # 单元测试,不连 Creo
```

改插件(需要 JDK 1.8;路径不同时设 `JDK_HOME`、`CREO_COMMON_FILES`):

```powershell
powershell -File feature-poc\build.ps1    # 编译并生成 src\dream_creo_mcp\plugin\dream_feature_app.jar
dream-creo-mcp install-plugin             # 然后在 Creo 里停止、启动插件
```

开发时在 `%LOCALAPPDATA%\dream_creo_mcp\ipc\dev_classes.txt` 里写一行 `feature-poc\classes` 的绝对路径,插件就会在每次请求时重新加载建模代码,改完重新编译直接生效,不用重启插件;删掉这个文件就回到正式版行为。`feature-poc\plugin.ps1 <op> key=value` 可以绕过 MCP 直接调插件。

刷新随包的 CREOSON 规格:`scripts\sync_specs.ps1 -Creoson <CREOSON 源码目录>`。

目录:

```
src/dream_creo_mcp/
  cli.py                  命令行:serve / doctor / config / install-plugin
  server.py               MCP 服务器、工具分组、错误格式
  tools.py                建模工具目录      plugin_client.py   插件交换
  tools_creoson.py        CREOSON 工具      creoson_client.py  CREOSON HTTP/会话
  confirm.py results.py specs.py schema_gen.py
  plugin/dream_feature_app.jar               预编译插件
  jsonspecs/                                 CREOSON 函数规格(MIT)
feature-poc/
  src/FeatureOps.java     建模实现(元素树)  DreamFeatureApp.java  Creo 内插件入口
  NOTES.md                Creo 5 上逐项实测的结论和坑,改建模代码前建议先读
tests/                    pytest
DESIGN.md                 CREOSON 线设计文档
```

---

## 已知限制

- 只验证过 **Creo 5.0.0.0**。
- 不支持镜像;装配暂不支持约束(只能封装放到原点或指定变换)。
- 孔和方向阵列只朝一侧;体积没变说明打到了空处,用 `flip=true` 重做(工具说明里已写明,Agent 会照做)。
- Creo 弹出交互对话框时调用会等到超时(返回 `creo_blocked`),需要到 Creo 里手动关闭。
- CREOSON 写操作除改尺寸外只有单元测试,没有逐项实机验证。

## 路线图

| 版本 | 内容 |
| --- | --- |
| 1.2 | 沉头/螺纹孔、拔模、筋、混合、更多基准、样条草图;DXF 二维图转 3D |
| 1.3 | 带约束装配、干涉检查、BOM |
| 1.4 | 工程图生成与导出 |
| 2.0 | 更多 Creo 版本、钣金、参数化工作流 |

## 许可

[MIT](LICENSE)。随包附带的 CREOSON 函数规格(`src/dream_creo_mcp/jsonspecs/`)同样是 MIT 许可,版权属于 Simplified Logic, Inc.,见 `jsonspecs/CREOSON-LICENSE.txt`。Creo 本身不包含在内,使用时需要你自己有正版 Creo。