<div align="center">

# 🧊 Studio Bridge

**Connect Claude directly to Roblox Studio — fast, reliable, multi-session.**

An MCP (Model Context Protocol) server + Studio plugin that lets Claude build UI, edit scripts, run code, playtest and see your game — live, with zero configuration.

![Node](https://img.shields.io/badge/node-%E2%89%A518-339933?logo=node.js&logoColor=white)
![Platform](https://img.shields.io/badge/platform-Windows-0078D6?logo=windows&logoColor=white)
![Roblox Studio](https://img.shields.io/badge/Roblox-Studio-00A2FF?logo=roblox&logoColor=white)
![License](https://img.shields.io/badge/license-MIT-blue)

*by [JuanArtxz](https://github.com/juannastaken)*

</div>

---

## Why another Studio MCP?

Existing bridges break under real use. Studio Bridge was engineered around the failure modes that made them unusable on large projects:

| Problem elsewhere | Studio Bridge |
|---|---|
| Multiple Claude sessions fight over ports — agents time out | **One shared broker on one fixed port.** Any number of sessions multiplex through it, zero config |
| Slow commands get re-delivered and **execute 2-10×** | **Exactly-once leasing.** A command is handed to one poll and never re-delivered — if Studio freezes you get a clear error, never a duplicate |
| Big scripts corrupt in transit (`\n` escapes mangled) | **Verbatim transfer + 600 KB chunking both ways.** 2 MB scripts and 1080p screenshots just work |
| Two agents clobber each other's script edits | **Optimistic hashing.** Reads return a `hash`; edits take `expectedHash` and fail loudly if the script changed |
| Dead plugin = 30 s timeouts on every call | **Fast-fail in ~2 s** with an actionable message |
| Hardcoded list of ~40 properties | **Official Roblox API dump** — every scriptable property of every class, cached 7 days |

## Install (2 clicks)

> Requirement: [Node.js 18+](https://nodejs.org)

1. **Download** this repo (Code → Download ZIP) and extract it anywhere permanent
2. Double-click **`install.cmd`**
3. Open (or restart) Roblox Studio → the **Studio Bridge** panel connects by itself → click **Allow** if Studio asks for HTTP permission
4. Restart Claude (Code or Desktop) — done

Nothing to configure: the installer builds the plugin, copies it into your Roblox Plugins folder, and registers the MCP with both the Claude Code CLI and the Claude Desktop app. New Claude sessions load the tools automatically — just ask:

> *"build a shop UI in Studio with a grid of item buttons"*

To remove everything: `uninstall.cmd`.

## What Claude can do with it

**32 tools** covering the full Studio workflow:

- 🏗️ **Build** — `create_instance` spawns a whole hierarchy (a complete UI!) in one call; clone with offsets, move models, mass-edit properties with a full datatype codec (Vector3, CFrame, UDim2, ColorSequence, Font, Enum, …)
- 📜 **Script** — read with line numbers + content hash, surgical multi-edits (atomic), full-project grep and find/replace (dry-run by default)
- ▶️ **Test** — start/stop playtests, read output incrementally (`sinceSeq` — no re-dumped walls of text), run Luau in edit/server/client contexts with captured prints and tracebacks, simulate input
- 👁️ **See** — move the camera (`focusPath` = pressing <kbd>F</kbd> on an object) and take PNG screenshots to verify its own work
- 🔎 **Explore** — tree with smart summarization for huge places, search by name/class/tag/property, stable `ref:` handles that survive renames
- 🛡️ **Safety** — every write is an undo waypoint, `preview_asset` inspects toolbox assets (and flags scripts) *before* inserting

## Architecture

```
Claude session #1 ──stdio──> MCP shim ─┐
Claude session #2 ──stdio──> MCP shim ─┼─HTTP──> broker daemon ◄──long-poll── Studio plugin
Claude session #3 ──stdio──> MCP shim ─┘        (127.0.0.1:33361)
```

- The first shim that needs it spawns the **broker**; everyone else reuses it. It exits on its own after 20 min idle.
- The **plugin** long-polls the broker (instant wake-up, ~50-200 ms per command), executes reads in parallel and writes in strict FIFO (race-free), and reconnects automatically with backoff.
- Everything stays on `127.0.0.1` — nothing ever leaves your machine.
- 100% official plugin APIs (same category as Rojo). No injection, no client modification — Roblox themselves ship an MCP with this exact plugin+local-server design.

## Config & troubleshooting

| What | Where |
|---|---|
| Port | `STUDIO_BRIDGE_PORT` env var + the Port field in the plugin panel (default `33361`) |
| Broker logs | `%LOCALAPPDATA%\StudioBridge\broker.log` |
| Bridge status | `node server\cli.js status` |
| Panel stuck on "Looking for bridge" | Open any Claude session (the broker starts with it) |
| Panel stuck on "Permission needed" | Click **Allow** in Studio's HTTP permission popup |
| Tools missing in Claude | Fully restart Claude (including the tray icon) — MCP configs load at startup |
| Moved the folder after installing | Run `install.cmd` again (registration points at the folder path) |

## Development

```bash
npm run build-plugin          # plugin/*.lua  →  dist/StudioBridge.rbxmx (no Rojo needed)
npm test                      # broker integration: exactly-once, chunking, leases, 30-way concurrency
node test/mcp-smoke.test.js   # MCP handshake + API dump
```

Luau static analysis (all plugin code passes clean):

```bash
luau-lsp analyze --definitions=globalTypes.d.luau --sourcemap=sourcemap.json plugin/*.lua plugin/Commands/*.lua
```

## License

[MIT](LICENSE) © JuanArtxz