# Raven Roblox MCP

[![verify](https://github.com/valrinx/raven-roblox-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/valrinx/raven-roblox-mcp/actions/workflows/ci.yml)
![Node 22+](https://img.shields.io/badge/node-22%2B-339933)
![MCP](https://img.shields.io/badge/MCP-Streamable_HTTP_%2B_STDIO-7c3aed)

A clean-room Roblox MCP bridge owned by N3zuui. Raven connects Codex and other MCP clients to an authorized live Roblox client through a private loopback-only daemon.

## Install in one command

Requirements: Windows, Node.js 22+, Codex, Roblox, and an executor you are authorized to use.

```powershell
npx -y github:valrinx/raven-roblox-mcp#main setup codex
```

The installer configures `raven_roblox`, starts the shared daemon, and prints this connector loader:

```luau
loadstring(game:HttpGet("http://127.0.0.1:17654/loader.luau"))()
```

Restart Codex once after initial setup. That is the entire installation—no clone, manual build, JSON editing, or separate server per chat.

Full Codex instructions: [docs/CODEX.md](docs/CODEX.md). Problems: [docs/TROUBLESHOOTING.md](docs/TROUBLESHOOTING.md).

## Why Raven is different

- One singleton daemon on `127.0.0.1:17654`; every Codex chat/agent shares the same Roblox connection.
- A tiny STDIO proxy auto-starts or attaches to the daemon, eliminating port conflicts between agents.
- Accurate public place/experience names through cached `MarketplaceService:GetProductInfo(game.PlaceId)` metadata. Internal `game.Name` is exposed separately as `dataModelName`.
- Smooth-by-default connector: delayed startup, duplicate-launch guard, 2 ms cooperative work slices, 15-second heartbeat, and error-only console forwarding.
- Persistent per-user loopback token, so the connector automatically reconnects after daemon restarts.
- No telemetry, analytics, remote updater, external decompiler, or third-party Roblox API calls.
- Multiple Roblox clients with explicit active-client routing.
- Stateless Streamable HTTP MCP endpoint at `/mcp`, plus STDIO compatibility through the proxy.

## Architecture

```text
Codex chat A ─┐
Codex chat B ─┼─ STDIO proxies ── Streamable HTTP /mcp ─┐
Codex agent C ┘                                         │
                                                       ▼
                                            Raven daemon :17654
                                             │              │
                                  /loader.luau│              │/dashboard
                                             ▼              ▼
                                      Roblox connector   Browser UI
```

The daemon binds only to `127.0.0.1`. Roblox receives the WebSocket token from the locally served connector; the token is never committed to Git.

## Useful commands

```powershell
# Configure Codex and start Raven
npx -y github:valrinx/raven-roblox-mcp#main setup codex

# Check server, MCP endpoint, and connected Roblox clients
npx -y github:valrinx/raven-roblox-mcp#main doctor

# Print only the Roblox loader
npx -y github:valrinx/raven-roblox-mcp#main loader

# Run the shared daemon visibly
npx -y github:valrinx/raven-roblox-mcp#main daemon
```

Dashboard: [http://127.0.0.1:17654/dashboard](http://127.0.0.1:17654/dashboard)

## Capabilities

### Live inspection and control

- Smart snapshots of game, player, nearby world, visible UI, and console
- Bounded instance search, property inspection, and hierarchy trees
- Visible UI dump and button activation
- Player state, teleport, interaction, waits, benchmarks, and screenshots
- Atomic typed property mutations with rollback
- Sequential or parallel batches of up to 50 operations

### Authorized reverse engineering

- Unified bounded behavior traces for transient instance lifecycle, selected
  properties, remote calls, console entries, and explicit experiment markers
- Script indexing, search, bytecode metadata, closure/constants/prototype inspection
- Luau v3-v12 bytecode parser with Roblox opcode-decoder auto-detection
- Instruction disassembly, register-oriented pseudo code, and control-flow graphs
- Evidence-scored VM-obfuscation signals and snapshot-driven regression plans
- Unified bounded behavior graph across scripts, callsites, remotes, UI, and state effects
- Controlled-repeat scoring against no-action runs, with explicit non-causal semantics
- Direct controlled comparison of completed causal sessions and their runtime fingerprints
- Bounded semantic alias registry with hash history and conservative conflict resolution
- Static virtual-dispatch slices with PC ranges and effect-boundary graphs
- Automatic hypothesis-session creation from changed snapshot regions
- Runtime-to-static attribution with ranked effect PCs and explicit non-exact semantics
- Time-decayed graph confidence and bounded evidence-refresh queues
- Deduplicated hypothesis sessions generated from graph refresh queues
- Executor/runtime capability audit with readiness, blind spots, and evidence fallbacks
- Evidence-aware next-strategy recommendation with explicit stop conditions and no automatic action
- Source-line reconstruction from Luau relative/baseline debug metadata when present
- Optional debug local/upvalue names with PC lifetimes and line-aware static candidate ranking
- Ambiguity-aware PC confidence separated from higher-confidence source-line attribution
- Bounded whole-program nested prototype analysis with explicit child/closure graphs
- Bounded restart-resilient prototype registry that preserves genuine serialized debug-name evidence without inventing names for anonymous functions; its local atomic store keeps hashes and diff fingerprints only (25 scripts, 200 prototypes/version, 10 versions, 10 MB), never bytecode, instructions, disassembly, or runtime traces
- Differential whole-program fingerprints across bytecode hashes (opcode/effect/VM changes), with anonymous matches explicitly marked tentative
- Read-only visible UI → registered closure → script/source evidence graphs when the executor exposes signal connections
- Runtime source-line correlation from registered UI closures to ambiguity-aware serialized prototype candidates
- Same-line static effect-boundary candidates extending UI evidence paths through prototype to CALL/NAMECALL/API boundaries without claiming execution
- Bounded behavioral closure constants and direct/shallow captured Instance upvalues, inspected without invoking registered callbacks
- Class-evidenced closure capture semantics for tools, UI, modules, remotes, and generic instances (for example hotbar button closures capturing their corresponding Tool)
- Controlled UI observation orchestration (`prepare → external/user action → finish`) that combines structural UI evidence with causal-session traces while never clicking on the user's behalf
- Before/after visible-UI fingerprints and ScreenGui-level transient monitoring so panels created or revealed by an action are observable beyond the clicked button itself
- Comparison-eligibility guard: controls are explicit, while action runs require confirmed/direct action evidence before they can affect repeatability scores
- Passive UI signal experiments that never activate the target: temporary `GuiButton.Activated` listeners produce direct action evidence, bounded no-signal control windows, daemon-restart hydration from connector memory, and role-validated repeated-action/control comparison
- Connector and daemon hydration retain up to 20 passive UI captures, matching the maximum size of one experiment plan; older evidence across multiple plans remains intentionally bounded and may be reported unavailable
- Connector reload/stop cancels armed captures and the active causal session before disconnecting, while experiment plans bind to the exact client/place/game/job origin so evidence cannot cross a teleport or server-session boundary accidentally
- UI experiment precondition fingerprints that reject comparisons across different effect-root states (for example opening versus closing the same toggle button), plus a bounded action-arm timeout to prevent indefinitely stale baselines
- Root-scoped visible-UI collection for experiment baselines, so unrelated large interfaces cannot exhaust the global item budget before the target ScreenGui is fingerprinted
- Opt-in, local-only high-confidence evidence summaries with an allowlisted schema, 100-record/1 MB bounds, atomic replacement with in-memory rollback on write failure, restart recovery, explicit per-ID deletion, and no raw traces, console output, bytecode, or UI dumps
- A restart-resilient daemon-local UI experiment orchestrator that freezes the initial precondition, interleaves controls/actions, emits exact passive-capture arguments, and accepts only ordered finished captures whose path, role, eligibility, and precondition all match; its bounded local file contains plan metadata and capture IDs only, never raw evidence, failed writes roll memory back, and attribution stays gated until every ID is available or explicitly reconciled from matching connector evidence
- One-step experiment advancement: control windows arm, finish, normalize, and attach automatically without activating UI; action windows persist as pending and explicitly wait for one real user activation before the next advance. Cancel cleans pending connector state, and completed/cancelled plans support transactional exact-ID deletion
- Long-lived UI observations default to structural/UI evidence only; remote serialization requires explicit opt-in, and behavior traces restore only remote-monitor state they enabled themselves
- Passive `Activated` capture with a temporary listener and automatic short causal window; Raven observes the real user action but never invokes the button
- Controlled comparison of repeated UI-action observations against no-action controls across remote, instance, state, and structural UI fingerprints
- Evidence-completeness and uncertainty audit separating executor capability from current observations, freshness, ambiguity, hard limits, and prioritized minimal recapture actions
- Conservative VM classification using descriptive debug names and weak slices as counter-evidence
- Capability preflight with actionable stale daemon/connector diagnostics
- Status-level compatibility report for daemon version, connector version, and missing core capabilities
- Evidence-scored cross-script dependency graph
- Bounded remote monitoring, argument-schema clustering, replay, and snapshots/diffs
- Evidence-scored remote callsite attribution using the calling script and a
  bounded runtime stack when the executor exposes those APIs
- `find_remote_callsites` graph linking captured remotes to runtime callsites and
  exact or candidate indexed scripts with inspectable confidence/evidence
- Semantic symbol suggestions derived from paths, attributed remotes, and
  bounded runtime constants; suggestions are explicitly never claimed as
  original source identifiers
- Runtime FPS, memory, ping, class-count, and traversal profiling

### Evidence-driven behavior trace

Use `behavior_trace_control` when an object or effect may exist for only a few
frames, or when one action needs to be correlated with remote traffic:

1. Start a trace with narrow roots such as `game/Workspace/RedShow` and select
   only the properties needed for the hypothesis.
2. Add a marker immediately before the authorized test action.
3. Perform the action once.
4. Read `get_behavior_trace` incrementally and stop the trace.

The trace is retained only in bounded client memory (100–5,000 events). Instance
creation/removal records include lifetime when Raven observed both boundaries.
Starting a new trace disconnects prior trace listeners; stopping or unloading the
connector cleans them up.

Use `causal_session_control` to wrap one controlled experiment. `start` captures
the before snapshot and opens a trace; `mark` records an action boundary without
performing the action; `finish` captures after state, closes the trace, computes
the snapshot diff, and groups observations into marker windows. Results explicitly
label temporal correlation as non-causal until controlled repetition or direct
callsite evidence supports a stronger conclusion.

The daemon-local hypothesis tools encode Raven's troubleshooting guardrails:
every attempt requires current evidence, an unchanged strategy cannot be retried
without new evidence, one strategy is limited to two attempts, failures require
an updated hypothesis, and three distinct failed strategies move the session to
`review_required` instead of permitting more guesses. Sessions remain bounded to
20 and survive Roblox connector reconnects while the daemon stays running.

Pseudo code is an evidence-oriented representation, not claimed source recovery. Original identifiers, comments, formatting, and some high-level constructs do not exist in bytecode.

## Recommended agent workflow

1. Call `status`, then `list_clients`.
2. Use `smart_snapshot` for initial orientation.
3. Narrow with `query_instances`, `inspect_instance`, `get_tree`, or `dump_visible_ui`.
4. Use `batch` for related reads.
5. Use mutation and remote-replay tools only when a live change is explicitly intended.

## Build from source

```powershell
git clone https://github.com/valrinx/raven-roblox-mcp.git
cd raven-roblox-mcp
npm ci
npm run check
npm run privacy:audit
npm audit
```

Run locally:

```powershell
npm start
```

## Security and scope

Raven is intended only for experiences, clients, and accounts you own or are explicitly authorized to test. `execute_luau`, remote replay, teleport, UI interaction, and property mutation can change live client state. See [SECURITY.md](SECURITY.md) for the complete security model.

## Ownership and license

Raven's Roblox bridge, RPC protocol, tool schemas, security limits, bytecode analysis, and connector were developed as a clean-room implementation. Runtime dependencies are the official MCP SDK, Zod, and `ws`.

Copyright © 2026 N3zuui. Source-available for lawful use and private modification; redistribution, resale, relicensing, and removal of attribution are restricted. See [LICENSE](LICENSE).