# Roblox Studio MCP Bridge

Connect Kiro (or any MCP-compatible AI assistant) directly to Roblox Studio. Create, read, update, and delete scripts, list instances, execute Luau code, and inspect properties — all through natural language.

## Architecture

```
┌─────────┐       stdio        ┌────────────┐      HTTP       ┌─────────────────┐
│  Kiro   │ ◄──────────────► │  MCP Server │ ◄────────────► │  Relay Server    │
│  (AI)   │                    │  (index.js) │                 │  (relay-server)  │
└─────────┘                    └────────────┘                  └────────┬────────┘
                                                                        │
                                                                   HTTP polling
                                                                        │
                                                               ┌────────▼────────┐
                                                               │  Roblox Studio   │
                                                               │  Plugin (Lua)    │
                                                               └─────────────────┘
```

## Quick Start

```bash
# 1. Clone and install
git clone https://github.com/iknouee/roblox-studio-mcp.git
cd roblox-studio-mcp
npm install

# 2. Copy plugin to Roblox Studio plugins folder
# Windows: copy plugin\KiroMCPBridge.server.lua "%LOCALAPPDATA%\Roblox\Plugins\"
# Mac:     cp plugin/KiroMCPBridge.server.lua ~/Documents/Roblox/Plugins/

# 3. Enable HTTP Requests in Studio (Game Settings → Security → Allow HTTP Requests)

# 4. Start the relay server
npm run relay

# 5. Open Roblox Studio — plugin auto-connects!
```

## Available Tools

| Tool | Description |
|------|-------------|
| `create_script` | Create a Script, LocalScript, or ModuleScript |
| `read_script` | Read the source code of any script |
| `update_script` | Update an existing script's source code |
| `delete_script` | Delete a script instance |
| `list_instances` | List children of any instance (optional recursion) |
| `execute_luau` | Run arbitrary Luau code in Studio's plugin context |
| `get_properties` | Read properties of any instance |

## Instance Paths

Scripts and instances are referenced using dot notation:

```
ServerScriptService.MyScript
ReplicatedStorage.Modules.Utils
Workspace.Map.SpawnPoints
StarterPlayer.StarterPlayerScripts.CameraController
StarterGui.MainUI.Frame.Button
```

## Troubleshooting

| Problem | Fix |
|---------|-----|
| "Timeout waiting for Studio" | Make sure Studio is open AND relay server is running |
| Plugin not in toolbar | Re-copy the .lua file and restart Studio |
| "HTTP Requests are not enabled" | Game Settings → Security → Allow HTTP Requests = ON |
| npm install fails | Make sure Node.js 18+ is installed |
| Port 3001 in use | `RELAY_PORT=3002 npm run relay` |

## License

MIT