⚡ Universal Roblox AI Studio — 自主多模式能力 MCP 平台

Universal Roblox AI Studio 是一款新一代模型上下文协议（MCP）运行时，可将 Roblox Studio 转变为面向外部 AI 编码助手（Claude Desktop、Cursor、Antigravity、VS Code 等）的 AI 原生、自主且双向的开发平台。

📖 目录

• 🌟 核心特性

• 🏛️ 架构与 11 个专用提供程序（Provider）

• 🧱 层级与组件优先构建（"+" 范式）

• 🛡️ 受限与官方 MCP 路由树（Restricted Taxonomy）

• 🧠 自愈诊断引擎（Self-Healing Diagnostics）

• 🛠️ 全面的 MCP 工具列表（63+ 工具）

• 🚀 快速安装与入门

• 🤖 AI 客户端配置（Claude Desktop / Cursor）

• 📊 实时遥测与 Studio 界面

• 🧪 测试与验证

🌟 核心特性

1. 63+ 一流通用 MCP 工具：DataModel 层级、Instance 生命周期、Luau 脚本管理、PBR 材质、Voxel Terrain、Playtest 模拟、3D 生成式 AI 和虚拟硬件输入。

2. 官方 Roblox Studio MCP（StudioMCP.exe）本地集成：自动发现 Roblox 官方 MCP 客户端（%LOCALAPPDATA%\Roblox\Versions\...\StudioMCP.exe 和 mcp.bat），并将受限的 3D/Asset/Playtest 命令直接路由到官方引擎。

3. 组件与层级优先构建（VisualConstructionEngine）：不是用庞大的脚本生成一切，而是按照 Studio Explorer 中的 +（插入对象）逻辑，逐层创建物理对象、约束（Constraints）、灯光、粒子和声音。

4. 高级动画与硬件校准（AnimationAuthoringEngine）：R15/R6 骨骼摆姿（Motor6D）、关节安全、KeyframeSequence 创建，以及通过 Tool.Grip 校准确保工具在角色手中正确握持。

5. 自愈错误诊断（DiagnosticsEngine）：即时分析 Luau 引擎错误（C0 is read only、attempt to index nil、HttpDisabled 等），为 AI 助手提供现成的修复代码（suggestedFix）和建议。

6. 4 级动态能力解析（UniversalCapabilityEngine）：一条命令可通过直接工具、工作流模板、编译原语或自主规划器来解析。

7. 双向安全 HTTP/HTTPS 桥接：在 Studio 插件与 Node.js 服务器之间实现即时事件监听（LogService、错误、选择变更），并支持 ChangeHistoryService 撤销/重做（Ctrl+Z）安全性。

🏛️ 架构与 11 个专用提供程序（Provider）

Universal Roblox MCP 不是使用单一的静态工具列表，而是通过 11 个专业化提供程序（IProvider）和一个**中央能力路由器（CapabilityRouter）**来运行：

                      ┌────────────────────────────────────────────────────────┐
                      │             AI Client (Claude / Cursor)                │
                      └──────────────────────────┬─────────────────────────────┘
                                                 │ MCP (JSON-RPC)
                                                 ▼
                      ┌────────────────────────────────────────────────────────┐
                      │         Universal Roblox Studio MCP Router             │
                      │           (UniversalCapabilityEngine)                  │
                      └───────┬──────────────────┬───────────────────┬─────────┘
                              │                  │                   │
         ┌────────────────────┴───┐     ┌────────┴────────┐   ┌──────┴────────────────┐
         │ 1. Embedded Plugin     │     │ 2. Official MCP │   │ 3-11. Specialized     │
         │    (HTTP/HTTPS Bridge) │     │ (StudioMCP.exe) │   │       Domain Engines  │
         └────────────┬───────────┘     └────────┬────────┘   └──────┬────────────────┘
                      │                          │                   │
                      │ Polling RPC              │ Stdio / WS        │ Logic & Templates
                      ▼                          ▼                   ▼
    ┌──────────────────────────────────────────────────────────────────────────────────┐
    │                               Roblox Studio Session                              │
    │  • DataModel Tree    • Luau ScriptEditor    • Viewport Framebuffer  • Simulation │
    └──────────────────────────────────────────────────────────────────────────────────┘

11 个提供程序层：

1. EmbeddedPluginProvider：与 Roblox Studio 内的本地插件通信，管理 36 个基础原语。

2. OfficialRobloxMCPProvider：连接到 Roblox 官方 StudioMCP.exe 二进制文件，执行受限的 3D、Asset 和 Playtest 命令。

3. ModelingProvider：协调 3D 网格、PBR 材质和程序化部件装配。

4. AnimationProvider：管理动画片段、播放器控制和骨骼摆姿。

5. LuauProvider：提供 Luau 静态分析、语法验证和安全代码执行。

6. WorkflowProvider：以模板形式实现复合游戏系统（昼夜循环、Leaderstats、岛屿生成器等）。

7. AssetProvider：从 Creator Store 和云库存中获取/插入模型、声音和视觉资源。

8. TestingProvider：管理自动化场景测试、虚拟键盘/鼠标输入和验证流程。

9. DiagnosticsProvider：监控 Studio 输出，进行根因分析，并建议安全修复。

10. ObservationProvider：管理视口屏幕捕获和视觉检查。

11. DesignProvider：审查空间美学、色彩协调和设计规则。

🧱 层级与组件优先构建（"+" 范式）

Roblox Studio 中经验丰富的开发者不会用单个庞大的 Luau 脚本程序化地生成一切。相反，他们采用**基于组件与层级（Component-Driven）**的开发方式。我们的系统通过 5 阶段行业标准层级来创建对象：

[Katman 1: Mekansal İskelet]  ───▶ Model / Folder / Frame / Parts / Meshes / PrimaryPart
            ↓
[Katman 2: Görsel & Duyusal]  ───▶ PBR Materials / PointLight / Particles / Sounds / SurfaceGui
            ↓
[Katman 3: Etkileşim & Fizik] ───▶ ProximityPrompt / HingeConstraint / WeldConstraint / Attachments
            ↓
[Katman 4: Animasyon & Donanım]──▶ KeyframeSequence / Motor6D Poses / Tool Grip Calibration
            ↓
[Katman 5: Ayrık Mantık]      ───▶ Sadece sinyalleri dinleyen hafif ve modüler Luau Controller

现成组件模板（component_compose）：

• interactive_door：木质门框（Frame）、铰链（HingePart）、门板（DoorPanel）、ProximityPrompt、开门音效（Sound）、TweenService 控制器和自定义 Attributes（IsOpen、OpenAngle）。

• collectible_coin：旋转圆柱硬币、金属材质、金色 PointLight、Sparkles、拾取音效和 CollectionService 标签。

• equippable_weapon：校准的 Tool.Grip、RightGripAttachment、Handle、挥动音效、挥击轨迹（Trail）和激活脚本。

• interactive_chest：固定宝箱主体、可开合盖子（ChestLid）、HingeConstraint、ProximityPrompt、金色光芒和 LootTable 属性。

• streetlamp_fixture：金属灯柱、玻璃灯罩、PointLight、SpotLight、Neon 材质和昼夜自动光感传感器。

• teleporter_pad：传送平台、粒子光束（ParticleEmitter 和 Beam）、传送音效和目标坐标。

• dialogue_npc：摆好姿势的 R15/R6 角色、BillboardGui 名称标签、对话 ProximityPrompt 和对话树。

🛡️ 受限与官方 MCP 路由树（Restricted Taxonomy）

出于安全考虑，Roblox 引擎对第三方插件限制某些 API（RobloxSecurity、RobloxScriptSecurity、SensitiveInput、Capture）。我们的系统通过 RestrictedCapabilityRegistry 自动识别这些限制，并直接路由到官方 StudioMCP.exe 代理：

RESTRICTED / OFFICIAL-ONLY (12 Kategori)
├── 1. RobloxSecurity                   ──▶ official-roblox-mcp (execute_luau / search_game_tree)
├── 2. RobloxScriptSecurity             ──▶ official-roblox-mcp (script_grep / execute_luau)
├── 3. Internal Studio APIs             ──▶ official-roblox-mcp (get_studio_state, list_roblox_studios)
├── 4. Internal Engine APIs             ──▶ official-roblox-mcp (generate_mesh / get_console_output)
├── 5. Internal Plugin APIs             ──▶ official-roblox-mcp (internal plugin manager)
├── 6. Protected Debug APIs             ──▶ official-roblox-mcp (get_console_output)
├── 7. Protected Studio Control APIs    ──▶ official-roblox-mcp (start_stop_play [Play/Run/Stop])
├── 8. Missing Sandbox Capabilities     ──▶ official-roblox-mcp (screen_capture, keyboard/mouse input)
├── 9. Restricted Asset APIs            ──▶ official-roblox-mcp (generate_mesh, generate_material, search_asset)
├── 10. Restricted HTTP APIs            ──▶ official-roblox-mcp (Cloud Auth HTTP)
├── 11. Internal Network APIs           ──▶ official-roblox-mcp (Replication diagnostics)
└── 12. Provider-Specific Capabilities  ──▶ official-roblox-mcp (subagent, execute_luau)

🧠 自愈诊断引擎（Self-Healing Diagnostics）

AI 模型在运行代码时可能会遇到常见的 Roblox API 错误。DiagnosticsEngine 会捕获这些错误，并直接为 AI 生成可用的解决方案：

🛠️ 全面的 MCP 工具列表（63+ 工具）

1. 视觉构建与动画工具

• component_compose：使用现成模板构建完整组件（门、宝箱、硬币、NPC 等）。

• component_template_list：列出所有可用的组件模板及其层级树。

• hierarchy_scaffold：按专业行业标准将 Studio 项目划分为文件夹。

• tool_grip_calibrate：自动校准武器和物品在角色手中的握持角度（Tool.Grip）。

• rig_pose_and_animate：安全地为 R15/R6 角色关节（Motor6D）摆姿。

2. 官方 Roblox MCP 工具（StudioMCP.exe 集成）

• generate_mesh：从自然语言提示生成 Roblox Cloud AI 3D 网格。

• generate_material：从自然语言提示生成 PBR 材质和纹理。

• generate_procedural_model：创建程序化部件装配。

• search_asset 和 insert_asset：从 Creator Store 和云库中搜索并插入资源。

• screen_capture：从 Studio 3D 视口捕获高分辨率屏幕截图。

• start_stop_play：物理启动游戏（Play/Run）或返回编辑模式（Stop）。

• get_studio_state：查询 Studio 会话、打开的文档和活动模拟模式。

• list_roblox_studios 和 set_active_studio：列出正在运行的 Studio 窗口并选择活动窗口。

• character_navigation：在模拟期间将角色移动到 3D 世界坐标。

• user_keyboard_input 和 user_mouse_input：在硬件层面将按键和鼠标点击注入模拟。

• script_read、multi_edit、script_search、script_grep：通过 Studio 脚本编辑器进行本地多文件编辑和搜索。

• subagent 和 execute_luau：运行 Roblox 本地子代理和 Luau 代码执行引擎。

3. 基础 DataModel 与原语工具

• studio_info、studio_get_tree、studio_search、studio_inspect：DataModel 层级扫描和深度属性检查。

• instance_create、instance_delete、instance_clone、instance_reparent、instance_rename、instance_move：对象生命周期和 3D 定位。

• property_get、property_set、property_get_all：带自动 Luau 类型转换的属性读写。

• attribute_get、attribute_set、attribute_delete、attribute_get_all：属性（Attribute）管理。

• script_get_source、script_set_source、script_patch_source、script_search_code：脚本源码读取、逐行补丁和代码搜索。

• selection_get、selection_set、selection_add、selection_clear：Studio Explorer 选择控制。

• output_get、output_get_errors、output_clear：输出日志和错误捕获。

• terrain_fill_block、terrain_fill_ball、terrain_clear：Voxel Terrain 创建和清除。

• batch_execute：在单个操作中原子执行多个命令（支持 Undo/Redo 检查点）。

🚀 快速安装与入门

1. 环境要求

• Node.js：v18.0.0 或更高版本（推荐 v20+ / v24）。

• Roblox Studio：已安装在 Windows 或 macOS 上。

2. 克隆仓库并构建

git clone <repo-url>
cd "Roblox Studio MCP"
npm install
npm run build

3. 安装 Roblox Studio 插件

您可以通过以下两种方法之一安装插件：

方法 A：复制现成的插件文件（推荐）

运行 npm run bundle:plugin 和 node scripts/build-rbxmx.js 命令（或直接复制编译好的文件）：

• Windows：将 plugin-build\RobloxUniversalMCP.rbxmx 文件复制到 %LOCALAPPDATA%\Roblox\Plugins\ 目录。

• macOS：将 plugin-build/RobloxUniversalMCP.rbxmx 文件复制到 ~/Library/Application Support/Roblox/Plugins/ 目录。

方法 B：在 Studio 内手动安装

1. 在 Roblox Studio 中打开任意一个 Place。

2. 将 plugin-build/RobloxUniversalMCP.luau 文件的内容粘贴到一个 Script 中。

3. 右键点击 Script，选择 "Save as Local Plugin..." 选项。

4. 在 Home > Game Settings > Security 部分中，启用 "Allow HTTP Requests" 选项。

🤖 AI 客户端配置（适用于所有电脑的通用安装）

为了在任何电脑上稳定且可移植地运行，提供了 3 种不同的通用方法：

🌟 方法 1：全局 CLI 注册（推荐 — 在所有电脑上只需一行！）

在项目文件夹中运行一次 npm link，将系统注册为全局命令：

npm run build
npm link

现在，在 Claude Desktop、Cursor 或任何 MCP 客户端中，您无需再输入任何文件路径：

Claude Desktop（claude_desktop_config.json）

• Windows：%APPDATA%\Claude\claude_desktop_config.json

• macOS：~/Library/Application Support/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "roblox-universal-studio": {
      "command": "roblox-studio-mcp"
    }
  }
}

🚀 方法 2：Cursor / VS Code 通用工作区（${workspaceFolder}）

在 Cursor 或 VS Code 中打开项目时，将其添加到 .cursor/mcp.json 或 .vscode/mcp.json 文件中。无论在哪台电脑上打开，${workspaceFolder} 都会自动被检测到：

{
  "mcpServers": {
    "roblox-universal-studio": {
      "command": "node",
      "args": [
        "${workspaceFolder}/dist/index.js"
      ]
    }
  }
}

📁 方法 3：直接指定文件路径运行

如果您想直接调用编译好的 dist/index.js 文件，而不是使用全局 CLI：

{
  "mcpServers": {
    "roblox-universal-studio": {
      "command": "node",
      "args": [
        "<PROJE_KLASORUNUZ_TAM_YOLU>/dist/index.js"
      ]
    }
  }
}

（示例 Windows：C:\\Projects\\Roblox-Studio-MCP\\dist\\index.js | macOS：/Users/username/Projects/Roblox-Studio-MCP/dist/index.js）

📊 实时遥测和 Studio 界面

插件加载后，Roblox Studio 中会打开一个专用的 DockWidget（DiagnosticsView）：

• Plugin Runtime：ONLINE / STANDALONE

• MCP Bridge：CONNECTED（绿色）/ DISCONNECTED（红色）

• Capabilities Discovered：80+ Live Capabilities（所有提供程序和子系统）

• Low-Level Tools：57 个原始工具

• High-Level Workflows：19 个复合工作流

• Total Universal Tools：76 个通用工具

• Active Mode：CHAT | OBSERVE | BUILD | PLAYTEST | AUTONOMOUS

🧪 测试与验证

要运行完整的测试套件：

npm test

测试输出：

✔ Tool Registry contains all universal tools
✔ HTTP Bridge Status returns disconnected when no session is active
✔ HTTP Bridge Handshake registers studio session
✔ Executing a command dispatches over polling RPC and resolves with response
✔ 11 Providers are registered and operational in ProviderRegistry
✔ Universal Capability Engine resolves across 4-tier hierarchy
✔ MultiModeEngine handles operating mode transitions and permissions
✔ Live Dashboard endpoint returns comprehensive real-time telemetry
✔ Visual Construction Engine lists rich archetypes and templates
✔ Animation Authoring Engine calibrates tool grips and keyframe sequences

📄 许可证

本项目基于 MIT 许可证 授权。祝您享受 Roblox Studio 与 AI 原生游戏开发的体验！🎮⚡