============================================================
  Soar Revit MCP — V1.1.1
  一鍵安裝包（客戶版，Claude / Cowork）
  For Autodesk Revit 2024
  By Soar Design (Jimmy Kwok) © 2026
============================================================

【安裝前確認】

1. Windows 10 / 11 64-bit
2. Autodesk Revit 2024 已裝（目前只支援 2024；2025/2026 之後推出）
3. Claude 桌面版或 Cowork 已安裝
4. 已向 Soar Design 買咗 Revit 專用 license key
       格式：SOAR-XXXX-XXXX-XXXX-XXXX
       （Revit 同 Office 係獨立 license，唔共用）

* 唔需要裝 Python！安裝包已包含所有執行檔。

【架構簡介】

Soar Revit MCP 由兩部份組成：

  (a) C# Revit Addin (RevitMCPBridge.dll)
      — 跑喺 Revit 入面，接 Named Pipe 命令，直接 call Revit API
      — 自動安裝到 %APPDATA%\Autodesk\Revit\Addins\2024\

  (b) MCP Server (launcher.exe + in-memory server)
      — 跑喺 Claude / Cowork 啟動嘅 stdio subprocess
      — 每次啟動自動 check Cloudflare 有冇新版 server module
      — C# Addin DLL 唔係自動更新（要 update 就重裝 installer）

【安裝步驟】

1. 解壓呢個 zip 去任何資料夾（建議 D:\SoarMCP\Revit）
   * 唔好放喺 Program Files（會權限問題）
   * 路徑唔好有中文、空格、括號或特殊字元

2. 雙擊 install.bat
   等佢自動做晒 5 步：
   - 檢查 launcher.exe 存在
   - 問你攞 license key
   - 自動 copy RevitMCPBridge.dll + .addin 去
     %APPDATA%\Autodesk\Revit\Addins\2024\
   - 試連 Cloudflare server，下載最新 server module
   - 寫 Cowork MCP config

3. 見到「Installation complete!」：
   a. 如果 Revit 正開緊，關咗再開 Revit 2024
   b. 開任何 .rvt 檔
   c. 退出 Cowork / Claude Desktop 再重開
   d. 試 prompt：「ping Revit」或「List all walls」

【日常使用】

* 開 Autodesk Revit 2024 + 開一個 .rvt 檔（唔係 Start 頁）
* 開 Claude / Cowork
* 直接問，例如：
    「列出所有 walls」
    「建立一個 3 層樓建築：每層 3 米高，5x6 米」
    「將 grid A 向右移 2 米」
    「export 當前 view 做 PDF」
    「run Dynamo 腳本 'BatchRename.dyn'」

MCP 會 route 到 Revit MCP Bridge，直接操控 Revit。

【自動更新】

Server 邏輯係自動更新：每次啟動時，launcher 會
check Cloudflare 有冇新版 server module，有就 download 到 RAM。
客戶完全被動。

C# Addin DLL 唔係自動更新 — 要 update 就重新 install.bat
（因為 Revit 要關閉先換得 DLL）。

【卸載】

雙擊 uninstall.bat 會：
* 刪除本地 cache
* 刪除 Cowork / Claude 入面 soar-revit MCP entry
* 刪除 %APPDATA%\Autodesk\Revit\Addins\2024\ 入面 3 個 Addin 檔
  （執行 uninstall.bat 前請先關 Revit，否則檔案會被鎖定）

【緊急解鎖】

如果 MCP 被鎖定（例如 anomaly 觸發），雙擊 unlock_mcp.bat
清除本地鎖定檔案，然後重啟 MCP。

【疑難解答】

Q: install.bat 話 "Install path contains special characters"？
A: 路徑有括號、!、& 等特殊字元。搬去簡單路徑如 D:\SoarMCP\Revit

Q: install.bat 話 "Autodesk Revit not found"？
A: 你部機未裝 Revit，或者唔係裝喺預設位置。確認 Revit 2024 已裝。

Q: Revit 開咗但 Addin 冇 load？
A: 睇 Revit 內 Add-Ins 面板，確認 "RevitMCPBridge" 有啟用。
   或者 %APPDATA%\Autodesk\Revit\Addins\2024\ 入面檢查有無：
       RevitMCPBridge.addin
       RevitMCPBridge.dll
       Newtonsoft.Json.dll

Q: Claude / Cowork 收唔到 Revit MCP？
A: 確認：
   1. install.bat 完成時冇 error
   2. 完全退出 Cowork 再開（file -> exit，唔係 X）
   3. 如仍有問題，聯絡 Soar

Q: MCP 連到但 Revit API 命令報 "no Revit detected"？
A: Revit 要喺啟動狀態，而且要打開至少一個 project（.rvt）。

Q: License 話 invalid？
A: 核對 key 冇打錯；過期請聯絡 Soar。Revit key 獨立，唔通 Office。

Q: License 話 "bound to another machine"？
A: 每個 license 綁定一部機。如需轉機，聯絡 Soar 申請 transfer。

【技術支援】

Email   : info@soarmcpsoftware.com
Subject : 請包含 license key 前 8 位，例如 SOAR-AB12 Revit 問題

============================================================
