# Roblox MCP Server

A Model Context Protocol (MCP) server that acts as a bridge between AI assistants (like Claude/Gemini in IDEs) and a running Roblox instance. This allows the AI to inspect the game hierarchy, read scripts, and execute code directly within the Roblox client.

## Architecture

```mermaid
graph LR
    IDE["AI / IDE"] <-->|"MCP Protocol (Stdio)"| MCPServer["MCP Server (Node.js)"]
    MCPServer <-->|"WebSocket (ws://localhost:3000)"| Roblox["Roblox Client"]
    subgraph Roblox Client
        Bridge["Bridge.lua"]
        Game["Game Engine"]
    end
    Bridge <--> Game
```

The system consists of two parts:
1.  **MCP Server (`src/`)**: A Node.js application that implements the MCP specification. It hosts a WebSocket server to communicate with Roblox.
2.  **Roblox Bridge (`roblox/Bridge.lua`)**: A Lua script that runs inside a Roblox executor. It connects to the MCP server via WebSocket and executes commands.

## Prerequisites

*   **Node.js**: v18 or higher.
*   **Roblox Executor**: A Roblox script executor that supports:
    *   `WebSocket.connect` (or compatible `WebSocket` library).
    *   `getgenv()` (optional, for safe environment access).
    *   `decompile` (optional, for reading local scripts).
*   **npm** or **yarn**.

## Installation

1.  Clone the repository.
2.  Install dependencies:
    ```bash
    npm install
    ```

## Usage

### 1. Start the MCP Server

You can run the server in development mode or build it for production.

**Development:**
```bash
# Compile and run
npm run build && npm start
```

The server will start listening on `stdio` for MCP connections and `ws://localhost:3000` for the Roblox bridge.

### 2. Inject the Roblox Bridge

1.  Open your Roblox Executor.
2.  Open `roblox/Bridge.lua`.
3.  Execute the script in the desired Roblox game instance.
4.  Check the executor console (F9) for a connection message: `[MCP-Bridge] Connected!`.

## Available Tools

The MCP server exposes the following tools to the AI:

### `list_children`
Lists the children of a specific instance.
*   **Arguments**: `path` (string, e.g., "game.Workspace")
*   **Returns**: list of `{ name, className, path }`

### `get_properties`
Retrieves the properties of a specific instance.
*   **Arguments**: `path` (string), `properties` (array of strings, optional)
*   **Returns**: Map of property names to values.

### `read_script`
Reads the source code of a script.
*   **Arguments**: `path` (string)
*   **Returns**: Source code string.
*   **Notes:**
    *   Works for `LocalScript` and `ModuleScript` (client-side).
    *   **Cannot** read server-side `Script` source due to Roblox replication security (returns empty/error).

### `run_script`
Executes arbitrary Lua code in the context of the bridge script.
*   **Arguments**: `code` (string)
*   **Returns**: Array of return values converted to strings.

## Troubleshooting

*   **Server Code Access**: You cannot read server scripts from the client. This is a Roblox engine limitation, not a bug.
*   **Connection Failed**: Ensure port `3000` is free and the executor supports WebSockets (most modern ones do).
*   **Executor Compatibility**: If `WebSocket` is not defined, check your executor's documentation. You may need a polyfill.