Tip

🤖 AI 協作指南 (AI Collaboration Guide)

開始協作前，請務必遵循以下規範：

1. 人類開發者 (Human Developer)：

   • 請詳讀 SYSTEM_PROMPT.md，了解本專案對 AI 協作角色的定義與行為準則。
   • 執行任務前，請確保 AI 了解 GEMINI.md 中的專案結構。

2. AI 助手 (AI Assistant / Agent)：

   • Context Loading：啟動時必須載入 GEMINI.md 以獲取專案地圖與技術指引。
   • Workflow Compliance：執行任務前，必須檢查 domain/ 目錄下是否有定義好的工作流程（如上色任務）。
   • Safety First：所有 Revit 操作必須是可逆的，且需遵守 SYSTEM_PROMPT.md 中的安全規範。

Caution

⚠️ Git Pull 後必讀：重新編譯 Revit Add-in

如果您執行了 git pull 更新專案，且更新內容包含 C# 程式碼變更（MCP/*.cs 檔案），必須重新編譯並部署 Revit Add-in DLL，否則新功能將無法使用！

快速步驟：

1. 關閉 Revit（否則無法覆蓋 DLL）
2. 執行編譯：

   cd "您的專案路徑/MCP"
   dotnet build -c Release

3. 複製 DLL 到 Revit Addins 資料夾：

   Copy-Item "bin/Release/RevitMCP.dll" "C:\ProgramData\Autodesk\Revit\Addins\2022\RevitMCP\" -Force

4. 重新啟動 Revit

REVIT-MCP/
├── MCP/                    # Revit Add-in (C#)
│   ├── Application.cs           # 主程式進入點
│   ├── ConnectCommand.cs        # 連線命令
│   ├── RevitMCP.addin           # Add-in 配置
│   ├── RevitMCP.csproj          # 專案檔 (Revit 2022/2023)
│   ├── RevitMCP.2024.csproj     # 專案檔 (Revit 2024)
│   ├── Core/                    # 核心功能
│   │   ├── SocketService.cs     # WebSocket 服務
│   │   ├── CommandExecutor.cs   # 命令執行器
│   │   └── ExternalEventManager.cs
│   ├── Models/                  # 資料模型
│   └── Configuration/           # 設定管理
├── MCP-Server/             # MCP Server (Node.js/TypeScript)
│   ├── src/
│   │   ├── index.ts                 # MCP Server 主程式
│   │   ├── socket.ts                # Socket 客戶端
│   │   └── tools/
│   │       └── revit-tools.ts       # Revit 工具定義
│   ├── build/                       # 編譯輸出
│   ├── package.json
│   └── tsconfig.json
└── README.md

Important

以下檔案不包含在 Git 儲存庫中（被 .gitignore 排除）：

• MCP-Server/build/ - MCP Server 編譯輸出
• MCP-Server/node_modules/ - Node.js 相依套件
• MCP/bin/ - Revit Add-in 編譯輸出

# 檢查是否已安裝
node --version

# 如果沒有安裝，請前往 https://nodejs.org 下載 LTS 版本

# 進入 MCP-Server 資料夾
cd "您的專案路徑/MCP-Server"

# 安裝相依套件
npm install

# 編譯 TypeScript
npm run build

# 進入 MCP 專案資料夾
cd "您的專案路徑/MCP"

# 編譯專案
dotnet build -c Release

┌─────────────────┐
│   AI 應用程式   │  (Claude Desktop / Gemini CLI / VS Code / Antigravity)
│  (MCP Client)   │
└────────┬────────┘
         │ 1. 讀取 MCP Server 地址
         │
┌────────▼────────┐
│   MCP Server    │  (Node.js - 本專案提供)
│  (Revit Tools)  │
└────────┬────────┘
         │ 2. WebSocket 連接
         │
┌────────▼────────┐
│  Revit Add-in   │  (C# - RevitMCP.dll)
│  (WebSocket)    │
└────────┬────────┘
         │ 3. Revit API 調用
         │
┌────────▼────────┐
│  Revit 應用程式  │
└─────────────────┘

┌────────────────────────────────┐
│     Revit 應用程式             │
├────────────────────────────────┤
│  Revit Add-in with AI Chat     │
│                                │
│  ┌──────────────────────────┐  │
│  │  Chat Window UI (WPF)    │  │
│  └──────────────────────────┘  │
│           │ 使用 API Key        │
│  ┌────────▼──────────────────┐  │
│  │  GeminiChatService        │  │
│  │  (C# 直接呼叫 Gemini)     │  │
│  └────────┬──────────────────┘  │
│           │                     │
└───────────┼─────────────────────┘
            │ HTTP 請求到 Gemini API
            │
        ┌───▼──────┐
        │ Gemini   │
        │ API      │
        └──────────┘

MCP Server 的責任：
1. 定義 Revit 工具 (create_wall、query_elements 等)
2. 接收 AI 應用程式的工具調用請求
3. 透過 WebSocket 將請求轉發給 Revit Add-in
4. 返回執行結果給 AI 應用程式

Important

Gemini CLI 使用 settings.json 設定 MCP，而非 --config 參數！

這與 Claude Desktop 和其他工具不同。Gemini CLI 會讀取使用者目錄下的 ~/.gemini/settings.json 檔案。

┌─────────────────────────────────────┐
│        Revit 視窗                   │
├─────────────────────────────────────┤
│  MCP Tools                          │
│  ┌──────────────────────────────┐  │
│  │ MCP 服務(開/關)              │  │
│  ├──────────────────────────────┤  │
│  │ MCP 設定                     │  │
│  ├──────────────────────────────┤  │
│  │ 🆕 AI Chat 助手（新功能）    │  │
│  └──────────────────────────────┘  │
│                                     │
│  ┌─────────────────────────────────┐│
│  │ AI Chat 視窗 (WPF 對話框)       ││
│  ├─────────────────────────────────┤│
│  │ 您：請幫我建立一個 3mx5m 的樓板 ││
│  │ AI: 我已建立樓板，ID: 123456   ││
│  │                                 ││
│  │ [輸入框] [傳送按鈕]             ││
│  └─────────────────────────────────┘│
└─────────────────────────────────────┘

using System;
using System.Net.Http;
using System.Text;
using System.Threading.Tasks;
using Newtonsoft.Json;

namespace RevitMCP.Core
{
    /// <summary>
    /// Gemini 2.5 Flash API 整合服務
    /// </summary>
    public class GeminiChatService
    {
        private readonly string _apiKey;
        private readonly string _apiUrl = "https://generativelanguage.googleapis.com/v1beta/models/gemini-2.5-flash:generateContent";
        private readonly HttpClient _httpClient;

        public GeminiChatService(string apiKey)
        {
            _apiKey = apiKey ?? throw new ArgumentNullException(nameof(apiKey));
            _httpClient = new HttpClient();
        }

        /// <summary>
        /// 與 Gemini AI 交互式對話
        /// </summary>
        public async Task<string> ChatAsync(string userMessage, string context = "")
        {
            try
            {
                // 構建請求
                var requestBody = new
                {
                    contents = new[]
                    {
                        new
                        {
                            parts = new[]
                            {
                                new
                                {
                                    text = $"{context}\n\n用戶問題: {userMessage}"
                                }
                            }
                        }
                    },
                    generationConfig = new
                    {
                        temperature = 0.7,
                        maxOutputTokens = 1024
                    }
                };

                var jsonContent = JsonConvert.SerializeObject(requestBody);
                var content = new StringContent(jsonContent, Encoding.UTF8, "application/json");

                // 發送請求到 Gemini API
                var response = await _httpClient.PostAsync(
                    $"{_apiUrl}?key={_apiKey}",
                    content
                );

                if (!response.IsSuccessStatusCode)
                {
                    throw new Exception($"Gemini API 錯誤: {response.StatusCode}");
                }

                // 解析回應
                var responseContent = await response.Content.ReadAsStringAsync();
                dynamic result = JsonConvert.DeserializeObject(responseContent);
                
                string aiResponse = result.candidates[0].content.parts[0].text;
                return aiResponse;
            }
            catch (Exception ex)
            {
                return $"AI 服務錯誤: {ex.Message}";
            }
        }
    }
}

using System;
using Autodesk.Revit.UI;
using RevitMCP.Core;

namespace RevitMCP.Commands
{
    public class ChatCommand : IExternalCommand
    {
        public Result Execute(ExternalCommandData commandData, ref string message, ElementSet elements)
        {
            try
            {
                // 從設定中讀取 API Key
                var apiKey = System.Environment.GetEnvironmentVariable("GEMINI_API_KEY");
                
                if (string.IsNullOrEmpty(apiKey))
                {
                    TaskDialog.Show("設定錯誤", 
                        "請設定環境變數 GEMINI_API_KEY\n\n" +
                        "在 Windows 中：\n" +
                        "1. 按 Win + Pause\n" +
                        "2. 進階系統設定\n" +
                        "3. 環境變數\n" +
                        "4. 新增：GEMINI_API_KEY = 您的 API Key");
                    return Result.Failed;
                }

                // 建立聊天服務
                var chatService = new GeminiChatService(apiKey);

                // 開啟對話視窗
                var chatWindow = new ChatWindow(chatService, commandData.Application);
                chatWindow.Show();

                return Result.Succeeded;
            }
            catch (Exception ex)
            {
                TaskDialog.Show("錯誤", $"開啟 AI Chat 失敗: {ex.Message}");
                return Result.Failed;
            }
        }
    }
}

<Window x:Class="RevitMCP.ChatWindow"
        xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
        xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
        Title="Revit AI Chat 助手"
        Height="600"
        Width="500"
        Background="#F5F5F5">
    <Grid>
        <Grid.RowDefinitions>
            <RowDefinition Height="*"/>
            <RowDefinition Height="Auto"/>
        </Grid.RowDefinitions>

        <!-- 聊天歷史 -->
        <ListBox x:Name="ChatHistory"
                 Grid.Row="0"
                 Margin="10"
                 Background="White"
                 BorderThickness="1"
                 BorderBrush="#DDD">
            <ListBox.ItemTemplate>
                <DataTemplate>
                    <Border Margin="5" Padding="10" CornerRadius="5">
                        <TextBlock Text="{Binding}"
                                   TextWrapping="Wrap"
                                   Foreground="#333"/>
                    </Border>
                </DataTemplate>
            </ListBox.ItemTemplate>
        </ListBox>

        <!-- 輸入區域 -->
        <Grid Grid.Row="1" Margin="10" Background="White" Height="80">
            <Grid.ColumnDefinitions>
                <ColumnDefinition Width="*"/>
                <ColumnDefinition Width="Auto"/>
            </Grid.ColumnDefinitions>

            <TextBox x:Name="InputBox"
                     Grid.Column="0"
                     VerticalAlignment="Top"
                     Padding="10"
                     TextWrapping="Wrap"
                     AcceptsReturn="True"
                     PlaceholderText="輸入您的問題..."/>

            <Button x:Name="SendButton"
                    Grid.Column="1"
                    Margin="5"
                    Padding="15,10"
                    Background="#007ACC"
                    Foreground="White"
                    Content="傳送"
                    Click="SendButton_Click"/>
        </Grid>
    </Grid>
</Window>

using System.Collections.ObjectModel;
using System.Windows;
using Autodesk.Revit.UI;
using RevitMCP.Core;

namespace RevitMCP
{
    public partial class ChatWindow : Window
    {
        private readonly GeminiChatService _chatService;
        private readonly UIApplication _uiApp;
        private readonly ObservableCollection<string> _messages;

        public ChatWindow(GeminiChatService chatService, UIApplication uiApp)
        {
            InitializeComponent();
            _chatService = chatService;
            _uiApp = uiApp;
            _messages = new ObservableCollection<string>();
            ChatHistory.ItemsSource = _messages;

            _messages.Add("🤖 AI 助手已就緒。請輸入您的問題來控制 Revit。");
            _messages.Add("💡 例如：請建立一個 5 米長的牆");
        }

        private async void SendButton_Click(object sender, RoutedEventArgs e)
        {
            string userInput = InputBox.Text.Trim();
            if (string.IsNullOrEmpty(userInput)) return;

            // 顯示用戶訊息
            _messages.Add($"👤 您: {userInput}");
            InputBox.Clear();

            // 獲取 AI 回應
            SendButton.IsEnabled = false;
            SendButton.Content = "處理中...";

            try
            {
                string context = $"您是 Revit BIM 專家助手。可用的 Revit 命令包括: " +
                    "create_wall, create_floor, query_elements, get_project_info 等。" +
                    "請用中文簡潔回答，並說明您的操作。";

                string response = await _chatService.ChatAsync(userInput, context);
                _messages.Add($"🤖 AI: {response}");

                // 如果 AI 建議執行操作，可以在這裡添加自動執行邏輯
            }
            finally
            {
                SendButton.IsEnabled = true;
                SendButton.Content = "傳送";
            }
        }
    }
}

public Result OnStartup(UIControlledApplication application)
{
    try
    {
        RibbonPanel panel = application.CreateRibbonPanel("MCP Tools");
        
        string assemblyPath = Assembly.GetExecutingAssembly().Location;

        // 現有按鈕...
        
        // 🆕 新增 AI Chat 按鈕
        PushButtonData chatButtonData = new PushButtonData(
            "MCPChat",
            "AI Chat\n助手",
            assemblyPath,
            "RevitMCP.Commands.ChatCommand");
        chatButtonData.ToolTip = "開啟 AI 對話助手，與 Gemini 2.5 Flash 交互式控制 Revit";
        PushButton chatButton = panel.AddItem(chatButtonData) as PushButton;

        return Result.Succeeded;
    }
    catch (Exception ex)
    {
        TaskDialog.Show("錯誤", "載入 MCP Tools 失敗: " + ex.Message);
        return Result.Failed;
    }
}

👤 用戶：我想在 Level 2 建立 3 個方形樓板，尺寸都是 5m × 5m

🤖 AI：我可以幫您建立 3 個方形樓板。我會在以下位置建立它們：
- 樓板1：(0, 0) 到 (5, 5)
- 樓板2：(6, 0) 到 (11, 5)  
- 樓板3：(12, 0) 到 (17, 5)

現在建立中...完成！已建立 3 個樓板，ID 分別為 123456, 123457, 123458

👤 用戶：請把樓板1 的高度改成 4m

🤖 AI：我已將樓板1 的高度改為 4m。修改完成！