⚡ Universal Roblox AI Studio — Autonomous Multi-Mode Capability MCP Platform

Universal Roblox AI Studio is a next-generation Model Context Protocol (MCP) runtime that transforms Roblox Studio into an AI-Native, autonomous, and bidirectional development platform for external AI coding assistants (Claude Desktop, Cursor, Antigravity, VS Code, etc.).

📖 Table of Contents

• 🌟 Core Features

• 🏛️ Architecture and 11 Specialized Providers

• 🧱 Hierarchy & Component-First Construction ("+ Sign" Paradigm)

• 🛡️ Restricted and Official MCP Routing Tree (Restricted Taxonomy)

• 🧠 Self-Healing Diagnostics Engine

• 🛠️ Comprehensive MCP Tool List (63+ Tools)

• 🚀 Quick Setup & Getting Started

• 🤖 AI Client Configurations (Claude Desktop / Cursor)

• 📊 Live Telemetry and Studio Interface

• 🧪 Testing and Validation

🌟 Core Features

1. 63+ First-Class Universal MCP Tools: DataModel hierarchy, Instance lifecycle, Luau script management, PBR materials, Voxel Terrain, Playtest simulation, 3D Generative AI, and Virtual Hardware input.

2. Official Roblox Studio MCP (StudioMCP.exe) Native Integration: Roblox's own official MCP client (%LOCALAPPDATA%\Roblox\Versions\...\StudioMCP.exe and mcp.bat) is auto-discovered, and restricted 3D/Asset/Playtest commands are routed directly to the official engine.

3. Component & Hierarchy-First Construction (VisualConstructionEngine): Instead of generating everything with massive scripts, it builds physical objects, constraints, lights, particles, and sounds layer by layer using the + (Insert Object) logic from Studio Explorer.

4. Advanced Animation & Hardware Calibration (AnimationAuthoringEngine): R15/R6 rig posing (Motor6D), joint safety, KeyframeSequence creation, and Tool.Grip calibration to ensure tools sit correctly in the character's hand.

5. Self-Healing Error Diagnostics (DiagnosticsEngine): Instantly analyzes Luau engine errors (C0 is read only, attempt to index nil, HttpDisabled, etc.) and provides ready-to-use fix code (suggestedFix) and recommendations to the AI assistant.

6. 4-Tier Dynamic Capability Resolution (UniversalCapabilityEngine): A command is resolved via a direct tool, a workflow template, compiled primitives, or an autonomous planner.

7. Bidirectional Secure HTTP/HTTPS Bridge: Real-time event listening between the Studio plugin and the Node.js server (LogService, errors, selection changes) with ChangeHistoryService Undo/Redo (Ctrl+Z) safety.

🏛️ Architecture and 11 Specialized Providers

Instead of a single static tool list, Universal Roblox MCP operates through 11 specialized providers (IProvider) and a Central Capability Router (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 Provider Layers:

1. EmbeddedPluginProvider: Manages 36 core primitives by communicating with the native plugin inside Roblox Studio.

2. OfficialRobloxMCPProvider: Connects to Roblox's official StudioMCP.exe binary to execute restricted 3D, Asset, and Playtest commands.

3. ModelingProvider: Coordinates 3D meshes, PBR materials, and procedural part assemblies.

4. AnimationProvider: Manages animation clips, player controls, and rig poses.

5. LuauProvider: Provides Luau static analysis, syntax validation, and safe code execution.

6. WorkflowProvider: Applies composite game systems (Day/Night, Leaderstats, Island Generator, etc.) as templates.

7. AssetProvider: Fetches/inserts models, sounds, and visual assets from the Creator Store and Cloud inventory.

8. TestingProvider: Manages automated scenario tests, virtual keyboard/mouse inputs, and validation processes.

9. DiagnosticsProvider: Monitors Studio output, performs root cause analysis, and suggests safe repairs.

10. ObservationProvider: Manages viewport screen capture and visual inspection.

11. DesignProvider: Audits spatial aesthetics, color harmony, and design rules.

🧱 Hierarchy & Component-First Construction ("+ Sign" Paradigm)

An experienced developer in Roblox Studio does not procedurally generate everything with a single massive Luau script. Instead, they use Component-Driven development. Our system builds objects in 5 stages following industry-standard layering:

[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

Ready-Made Component Templates (component_compose):

• interactive_door: Wooden frame (Frame), hinge (HingePart), door panel (DoorPanel), ProximityPrompt, opening sound (Sound), TweenService controller, and custom Attributes (IsOpen, OpenAngle).

• collectible_coin: Spinning cylinder coin, metal material, golden PointLight, Sparkles, collection sound, and CollectionService tag.

• equippable_weapon: Calibrated Tool.Grip, RightGripAttachment, Handle, swing sound, hit trail (Trail), and activation script.

• interactive_chest: Fixed chest body, opening lid (ChestLid), HingeConstraint, ProximityPrompt, golden glow, and LootTable attributes.

• streetlamp_fixture: Metal pole, glass lamp head, PointLight, SpotLight, Neon material, and Day/Night automatic light sensor.

• teleporter_pad: Teleportation platform, particle beam (ParticleEmitter & Beam), teleport sound, and target coordinates.

• dialogue_npc: Posed R15/R6 character, BillboardGui name tag, dialogue ProximityPrompt, and conversation tree.

🛡️ Restricted and Official MCP Routing Tree (Restricted Taxonomy)

For security reasons, the Roblox engine restricts certain APIs (RobloxSecurity, RobloxScriptSecurity, SensitiveInput, Capture) for third-party plugins. Our system automatically recognizes these restrictions via the RestrictedCapabilityRegistry and routes them directly to the official StudioMCP.exe proxy:

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 Engine

AI models can get stuck on common Roblox API errors while running code. The DiagnosticsEngine catches these errors and produces directly working solutions for the AI:

🛠️ Comprehensive MCP Tool List (63+ Tools)

1. Visual Construction & Animation Tools

• component_compose: Builds complete components (door, chest, coin, NPC, etc.) from ready-made templates.

• component_template_list: Lists all available component templates and their hierarchy trees.

• hierarchy_scaffold: Organizes the Studio project into folders following professional industry standards.

• tool_grip_calibrate: Automatically calibrates the grip angles (Tool.Grip) of weapons and items in the character's hand.

• rig_pose_and_animate: Safely poses R15/R6 character joints (Motor6D).

2. Official Roblox MCP Tools (StudioMCP.exe Integrated)

• generate_mesh: Generates Roblox Cloud AI 3D meshes from natural language prompts.

• generate_material: Generates PBR materials and textures from natural language prompts.

• generate_procedural_model: Creates procedural part assemblies.

• search_asset & insert_asset: Searches and inserts assets from the Creator Store and Cloud library.

• screen_capture: Captures high-resolution screenshots from the Studio 3D Viewport.

• start_stop_play: Physically starts the game (Play/Run) or returns to edit mode (Stop).

• get_studio_state: Queries the Studio session, open document, and active simulation mode.

• list_roblox_studios & set_active_studio: Lists running Studio windows and selects the active one.

• character_navigation: Moves the character to 3D world coordinates during simulation.

• user_keyboard_input & user_mouse_input: Injects hardware-level key presses and mouse clicks into the simulation.

• script_read, multi_edit, script_search, script_grep: Local multi-file editing and search via the Studio Script Editor.

• subagent & execute_luau: Runs Roblox's native sub-agent and Luau code execution engine.

3. Core DataModel & Primitive Tools

• studio_info, studio_get_tree, studio_search, studio_inspect: DataModel hierarchy scanning and deep property inspection.

• instance_create, instance_delete, instance_clone, instance_reparent, instance_rename, instance_move: Object lifecycle and 3D positioning.

• property_get, property_set, property_get_all: Property read/write with automatic Luau type conversion.

• attribute_get, attribute_set, attribute_delete, attribute_get_all: Attribute management.

• script_get_source, script_set_source, script_patch_source, script_search_code: Script source reading, line-based patching, and code search.

• selection_get, selection_set, selection_add, selection_clear: Studio Explorer selection control.

• output_get, output_get_errors, output_clear: Output log and error capture.

• terrain_fill_block, terrain_fill_ball, terrain_clear: Voxel Terrain creation and clearing.

• batch_execute: Atomic multi-command execution in a single operation (with Undo/Redo waypoint support).

🚀 Quick Setup & Getting Started

1. Requirements

• Node.js: v18.0.0 or higher (v20+ / v24 recommended).

• Roblox Studio: Installed on Windows or macOS.

2. Cloning the Repository and Building

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

3. Installing the Roblox Studio Plugin

You can install the plugin using one of two methods:

Method A: Copy the Ready-Made Plugin File (Recommended)

Run npm run bundle:plugin and node scripts/build-rbxmx.js (or copy the compiled files):

• Windows: Copy the plugin-build\RobloxUniversalMCP.rbxmx file to the %LOCALAPPDATA%\Roblox\Plugins\ directory.

• macOS: Copy the plugin-build/RobloxUniversalMCP.rbxmx file to the ~/Library/Application Support/Roblox/Plugins/ directory.

Method B: Manual Installation Inside Studio

1. Open any Place in Roblox Studio.

2. Paste the contents of the plugin-build/RobloxUniversalMCP.luau file into a Script.

3. Right-click the Script and select "Save as Local Plugin...".

4. Enable "Allow HTTP Requests" from Home > Game Settings > Security.

🤖 AI Client Configurations (Universal Setup for All Computers)

Three different universal methods are provided to run it consistently and portably on any computer:

🌟 Method 1: Global CLI Registration (Recommended — One Line on All Computers!)

Run npm link once in the project folder to register the system as a global command:

npm run build
npm link

Now you don't need to type any file path in Claude Desktop, Cursor, or any MCP client:

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"
    }
  }
}

🚀 Method 2: Cursor / VS Code Universal Workspace (${workspaceFolder})

When you open the project in Cursor or VS Code, add it to the .cursor/mcp.json or .vscode/mcp.json file. No matter which computer it opens on, ${workspaceFolder} is detected automatically:

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

📁 Method 3: Running by Specifying a Direct File Path

If you want to call the compiled dist/index.js file directly instead of the global CLI:

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

(Example Windows: C:\\Projects\\Roblox-Studio-MCP\\dist\\index.js | macOS: /Users/username/Projects/Roblox-Studio-MCP/dist/index.js)

📊 Live Telemetry and Studio Interface

When the plugin is loaded, a special DockWidget (DiagnosticsView) opens inside Roblox Studio:

• Plugin Runtime: ONLINE / STANDALONE

• MCP Bridge: CONNECTED (Green) / DISCONNECTED (Red)

• Capabilities Discovered: 80+ Live Capabilities (All providers and subsystems)

• Low-Level Tools: 57 Primitive Tools

• High-Level Workflows: 19 Composite Workflows

• Total Universal Tools: 76 Universal Tools

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

🧪 Testing and Verification

To run the full test suite:

npm test

Test output:

✔ 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

📄 License

This project is licensed under the MIT License. Enjoy the AI-native game development experience with Roblox Studio! 🎮⚡