robloxstudio-mcp

Implements a Model Context Protocol (MCP) server that registers 39 distinct tools (or 21 in inspector mode) as callable endpoints with JSON schemas, exposing them over stdio to AI assistants like Claude and Gemini. The RobloxStudioMCPServer class in packages/core/src/server.ts handles ListToolsRequestSchema and CallToolRequestSchema requests, dynamically loading tool definitions from TOOL_DEFINITIONS array and dispatching calls through a StudioHttpClient bridge. Tools are filtered at startup via getAllTools() or getReadOnlyTools() to enforce read-only vs read-write access policies.

Implements a localhost HTTP server (createHttpServer / BridgeService in packages/core/src/http-server.ts) on port 58741 that maintains an in-memory request queue and response map, keyed by UUID. When an MCP tool is called, the server enqueues the request; the Studio plugin polls /poll endpoint to fetch pending requests, executes them via Studio APIs, and posts results to /response endpoint. UUID tracking ensures responses are correctly correlated to requests even when multiple concurrent AI calls are in flight, enabling asynchronous coordination without WebSocket or persistent connections.

The robloxstudio-mcp-inspector package exposes only 21 read-only tools (vs 39 in the full package) by filtering TOOL_DEFINITIONS at startup using getReadOnlyTools(). Tools are tagged with category: 'read' or category: 'write' in the TOOL_DEFINITIONS array; the inspector package loads only 'read' tools, preventing any mutations (script edits, instance creation/deletion, property changes). This enables safe, read-only inspection of games without risk of accidental or malicious modifications.

Provides tools like GetClassMetadata and GetPropertyMetadata that return information about Roblox classes (Part, Model, Script, etc.) and their properties (type, default value, read-only status, etc.). These tools query the Studio's DataModel API to introspect class definitions and return structured JSON describing available properties, their types, and constraints. This enables AI to understand what properties are available on instances and what values are valid, reducing errors when setting properties or creating instances.

The HTTP bridge maintains UUID-keyed request and response maps that enable the MCP server to handle multiple concurrent AI requests without blocking or losing response correlation. When an MCP tool is called, the server generates a UUID, enqueues the request, and returns immediately; the Studio plugin polls /poll, fetches the request by UUID, executes it, and posts the result to /response with the same UUID. The MCP server retrieves the response by UUID and returns it to the AI. This architecture allows the MCP server to be stateless and the Studio plugin to be event-driven, with no persistent connections required.

The MCPPlugin.rbxmx Studio plugin (Lua code running inside Roblox Studio) implements a polling loop that periodically calls the /poll HTTP endpoint on localhost:58741, receives pending tool requests, dispatches them via a routeMap (a table mapping tool names to handler functions), executes the corresponding Studio API calls, and posts results back to /response. The plugin is stateless and event-driven, with no persistent connection to the MCP server, making it resilient to MCP server restarts.

Exposes tools like GetInstance, GetInstanceChildren, GetInstanceProperties, and DescribeInstance that allow AI to navigate the Roblox game hierarchy by path (e.g., 'Workspace/Baseplate/Part1') and inspect instance metadata, properties, and children. These tools use the Studio's DataModel API to traverse the object tree and return structured JSON describing instances, their properties, and their relationships. Path-based querying enables AI to understand game structure without loading the entire hierarchy into memory.

Provides tools like GetScript, SetScript, and InsertScript that allow AI to read Lua script source code from instances (LocalScripts, Scripts, ModuleScripts) and replace or insert new code. The SetScript tool takes an instance path and new source code, replacing the entire script source via the Studio API. InsertScript creates a new script instance at a given path with initial source code. This enables AI to generate, refactor, or debug Lua code directly within the game structure.

Provides tools like CreateInstance and DeleteInstance that allow AI to create new instances (Parts, Models, Scripts, etc.) at specified parent paths with optional initial properties, and delete instances by path. CreateInstance takes a parent path, class name (e.g., 'Part', 'Model', 'LocalScript'), and optional property dict (e.g., {Position: [0, 5, 0], Color: [1, 0, 0]}), and returns the path of the newly created instance. DeleteInstance removes an instance and its descendants by path. These tools enable AI to build game structure programmatically.

Provides tools like GetProperty and SetProperty that allow AI to read and write instance properties (Position, Color, Size, Transparency, etc.) by instance path and property name. GetProperty returns the current value as JSON; SetProperty takes a path, property name, and new value, and updates the property via the Studio API. The tools handle type coercion (e.g., converting JSON arrays to Vector3) and basic validation (e.g., ensuring Transparency is between 0 and 1). This enables AI to modify instance appearance and behavior without creating or deleting instances.

Integrates with the Roblox Open Cloud API (OpenCloudClient in packages/core/src/open-cloud-client.ts) to enable AI to search the Creator Store for assets (models, decals, audio, etc.) by keyword and insert them into the game. The SearchCreatorStoreAssets tool queries the Open Cloud API with a search term and returns matching assets with metadata (ID, name, description, thumbnail). The InsertCreatorStoreAsset tool inserts a selected asset into the game at a specified parent path. This enables AI to populate games with community-created assets without manual browsing.

Provides a PlaytestGame tool that launches a Studio playtest session, waits for completion, and collects output (print statements, errors, warnings) from the game's execution. The tool captures console output from the running game and returns it as structured JSON, enabling AI to understand game behavior and debug issues without manually reading the Output window. This enables AI to test game logic and iterate based on playtest results.

Provides tools like GetBuildLibraryAssets and InsertBuildLibraryAsset that allow AI to browse and insert pre-built game components (buildings, terrain, UI templates) from a local build library. The build library is a collection of .rbxm files with metadata (name, description, tags, version) stored in a JSON manifest. GetBuildLibraryAssets returns the list of available assets with metadata; InsertBuildLibraryAsset loads a selected asset file and inserts it into the game at a specified parent path. This enables AI to reuse pre-built components without creating them from scratch.