# NOTE: This is from 'C:\Users\User\Desktop\VSCode2\RobloxStudio-MCP-GoogleAntigravity\references\robloxstudio-mcp-main'.

# Roblox Studio MCP Server (Node.js/TypeScript) System Mechanics

This document provides a detailed breakdown of the system architecture and mechanics for the `robloxstudio-mcp` project, which facilitates communication between an LLM Client (like Claude or Cursor) and Roblox Studio.

## Architecture Diagram

Below is a detailed Mermaid sequence diagram illustrating the lifecycle of a tool request in this environment.

```mermaid
sequenceDiagram
    participant LLM as LLM Client (Claude/Cursor)
    participant MCP as Node.js MCP Server (stdio)
    participant Bridge as BridgeService (Memory)
    participant HTTP as Express HTTP Server (:port)
    participant Plugin as Roblox Studio Plugin (Luau)

    note over LLM,Plugin: 1. Setup Phase
    HTTP-->>Plugin: Setup Endpoints (/health, /poll, /response)
    Plugin->>HTTP: POST /ready (Initialize Connection)
    HTTP->>Bridge: bridge.clearAllPendingRequests()

    note over LLM,Plugin: 2. Long Polling Loop
    loop Every few seconds or immediately after a response
        Plugin->>HTTP: GET /poll
        HTTP->>Bridge: getPendingRequest()
        alt No pending request
            HTTP-->>Plugin: empty response (after delay/timeout)
        else Has pending request
            HTTP-->>Plugin: JSON { request, requestId }
        end
    end

    note over LLM,Plugin: 3. Tool Execution Lifecycle
    LLM->>MCP: CallTool (e.g., get_file_tree)
    MCP->>Bridge: sendRequest(endpoint, data)
    Bridge->>Bridge: generate UUID & store in pendingRequests Map
    
    note right of HTTP: The next long poll from Plugin hits...
    Plugin->>HTTP: GET /poll
    HTTP->>Bridge: getPendingRequest()
    Bridge-->>HTTP: oldest pending request
    HTTP-->>Plugin: Return Request Payload (requestId, tool data)
    
    note over Plugin: Evaluates request & interacts with Roblox DataModel

    Plugin->>HTTP: POST /response { requestId, response, error }
    HTTP->>Bridge: resolveRequest(requestId, response)
    Bridge->>Bridge: Match UUID, trigger promise resolve
    Bridge-->>MCP: Return result
    MCP-->>LLM: Return CallToolResult
```

## Detailed Discussion

### Components Overview

1. **MCP Server over stdio (`src/index.ts`)**:
   The core entry point utilizes the `@modelcontextprotocol/sdk` to expose Roblox Studio capabilities to AI assistants via Standard AI standard input/output streams (`stdio`). It initializes various available tools (like `get_file_tree`, `search_files`, `edit_script_lines`, etc.) and maps them to functions in `RobloxStudioTools`.

2. **BridgeService (`src/bridge-service.ts`)**:
   Since standard LLMs cannot execute HTTP requests directly into the Roblox Studio execution context, a "Bridge" is required. The `BridgeService` stores requests originating from the LLM in memory utilizing a `Map<string, PendingRequest>`. It assigns a `uuidv4` identifier to each request, resolving or rejecting Javascript Promises when Roblox Studio responds or naturally timing out after 30 seconds.

3. **Express HTTP Server (`src/http-server.ts`)**:
   Exposed locally, this server creates standard REST API endpoints mapping to the bridge context:
   - `/ready` and `/disconnect`: Manage lifecycle awareness for the connected plugin.
   - `/poll`: The crucial endpoint for the long-polling architecture. The Roblox Studio plugin continuously sends GET requests here. If a request exists, it returns immediately; otherwise, it waits/cycles to keep the network open without overwhelming the LLM client.
   - `/response`: Where the plugin submits the results of executed queries natively run inside Studio.
   - Various `/mcp/*` endpoints exist natively simulating the tools routing.

4. **Roblox Studio Plugin (`studio-plugin/src/...`)**:
   Written in Luau. Because Roblox restricts incoming connections for security, the plugin utilizes `HttpService` to make outgoing requests to the local Express server. It intercepts the HTTP Polling results, runs internal Studio SDK functions (e.g., getting hierarchical Place structures, updating script source code), and uses `/response` to fire the feedback back up the chain.

### Core Mechanics

- **Asynchronous Execution Gap Check**: The Node.js application is cleanly divided between the immediate `stdio` processing required by AI environments and the delayed networking constraints of `HttpService` in Roblox. The Promise architecture in the `BridgeService` forces the LLM to patiently await a complete trip through the local REST API and back.
- **Robust Toolset**: Uniquely among implementations, the TS-based server opts to fully define over 30 distinct granular tools (e.g., `insert_script_lines`, `mass_create_objects`) rather than primarily depending on evaluating raw Luau injected as strings. This gives the AI safer, strictly structured constraints to work within instead of writing custom engine scripts consistently over REST.