# Vision Roblox MCP

Vision is a local Roblox Studio automation workbench and MCP server. It combines four backends instead of forcing every operation through one fragile channel:

| Backend | Owns |
| --- | --- |
| Vision Studio plugin | Durable scene edits, undo recordings, approvals, retries, snapshots, properties, tags, grouping, and selection |
| Roblox Studio native MCP | Deep inspection, script tools, Luau execution, asset generation, viewport capture, playtesting, and input simulation |
| Rojo 7 | Source-controlled Luau files, live source sync, builds, and sourcemaps |
| Vision MCP | One Codex-facing tool and resource surface that routes across the other three |

The API and browser UI bind to `127.0.0.1`. Vision does not use Roblox browser cookies. Open Cloud keys stay in the ignored local `.env` file.

## What It Can Do

- Inspect up to 2,500 instances per Studio snapshot, including common properties, attributes, tags, scripts, selection, service ownership, and spatial data.
- Queue named tasks with `queued`, `leased`, `succeeded`, `failed`, and `cancelled` states.
- Retry failed tasks without losing history and recover leases after a Studio interruption.
- Apply task groups as Studio undo recordings through `ChangeHistoryService`.
- Create, move, clone, rename, pivot, group, ungroup, tag, select, focus, edit, and delete instances.
- Edit open scripts safely through `ScriptEditorService` and apply exact source patches.
- Insert approved assets, publish supported local assets through Open Cloud, and retain an audit trail.
- Connect to Roblox's built-in Studio MCP and expose its discovered tools with Vision safety gates.
- Start, stop, build, scaffold, and inspect Rojo projects from the UI or MCP.
- Expose 13 Codex MCP tools, three resources, and a reusable build prompt over stdio.

## Install

Requirements: Node.js 20+, pnpm, Roblox Studio, and Windows PowerShell.

```powershell
pnpm install
powershell -ExecutionPolicy Bypass -File .\scripts\install.ps1
pnpm dev
```

Open [http://127.0.0.1:5173](http://127.0.0.1:5173), restart Roblox Studio, open the Vision plugin, and press **Sync Scripts**.

To enable Roblox's native MCP backend in a current Studio build:

1. Open Studio Assistant.
2. Click **...** and open **Manage MCP Servers**.
3. Enable **Studio as MCP server**.
4. Return to Vision and press **Connect** under Roblox native MCP.

The tracked [`.codex/config.toml`](./.codex/config.toml) configures both `vision_roblox` and Roblox's native `roblox_studio` server for Codex when the repository is trusted. Start the Vision API before asking Codex to use Vision tools.

## Commands

```powershell
pnpm dev          # UI on 5173 and API on 5174
pnpm test         # durable queue and lease regression suite
pnpm build        # type-check and production web build
pnpm mcp          # run the Codex-facing stdio MCP server
pnpm verify:mcp   # perform a real initialize/list handshake
pnpm start        # API only
```

## Safety Model

Vision classifies operations as read, write, destructive, code, asset, or playtest. Destructive edits, script changes/Luau execution, asset insertion, and playtest automation have separate switches. Native MCP mutation calls also require an explicit `approved` flag. Live mode only bypasses proposal creation for capabilities already enabled by those switches.

Studio changes use undo recordings whenever the plugin applies a task group. Task leasing prevents a failed request or Studio restart from silently deleting queued work.

## Documentation

- [Architecture](./docs/architecture.md)
- [Codex and MCP integration](./docs/chatgpt-codex-integration.md)
- [Roblox and Rojo limits](./docs/roblox-integration-limits.md)
- [Open Cloud setup](./docs/roblox-open-cloud-setup.md)
- [Studio plugin contract](./plugins/roblox-studio/README.md)

## Current Limits

- Roblox creates its native MCP launcher only after **Studio as MCP server** is enabled in Assistant. Restart Studio and Codex if a newly enabled server is not discovered.
- Studio plugins cannot write every protected or security-scoped property. Failed properties are reported against the task and remain retryable.
- Snapshot sync is capped at 2,500 scene objects. Native MCP inspection is the preferred path for larger places.
- Rojo owns files that are inside its project mapping. Use the Vision plugin for instances intentionally outside that mapping.
- Asset upload support follows Roblox Open Cloud's current supported types, permissions, size limits, moderation, and asynchronous operation behavior.

## License

MIT