Robloxstudio MCP

🚀 Roblox Studio MCP Server

Roblox Studio MCP Server 是一个强大的 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": "Advanced Roblox Studio integration for AI assistants"
    }
  }
}

📦 安装指南

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

MCP 服务器需要一个配套的 Roblox Studio 插件，你可以通过以下方式进行安装：

1. Roblox 创作者商店（最简单 ⭐）：

   • 从 此处 安装。
   • 点击“安装”，插件将自动在 Studio 中打开。

2. 手动下载：

   • 下载 MCPPlugin.rbxmx。
   • 将其保存到 %LOCALAPPDATA%/Roblox/Plugins 文件夹中。

3. 高级设置：

   • 更多方法请参考 [studio - plugin/INSTALLATION.md](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/Desktop"]
        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 -->|stdio| 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 毫秒轮询一次，执行 Studio 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 智能：文本内容、可见性、容器与交互式。
• 性能优化：移除冗余工具以实现更快的操作。

💻 使用示例

// 获取服务概述
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")

🚀 开发与测试

命令

npm run dev         # 带有热重载的开发服务器
npm run build       # 生产构建
npm start           # 运行构建后的服务器
npm run lint        # ESLint 代码质量检查
npm run typecheck   # TypeScript 验证

插件开发

• 实时重载：插件更新会自动检测服务器更改。
• 错误处理：强大的超时和重试机制。
• 调试模式：在 Studio 输出窗口中进行详细日志记录。
• 连接状态：插件 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: 执行 Studio API
    Note over STUDIO: 🎯 game.ServerStorage<br/>📋 Selection:Get()<br/>🔍 实例属性
    STUDIO->>-PLUGIN: 返回 Studio 数据 📊
    
    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 秒超时：采用指数退避机制。
• 🔄 自动重试：处理网络问题。
• 📏 响应限制：防止上下文溢出。
• 🎯 请求去重：提高效率。

🔧 配置

环境变量：

• MCP_SERVER_PORT：MCP 服务器端口（默认：标准输入输出）。
• HTTP_SERVER_PORT：HTTP 桥接端口（默认：3002）。
• PLUGIN_POLL_INTERVAL：插件轮询频率（默认：500 毫秒）。
• REQUEST_TIMEOUT：请求超时时间（默认：30000 毫秒）。

Studio 设置：

• ✅ 允许 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 许可证，你可以自由地将其用于商业和个人项目！