┌──────────────┐      stdio       ┌──────────────┐    WebSocket     ┌──────────────────┐
│  AI 平台      │ ◄──────────────► │  MCP Server  │ ◄──────────────► │  Navisworks 插件  │
│  Claude       │     MCP 協議     │  (Node.js)   │    port 2233    │  (C# Add-in)     │
│  Gemini       │                  │              │                  │                  │
│  VS Code      │                  │  index.ts    │                  │  Application.cs  │
└──────────────┘                  └──────────────┘                  └──────────────────┘

# 1. 一鍵安裝 MCP Server 依賴並編譯
scripts\setup.bat

# 2. 在 Visual Studio 開啟解決方案
#    → 確認 NavisworksMCP.csproj 中的 NavisworksPath 正確
#    → Build Release

# 3. 部署 Plugin（需要管理員權限）
powershell -ExecutionPolicy Bypass -File scripts\install-addon.ps1

{
  "mcpServers": {
    "navisworks": {
      "command": "node",
      "args": ["C:/Users/你的帳號/DESKTOP/NV_mcp/MCP-Server/build/index.js"],
      "env": { "NAVIS_MCP_PORT": "2233" }
    }
  }
}

get_document_info          → 文件名稱、單位、模型數量
get_model_info             → 各來源檔案的根節點與子項目數
get_model_statistics       → 按分類/圖層/來源檔案統計數量  ★ 核心工具
get_all_categories         → 列出所有屬性分類名稱
get_model_tree             → 展開模型樹結構（可指定深度）

用戶：「幫我分析一下這個模型的組成」
AI 呼叫：get_model_statistics(groupBy: "sourceFile")
         → 回傳：Architectural.nwc (3,200 items), MEP.nwc (1,800 items), Structure.nwc (950 items)
AI 呼叫：get_model_statistics(groupBy: "classDisplayName")
         → 回傳：Wall (420), Door (180), Pipe (650), Duct (320)...

get_selection_sets         → 列出所有已儲存的選擇集
get_selection_set_items    → 讀取 Set 內容（不改變選擇）   ★ 安全讀取
execute_search_set         → 執行 Search Set 並回傳結果    ★ 搜尋集
search_items               → 自定義搜尋（按分類+屬性+值）
select_items_by_search     → 搜尋並選擇項目
select_items_by_set        → 選擇指定 Set 的所有項目
clear_selection            → 清除選擇

用戶：「模型裡有哪些選擇集？」
AI 呼叫：get_selection_sets
         → 回傳：MEP-Piping (Search Set, 650 items), Clash-Group-A (120 items)...

用戶：「看一下 MEP-Piping 裡面有什麼」
AI 呼叫：get_selection_set_items(name: "MEP-Piping", maxResults: 50)
         → 回傳項目清單（不影響當前選擇狀態）

用戶：「找出所有 Element 分類中 Type 是 Wall-200mm 的項目」
AI 呼叫：search_items(category: "Element", property: "Type", value: "Wall-200mm")

get_override_status        → 綜合報告：隱藏/凍結概覽       ★ 狀態總覽
get_hidden_items           → 列出所有被隱藏的項目
get_frozen_items           → 列出所有被凍結的項目

用戶：「看看模型現在的篩選狀態」
AI 呼叫：get_override_status(scope: "all", maxResults: 50)
         → 回傳：隱藏 23 項、凍結 5 項，附帶路徑清單

用戶：「哪些管線被隱藏了？」
AI 呼叫：get_hidden_items(maxResults: 200)
         → 回傳所有隱藏項目的名稱、分類、路徑

get_item_properties        → 單項完整屬性（所有分類）
batch_get_properties       → 批量抽取，可指定欄位          ★ 資料匯出
get_item_geometry_info     → 幾何包圍盒與中心點座標

用戶：「把 MEP-Piping 選擇集裡所有管線的直徑和材質抽出來」
AI 呼叫：batch_get_properties(
           setName: "MEP-Piping",
           fields: ["Element.Diameter", "Element.Material"],
           maxResults: 500
         )
         → 回傳表格式資料，每列包含 displayName、path、指定欄位值

用戶：「看一下選中項目的完整屬性」
AI 呼叫：get_item_properties
         → 回傳所有分類 > 屬性名 > 值 > 資料類型

set_item_override_color    → 覆蓋選中項目的顯示顏色 (RGB)
clear_override_colors      → 清除顏色覆蓋（重設材質）
hide_items                 → 隱藏選中項目
unhide_all                 → 取消隱藏所有項目
zoom_to_selection          → 視圖對準選中項目
get_viewpoints             → 列出已儲存的視點
set_active_viewpoint       → 切換到指定視點
get_current_selection      → 確認當前選了什麼

用戶：「把碰撞區域的管線標成紅色」
AI 呼叫：select_items_by_set(name: "Clash-Group-A")
AI 呼叫：set_item_override_color(r: 255, g: 0, b: 0)
AI 呼叫：zoom_to_selection

用戶：「隱藏所有結構柱，只看機電」
AI 呼叫：search_items(category: "Element", property: "Category", value: "Structural Columns")
AI 呼叫：select_items_by_search(category: "Element", property: "Category", value: "Structural Columns")
AI 呼叫：hide_items

用戶：「恢復全部顯示」
AI 呼叫：unhide_all
AI 呼叫：clear_override_colors

1. get_document_info                          → 了解基本資訊
2. get_model_statistics(groupBy: "sourceFile") → 看各來源檔案佔比
3. get_model_statistics(groupBy: "classDisplayName") → 看分類分佈
4. get_selection_sets                          → 看有哪些預設篩選
5. get_override_status(scope: "all")           → 看是否有已套用的篩選

1. get_selection_sets                          → 找到 "MEP-Piping" 集
2. get_selection_set_items(name: "MEP-Piping") → 預覽內容
3. batch_get_properties(                       → 批量抽取指定欄位
     setName: "MEP-Piping",
     fields: ["Element.Id", "Element.Diameter", "Element.Material"]
   )

1. get_selection_sets                          → 找碰撞相關 Set
2. select_items_by_set(name: "Clash-Group-A")  → 選擇碰撞群組
3. set_item_override_color(r:255, g:0, b:0)    → 標紅色
4. zoom_to_selection                           → 對準畫面
5. get_item_properties                         → 看碰撞項目屬性

1. get_model_statistics(groupBy: "sourceFile") → 確認有哪些來源
2. search_items(category: "Item", property: "Source File", value: "Structure.nwc")
3. select_items_by_search(同上參數)             → 選擇結構模型
4. hide_items                                  → 隱藏結構
5. unhide_all                                  → 完成後恢復

NV_mcp/
├── NavisworksMCP.sln           # Visual Studio 解決方案
├── CLAUDE.md                   # AI 開發規範
├── README.md                   # 本文件
├── .gitignore
│
├── MCP/                        # C# Navisworks Add-in
│   ├── NavisworksMCP.csproj    # .NET Framework 4.8
│   ├── Application.cs          # Plugin 入口 (Toggle + Log + EventWatcher)
│   ├── Core/
│   │   ├── SocketService.cs    # WebSocket 服務 (port 2233)
│   │   ├── CommandExecutor.cs  # 27 個命令的執行器
│   │   ├── IdleEventManager.cs # 主執行緒安全排程
│   │   └── Logger.cs           # 日誌系統
│   └── Models/
│       ├── NavisCommandRequest.cs
│       └── NavisCommandResponse.cs
│
├── MCP-Server/                 # Node.js MCP Server
│   ├── package.json            # @modelcontextprotocol/sdk + ws
│   ├── tsconfig.json
│   └── src/
│       ├── index.ts            # MCP Server 入口 (stdio transport)
│       ├── socket.ts           # WebSocket 客戶端
│       └── tools/
│           └── navis-tools.ts  # 27 個工具定義
│
├── scripts/
│   ├── setup.bat               # 一鍵安裝
│   └── install-addon.ps1       # Plugin 部署
│
└── .vscode/
    └── mcp.json                # VS Code MCP 配置