<p align="center">
  <img src="docs/banner.svg" alt="Roblox Executor MCP" width="900"/>
</p>

# Roblox Executor MCP + Vyre Dashboard

An MCP server that lets AI agents drive a **running Roblox client** — execute Luau, decompile and search scripts, spy on remotes, walk the datamodel, automate the UI, and more — with **Vyre**, a modern local web dashboard on top.

> The upstream project went offline, so this is a maintained, installable distribution. Same engine, a fully redesigned dashboard, and new tools. MIT-licensed (see [LICENSE](LICENSE)).

## Vyre dashboard

Served locally at `http://localhost:16384/` once the server is running.

![Overview](docs/dashboard/overview.png)

<table>
<tr>
<td><img src="docs/dashboard/server.png" alt="Server topology"/></td>
<td><img src="docs/dashboard/scripts.png" alt="Scripts Explorer"/></td>
</tr>
<tr>
<td align="center"><b>Live relay topology</b></td>
<td align="center"><b>Studio-style script Explorer</b></td>
</tr>
</table>

<details>
<summary>More views — Tools, Logs, Settings</summary>

![Tools](docs/dashboard/tools.png)
![Logs](docs/dashboard/logs.png)
![Settings](docs/dashboard/settings.png)

</details>

### Dashboard highlights

- Floating **dock** navigation + **⌘K command palette** with grouped, highlighted results.
- **Mission-control overview** — hero client card, uptime ring, live stat tiles, quick actions, activity ticker.
- **Live relay topology** — animated MCP-core network graph with flowing packets and clickable client nodes.
- **Studio-style Scripts Explorer** — services → folders → scripts tree with a syntax-highlighted source viewer, plus the classic **Scripts Synced / Semantic Index** progress panels.
- **Grouped logs** — Activity vs System, level filters, search, and duplicate collapsing.
- **Embedding settings** — OpenAI / Ollama, save / test / clear, and a **"Suggest for my machine"** button that reads your GPU and recommends a local model.
- Six color themes, real player headshots, latency chip, snapshot export, and a demo mode.

## MCP features

- **Code execution** — run Luau and fetch data from the game client.
- **Script inspection** — decompile scripts, `script-grep`, and semantic (meaning-based) search.
- **Instance search** — CSS-like selectors and descendant trees.
- **Remote spy** — intercept, log, block, and ignore Remotes/Bindables (via [Cobalt](https://github.com/notpoiu/cobalt)).
- **UI + input automation** — click by text, fire ClickDetectors/ProximityPrompts, type, move the camera, path the character.
- **Screenshots** — capture the Roblox window (Windows only).
- **Multi-client** — connect several Roblox clients; primary/secondary instances auto-coordinate and can relay over a LAN with `--baseurl`.
- **~150 convenience tools** on top of the raw channel, plus the new intel tools below.

### New tools

| Tool | What it returns |
|---|---|
| `get-avatar-appearance` | A player's HumanoidDescription — body colors, scales, clothing, worn accessories |
| `count-instances-by-class` | Descendants grouped by ClassName under a root, largest-first |
| `list-nearby-players` | Other players sorted by distance, with health and team |
| `list-playing-sounds` | Currently playing Sounds with volume, live loudness, and path |
| `list-playing-animations` | Animation tracks playing on a player, with id, weight, speed, loop |
| `raycast-forward` | First instance hit by a ray from the camera — name, class, distance, material |

## Prerequisites

- **Node.js** ≥ 18
- **Bun** ≥ 1.3 for the interactive harness installer (auto-installed if missing)
- **A Roblox executor** with `loadstring`, `request`, and preferably `WebSocket`

## Quick start

### 1. Clone

```bash
git clone https://github.com/dedankschool-oss/roblox-executor-mcp.git
cd roblox-executor-mcp
```

### 2. Install into your AI client

The harness installer builds the server, lets you pick AI clients, writes their MCP configs, and prints the Roblox loader.

```bash
npm run install:harnesses
```

Trouble with the interactive picker? Use the plain prompt:

```bash
npm run install:harnesses -- --plain
```

It can also drop the loader into a detected executor autoexec folder:

```bash
npm run getscript -- --autoexec
```

Update an existing install later (stops running server processes, optionally pulls, always rebuilds):

```bash
npm run update
```

### Manual setup

Prefer to wire a client yourself? See the guide for your client:

| Client | Guide |
|---|---|
| Cursor | [Setup](docs/setup-cursor.md) |
| Claude Desktop | [Setup](docs/setup-claude-desktop.md) |
| Claude Code | [Setup](docs/setup-claude-code.md) |
| Codex CLI | [Setup](docs/setup-codex.md) |
| Windsurf | [Setup](docs/setup-windsurf.md) |
| Antigravity | [Setup](docs/setup-antigravity.md) |

Or run it directly:

```bash
npm run build
npm start
```

### 3. Connect from Roblox

Paste this into your executor (or Auto Execute):

```lua
local bridgeUrl = getgenv().BridgeURL or "localhost:16384"
loadstring(game:HttpGet("http://" .. bridgeUrl .. "/script.luau"))()
```

Optional settings (set before the `loadstring`):

```lua
getgenv().BridgeURL = "10.0.0.4:16384"               -- default: localhost:16384
getgenv().DisableWebSocket = true                     -- force HTTP polling
getgenv().DisableInitialScriptDecompMapping = true    -- skip initial decompilation
```

Then open the dashboard at `http://localhost:16384/`.

## Semantic search & embeddings

Semantic search turns decompiled scripts into vectors so you can search by meaning ("how does data saving work") instead of exact text. Pick a provider in **Settings → Embedding Provider**:

- **OpenAI** (`text-embedding-3-small`) — cloud, needs an API key, no local compute.
- **Ollama** — runs locally on your GPU, free and private.

For a decent GPU, local Ollama is great. Recommended models:

| Model | Notes |
|---|---|
| `mxbai-embed-large` | Highest quality; ideal if you have a dedicated GPU |
| `nomic-embed-text` | Fast, excellent for code; light on VRAM |
| `embeddinggemma` | Newer Google model; solid all-rounder |

```bash
ollama pull mxbai-embed-large
```

The dashboard's **"Suggest for my machine"** button detects your GPU and picks a model for you.

## Security

> **This server allows arbitrary code execution.** Only use it with AI clients you trust. Port `16384` has **no authentication — never expose it to the internet.** For cross-machine setups use a LAN, VPN, or SSH tunnel. See [Advanced](docs/advanced.md).

## License

[MIT](LICENSE). The original engine is MIT-licensed; that notice is retained in `LICENSE`.