Robloxstudio MCP

🚀 Roblox Studio MCP 服務器

Roblox Studio MCP 服務器是一個強大的 MCP（模型上下文協議）服務器，它為 AI 助手提供了全面訪問 Roblox Studio 項目的能力。藉助 18 種專業的 AI 工具，包括用於批量編輯的批量操作工具，你可以探索遊戲架構、分析腳本、調試問題以及理解複雜的 Roblox 項目。

🚀 快速開始

⚡ 一鍵啟動

Claude Code 用戶：

claude mcp add robloxstudio -- npx -y robloxstudio-mcp

其他 MCP 客戶端（如 Claude Desktop 等）：

{
  "mcpServers": {
    "robloxstudio-mcp": {
      "command": "npx",
      "args": ["-y", "robloxstudio-mcp"],
      "description": "為 AI 助手提供高級 Roblox Studio 集成"
    }
  }
}

🔌 工作室插件設置（必需）

MCP 服務器需要一個配套的 Roblox Studio 插件：

1. Roblox 創作者商店（最簡單 ⭐）：

   • 從以下鏈接安裝：https://create.roblox.com/store/asset/132985143757536
   • 點擊“安裝” → 自動在工作室中打開

2. 手動下載：

   • 下載 MCPPlugin.rbxmx
   • 保存到 %LOCALAPPDATA%/Roblox/Plugins 文件夾

3. 高級設置：

   • 其他方法請參考 studio-plugin/INSTALLATION.md

安裝後：

• ✅ 在遊戲設置 → 安全中啟用“允許 HTTP 請求”
• 🔘 點擊插件工具欄中的“MCP 服務器”按鈕
• 🟢 正常工作時狀態應顯示為“已連接”

🏗️ 架構概述

這是一個將 Roblox Studio 與 AI 助手連接起來的雙組件系統：

%%{init: {'theme':'dark', 'themeVariables': {'primaryColor':'#2d3748', 'primaryTextColor':'#ffffff', 'primaryBorderColor':'#4a5568', 'lineColor':'#718096', 'sectionBkgColor':'#1a202c', 'altSectionBkgColor':'#2d3748', 'gridColor':'#4a5568', 'secondaryColor':'#2b6cb0', 'tertiaryColor':'#319795'}}}%%
graph TB
    subgraph AI_ENV ["🤖 AI 環境"]
        AI["🤖 AI 助手<br/>Claude Code/桌面版"]
        MCP["📡 MCP 服務器<br/>Node.js + TypeScript"]
    end
    
    subgraph COMM_LAYER ["🔗 通信層"]
        HTTP["🌐 HTTP 橋接<br/>localhost:3002"]
        QUEUE["📋 請求隊列<br/>UUID 跟蹤"]
    end
    
    subgraph STUDIO_ENV ["🎮 Roblox Studio 環境"]
        PLUGIN["🎮 工作室插件<br/>Luau 腳本"]
        STUDIO["🎯 Roblox Studio<br/>API 和數據"]
    end
    
    subgraph TOOLS ["🛠️ 18 種 AI 工具"]
        FILE["📁 文件系統<br/>樹結構、搜索"]
        CONTEXT["🎯 工作室上下文<br/>服務、對象"]
        PROPS["🔍 屬性<br/>獲取、設置、批量操作"]
        CREATE["🏗️ 對象創建<br/>單個、批量、屬性設置"]
        PROJECT["🏢 項目分析<br/>智能結構"]
    end
    
    AI -->|標準輸入輸出| MCP
    MCP -->|HTTP POST| HTTP
    HTTP -->|隊列請求| QUEUE
    PLUGIN -->|每 500ms 輪詢一次| HTTP
    HTTP -->|待處理工作| PLUGIN
    PLUGIN -->|執行 API 調用| STUDIO
    STUDIO -->|返回數據| PLUGIN
    PLUGIN -->|HTTP 響應| HTTP
    HTTP -->|解析承諾| MCP
    MCP -->|工具結果| AI
    
    MCP -.->|暴露| FILE
    MCP -.->|暴露| CONTEXT  
    MCP -.->|暴露| PROPS
    MCP -.->|暴露| CREATE
    MCP -.->|暴露| PROJECT
    
    classDef aiStyle fill:#1e40af,stroke:#3b82f6,stroke-width:2px,color:#ffffff
    classDef mcpStyle fill:#7c3aed,stroke:#8b5cf6,stroke-width:2px,color:#ffffff
    classDef httpStyle fill:#ea580c,stroke:#f97316,stroke-width:2px,color:#ffffff
    classDef pluginStyle fill:#059669,stroke:#10b981,stroke-width:2px,color:#ffffff
    classDef studioStyle fill:#dc2626,stroke:#ef4444,stroke-width:2px,color:#ffffff
    classDef toolStyle fill:#0891b2,stroke:#06b6d4,stroke-width:2px,color:#ffffff
    
    class AI aiStyle
    class MCP mcpStyle
    class HTTP,QUEUE httpStyle
    class PLUGIN pluginStyle
    class STUDIO studioStyle
    class FILE,CONTEXT,PROPS,CREATE,PROJECT toolStyle

關鍵組件：

• 🧠 MCP 服務器（Node.js/TypeScript） - 通過標準輸入輸出暴露 18 種工具，用於 AI 集成
• 🔗 HTTP 橋接 - 在 localhost:3002 上的請求/響應隊列，超時時間為 30 秒
• 🎮 工作室插件（Luau） - 每 500 毫秒輪詢一次，執行工作室 API 調用，處理錯誤
• 📊 智能緩存 - 通過智能響應限制實現高效的數據傳輸

🛠️ 18 種強大的 AI 工具

📁 文件系統工具

• get_file_tree - 獲取包含腳本、模型和文件夾的完整項目層次結構
• search_files - 按名稱、類型或內容模式查找文件

🎯 工作室上下文工具

• get_place_info - 獲取地點 ID、名稱、遊戲設置和工作區信息
• get_services - 獲取所有 Roblox 服務及其子項數量
• search_objects - 按名稱、類或屬性查找實例

🔍 實例與屬性工具

• get_instance_properties - 獲取任何對象的完整屬性轉儲
• get_instance_children - 獲取帶有元數據（如腳本、GUI 類型等）的子對象
• search_by_property - 查找具有特定屬性值的對象
• get_class_info - 獲取 Roblox 類的可用屬性/方法

⚡ 屬性修改工具

• set_property - 設置任何 Roblox 實例的屬性
• mass_set_property - 🆕 新增！ 一次性為多個實例設置相同的屬性
• mass_get_property - 🆕 新增！ 一次性從多個實例獲取相同的屬性

🏗️ 對象創建工具

• create_object - 創建一個新的 Roblox 對象實例（基本操作）
• create_object_with_properties - 🆕 新增！ 創建帶有初始屬性的對象
• mass_create_objects - 🆕 新增！ 一次性創建多個對象（基本操作）
• mass_create_objects_with_properties - 🆕 新增！ 創建多個帶有屬性的對象
• delete_object - 刪除一個 Roblox 對象實例

🏢 項目分析工具

• get_project_structure - 🔥 增強版！ 具有改進的深度控制的智能層次結構（建議最大深度為 5 - 10）

⚠️ 重要提示

之前的工具如 get_file_content、get_file_properties、get_selection、get_dependencies 和 validate_references 已被移除。建議使用 Rojo/Argon 工作流或文件系統讀取以獲得更好的性能。

🧠 針對 AI 優化的特性

🚀 批量操作（v1.3.0 新增）

• 批量屬性編輯：瞬間為數百個實例設置相同的屬性
• 批量對象創建：通過一次調用創建複雜的對象層次結構
• 批量屬性讀取：高效地從多個對象獲取屬性
• 原子操作：所有批量操作都被分組到單個撤銷/重做點

示例用例：

// 將工作區中的所有部件設置為紅色
mass_set_property(["game.Workspace.Part1", "game.Workspace.Part2"], "BrickColor", "Really red")

// 創建 10 個帶有屬性的部件
mass_create_objects_with_properties([
  {className: "Part", parent: "game.Workspace", name: "RedPart", properties: {BrickColor: "Really red"}},
  {className: "Part", parent: "game.Workspace", name: "BluePart", properties: {BrickColor: "Really blue"}}
])

智能項目結構

• 服務概述模式：帶有子項數量的清晰服務列表
• 基於路徑的探索：get_project_structure("game.ServerStorage", maxDepth=5)
• 僅腳本過濾：scriptsOnly=true 用於代碼分析
• 智能分組：大型文件夾按類類型自動分組
• 增強的深度控制：建議最大深度為 5 - 10 以進行全面探索

豐富的元數據

• 腳本狀態：啟用/禁用、源檢測、腳本類型
• GUI 智能：文本內容、可見性、容器與交互式
• 性能優化：移除冗餘工具以實現更快的操作

🚀 開發與測試

命令

npm run dev         # 帶有熱重載的開發服務器  
npm run build       # 生產環境構建
npm start           # 運行構建後的服務器
npm run lint        # ESLint 代碼質量檢查
npm run typecheck   # TypeScript 驗證

插件開發

• 實時重載：插件更新會自動檢測服務器更改
• 錯誤處理：強大的超時和重試機制
• 調試模式：在工作室輸出窗口中進行詳細日誌記錄
• 連接狀態：插件 UI 中的可視化指示器

📊 通信協議

%%{init: {'theme':'dark', 'themeVariables': {'primaryColor':'#2d3748', 'primaryTextColor':'#ffffff', 'primaryBorderColor':'#4a5568', 'lineColor':'#10b981', 'sectionBkgColor':'#1a202c', 'altSectionBkgColor':'#2d3748', 'gridColor':'#4a5568', 'secondaryColor':'#3b82f6', 'tertiaryColor':'#8b5cf6', 'background':'#1a202c', 'mainBkg':'#2d3748', 'secondBkg':'#374151', 'tertiaryColor':'#6366f1'}}}%%
sequenceDiagram
    participant AI as 🤖 AI 助手
    participant MCP as 📡 MCP 服務器  
    participant HTTP as 🌐 HTTP 橋接
    participant PLUGIN as 🎮 工作室插件
    participant STUDIO as 🎯 Roblox Studio
    
    Note over AI,STUDIO: 🚀 工具請求流程
    
    AI->>+MCP: 調用工具（如 get_file_tree）
    MCP->>+HTTP: 使用 UUID 對請求進行排隊
    HTTP->>HTTP: 存儲在待處理請求映射中
    HTTP-->>-MCP: 請求已排隊 ✅
    
    Note over PLUGIN: 🔄 每 500ms 輪詢一次
    PLUGIN->>+HTTP: GET /poll
    HTTP->>-PLUGIN: 返回待處理請求 + UUID
    
    PLUGIN->>+STUDIO: 執行工作室 API
    Note over STUDIO: 🎯 game.ServerStorage<br/>📋 Selection:Get()<br/>🔍 實例屬性
    STUDIO->>-PLUGIN: 返回工作室數據 📊
    
    PLUGIN->>+HTTP: POST /response 並附帶 UUID + 數據
    HTTP->>-MCP: 使用數據解析承諾
    MCP->>-AI: 返回工具結果 🎉
    
    Note over AI,STUDIO: ⚠️ 錯誤處理
    
    alt 請求超時（30 秒）
        HTTP->>MCP: 使用超時拒絕承諾 ⏰
        MCP->>AI: 返回錯誤消息 ❌
    end
    
    alt 插件斷開連接
        PLUGIN->>HTTP: 連接丟失 🔌
        HTTP->>HTTP: 指數退避重試 🔄
        Note over PLUGIN: 狀態：“等待服務器...” ⏳
    end

特性：

• 🕐 30 秒超時 並採用指數退避策略
• 🔄 網絡問題自動重試
• 📏 響應限制 防止上下文溢出
• 🎯 請求去重 提高效率

💻 使用示例

// 獲取服務概述
get_project_structure()

// 探索武器文件夾
get_project_structure("game.ServerStorage.Weapons", maxDepth=2)

// 查找所有 Sound 對象
search_by_property("ClassName", "Sound")

// 檢查腳本依賴項
get_dependencies("game.ServerScriptService.MainScript")

// 查找損壞的引用
validate_references()

// 獲取 UI 組件詳細信息
get_instance_properties("game.StarterGui.MainMenu.SettingsFrame")

🔧 配置

環境變量：

• MCP_SERVER_PORT - MCP 服務器端口（默認：標準輸入輸出）
• HTTP_SERVER_PORT - HTTP 橋接端口（默認：3002）
• PLUGIN_POLL_INTERVAL - 插件輪詢頻率（默認：500 毫秒）
• REQUEST_TIMEOUT - 請求超時時間（默認：30000 毫秒）

工作室設置：

• ✅ 允許 HTTP 請求（遊戲設置 → 安全）
• 🌐 HttpService.HttpEnabled = true
• 🔌 通過工具欄按鈕激活插件

📋 更新日誌

v1.3.0 - 批量操作更新（最新版本）

• ➕ 新增：mass_set_property - 批量屬性修改
• ➕ 新增：mass_get_property - 批量屬性讀取
• ➕ 新增：create_object_with_properties - 創建帶有初始屬性的對象
• ➕ 新增：mass_create_objects - 批量對象創建
• ➕ 新增：mass_create_objects_with_properties - 批量創建帶有屬性的對象
• 🔥 增強：get_project_structure 改進了深度參數文檔
• 🗑️ 移除：get_file_content、get_file_properties、get_selection、get_dependencies、validate_references（建議使用 Rojo/Argon 工作流代替）
• ⚡ 性能：簡化 API，從 15 個多用途工具精簡為 18 個專注工具

v1.2.0 - 屬性修改

• ➕ 新增 set_property 工具用於實例修改
• ➕ 新增 create_object 和 delete_object 工具
• 🔧 增強錯誤處理和驗證

v1.1.0 - 增強發現功能

• 🔍 改進項目結構分析
• 📊 更好的元數據提取
• 🎯 腳本和 GUI 智能

📄 許可證

本項目採用 MIT 許可證，你可以自由地在商業和個人項目中使用！