🚀 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 许可证，你可以自由地在商业和个人项目中使用！