内容
<!-- mcp-name: io.github.bimwright/ipt-mcp -->
<h1 align="center">ipt-mcp</h1>
<p align="center">
<a href="https://github.com/bimwright/ipt-mcp/actions/workflows/build.yml"><img src="https://github.com/bimwright/ipt-mcp/actions/workflows/build.yml/badge.svg" alt="build" /></a>
<a href="LICENSE"><img src="https://img.shields.io/badge/license-Apache%202.0-blue.svg" alt="license" /></a>
<a href="#supported-inventor-versions"><img src="https://img.shields.io/badge/Inventor-2022--2027-F5A300" alt="Inventor 2022-2027" /></a>
<a href="#tool-surface"><img src="https://img.shields.io/badge/MCP-46%20tools-6C47FF" alt="MCP tools" /></a>
</p>
<p align="center">
简体中文 · <a href="README.vi.md">Tiếng Việt</a>
</p>
---
`ipt-mcp` 是一个开源的（Apache-2.0）模型上下文协议（Model Context Protocol）网关，允许 Claude Code 和任何支持 MCP 的客户端驱动 **Autodesk Inventor 2022-2027** 在本地运行。
代理通过 stdio 进行 MCP 通信。服务器通过本地认证传输（TCP 或命名管道）与每个版本的进程内 Inventor 插件通信。插件将每个命令调度到 Inventor 的 STA 线程，并与 Inventor API 通信。
您的模型保留在您的机器上。
---
## ipt-mcp 是什么
两个进程，一个本地管道：
- **`Bimwright.Ipt.Server.exe`** — 一个 .NET 8 MCP stdio 服务器，由 Claude Code、Cursor、Cline、Codex 或另一个 stdio MCP 客户端启动。它没有 Inventor 引用；它只编译 API 无关的契约文件，因此它可以在任何安装了 .NET 8 SDK 的机器上构建和运行。
- **`Bimwright.Ipt.Plugin.InvNN.dll`** — 一个 `ApplicationAddInServer` 插件，加载到 `Inventor.exe` 中，运行一个 TCP 或命名管道监听器，并在 Inventor 的主 UI（STA）线程上执行命令。每个 Inventor 版本一个薄壳，所有文件都从相同的 `src/shared/**` 源代码 glob 编译。
与 Revit 不同，Inventor 没有 **ExternalEvent** 等价物。插件通过一个隐藏的消息-仅限 WinForms 控件（`InventorStaDispatcher`）将工作调度到 STA 线程。有关完整设计，请参见 [ARCHITECTURE.md](ARCHITECTURE.md)。
---
## 支持的 Inventor 版本
| Inventor | 目标框架 | 传输 | 备注 |
|----------|------------------|-----------|-------|
| 2022 | `net48` (.NET Framework 4.8) | TCP | 直接引用 `System.Windows.Forms` |
| 2023 | `net48` (.NET Framework 4.8) | TCP | |
| 2024 | `net48` (.NET Framework 4.8) | TCP | |
| 2025 | `net8.0-windows7.0` | 命名管道 | `UseWindowsForms`、`EnableDynamicLoading` |
| 2026 | `net8.0-windows7.0` | 命名管道 | |
| 2027 | `net10.0-windows7.0` | 命名管道 | 需要 .NET 10 SDK；遵循 `UseInventorAssemblyContext` |
- MCP 服务器是一个进程，**不受 Inventor 版本影响** — 它只转发 JSON 信封。
- 2022-2024 的 TCP（net48 插件）；2025-2027 的命名管道 — 命名管道避免了现代 Windows 上的环回防火墙提示。
- Inventor 从 2025 年开始将桌面插件开发从 .NET Framework 移至 **.NET 8 for 2025/2026，.NET 10 for 2027**。（.NET 8 插件在 2027 年仍然二进制兼容，但 net10 是原生目标。）
- 在所有地方都使用 **4 位日历年**（2022..2027）— 绝不使用旧版版本号。
> **状态：已验证。** 第 1-3 阶段已经完成且正常运行（46 个 MCP 工具；服务器 + 测试在没有安装 Inventor 的情况下构建）；并且 Inventor-API 处理程序已经针对实时 Inventor 会话进行了测试。始终在使用自己的模板测试生产模型之前进行测试。
---
## 安装 / 连接 MCP 客户端
服务器是一个普通的 stdio MCP 进程。将您的客户端指向已构建的 `Bimwright.Ipt.Server.exe`（或使用 `dotnet run` 运行），然后在 Inventor 中加载插件。
典型的 `.mcp.json`（或等效的客户端配置）条目：
```json
{
"mcpServers": {
"ipt-mcp": {
"command": "D:\\path\\to\\src\\server\\bin\\Debug\\net8.0\\Bimwright.Ipt.Server.exe",
"args": []
}
}
}
```
插件发现是自动的：每个正在运行的 Inventor 插件都会在 `%LOCALAPPDATA%\Bimwright\ipt-mcp\inventor-<year>-<pid>.json` 下写入一个每个实例的描述符。服务器扫描这些描述符，尽力删除死亡/过时的描述符，然后连接。MCP 目标列表工具会编辑描述符 `auth_token`。当可能打开多个 Inventor 时，请调用 `inventor_list_available_targets` 然后 `inventor_switch_target`。
---
## 构建与开发
Autodesk Inventor 二进制文件和 Inventor SDK **未在此仓库中分发**（参见 [未分发](#not-redistributed)）。构建 **服务器和测试** 只需要 .NET 8 SDK；构建 **每个版本的插件** 需要匹配的 SDK 和 Inventor 互操作引用程序集。
```bash
# 服务器 + 测试（服务器端；不需要 Inventor — 在任何安装了 .NET 8 SDK 的机器上都有效）：
dotnet build src/IptMcp.sln -c Debug
dotnet test tests/Bimwright.Ipt.Tests -c Debug
# 在没有安装 Inventor 的情况下检查插件项目 SHAPE：
dotnet build src/plugin-inv24 -c Debug /p:SkipInventorReferenceCheck=true
dotnet build src/plugin-inv27 -c Debug /p:SkipInventorReferenceCheck=true # 需要 .NET 10 SDK
# 真实的插件编译（仅在具有 Inventor + 匹配 SDK 的盒子上）：删除 SkipInventorReferenceCheck。
# 如果互操作程序集不在默认路径，请传递 /p:InventorInteropDir=...。
```
- **服务器** 显式包含 `shared/Contracts/*` + `shared/Security/*`（+ ToolBaker），因此它可以在没有 Inventor SDK 的情况下编译。
- 每个 **插件** 都使用 `<Compile Include="..\shared\**\*.cs" />` 来引入所有内容，包括 API 触摸 `Infrastructure`/`Plugin`/`Handlers`。
- 默认互操作提示路径为 `C:\Program Files\Common Files\Autodesk Shared\Extensions <year>\Framework\Interop\Autodesk.Inventor.Interop.dll`。
- 构建插件 2027 需要安装 **.NET 10 SDK**。
- **在部署插件 DLL 之前关闭 Inventor**，否则它将锁定。
---
## 工具表面
当启用所有平台工具集时，完整的表面为 **46 个工具**。每个 MCP 面向的名称都以 `inventor_` 为前缀。工具被分组到工具集类中；`--toolsets sketch,feature` 和 `--read-only` 控制哪些工具注册，因此弱模型永远不会看到禁用的工具。
默认开启工具集：`meta`、`query`、`document`、`parameters`、`properties`、`sketch`、`feature`、`export`、`toolbaker`、`toolbaker_write`。
默认关闭：`code`（`send_code` 出口 - 仅限选择加入）。
所有长度输入以 **毫米** 为单位，角度以 **度** 为单位；插件将其转换为 Inventor 的内部厘米/弧度。
### meta（3）— 服务器端目标工具，永不回环到插件；保持在 `--read-only` 下
| 工具 | 描述 |
|---|---|
| `inventor_list_available_targets` | 列出检测到的实时 Inventor 插件目标（年份、PID、传输、活动文档）。 |
| `inventor_get_current_target` | 报告服务器当前选择的目標，或如果没有目標则返回 `NO_TARGET`。 |
| `inventor_switch_target` | 按描述符 ID、Inventor 年份、进程 ID 或管道/会话名称选择活动目标。仅限服务器端。 |
### query（3）— 只读文档/健康探测
| 工具 | 描述 |
|---|---|
| `inventor_health` | 探测活动插件：inventor_year、process_id、是否打开文档、活动文档类型。 |
| `inventor_list_open_documents` | 列出所有打开的文档：标题、路径、类型和哪个是活动的。 |
| `inventor_get_document_info` | 获取活动文档的标题、完整路径和文档类型。 |
### document（7）— 文档生命周期（写入）
| 工具 | 描述 |
|---|---|
| `inventor_new_part` | 创建新的零件文档（.ipt）；可选模板路径。 |
| `inventor_new_assembly` | 创建新的装配文档（.iam）；可选模板路径。 |
| `inventor_open_document` | 从完整路径打开现有文档并使其成为活动文档。 |
| `inventor_save_document` | 保存活动文档，或另存为给定路径。 |
| `inventor_close_document` | 关闭活动文档；`save=true` 先保存。 |
| `inventor_set_units` | 设置活动文档的长度单位（毫米、厘米、米、英寸、英尺）。 |
| `inventor_set_material` | 按名称为活动零件分配材料。 |
### parameters（4）— 模型和用户参数（写入）
| 工具 | 描述 |
|---|---|
| `inventor_list_parameters` | 列出参数（模型 + 用户）：名称、表达式、值、单位、类型。 |
| `inventor_get_parameter` | 按名称获取一个参数：表达式、值、单位。 |
| `inventor_set_parameter` | 设置现有参数的表达式/值，然后更新文档。 |
| `inventor_create_parameter` | 创建新的用户参数（名称、表达式、单位）。 |
### properties（3）— iProperties 和质量属性（写入）
| 工具 | 描述 |
|---|---|
| `inventor_get_iproperty` | 按属性集和属性名称获取 iProperty 值。 |
| `inventor_set_iproperty` | 设置 iProperty 值。 |
| `inventor_get_mass_properties` | 质量（克）、体积（立方毫米）、表面积（平方毫米）、质心、边界框。 |
### sketch（9）— 2D 草图几何和约束（写入）
| 工具 | 描述 |
|---|---|
| `inventor_create_sketch` | 在平面（XY/XZ/YZ 或面/工作平面参考）上创建 2D 草图。 |
| `inventor_project_geometry` | 将模型边缘/顶点（按边缘 ID）投影到活动草图中。 |
| `inventor_draw_line` | 从 (x1,y1) 到 (x2,y2) 绘制草图线。 |
| `inventor_draw_circle` | 从中心 + 半径绘制草图圆。 |
| `inventor_draw_rectangle` | 绘制两点草图矩形。 |
| `inventor_draw_arc` | 绘制草图弧（中心、半径、起始/结束角度）。 |
| `inventor_add_sketch_dimension` | 向草图实体添加驱动尺寸约束。 |
| `inventor_add_sketch_constraint` | 添加几何约束（重合、平行、相切、...）。 |
| `inventor_close_sketch` | 完成草图编辑（退出草图编辑模式）。 |
### feature（6）— 立体和工作特征（写入）
| 工具 | 描述 |
|---|---|
| `inventor_extrude` | 拉伸命名草图（距离、连接/切割/相交、方向）。 |
| `inventor_revolve` | 围绕轴旋转命名草图（角度、操作）。 |
| `inventor_fillet` | 在模型边缘上添加恒定半径的边缘圆角。 |
| `inventor_chamfer` | 在模型边缘上添加等距边缘倒角。 |
| `inventor_create_work_plane` | 创建工作平面（偏移、三个点或相切）。 |
| `inventor_create_work_axis` | 创建工作轴（两点、边缘、平面交点、法线到面穿过点）。 |
### export（4）— 视图捕获和几何导出（写入）
| 工具 | 描述 |
|---|---|
| `inventor_capture_view` | 捕获活动视图为有界的 base64 PNG（不写入文件）。 |
| `inventor_export_step` | 将活动零件/装配导出为 STEP（.stp/.step）。 |
| `inventor_export_stl` | 将活动零件/装配导出为 STL（.stl）。 |
| `inventor_export_dxf` | 导出 2D DXF；必须声明源（`sketch` 或 `flat_pattern`）。 |
> 导出路径必须是绝对路径，并且在允许的输出根目录（用户配置文件或临时目录）下。
### code（1）— 选择加入的出口（默认关闭）
| 工具 | 描述 |
|---|---|
| `inventor_send_code` | **危险，选择加入。** 在 `Inventor.Application` 上执行 C# 代码段。默认禁用，除非服务器和插件都选择加入（否则 `SEND_CODE_DISABLED`）；禁止的 API（文件/进程/网络/环境）被拒绝。 |
### toolbaker（3，只读）— 在服务器端烘焙数据库上操作
| 工具 | 描述 |
|---|---|
| `inventor_list_baked_tools` | 列出所有已验证、编译、注册的烘焙工具。 |
| `inventor_list_bake_suggestions` | 列出来自重复工作流的活动 ToolBaker 建议。 |
| `inventor_create_bake_issue_draft` | 为建议创建 GitHub 问题草稿（不提交）。 |
### toolbaker_write（3，写入）— 运行烘焙工具和管理建议生命周期
| 工具 | 描述 |
|---|---|
| `inventor_run_baked_tool` | 按名称使用 JSON 参数执行已注册的烘焙工具。 |
| `inventor_accept_bake_suggestion` | 接受建议：验证 + 编译 + 应用 + 持久化为烘焙工具。 |
| `inventor_dismiss_bake_suggestion` | 驳回或暂停活动建议。 |
---
## 安全
简而言之：您的模型保留在您的机器上，并且写入/危险工具是受限的。
- **只读模式。** `--read-only`（或 `BIMWRIGHT_INVENTOR_READ_ONLY=1`）删除每个可写入的工具集（`document`、`parameters`、`properties`、`sketch`、`feature`、`export`、`code`、`toolbaker_write`），但保留 `meta` + `query` + 只读 `toolbaker`，并且 **保留 `inventor_switch_target` 暴露**。服务器在每个命令信封中发送只读模式；插件还遵循 `BIMWRIGHT_INVENTOR_PLUGIN_READ_ONLY=1` / `BIMWRIGHT_INVENTOR_READ_ONLY=1`。在强制只读模式下，写入命令返回 `READ_ONLY`。
- **send_code 双向选择加入。** `inventor_send_code` **默认禁用**。仅当 **两者** 都设置了门控时才公开：服务器使用 `--enable-send-code`（或 `BIMWRIGHT_INVENTOR_ENABLE_SEND_CODE=1`）**和** 插件进程使用 `BIMWRIGHT_INVENTOR_PLUGIN_ENABLE_SEND_CODE=1`。否则调度器返回 `SEND_CODE_DISABLED`。禁止的 API（文件/进程/网络/环境）被拒绝。
- **本地认证传输。** TCP 绑定回环；命名管道是本地机器范围的。每个会话描述符都带有随机身份验证令牌，但 MCP 元工具从不返回它。
- **清理错误。** 返回模型的错误消息被清理以避免泄漏绝对路径/机密。
**ToolBaker** 将重复的本地工作流转换为个人验证工具：建议通过 `inventor_list_bake_suggestions` 显示，您通过 `inventor_accept_bake_suggestion` 显式接受一个建议（验证 → 编译 → 应用 → 持久化），并且接受的工具可以通过 `inventor_list_baked_tools` / `inventor_run_baked_tool` 调用。烘焙数据库和审计日志存储在 `%LOCALAPPDATA%\Bimwright\ipt-mcp\baked\` 下。参见 [docs/toolbaker.md](docs/toolbaker.md) 和 [SECURITY.md](SECURITY.md)。
---
## 未分发
本项目 **不** 分发 Autodesk Inventor 二进制文件或 Inventor SDK / 互操作 DLL。已发布的服务器和单元测试在没有任何 Inventor 的情况下构建和运行。构建每个版本的插件需要 **本地 Inventor 安装** 或匹配的 **互操作引用程序集**（`Autodesk.Inventor.Interop.dll`），通过默认的 Autodesk 共享扩展路径或显式的 `/p:InventorInteropDir=...` MSBuild 属性提供。在 Inventor 上运行网关需要获得许可的 Inventor 安装。
---
## 许可证
[Apache-2.0](LICENSE)。参见 [LICENSE](LICENSE)。
Inventor 和 Autodesk 是 Autodesk, Inc. 的注册商标。bimwright 是一个独立的开源项目，与 Autodesk, Inc. 无关、未赞助且未获得其认可。
