@el4cteo/rbx-studio-mcp 0.5.3 → 0.5.4

package/README.md

@@ -1,84 +1,33 @@
 # Roblox Studio MCP
 
-Let an AI agent drive Roblox Studio: read your place, edit scripts, build and generate geometry, run playtests, take screenshots. 30 tools. MIT.
+Let an AI agent drive Roblox Studio: read your place, edit scripts, build geometry, run playtests, take screenshots. 31 tools. MIT.
 
-![The Studio MCP panel: a live activity band, a call log with latencies, and the theme drawer open](docs/rbx-studio.png)
+![The Studio MCP panel](docs/rbx-studio.png)
 
 ## Install
 
-**1. The Studio plugin**
+**1. The plugin**
 
 ```bash
 npx -y @el4cteo/rbx-studio-mcp --install-plugin
 ```
 
-Or download `StudioMCP.rbxmx` from [Releases](https://github.com/EL4CTEO/rbx-studio-mcp/releases) into your Studio plugins folder.
-
-**2. The server**, in whichever client you use:
-
-<details>
-<summary><b>Claude Code</b></summary>
+**2. The server**
 
 ```bash
 claude mcp add roblox-studio -- npx -y @el4cteo/rbx-studio-mcp
 ```
-</details>
 
 <details>
-<summary><b>Codex CLI</b></summary>
+<summary>Other clients</summary>
+
+Codex CLI:
 
 ```bash
 codex mcp add roblox-studio -- npx -y @el4cteo/rbx-studio-mcp
 ```
-</details>
-
-<details>
-<summary><b>Cursor</b> — <code>~/.cursor/mcp.json</code> or <code>.cursor/mcp.json</code></summary>
-
-```json
-{
-  "mcpServers": {
-    "roblox-studio": {
-      "command": "npx",
-      "args": ["-y", "@el4cteo/rbx-studio-mcp"]
-    }
-  }
-}
-```
-</details>
-
-<details>
-<summary><b>Claude Desktop</b> — <code>claude_desktop_config.json</code></summary>
-
-```json
-{
-  "mcpServers": {
-    "roblox-studio": {
-      "command": "npx",
-      "args": ["-y", "@el4cteo/rbx-studio-mcp"]
-    }
-  }
-}
-```
-</details>
-
-<details>
-<summary><b>Gemini CLI</b> — <code>~/.gemini/settings.json</code></summary>
-
-```json
-{
-  "mcpServers": {
-    "roblox-studio": {
-      "command": "npx",
-      "args": ["-y", "@el4cteo/rbx-studio-mcp"]
-    }
-  }
-}
-```
-</details>
 
-<details>
-<summary><b>Windsurf</b> — <code>~/.codeium/windsurf/mcp_config.json</code></summary>
+Cursor, Claude Desktop, Gemini CLI, Windsurf — add to their config file:
 
 ```json
 {
@@ -90,30 +39,13 @@ codex mcp add roblox-studio -- npx -y @el4cteo/rbx-studio-mcp
   }
 }
 ```
-</details>
 
-<details>
-<summary><b>VS Code / Copilot</b> — <code>.vscode/mcp.json</code></summary>
-
-```json
-{
-  "servers": {
-    "roblox-studio": {
-      "type": "stdio",
-      "command": "npx",
-      "args": ["-y", "@el4cteo/rbx-studio-mcp"]
-    }
-  }
-}
-```
-</details>
+VS Code / Copilot (`.vscode/mcp.json`) uses `"servers"` instead of `"mcpServers"`, plus `"type": "stdio"`.
 
-<details>
-<summary><b>opencode</b> — <code>opencode.json</code></summary>
+opencode (`opencode.json`):
 
 ```json
 {
-  "$schema": "https://opencode.ai/config.json",
   "mcp": {
     "roblox-studio": {
       "type": "local",
@@ -125,25 +57,11 @@ codex mcp add roblox-studio -- npx -y @el4cteo/rbx-studio-mcp
 ```
 </details>
 
-**3.** Open Studio and accept the `127.0.0.1` prompt — the plugin connects automatically. Verify with `studio_status`.
-
-**4.** `debug` additionally needs **Debugger Luau API** in File → Beta Features, plus a Studio restart. Nothing else requires it.
-
-![The Debugger Luau API beta feature toggle in Studio](docs/betatoggle.png)
-
-Port defaults to **44755** — change with `--port` or `ROBLOX_STUDIO_MCP_PORT`, and match it in the plugin widget. Loopback only.
+**3.** Open Studio and accept the `127.0.0.1` prompt. Check it works with `studio_status`.
 
-If anything looks wrong, run the health check. It reports Node, the plugin install, the bridge, and every connected Studio, and ends each line with the fix:
+Something wrong? Run `npx -y @el4cteo/rbx-studio-mcp doctor` — it says what is broken and how to fix it.
 
-```bash
-npx -y @el4cteo/rbx-studio-mcp doctor
-```
-
-## Multiple agents
-
-Register the server in as many clients as you like. No extra configuration.
-
-Each agent keeps its own target, so two agents can work on two open places. Subagents share their parent's target — give them an explicit `studioId` per call.
+Port is **44755**, loopback only. Change it with `--port` and match it in the plugin.
 
 ## Tools
 
@@ -153,101 +71,67 @@ Each agent keeps its own target, so two agents can work on two open places. Suba
 | **Discover** | `tree` `inspect` `find` `api` |
 | **Scripts** | `script_read` `script_edit` `script_grep` `script_create` |
 | **Instances** | `create` `modify` `delete` `move` |
-| **World** | `geometry` `generate` `assets` `collision` `undo` |
+| **World** | `geometry` `terrain` `generate` `assets` `collision` `undo` |
 | **Run & debug** | `playtest` `execute_luau` `character` `input` `console` `debug` `performance` |
 | **Look** | `screenshot` `viewport` `device` |
 
-`geometry` holds every mesh operation: `union`, `subtract`, `intersect`, `fragment`, `segment` (cut a mesh into parts you name) and `sweep` (the volume a part moves through, and what it would hit).
-
-`generate` builds 3D models from a prompt using Roblox's Cube model — `Body1` for props, `Car5` for a body and four named wheels a script can drive, or your own part names.
+Write tools take arrays — ten script edits is one call, one **Ctrl+Z**, and all-or-nothing.
 
-Gotchas: during a playtest two sessions connect — pass `studioId` explicitly and use the edit session for anything that must persist. `device` emulation persists until `device op="stop"`. Generated meshes are edit-mode only; their content reads as empty inside a playtest.
+Two things to watch: a playtest connects a second session, so pass `studioId` and use the edit one for changes that must last; `device` emulation stays on until `device op="stop"`.
 
 ## The console panel
 
-Every call is logged with its latency, above a trace of the last forty. The badge names which agents are connected, with process id and uptime.
-
-Under the header is a command line. Type a command, or type a sentence and it goes to a coding agent.
+Every call is logged with how long it took. Below the header is a command line — type a command, or type a sentence and a coding agent answers it.
 
 | | |
 |---|---|
 | `help` | list everything |
-| `doctor` | check every part of the setup |
+| `doctor` | check the setup |
 | `status` `version` `place` `clients` | what this session is |
-| `studios` `use <n>` | which Studio window calls land on |
-| `theme [name]` `visuals` `log [level]` `clear` `copy` | the panel itself |
+| `studios` `use <n>` | which Studio window calls go to |
+| `theme [name]` `visuals` `log [level]` `clear` `copy` | the panel |
 | `port [n]` `reconnect` | the connection |
-| `agent [use <id>\|new]` `stop` | which coding agent runs your prompts |
+| `agent [use <id>\|new]` `stop` | which agent runs your prompts |
 | anything else | sent to that agent |
 
-Up and down walk the history, Tab completes.
+Arrows walk the history, Tab completes.
+
+**Prompts start a real agent** — whichever you have on PATH: Claude Code, Codex, opencode, Gemini, Cursor, Amp, Qwen Code, Factory Droid, goose, Copilot CLI, Aider, Crush, DeepSeek Harness. It runs headless, drives the same Studio, and its work appears in the log. It is a separate session from your terminal, billed separately, and allowed the `rbx-studio` tools only. `stop` cancels it.
 
-**Prompts start a real agent.** The bridge runs whichever tool you have on PATH — Claude Code, Codex, opencode, DeepSeek Harness, Gemini, Cursor, Amp, Qwen Code, Factory Droid, goose, GitHub Copilot CLI, Aider, Crush — in headless mode. It connects back to this same bridge, drives the same Studio, and its work streams into the log line by line. It is a separate session from the terminal you may already have open, billed separately, and it is allowed the `rbx-studio` tools and nothing else. `stop` cancels it.
+Eight themes behind the tab on the right edge. Your pick is remembered.
 
-Hover the tab on the right edge for eight themes — Lattice, Observatory, Orbit, Void, Nebula, Aurora, Phosphor, Blueprint. Each redraws the activity band, not just its colours. Your pick is remembered.
+## Why this one
+
+- **Push, not poll** — 13.6 ms per call against 25.8 ms.
+- **Safe script edits** — writes go through the script editor, so unsaved work survives.
+- **Stale edits are refused** — pass back the `rev` from `script_read` and a write lands only if nobody else touched the file.
+- **Property names are checked** against the running engine, so `Anchorred` comes back as a suggestion, not a runtime error.
 
 ## DeepSeek Harness (dsh)
 
-dsh is "everything is a plugin", and this server becomes one through its MCP bridge. One overlay row, and the tools arrive as `mcp__rbx-studio__*` — the same names Claude Code and Codex use.
+This server registers as a dsh plugin. `config/dsh.cordis.yml` is the row:
 
 ```sh
 dsh --profile headless --patch config/dsh.cordis.yml "add a spawn point"
 ```
 
-To keep it, append that row to your own patch layer — `$DSH_HOME/profiles/<name>/cordis.patch.yml` for one profile, `$DSH_HOME/cordis.patch.yml` for all of them. Don't overwrite the file; it may already hold unrelated patches.
-
-`config/dsh.cordis.yml` in this repo is the row. The console panel also lists `dsh` as an agent, and passes the overlay itself, so a prompt typed there works before you have merged anything.
-
-Two limits, both dsh's rather than ours: its headless profile prints the final answer instead of streaming, so the panel shows the reply at the end rather than step by step, and it has no `--resume`, so every prompt is a fresh conversation. It needs `DEEPSEEK_API_KEY`.
-
-## Batching
-
-Every write tool takes an array — ten script edits is one call.
-
-| tool | takes | cap |
-|---|---|---|
-| `create` | instances, each nesting `children` to any depth | 100 |
-| `modify` | entries, each with an unlimited list of `paths` | 100 entries |
-| `delete` | paths | 200 |
-| `move` | moves | 200 |
-| `script_edit` | edits, across any number of scripts | 50 |
-| `script_create` | scripts | 50 |
-| `inspect` | paths | 50 |
-| `input` | input steps, delivered in order | 40 |
-
-`modify` caps *entries*, not targets — one entry can anchor five hundred parts.
-
-Each batch is one **Ctrl+Z**, and all-or-nothing: a failed match leaves the place untouched.
-
-## Why this one
-
-- **Push, not poll.** 50 sequential round trips average 13.6 ms, against 25.8 ms polling — reproduce with `node scripts/latency.mjs --count 50 --compare`.
-- **Safe script edits.** Writes go through `ScriptEditorService:UpdateSourceAsync`, so your unsaved editor buffer survives.
-- **Edits can refuse to be stale.** `script_read` prints a `rev`; pass it back and the write is rejected if anyone changed the script meanwhile, instead of landing on lines that moved.
-- **One Ctrl+Z per call.** Every batch is a single undo recording.
-- **Property names are checked** against the running engine's API dump, so a typo comes back as `Anchorred` → `Anchored` instead of a runtime error.
-- **~16k tokens of schema**, cursor-paged and capped, with `detail: concise | standard | full`.
-
-Not built here: material generation.
+To keep it, append that row to your own `cordis.patch.yml`. Needs `DEEPSEEK_API_KEY`.
 
 ## Security
 
-Loopback only. Requires a header a browser cannot set cross-origin, which closes the DNS-rebinding hole. Your experience's "Allow HTTP Requests" setting is untouched.
+Loopback only, and requires a header a browser cannot set cross-origin. Your experience's "Allow HTTP Requests" setting is untouched.
 
 ## Development
 
 ```bash
 npm install
 npm run build          # TypeScript -> dist/
-npm run build:plugin   # plugin/src -> build/StudioMCP.rbxmx
-npm run install:plugin # build + copy into the Studio plugins folder
-npm test               # plugin (Luau) + bridge (Node) tests
+npm run install:plugin # build the plugin and copy it into Studio
+npm test
 ```
 
 Needs `luau`, `luau-compile` and `luau-analyze` from [the Luau releases](https://github.com/luau-lang/luau/releases) on `PATH` or in `tools/`.
 
-`evals/` holds ten questions answerable only by driving a real Studio session — see [evals/README.md](evals/README.md).
-
 ## Licence
 
 MIT.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@el4cteo/rbx-studio-mcp",
-  "version": "0.5.3",
+  "version": "0.5.4",
   "description": "MCP server for Roblox Studio. 31 tools, push-based SSE bridge, editor-safe script edits, one-step undo.",
   "type": "module",
   "license": "MIT",

package/plugin/src/Config.luau

@@ -9,7 +9,7 @@
 
 local Config = {}
 
-Config.PLUGIN_VERSION = "0.5.3"
+Config.PLUGIN_VERSION = "0.5.4"
 
 -- Fingerprint of plugin/src, stamped in by scripts/build-plugin.mjs. The server
 -- computes the same hash from its own copy of the sources and compares, so a