# Inventor MCP

透過自然語言操作 Autodesk Inventor，建立參數化零件、草圖、孔位與鈑金特徵，並儲存或匯出模型。

本儲存庫提供 MCP 伺服器、建模 Skills 與 API 技術筆記。高階建模工具的長度參數以 **毫米（mm）** 為單位；透過 `execute_python` 直接操作 Inventor COM 時，內部長度單位為 **公分（cm）**，需自行換算。

## 功能介紹

目前 `src/server.py` 定義 **36 個 MCP 工具**：

| 類別 | 工具 | 用途 |
| --- | --- | --- |
| 連線 | `connect`、`status` | 連接 Inventor，查看目前文件資訊 |
| 文件 | `create_part`、`save_document`、`export_document` | 建立零件、儲存 IPT、匯出 STEP／STL／SAT／IGES |
| 草圖 | `create_sketch`、`draw_rectangle`、`draw_circle`、`draw_line`、`draw_polygon`、`draw_closed_profile` | 建立工作平面或面上的草圖與輪廓 |
| 實體特徵 | `extrude`、`revolve`、`fillet`、`chamfer`、`hole`、`hole_linear`、`circular_pattern` | 擠出、旋轉、圓角、倒角、孔與環形陣列 |
| 參數 | `get_parameters`、`set_parameter`、`add_parameter` | 查詢與調整模型參數 |
| 鈑金 | `set_sheet_metal_thickness`、`sheet_metal_face`、`flange`、`sheet_metal_cut` | 板厚、基礎板面、凸緣與切割 |
| 幾何檢查 | `inspect`、`list_edges`、`list_faces`、`find_edge`、`find_face` | 查看體積、邊界及拓撲，依位置尋找邊與面 |
| 特徵管理 | `list_features`、`delete_feature`、`suppress_feature` | 列出、刪除或抑制特徵 |
| 進階操作 | `transaction`、`execute_python`、`reload_api` | 交易與回復、執行 Python、重新載入 API 包裝程式 |

`execute_python` 可以處理專用工具尚未涵蓋的操作。鈑金展開可透過 Inventor API 與附帶 Skill 操作，目前沒有獨立的展開 MCP 工具。

## 系統需求

- Windows 電腦及已安裝、可正常啟動的 Autodesk Inventor。
- 此程式包含針對 Inventor 2026 的 API 處理；其他版本需另外驗證。
- Python 3.12 以上。
- Git，以及可連線下載 Python 套件的環境。

此 MCP 透過 Windows COM 操作本機 Inventor，不能直接在 macOS、Linux 或 WSL 的 Linux Python 中執行。

## 安裝方式

### 1. 下載程式並安裝依賴

在 PowerShell 執行，將專案放在固定資料夾：

```powershell
git clone https://github.com/allen2123231/inventor-mcp.git
cd inventor-mcp
python --version
python -m venv .venv
.\.venv\Scripts\python.exe -m pip install -e .
```

請確認 `python --version` 顯示 3.12 以上，再建立虛擬環境。依賴套件由 `pyproject.toml` 管理，包含 `mcp[cli]` 與 `pywin32`。

### 2. 設定 MCP 用戶端

以下為使用 `mcpServers` 格式的設定範例，亦可參考 [.mcp.json.example](.mcp.json.example)。請把 `C:/path/to/inventor-mcp` 換成實際安裝位置。

```json
{
  "mcpServers": {
    "inventor": {
      "command": "C:/path/to/inventor-mcp/.venv/Scripts/python.exe",
      "args": ["-X", "utf8", "-m", "src.server"],
      "cwd": "C:/path/to/inventor-mcp"
    }
  }
}
```

MCP 使用 **stdio** 通訊。不同用戶端的設定格式可能不同，請依用戶端規格填入相同的 Python 路徑與啟動參數。完成設定後，重新載入 MCP 連線。

### 3. 開啟 Inventor 並驗證

先開啟 Inventor，再由 AI 助理呼叫：

```text
connect()
status()
```

`connect` 會嘗試連接已執行的 Inventor；無法取得現有執行個體時，會嘗試啟動 Inventor。`status` 可檢查連線與目前文件資訊；尚未開啟文件時，會回報已連線但沒有文件。

目前工具未提供依視窗 HWND 選擇執行個體的參數。若同時開啟多個 Inventor，修改前必須先確認連上的文件。

## 中文操作範例

- 「先確認 Inventor 的連線狀態與目前零件。」
- 「建立直徑 50 mm、高 10 mm 的圓柱，檢查體積後另存 IPT。」
- 「在指定面建立孔，先列出面與位置，再執行建模。」
- 「列出零件參數，將指定長度改為 120 mm，檢查特徵是否正常。」
- 「建立指定板厚的鈑金零件，加入凸緣並確認高度。」
- 「把確認完成的零件匯出成 STEP。」

首次測試請使用新零件。可依序執行：

```text
connect()
create_part(name="MCP_Test", template="metric")
create_sketch(plane="XY")
draw_circle(x=0, y=0, diameter=50)
extrude(distance=10)
inspect()
```

理想圓柱體積約為 **19,634.95 mm³**。確認特徵與尺寸後，再以指定的完整路徑呼叫 `save_document`，並重新開啟檔案核對。

## 附帶 Skills

| Skill | 內容 |
| --- | --- |
| [inventor-modeling](skills/inventor-modeling/SKILL.md) | 建模流程、單位換算、草圖約束、孔位、鈑金與模型檢查 |
| [inventor-din-parts](skills/inventor-din-parts/SKILL.md) | DIN／ISO 標準零件的建模流程與尺寸表，例如螺帽、螺栓、墊圈及法蘭 |

Skills 提供操作流程，MCP 提供實際工具；使用 Skills 前仍須先完成 MCP 設定。Skill 內的參考尺寸需依實際採用的標準版本與加工需求確認。

在 Codex 中，可將這兩個 Skill 資料夾安裝到個人的 `.agents/skills/`。例如在本專案根目錄執行：

```powershell
$cadSkillsDir = Join-Path $env:USERPROFILE '.agents\skills'
New-Item -ItemType Directory -Force -Path $cadSkillsDir | Out-Null
Copy-Item -LiteralPath '.\skills\inventor-modeling' -Destination $cadSkillsDir -Recurse
Copy-Item -LiteralPath '.\skills\inventor-din-parts' -Destination $cadSkillsDir -Recurse
```

以上為首次安裝範例；若同名 Skill 已存在，請先比較內容再更新，避免覆蓋自己的修改。其他 AI 用戶端請使用其支援的 Skill 安裝位置。

## 使用注意與問題排除

- **連線失敗：** 確認 Inventor 能正常啟動、Python 是 Windows 版本，且使用安裝依賴的同一個虛擬環境。
- **找不到範本：** 檢查 Inventor 的範本設定；`create_part` 可傳入實際 IPT 範本完整路徑。鈑金可使用 `template="sheet_metal"`，仍需存在可用的鈑金範本。
- **草圖或特徵錯誤：** 先確認目前文件是目標零件，並檢查輪廓是否閉合、邊與面的選取是否正確。
- **邊與面編號改變：** 建立特徵後重新查詢幾何；可用 `find_edge`、`find_face` 依位置搜尋，避免沿用舊編號。
- **單位換算：** 高階工具長度使用 mm；直接呼叫 COM 時，長度常用 cm，角度需依 API 規格處理。
- **中文輸出：** 啟動參數加入 `-X utf8`，減少 Windows 編碼問題。
- **COM 快取問題：** 避免隨意混用 `EnsureDispatch` 與動態 COM；錯誤原因及排查方式見 [API 技術筆記](docs/inventor-api-notes.md)。
- **交易回復：** `transaction(action="begin")` 開始一組操作；成功後 `commit`，需要回復時 `abort`。檔案備份仍應獨立保留。

## 專案結構

```text
src/server.py          MCP 工具定義與 stdio 入口
src/inventor_api.py    Inventor COM 包裝與幾何操作
skills/                建模與標準零件 Skills
docs/                  API 技術筆記
assets/                專案資源
llms-install.md        AI 助理安裝與驗證指引
.mcp.json.example      MCP 設定範例
pyproject.toml         套件資訊與依賴
LICENSE                MIT 授權
```

## 後續開發方向

以下為規劃項目，尚未代表已完成功能。

### 第一階段：連線與驗證

- [ ] 新增多執行個體辨識，明確選擇目標 Inventor 視窗與文件。
- [ ] 補齊安裝診斷、連線失敗及 COM 中斷的中文提示。
- [ ] 建立特徵健康度、尺寸、儲存及重新開啟的驗證流程。
- [ ] 加入可重現的基本零件與鈑金測試案例。

### 第二階段：鈑金與加工圖

- [ ] 提供獨立的展開、展開尺寸讀取與 DXF 匯出工具。
- [ ] 增加折彎規則、扣料參數與材料設定管理。
- [ ] 擴充工程圖、視圖比例、尺寸與圖框操作。
- [ ] 支援板件編號、批次處理及逐件結果報告。

### 第三階段：Skills 與整合安裝

- [ ] 整理繁體中文建模 Skills、操作範例與驗收規則。
- [ ] 與 Rhino、AutoCAD 流程統一板件編號、單位及交換格式。
- [ ] 納入 CAD 整合 Plugin，提供集中安裝與連線檢查。
- [ ] 建立版本相容性清單、更新檢查及回復舊版機制。

## 授權

採用 [MIT License](LICENSE)，使用與散布時請保留該文件中的版權及授權聲明。