@el4cteo/rbx-studio-mcp 0.5.6 → 0.5.9

package/README.md

@@ -1,139 +1,141 @@
-# Roblox Studio MCP
-
-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](docs/rbx-studio.png)
-
-## Install
-
-**1. The plugin**
-
-```bash
-npx -y @el4cteo/rbx-studio-mcp --install-plugin
-```
-
-Or drop `StudioMCP.rbxmx` from [Releases](https://github.com/EL4CTEO/rbx-studio-mcp/releases) into your Studio plugins folder.
-
-**2. The server**
-
-```bash
-claude mcp add roblox-studio -- npx -y @el4cteo/rbx-studio-mcp
-```
-
-<details>
-<summary>Other clients</summary>
-
-Codex CLI:
-
-```bash
-codex mcp add roblox-studio -- npx -y @el4cteo/rbx-studio-mcp
-```
-
-Cursor, Claude Desktop, Gemini CLI, Windsurf — add to their config file:
-
-```json
-{
-  "mcpServers": {
-    "roblox-studio": {
-      "command": "npx",
-      "args": ["-y", "@el4cteo/rbx-studio-mcp"]
-    }
-  }
-}
-```
-
-VS Code / Copilot (`.vscode/mcp.json`) uses `"servers"` instead of `"mcpServers"`, plus `"type": "stdio"`.
-
-opencode (`opencode.json`):
-
-```json
-{
-  "mcp": {
-    "roblox-studio": {
-      "type": "local",
-      "command": ["npx", "-y", "@el4cteo/rbx-studio-mcp"],
-      "enabled": true
-    }
-  }
-}
-```
-</details>
-
-**3.** Open Studio and accept the `127.0.0.1` prompt. Check it works with `studio_status`.
-
-Something wrong? Run `npx -y @el4cteo/rbx-studio-mcp doctor` — it says what is broken and how to fix it.
-
-Port is **44755**, loopback only. Change it with `--port` and match it in the plugin.
-
-## Tools
-
-| | |
-|---|---|
-| **Session** | `studio_status` `list_studios` `set_active_studio` |
-| **Discover** | `tree` `inspect` `find` `api` |
-| **Scripts** | `script_read` `script_edit` `script_grep` `script_create` |
-| **Instances** | `create` `modify` `delete` `move` |
-| **World** | `geometry` `terrain` `generate` `assets` `collision` `undo` |
-| **Run & debug** | `playtest` `execute_luau` `character` `input` `console` `debug` `performance` |
-| **Look** | `screenshot` `viewport` `device` |
-
-Write tools take arrays — ten script edits is one call, one **Ctrl+Z**, and all-or-nothing.
-
-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 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 the setup |
-| `status` `version` `place` `clients` | what this session is |
-| `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 agent runs your prompts |
-| anything else | sent to that agent |
-
-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.
-
-Eight themes behind the tab on the right edge. 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)
-
-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 `cordis.patch.yml`. Needs `DEEPSEEK_API_KEY`.
-
-## Security
-
-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 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/`.
-
-## Licence
-
-MIT.
+# Roblox Studio MCP
+
+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](docs/rbx-studio.png)
+
+## Install
+
+**1. The plugin**
+
+```bash
+npx -y @el4cteo/rbx-studio-mcp --install-plugin
+```
+
+Or drop `StudioMCP.rbxmx` from [Releases](https://github.com/EL4CTEO/rbx-studio-mcp/releases) into your Studio plugins folder.
+
+**2. The server**
+
+```bash
+claude mcp add roblox-studio -- npx -y @el4cteo/rbx-studio-mcp
+```
+
+<details>
+<summary>Other clients</summary>
+
+Codex CLI:
+
+```bash
+codex mcp add roblox-studio -- npx -y @el4cteo/rbx-studio-mcp
+```
+
+Cursor, Claude Desktop, Gemini CLI, Windsurf — add to their config file:
+
+```json
+{
+  "mcpServers": {
+    "roblox-studio": {
+      "command": "npx",
+      "args": ["-y", "@el4cteo/rbx-studio-mcp"]
+    }
+  }
+}
+```
+
+VS Code / Copilot (`.vscode/mcp.json`) uses `"servers"` instead of `"mcpServers"`, plus `"type": "stdio"`.
+
+opencode (`opencode.json`):
+
+```json
+{
+  "mcp": {
+    "roblox-studio": {
+      "type": "local",
+      "command": ["npx", "-y", "@el4cteo/rbx-studio-mcp"],
+      "enabled": true
+    }
+  }
+}
+```
+</details>
+
+**3.** Open Studio and accept the `127.0.0.1` prompt. Check it works with `studio_status`.
+
+Something wrong? Run `npx -y @el4cteo/rbx-studio-mcp doctor` — it says what is broken and how to fix it.
+
+Port is **44755**, loopback only. Change it with `--port` and match it in the plugin.
+
+## Tools
+
+| | |
+|---|---|
+| **Session** | `studio_status` `list_studios` `set_active_studio` |
+| **Discover** | `tree` `inspect` `find` `api` |
+| **Scripts** | `script_read` `script_edit` `script_grep` `script_create` |
+| **Instances** | `create` `modify` `delete` `move` |
+| **World** | `geometry` `terrain` `generate` `assets` `collision` `undo` |
+| **Run & debug** | `playtest` `execute_luau` `character` `input` `console` `debug` `performance` |
+| **Look** | `screenshot` `viewport` `device` |
+
+Write tools take arrays — ten script edits is one call, one **Ctrl+Z**, and all-or-nothing.
+
+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 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 the setup |
+| `status` `version` `place` `clients` | what this session is |
+| `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 agent runs your prompts |
+| anything else | sent to that agent |
+
+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.
+
+Eight themes behind the tab on the right edge. 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)
+
+This server registers as a dsh plugin. The row ships in the package, at
+`node_modules/@el4cteo/rbx-studio-mcp/config/dsh.cordis.yml`:
+
+```sh
+dsh --profile headless --patch <that path> "add a spawn point"
+```
+
+To keep it, append the row to `$DSH_HOME/profiles/<name>/cordis.patch.yml` for one
+profile, or `$DSH_HOME/cordis.patch.yml` for all of them. Needs `DEEPSEEK_API_KEY`.
+
+## Security
+
+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 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/`.
+
+## Licence
+
+MIT.

package/config/dsh.cordis.yml

@@ -0,0 +1,45 @@
+# rbx-studio for DeepSeek Harness (dsh).
+#
+# dsh is "everything is a plugin", and an MCP server becomes one through the
+# `@deepseek-ai/dsh-mcp-client` bridge: one overlay row per server, and its
+# tools arrive as native tools named `mcp__<serverName>__<tool>`. That is the
+# same naming Claude Code and Codex use, so nothing else in this project has to
+# know which harness is driving it.
+#
+# Use it for one run:
+#
+#     dsh --profile headless --patch /path/to/dsh.cordis.yml "add a spawn point"
+#
+# Or keep it, by merging this row into your own patch layer -- append to it
+# rather than overwriting, since it may already hold unrelated patches:
+#
+#     $DSH_HOME/profiles/<name>/cordis.patch.yml   one profile
+#     $DSH_HOME/cordis.patch.yml                   every profile
+#
+# Studio must be open with the plugin installed; dsh starts the bridge, not the
+# editor. If the port is already held by another agent's server, this one
+# becomes a peer and proxies to it, which is how several agents share one
+# Studio.
+- insert:
+    - id: mcp-rbx-studio
+      name: '@deepseek-ai/dsh-mcp-client'
+      config:
+        # Fixes the tool prefix at `mcp__rbx-studio__`. Deliberately not left to
+        # the server's own reported name: dsh treats that as untrusted, and a
+        # rename would silently invalidate every permission rule and every
+        # session history entry that referred to these tools.
+        serverName: rbx-studio
+        transport: stdio
+        command: npx
+        args: ['-y', '@el4cteo/rbx-studio-mcp']
+        env: {}
+        # The place dsh was started from. The bridge itself does not care, but
+        # the tools report paths relative to it.
+        cwd: !!js process.cwd()
+        # Screenshots and script reads are the big payloads here, and a slow
+        # Studio round trip on a large place can outrun a shorter budget.
+        toolCallTimeoutMs: 60000
+        # A missing Studio is not a reason to refuse to start. The tools simply
+        # answer NO_STUDIO until the editor is open, which is a better first
+        # session than a harness that will not boot.
+        failOnStartupError: false

package/package.json

@@ -1,68 +1,74 @@
-{
-  "name": "@el4cteo/rbx-studio-mcp",
-  "version": "0.5.6",
-  "description": "MCP server for Roblox Studio. 31 tools, push-based SSE bridge, editor-safe script edits, one-step undo.",
-  "type": "module",
-  "license": "MIT",
-  "bin": {
-    "rbx-studio-mcp": "dist/index.js"
-  },
-  "files": [
-    "dist",
-    "plugin",
-    "scripts",
-    "README.md",
-    "LICENSE"
-  ],
-  "engines": {
-    "node": ">=22.15"
-  },
-  "scripts": {
-    "build": "tsc",
-    "watch": "tsc --watch",
-    "typecheck": "tsc --noEmit",
-    "start": "node dist/index.js",
-    "build:plugin": "node scripts/check-plugin.mjs && node scripts/build-plugin.mjs",
-    "sourcemap": "node scripts/sourcemap.mjs",
-    "test": "node scripts/test-plugin.mjs && node scripts/test-transport.mjs && node scripts/test-bridge.mjs && node scripts/test-console.mjs && node scripts/test-failover.mjs",
-    "build:all": "npm run build && npm run build:plugin",
-    "install:plugin": "node scripts/install-plugin.mjs",
-    "check:plugin": "node scripts/check-plugin.mjs",
-    "doctor": "node dist/index.js doctor",
-    "prepack": "npm run build"
-  },
-  "keywords": [
-    "mcp",
-    "mcp-server",
-    "model-context-protocol",
-    "roblox",
-    "roblox-studio",
-    "roblox-development",
-    "luau",
-    "claude",
-    "claude-code",
-    "cursor",
-    "ai",
-    "ai-agent"
-  ],
-  "dependencies": {
-    "@modelcontextprotocol/sdk": "^1.30.0",
-    "zod": "^4.5.4"
-  },
-  "devDependencies": {
-    "@types/node": "^26.5.0",
-    "typescript": "^7.0.2"
-  },
-  "author": "EL4CTEO",
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/EL4CTEO/rbx-studio-mcp.git"
-  },
-  "homepage": "https://github.com/EL4CTEO/rbx-studio-mcp#readme",
-  "bugs": {
-    "url": "https://github.com/EL4CTEO/rbx-studio-mcp/issues"
-  },
-  "publishConfig": {
-    "access": "public"
-  }
-}
+{
+  "name": "@el4cteo/rbx-studio-mcp",
+  "version": "0.5.9",
+  "description": "MCP server for Roblox Studio. 31 tools, push-based SSE bridge, editor-safe script edits, one-step undo.",
+  "type": "module",
+  "license": "MIT",
+  "bin": {
+    "rbx-studio-mcp": "dist/index.js"
+  },
+  "files": [
+    "dist",
+    "plugin",
+    "scripts",
+    "config/dsh.cordis.yml",
+    "README.md",
+    "LICENSE"
+  ],
+  "dsh": {
+    "bundle": {
+      "patch": "./config/dsh.cordis.yml"
+    }
+  },
+  "engines": {
+    "node": ">=22.15"
+  },
+  "scripts": {
+    "build": "tsc",
+    "watch": "tsc --watch",
+    "typecheck": "tsc --noEmit",
+    "start": "node dist/index.js",
+    "build:plugin": "node scripts/check-plugin.mjs && node scripts/build-plugin.mjs",
+    "sourcemap": "node scripts/sourcemap.mjs",
+    "test": "node scripts/test-plugin.mjs && node scripts/test-transport.mjs && node scripts/test-bridge.mjs && node scripts/test-console.mjs && node scripts/test-failover.mjs",
+    "build:all": "npm run build && npm run build:plugin",
+    "install:plugin": "node scripts/install-plugin.mjs",
+    "check:plugin": "node scripts/check-plugin.mjs",
+    "doctor": "node dist/index.js doctor",
+    "prepack": "npm run build"
+  },
+  "keywords": [
+    "mcp",
+    "mcp-server",
+    "model-context-protocol",
+    "roblox",
+    "roblox-studio",
+    "roblox-development",
+    "luau",
+    "claude",
+    "claude-code",
+    "cursor",
+    "ai",
+    "ai-agent"
+  ],
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.30.0",
+    "zod": "^4.6.2"
+  },
+  "devDependencies": {
+    "@types/node": "^26.5.1",
+    "typescript": "^7.0.2"
+  },
+  "author": "EL4CTEO",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/EL4CTEO/rbx-studio-mcp.git"
+  },
+  "homepage": "https://github.com/EL4CTEO/rbx-studio-mcp#readme",
+  "bugs": {
+    "url": "https://github.com/EL4CTEO/rbx-studio-mcp/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}