@el4cteo/rbx-studio-mcp 0.1.0 → 0.1.2

package/README.md

@@ -1,6 +1,8 @@
 # Roblox Studio MCP
 
-MCP server for Roblox Studio. 29 tools over a push-based bridge. MIT.
+MCP server for Roblox Studio. 29 tools over a push-based bridge, every write batched and undoable in one step. MIT.
+
+![The Studio MCP panel, showing calls and their latency](docs/console.png)
 
 ## Install
 
@@ -10,7 +12,7 @@ MCP server for Roblox Studio. 29 tools over a push-based bridge. MIT.
 npx -y @el4cteo/rbx-studio-mcp --install-plugin
 ```
 
-Or download `StudioMCP.rbxmx` from [Releases](https://github.com/EL4CTEO/roblox-studio-mcp/releases) into your Studio plugins folder.
+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:
 
@@ -145,8 +147,16 @@ args = ["-y", "@el4cteo/rbx-studio-mcp"]
 
 **3.** Open Studio, accept the `127.0.0.1` prompt, check the **Studio MCP** toolbar button. Verify with `studio_status`.
 
+**4. For `debug`**, turn on **Debugger Luau API** in File → Beta Features, then restart Studio. Everything else works without it; breakpoints do not, because `ScriptDebuggerService` is not registered until this is enabled.
+
+![The Debugger Luau API beta feature toggle in Studio](docs/betatoggle.png)
+
 Port defaults to **44755** — `--port` or `ROBLOX_STUDIO_MCP_PORT`, matched in the plugin widget. Loopback only.
 
+**Several agents at once work.** Register this in as many clients as you like — two Claude sessions, Claude plus Cursor, whatever. The plugin connects out to one port, so the first server to start owns it and the rest proxy through it automatically. Nothing to configure, and no second connection to Studio.
+
+Each agent keeps its **own** target: `set_active_studio` binds per client, so two agents can work on two open places at once and neither can retarget the other. Pass `studioId` on a single call to reach elsewhere without changing your default.
+
 ## Tools
 
 | | |
@@ -159,7 +169,41 @@ Port defaults to **44755** — `--port` or `ROBLOX_STUDIO_MCP_PORT`, matched in
 | **Look** | `screenshot` `viewport` `device` |
 | **Session** | `list_studios` `set_active_studio` |
 
-Gotchas: `screenshot` doesn't work mid-playtest. `debug` needs **API debugger Luau** in `File → Beta Features`. `device` emulation persists until `device op="stop"`.
+Gotchas: `debug` needs **API debugger Luau** in `File → Beta Features`. `device` emulation persists until `device op="stop"`. During a playtest two sessions connect — pass `studioId` explicitly, using the edit session for anything that must persist.
+
+## Batching
+
+Every write tool takes an array. Editing ten scripts, deleting two hundred
+parts or anchoring a whole map is **one call**, not a loop.
+
+| 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 |
+
+The cap on `modify` is on *entries*, not targets — one entry can anchor five
+hundred parts, so pair it with `find` and change a whole place in a single call.
+
+What that buys beyond speed:
+
+- **One Ctrl+Z.** The batch runs inside a single `ChangeHistoryService`
+  recording named after the tool. Ten script edits undo as one step, not ten.
+- **All-or-nothing.** Everything is read and transformed in memory before
+  anything is written, so a find that matches nothing — or matches twice —
+  fails with the place untouched instead of half-edited.
+- **Nesting.** `create` takes `children`, so a whole model arrives in one call.
+  A new instance's path is not knowable until it exists, and same-named siblings
+  make guessing it unreliable.
+
+Parallel tool calls work too — responses are keyed by request id, so several
+calls in one turn run concurrently. Prefer a batch where one exists: parallel
+calls are N round trips and N undo steps, a batch is one of each.
 
 ## Compared to what else exists
 
@@ -173,7 +217,7 @@ Gotchas: `screenshot` doesn't work mid-playtest. `debug` needs **API debugger Lu
 | [Roblox/studio-rust-mcp-server](https://github.com/Roblox/studio-rust-mcp-server) | 2 | HTTP | no | no | no | MIT (superseded) |
 
 - **Push, not poll.** SSE stream instead of a 500 ms poll. 50 sequential round trips: **13.6 ms** mean vs 25.8 ms, **12.8 ms** median vs 29.9 ms. Reproduce with `node scripts/latency.mjs --count 50 --compare`.
-- **Safe script edits.** `ScriptEditorService:UpdateSourceAsync`, not `script.Source` — your unsaved editor buffer survives. Batches are all-or-nothing.
+- **Safe script edits.** `ScriptEditorService:UpdateSourceAsync`, not `script.Source` — your unsaved editor buffer survives.
 - **One Ctrl+Z per action**, via `ChangeHistoryService`.
 - **29 tools, ~16k tokens of schema**, against 43–51 elsewhere. Cursor-paged, capped, with `detail: concise | standard | full`.
 - **Live API dump** for property validation, so typos get suggestions (`Anchorred` → `Anchored`).

package/dist/bridge/api.js

@@ -0,0 +1,34 @@
+import { randomUUID } from "node:crypto";
+/**
+ * The bridge as seen from the process that actually holds the port.
+ *
+ * Carries a client id like any other, rather than being privileged as "the"
+ * client. The process holding the port is still just one agent among however
+ * many are connected, and its chosen Studio has no more right to leak into
+ * everyone else's calls than a proxying peer's would.
+ */
+export class LocalBridge {
+    inner;
+    isOwner = true;
+    clientId = randomUUID();
+    constructor(inner) {
+        this.inner = inner;
+    }
+    call(op, params = {}, options = {}) {
+        return this.inner.call(op, params, { ...options, clientId: this.clientId });
+    }
+    async sessions() {
+        return {
+            list: this.inner.list(),
+            activeId: this.inner.activeId(this.clientId),
+            activeIsChosen: this.inner.activeIsChosen(this.clientId),
+        };
+    }
+    async setActive(studioId) {
+        this.inner.setActive(this.clientId, studioId);
+    }
+    async notePlaceName(studioId, placeName, context) {
+        this.inner.notePlaceName(studioId, placeName, context);
+    }
+}
+//# sourceMappingURL=api.js.map

package/dist/bridge/api.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"api.js","sourceRoot":"","sources":["../../src/bridge/api.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AA2CzC;;;;;;;GAOG;AACH,MAAM,OAAO,WAAW;IAIO,KAAK;IAHzB,OAAO,GAAG,IAAI,CAAC;IACP,QAAQ,GAAG,UAAU,EAAE,CAAC;IAEzC,YAA6B,KAAa;qBAAb,KAAK;IAAW,CAAC;IAE9C,IAAI,CACF,EAAU,EACV,MAAM,GAA4B,EAAE,EACpC,OAAO,GAA8C,EAAE;QAEvD,OAAO,IAAI,CAAC,KAAK,CAAC,IAAI,CAAI,EAAE,EAAE,MAAM,EAAE,EAAE,GAAG,OAAO,EAAE,QAAQ,EAAE,IAAI,CAAC,QAAQ,EAAE,CAAC,CAAC;IACjF,CAAC;IAED,KAAK,CAAC,QAAQ;QACZ,OAAO;YACL,IAAI,EAAE,IAAI,CAAC,KAAK,CAAC,IAAI,EAAE;YACvB,QAAQ,EAAE,IAAI,CAAC,KAAK,CAAC,QAAQ,CAAC,IAAI,CAAC,QAAQ,CAAC;YAC5C,cAAc,EAAE,IAAI,CAAC,KAAK,CAAC,cAAc,CAAC,IAAI,CAAC,QAAQ,CAAC;SACzD,CAAC;IACJ,CAAC;IAED,KAAK,CAAC,SAAS,CAAC,QAAgB;QAC9B,IAAI,CAAC,KAAK,CAAC,SAAS,CAAC,IAAI,CAAC,QAAQ,EAAE,QAAQ,CAAC,CAAC;IAChD,CAAC;IAED,KAAK,CAAC,aAAa,CAAC,QAAgB,EAAE,SAAiB,EAAE,OAAgB;QACvE,IAAI,CAAC,KAAK,CAAC,aAAa,CAAC,QAAQ,EAAE,SAAS,EAAE,OAAO,CAAC,CAAC;IACzD,CAAC;CACF"}

package/dist/bridge/remote.js

@@ -0,0 +1,122 @@
+import { randomUUID } from "node:crypto";
+import { CLIENT_HEADER, PROTOCOL_VERSION } from "../lib/protocol.js";
+import { ToolError } from "../lib/errors.js";
+/**
+ * Names this process to the owner, so its chosen Studio stays its own.
+ *
+ * Generated once per process and sent on every request. The owner keys each
+ * client's set_active_studio choice on it; without it, agents sharing a bridge
+ * would share one target and silently retarget each other.
+ */
+export const PEER_HEADER = "x-roblox-studio-mcp-peer";
+/**
+ * Asks whatever holds `port` whether it is another copy of this server.
+ *
+ * Deliberately narrow. Something else on 44755 is a reason to fail with the
+ * old "port is in use" message, not to start posting Luau at it, so this
+ * returns null on anything that is not an exact match — wrong shape, wrong
+ * protocol version, no answer at all.
+ */
+export async function probeOwner(port) {
+    try {
+        const response = await fetch(`http://127.0.0.1:${port}/identity`, {
+            headers: { [CLIENT_HEADER]: "peer" },
+            signal: AbortSignal.timeout(2_000),
+        });
+        if (!response.ok)
+            return null;
+        const body = (await response.json());
+        if (body.server !== "roblox-studio-mcp")
+            return null;
+        if (body.protocolVersion !== PROTOCOL_VERSION)
+            return null;
+        return body;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * A bridge that forwards everything to the process holding the port.
+ *
+ * There is no second connection to Studio and no second copy of the in-flight
+ * table: the owner does the work and this waits for the answer, so two agents
+ * calling at once are simply two commands on the owner's queue, and the undo
+ * recording each one opens still belongs to whichever tool made it.
+ */
+export class RemoteBridge {
+    port;
+    owner;
+    isOwner = false;
+    clientId = randomUUID();
+    constructor(port, owner) {
+        this.port = port;
+        this.owner = owner;
+    }
+    get base() {
+        return `http://127.0.0.1:${this.port}`;
+    }
+    get headers() {
+        return {
+            [CLIENT_HEADER]: "peer",
+            [PEER_HEADER]: this.clientId,
+            "Content-Type": "application/json",
+        };
+    }
+    async post(path, body, timeoutMs) {
+        let response;
+        try {
+            response = await fetch(`${this.base}${path}`, {
+                method: "POST",
+                headers: this.headers,
+                body: JSON.stringify(body),
+                // Padded past the command's own deadline so the owner's timeout wins and
+                // its diagnosis reaches the caller, rather than being cut off by ours.
+                signal: AbortSignal.timeout(timeoutMs + 10_000),
+            });
+        }
+        catch (cause) {
+            throw this.unreachable(cause);
+        }
+        const payload = (await response.json());
+        if (!payload.ok) {
+            const error = payload.error ?? { code: "PEER_ERROR", message: "the bridge owner refused" };
+            throw new ToolError(error.code, error.message);
+        }
+        return payload.data;
+    }
+    unreachable(cause) {
+        return new ToolError("OWNER_GONE", `The roblox-studio-mcp instance holding port ${this.port} (pid ${this.owner.pid}) ` +
+            `stopped answering: ${cause instanceof Error ? cause.message : String(cause)}`, "That process owns the Studio connection and this one borrows it. It has most " +
+            "likely exited — restart this MCP server and it will take the port itself.");
+    }
+    call(op, params = {}, options = {}) {
+        return this.post("/call", { op, params, ...options }, options.timeoutMs ?? 15_000);
+    }
+    async sessions() {
+        try {
+            const response = await fetch(`${this.base}/sessions`, {
+                headers: this.headers,
+                signal: AbortSignal.timeout(5_000),
+            });
+            return (await response.json());
+        }
+        catch (cause) {
+            throw this.unreachable(cause);
+        }
+    }
+    async setActive(studioId) {
+        await this.post("/active", { studioId }, 5_000);
+    }
+    async notePlaceName(studioId, placeName, context) {
+        // Best effort: this only refreshes a display name on the owner, and losing
+        // it should never fail the call that happened to learn it.
+        try {
+            await this.post("/place-name", { studioId, placeName, context }, 5_000);
+        }
+        catch {
+            /* ignored */
+        }
+    }
+}
+//# sourceMappingURL=remote.js.map

package/dist/bridge/remote.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"remote.js","sourceRoot":"","sources":["../../src/bridge/remote.ts"],"names":[],"mappings":"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"}

package/dist/bridge/rpc.js

@@ -1,5 +1,5 @@
 import { randomUUID } from "node:crypto";
-import { AMBIGUOUS_STUDIO, DISCONNECTED, NO_STUDIO, TIMEOUT, ToolError, } from "../lib/errors.js";
+import { AMBIGUOUS_STUDIO, DISCONNECTED, NO_STUDIO, SAME_PLACE_STUDIO, TIMEOUT, ToolError, } from "../lib/errors.js";
 /** Default per-command deadline. Studio round trips are single-digit ms over SSE. */
 export const DEFAULT_TIMEOUT_MS = 15_000;
 /** How long a long-poll request is parked before we answer "idle". */
@@ -15,17 +15,24 @@ const STALE_AFTER_MS = 90_000;
  */
 export class Bridge {
     sessions = new Map();
-    activeStudioId = null;
     /**
-     * Whether `activeStudioId` was picked by the user via set_active_studio, as
-     * opposed to being the only session that happened to connect first.
+     * Which Studio each connected client chose, keyed by client.
      *
-     * The distinction decides what happens when a second Studio appears. A
-     * defaulted target silently becomes ambiguous — editing whichever place
-     * connected first is not a reasonable guess — while a chosen one stays put,
-     * because the user said which place they meant.
+     * Per client, not per process, and that is the whole point. Any number of
+     * agents share this bridge — the first server to start owns the port and the
+     * rest proxy through it — so a single chosen target would be shared mutable
+     * state between agents that cannot see each other: one calling
+     * set_active_studio would silently retarget the next un-addressed call of
+     * every other. Editing the wrong place is not a failure that announces
+     * itself, so the answer is isolation rather than a warning.
+     *
+     * Presence in the map is what "chosen" means. That distinction decides what
+     * happens when a second Studio appears: a client that never chose goes
+     * ambiguous, because editing whichever place connected first is not a
+     * reasonable guess, while one that did stays put, because it said what it
+     * meant.
      */
-    activeWasChosen = false;
+    chosen = new Map();
     // --- session lifecycle -------------------------------------------------
     attach(identity, stream) {
         const existing = this.sessions.get(identity.studioId);
@@ -48,7 +55,6 @@ export class Bridge {
             waiter: null,
             pending: new Map(),
         });
-        this.activeStudioId ??= identity.studioId;
         return identity.studioId;
     }
     detach(studioId) {
@@ -63,11 +69,13 @@ export class Bridge {
         session.waiter?.(null);
         session.stream?.end();
         this.sessions.delete(studioId);
-        if (this.activeStudioId === studioId) {
-            // The place the user chose is gone, so the replacement is a fallback, not
-            // a choice: mark it as such so a remaining pair goes ambiguous again.
-            this.activeStudioId = this.sessions.keys().next().value ?? null;
-            this.activeWasChosen = false;
+        // A choice that no longer exists is not a choice. Dropping it rather than
+        // substituting a survivor is deliberate: with a pair left, going ambiguous
+        // asks the question again, where quietly promoting whichever remains would
+        // point the agent at a place nobody picked.
+        for (const [clientId, chosenId] of this.chosen) {
+            if (chosenId === studioId)
+                this.chosen.delete(clientId);
         }
     }
     /** Drops sessions whose plugin stopped checking in without a clean detach. */
@@ -110,19 +118,34 @@ export class Bridge {
             lastSeenAt: session.lastSeenAt,
         }));
     }
-    get activeId() {
-        return this.activeStudioId;
+    /**
+     * What this client's calls target when they name no studioId.
+     *
+     * A lone Studio is reported as the target whether or not anyone picked it,
+     * because with one connected there is nothing else a call could mean.
+     */
+    activeId(clientId) {
+        const picked = this.chosen.get(clientId);
+        if (picked !== undefined && this.sessions.has(picked))
+            return picked;
+        if (this.sessions.size === 1)
+            return this.sessions.keys().next().value ?? null;
+        return null;
     }
-    /** True only once the user has actually picked a target. */
-    get activeIsChosen() {
-        return this.activeWasChosen;
+    /** True only once this client has actually picked a target. */
+    activeIsChosen(clientId) {
+        const picked = this.chosen.get(clientId);
+        return picked !== undefined && this.sessions.has(picked);
     }
-    setActive(studioId) {
+    setActive(clientId, studioId) {
         if (!this.sessions.has(studioId)) {
             throw new ToolError("UNKNOWN_STUDIO", `No connected Studio has id "${studioId}".`, "Call list_studios to see the connected instances and their ids.");
         }
-        this.activeStudioId = studioId;
-        this.activeWasChosen = true;
+        this.chosen.set(clientId, studioId);
+    }
+    /** Forgets a client's choice when its server instance goes away. */
+    forgetClient(clientId) {
+        this.chosen.delete(clientId);
     }
     // --- request/response --------------------------------------------------
     /**
@@ -130,14 +153,24 @@ export class Bridge {
      * Rejects with a ToolError carrying an agent-readable hint on any failure,
      * including errors raised inside the plugin.
      */
-    call(op, params = {}, options = {}) {
-        const session = this.resolveSession(options.studioId);
+    call(op, params = {}, options) {
+        const session = this.resolveSession(options.clientId, options.studioId);
         const timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
         const command = { id: randomUUID(), op, params };
         return new Promise((resolve, reject) => {
             const timer = setTimeout(() => {
                 session.pending.delete(command.id);
-                reject(TIMEOUT(op, timeoutMs));
+                // A bare "it timed out" leaves nowhere to go, and the interesting part
+                // is knowable here: whether the command ever left this process, and
+                // whether the plugin has said anything since. A command still sitting in
+                // the queue was never seen by Studio, which is a different fault from
+                // one Studio took and did not finish.
+                reject(TIMEOUT(op, timeoutMs, {
+                    delivered: session.queue.every((queued) => queued.id !== command.id),
+                    silentForMs: Date.now() - session.lastSeenAt,
+                    alsoInFlight: session.pending.size,
+                    transport: session.stream ? "sse" : "poll",
+                }));
             }, timeoutMs);
             session.pending.set(command.id, {
                 resolve: resolve,
@@ -196,7 +229,7 @@ export class Bridge {
         });
     }
     // --- internals ---------------------------------------------------------
-    resolveSession(studioId) {
+    resolveSession(clientId, studioId) {
         if (studioId) {
             const session = this.sessions.get(studioId);
             if (!session)
@@ -209,16 +242,27 @@ export class Bridge {
         const only = this.sessions.values().next().value;
         if (this.sessions.size === 1 && only)
             return only;
-        if (this.activeWasChosen && this.activeStudioId) {
-            const session = this.sessions.get(this.activeStudioId);
+        const picked = this.chosen.get(clientId);
+        if (picked !== undefined) {
+            const session = this.sessions.get(picked);
             if (session)
                 return session;
         }
-        throw AMBIGUOUS_STUDIO(
+        const connected = this.list();
         // The context is the part that decides it. Two rows reading "Untitled
         // Experience" are indistinguishable, and picking the playtest means work
         // that disappears when it stops.
-        this.list().map((session) => `${session.studioId} (${session.placeName}${session.context ? `, ${session.context}` : ""})`));
+        const rows = connected.map((session) => `${session.studioId} (${session.placeName}${session.context ? `, ${session.context}` : ""})`);
+        // A playtest is not a second place. Starting one connects a second session
+        // on the same placeId, and telling the agent to go and ask which place the
+        // user means is then a question with no answer -- there is one place, in two
+        // states, and which to use follows from what is being asked rather than from
+        // anything the user knows.
+        const places = new Set(connected.map((session) => session.placeId));
+        if (places.size === 1 && connected.length > 1) {
+            throw SAME_PLACE_STUDIO(rows);
+        }
+        throw AMBIGUOUS_STUDIO(rows);
     }
     deliver(session, command) {
         if (session.stream && !session.stream.writableEnded) {

package/dist/bridge/rpc.js.map

@@ -1 +1 @@
-{"version":3,"file":"rpc.js","sourceRoot":"","sources":["../../src/bridge/rpc.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"rpc.js","sourceRoot":"","sources":["../../src/bridge/rpc.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAEzC,OAAO,EACL,gBAAgB,EAChB,YAAY,EACZ,SAAS,EACT,iBAAiB,EACjB,OAAO,EACP,SAAS,GACV,MAAM,kBAAkB,CAAC;AAQ1B,qFAAqF;AACrF,MAAM,CAAC,MAAM,kBAAkB,GAAG,MAAM,CAAC;AAEzC,sEAAsE;AACtE,MAAM,CAAC,MAAM,YAAY,GAAG,MAAM,CAAC;AAEnC,8EAA8E;AAC9E,MAAM,cAAc,GAAG,MAAM,CAAC;AAuB9B;;;;;;GAMG;AACH,MAAM,OAAO,MAAM;IACA,QAAQ,GAAG,IAAI,GAAG,EAAmB,CAAC;IAEvD;;;;;;;;;;;;;;;;OAgBG;IACc,MAAM,GAAG,IAAI,GAAG,EAAkB,CAAC;IAEpD,0EAA0E;IAE1E,MAAM,CAAC,QAAwB,EAAE,MAA6B;QAC5D,MAAM,QAAQ,GAAG,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,QAAQ,CAAC,QAAQ,CAAC,CAAC;QACtD,IAAI,QAAQ,EAAE,CAAC;YACb,0EAA0E;YAC1E,yEAAyE;YACzE,QAAQ,CAAC,MAAM,EAAE,GAAG,EAAE,CAAC;YACvB,QAAQ,CAAC,QAAQ,GAAG,QAAQ,CAAC;YAC7B,QAAQ,CAAC,MAAM,GAAG,MAAM,CAAC;YACzB,QAAQ,CAAC,UAAU,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;YACjC,IAAI,CAAC,KAAK,CAAC,QAAQ,CAAC,CAAC;YACrB,OAAO,QAAQ,CAAC,QAAQ,CAAC;QAC3B,CAAC;QAED,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,QAAQ,CAAC,QAAQ,EAAE;YACnC,QAAQ;YACR,WAAW,EAAE,IAAI,CAAC,GAAG,EAAE;YACvB,UAAU,EAAE,IAAI,CAAC,GAAG,EAAE;YACtB,MAAM;YACN,KAAK,EAAE,EAAE;YACT,MAAM,EAAE,IAAI;YACZ,OAAO,EAAE,IAAI,GAAG,EAAE;SACnB,CAAC,CAAC;QACH,OAAO,QAAQ,CAAC,QAAQ,CAAC;IAC3B,CAAC;IAED,MAAM,CAAC,QAAgB;QACrB,MAAM,OAAO,GAAG,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;QAC5C,IAAI,CAAC,OAAO;YAAE,OAAO;QACrB,KAAK,MAAM,OAAO,IAAI,OAAO,CAAC,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC;YAC/C,YAAY,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC;YAC5B,OAAO,CAAC,MAAM,CAAC,YAAY,EAAE,CAAC,CAAC;QACjC,CAAC;QACD,OAAO,CAAC,OAAO,CAAC,KAAK,EAAE,CAAC;QACxB,OAAO,CAAC,MAAM,EAAE,CAAC,IAAI,CAAC,CAAC;QACvB,OAAO,CAAC,MAAM,EAAE,GAAG,EAAE,CAAC;QACtB,IAAI,CAAC,QAAQ,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC;QAE/B,0EAA0E;QAC1E,2EAA2E;QAC3E,2EAA2E;QAC3E,4CAA4C;QAC5C,KAAK,MAAM,CAAC,QAAQ,EAAE,QAAQ,CAAC,IAAI,IAAI,CAAC,MAAM,EAAE,CAAC;YAC/C,IAAI,QAAQ,KAAK,QAAQ;gBAAE,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC;QAC1D,CAAC;IACH,CAAC;IAED,8EAA8E;IAC9E,SAAS;QACP,MAAM,MAAM,GAAG,IAAI,CAAC,GAAG,EAAE,GAAG,cAAc,CAAC;QAC3C,KAAK,MAAM,CAAC,EAAE,EAAE,OAAO,CAAC,IAAI,IAAI,CAAC,QAAQ,EAAE,CAAC;YAC1C,IAAI,OAAO,CAAC,UAAU,GAAG,MAAM,IAAI,CAAC,OAAO,CAAC,MAAM;gBAAE,IAAI,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC;QACtE,CAAC;IACH,CAAC;IAED,KAAK,CAAC,QAAgB;QACpB,MAAM,OAAO,GAAG,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;QAC5C,IAAI,OAAO;YAAE,OAAO,CAAC,UAAU,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;IAC/C,CAAC;IAED;;;;;;;OAOG;IACH,aAAa,CAAC,QAAgB,EAAE,SAAiB,EAAE,OAAgB;QACjE,MAAM,OAAO,GAAG,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;QAC5C,IAAI,CAAC,OAAO;YAAE,OAAO;QACrB,IAAI,SAAS;YAAE,OAAO,CAAC,QAAQ,CAAC,SAAS,GAAG,SAAS,CAAC;QACtD,IAAI,OAAO;YAAE,OAAO,CAAC,QAAQ,CAAC,OAAO,GAAG,OAAO,CAAC;IAClD,CAAC;IAED,GAAG,CAAC,QAAgB;QAClB,OAAO,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;IACrC,CAAC;IAED,IAAI;QACF,OAAO,CAAC,GAAG,IAAI,CAAC,QAAQ,CAAC,MAAM,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,CAAC;YACnD,GAAG,OAAO,CAAC,QAAQ;YACnB,WAAW,EAAE,OAAO,CAAC,WAAW;YAChC,UAAU,EAAE,OAAO,CAAC,UAAU;SAC/B,CAAC,CAAC,CAAC;IACN,CAAC;IAED;;;;;OAKG;IACH,QAAQ,CAAC,QAAgB;QACvB,MAAM,MAAM,GAAG,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;QACzC,IAAI,MAAM,KAAK,SAAS,IAAI,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,MAAM,CAAC;YAAE,OAAO,MAAM,CAAC;QACrE,IAAI,IAAI,CAAC,QAAQ,CAAC,IAAI,KAAK,CAAC;YAAE,OAAO,IAAI,CAAC,QAAQ,CAAC,IAAI,EAAE,CAAC,IAAI,EAAE,CAAC,KAAK,IAAI,IAAI,CAAC;QAC/E,OAAO,IAAI,CAAC;IACd,CAAC;IAED,+DAA+D;IAC/D,cAAc,CAAC,QAAgB;QAC7B,MAAM,MAAM,GAAG,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;QACzC,OAAO,MAAM,KAAK,SAAS,IAAI,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC;IAC3D,CAAC;IAED,SAAS,CAAC,QAAgB,EAAE,QAAgB;QAC1C,IAAI,CAAC,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,QAAQ,CAAC,EAAE,CAAC;YACjC,MAAM,IAAI,SAAS,CACjB,gBAAgB,EAChB,+BAA+B,QAAQ,IAAI,EAC3C,iEAAiE,CAClE,CAAC;QACJ,CAAC;QACD,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,QAAQ,EAAE,QAAQ,CAAC,CAAC;IACtC,CAAC;IAED,oEAAoE;IACpE,YAAY,CAAC,QAAgB;QAC3B,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC;IAC/B,CAAC;IAED,0EAA0E;IAE1E;;;;OAIG;IACH,IAAI,CACF,EAAU,EACV,MAAM,GAA4B,EAAE,EACpC,OAAoE;QAEpE,MAAM,OAAO,GAAG,IAAI,CAAC,cAAc,CAAC,OAAO,CAAC,QAAQ,EAAE,OAAO,CAAC,QAAQ,CAAC,CAAC;QACxE,MAAM,SAAS,GAAG,OAAO,CAAC,SAAS,IAAI,kBAAkB,CAAC;QAC1D,MAAM,OAAO,GAAY,EAAE,EAAE,EAAE,UAAU,EAAE,EAAE,EAAE,EAAE,MAAM,EAAE,CAAC;QAE1D,OAAO,IAAI,OAAO,CAAI,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE;YACxC,MAAM,KAAK,GAAG,UAAU,CAAC,GAAG,EAAE;gBAC5B,OAAO,CAAC,OAAO,CAAC,MAAM,CAAC,OAAO,CAAC,EAAE,CAAC,CAAC;gBACnC,uEAAuE;gBACvE,oEAAoE;gBACpE,yEAAyE;gBACzE,sEAAsE;gBACtE,sCAAsC;gBACtC,MAAM,CACJ,OAAO,CAAC,EAAE,EAAE,SAAS,EAAE;oBACrB,SAAS,EAAE,OAAO,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,MAAM,CAAC,EAAE,KAAK,OAAO,CAAC,EAAE,CAAC;oBACpE,WAAW,EAAE,IAAI,CAAC,GAAG,EAAE,GAAG,OAAO,CAAC,UAAU;oBAC5C,YAAY,EAAE,OAAO,CAAC,OAAO,CAAC,IAAI;oBAClC,SAAS,EAAE,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,MAAM;iBAC3C,CAAC,CACH,CAAC;YACJ,CAAC,EAAE,SAAS,CAAC,CAAC;YAEd,OAAO,CAAC,OAAO,CAAC,GAAG,CAAC,OAAO,CAAC,EAAE,EAAE;gBAC9B,OAAO,EAAE,OAAmC;gBAC5C,MAAM;gBACN,KAAK;gBACL,EAAE;aACH,CAAC,CAAC;YACH,IAAI,CAAC,OAAO,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;QACjC,CAAC,CAAC,CAAC;IACL,CAAC;IAED,+EAA+E;IAC/E,MAAM,CAAC,QAAgB,EAAE,MAAqB;QAC5C,MAAM,OAAO,GAAG,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;QAC5C,IAAI,CAAC,OAAO;YAAE,OAAO;QACrB,OAAO,CAAC,UAAU,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;QAEhC,MAAM,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,GAAG,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC;QAC/C,IAAI,CAAC,OAAO;YAAE,OAAO,CAAC,2CAA2C;QACjE,OAAO,CAAC,OAAO,CAAC,MAAM,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC;QAClC,YAAY,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC;QAE5B,IAAI,MAAM,CAAC,EAAE,EAAE,CAAC;YACd,OAAO,CAAC,OAAO,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;QAC/B,CAAC;aAAM,CAAC;YACN,OAAO,CAAC,MAAM,CACZ,MAAM,CAAC,KAAK;gBACV,CAAC,CAAC,SAAS,CAAC,gBAAgB,CAAC,MAAM,CAAC,KAAK,CAAC;gBAC1C,CAAC,CAAC,IAAI,SAAS,CAAC,cAAc,EAAE,yBAAyB,OAAO,CAAC,EAAE,IAAI,CAAC,CAC3E,CAAC;QACJ,CAAC;IACH,CAAC;IAED;;;;OAIG;IACH,cAAc,CAAC,QAAgB;QAC7B,MAAM,OAAO,GAAG,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;QAC5C,IAAI,CAAC,OAAO;YAAE,OAAO,OAAO,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC;QAC3C,OAAO,CAAC,UAAU,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;QAEhC,MAAM,MAAM,GAAG,OAAO,CAAC,KAAK,CAAC,KAAK,EAAE,CAAC;QACrC,IAAI,MAAM;YAAE,OAAO,OAAO,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC;QAE3C,OAAO,IAAI,OAAO,CAAC,CAAC,OAAO,EAAE,EAAE;YAC7B,MAAM,MAAM,GAAG,CAAC,OAAuB,EAAQ,EAAE;gBAC/C,YAAY,CAAC,KAAK,CAAC,CAAC;gBACpB,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC;gBACtB,OAAO,CAAC,OAAO,CAAC,CAAC;YACnB,CAAC,CAAC;YACF,MAAM,KAAK,GAAG,UAAU,CAAC,GAAG,EAAE;gBAC5B,IAAI,OAAO,CAAC,MAAM,KAAK,MAAM;oBAAE,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC;gBACrD,OAAO,CAAC,IAAI,CAAC,CAAC;YAChB,CAAC,EAAE,YAAY,CAAC,CAAC;YACjB,OAAO,CAAC,MAAM,GAAG,MAAM,CAAC;QAC1B,CAAC,CAAC,CAAC;IACL,CAAC;IAED,0EAA0E;IAElE,cAAc,CAAC,QAAgB,EAAE,QAAiB;QACxD,IAAI,QAAQ,EAAE,CAAC;YACb,MAAM,OAAO,GAAG,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;YAC5C,IAAI,CAAC,OAAO;gBAAE,MAAM,SAAS,EAAE,CAAC;YAChC,OAAO,OAAO,CAAC;QACjB,CAAC;QACD,IAAI,IAAI,CAAC,QAAQ,CAAC,IAAI,KAAK,CAAC;YAAE,MAAM,SAAS,EAAE,CAAC;QAEhD,iEAAiE;QACjE,MAAM,IAAI,GAAG,IAAI,CAAC,QAAQ,CAAC,MAAM,EAAE,CAAC,IAAI,EAAE,CAAC,KAAK,CAAC;QACjD,IAAI,IAAI,CAAC,QAAQ,CAAC,IAAI,KAAK,CAAC,IAAI,IAAI;YAAE,OAAO,IAAI,CAAC;QAElD,MAAM,MAAM,GAAG,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;QACzC,IAAI,MAAM,KAAK,SAAS,EAAE,CAAC;YACzB,MAAM,OAAO,GAAG,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC;YAC1C,IAAI,OAAO;gBAAE,OAAO,OAAO,CAAC;QAC9B,CAAC;QACD,MAAM,SAAS,GAAG,IAAI,CAAC,IAAI,EAAE,CAAC;QAE9B,sEAAsE;QACtE,yEAAyE;QACzE,iCAAiC;QACjC,MAAM,IAAI,GAAG,SAAS,CAAC,GAAG,CACxB,CAAC,OAAO,EAAE,EAAE,CACV,GAAG,OAAO,CAAC,QAAQ,KAAK,OAAO,CAAC,SAAS,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC,CAAC,KAAK,OAAO,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC,EAAE,GAAG,CAC/F,CAAC;QAEF,2EAA2E;QAC3E,2EAA2E;QAC3E,6EAA6E;QAC7E,6EAA6E;QAC7E,2BAA2B;QAC3B,MAAM,MAAM,GAAG,IAAI,GAAG,CAAC,SAAS,CAAC,GAAG,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC,CAAC;QACpE,IAAI,MAAM,CAAC,IAAI,KAAK,CAAC,IAAI,SAAS,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YAC9C,MAAM,iBAAiB,CAAC,IAAI,CAAC,CAAC;QAChC,CAAC;QAED,MAAM,gBAAgB,CAAC,IAAI,CAAC,CAAC;IAC/B,CAAC;IAEO,OAAO,CAAC,OAAgB,EAAE,OAAgB;QAChD,IAAI,OAAO,CAAC,MAAM,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,aAAa,EAAE,CAAC;YACpD,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,SAAS,IAAI,CAAC,SAAS,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC;YAC7D,OAAO;QACT,CAAC;QACD,IAAI,OAAO,CAAC,MAAM,EAAE,CAAC;YACnB,OAAO,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC;YACxB,OAAO;QACT,CAAC;QACD,OAAO,CAAC,KAAK,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;IAC9B,CAAC;IAED,qEAAqE;IAC7D,KAAK,CAAC,OAAgB;QAC5B,IAAI,CAAC,OAAO,CAAC,MAAM,IAAI,OAAO,CAAC,MAAM,CAAC,aAAa;YAAE,OAAO;QAC5D,KAAK,MAAM,OAAO,IAAI,OAAO,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC;YAC9C,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,SAAS,IAAI,CAAC,SAAS,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC;QAC/D,CAAC;IACH,CAAC;CACF"}

package/dist/bridge/server.js

@@ -1,12 +1,20 @@
 import { createServer } from "node:http";
 import { CLIENT_HEADER, PROTOCOL_VERSION } from "../lib/protocol.js";
+import { PEER_HEADER } from "./remote.js";
+import { toToolError } from "../lib/errors.js";
 import { Bridge } from "./rpc.js";
+import { LocalBridge } from "./api.js";
+import { probeOwner, RemoteBridge } from "./remote.js";
 /** Default loopback port. Deliberately not 58741 — that is drgost1's server. */
 export const DEFAULT_PORT = 44755;
 /** SSE comment cadence. Keeps intermediaries and Studio from reaping an idle stream. */
 const HEARTBEAT_MS = 15_000;
 /** Largest body we accept from the plugin (script sources and screenshots are big). */
 const MAX_BODY_BYTES = 32 * 1024 * 1024;
+// The bridge's own diagnostic calls. They always name a studioId outright, so
+// this never resolves anything -- it exists so they cannot inherit, or become,
+// some agent's chosen target.
+const INTERNAL_CLIENT = "bridge-internal";
 /**
  * Starts the loopback HTTP endpoint the Studio plugin talks to.
  *
@@ -38,9 +46,25 @@ export function startBridgeServer(options = {}) {
             // fight over the plugin's connection, so say so plainly instead of
             // surfacing a bare EADDRINUSE.
             if (cause.code === "EADDRINUSE") {
-                reject(new Error(`Port ${port} is already in use — another roblox-studio-mcp is probably ` +
-                    `running. Stop it, or start this one with --port <other> and set the ` +
-                    `matching port in the Studio plugin widget.`));
+                // Almost always another copy of this server, which is not a failure:
+                // the plugin can only connect to one port, so the right answer is to
+                // share that one connection rather than fight for it. Any number of MCP
+                // clients can then drive one Studio.
+                void probeOwner(port).then((existing) => {
+                    if (existing) {
+                        clearInterval(reaper);
+                        resolve({
+                            bridge: new RemoteBridge(port, existing),
+                            port,
+                            owner: false,
+                            close: async () => clearInterval(reaper),
+                        });
+                        return;
+                    }
+                    reject(new Error(`Port ${port} is in use by something that is not roblox-studio-mcp. ` +
+                        `Stop it, or start this one with --port <other> and set the matching ` +
+                        `port in the Studio plugin widget.`));
+                });
                 return;
             }
             reject(cause);
@@ -49,8 +73,9 @@ export function startBridgeServer(options = {}) {
         server.listen(port, "127.0.0.1", () => {
             server.removeListener("error", reject);
             resolve({
-                bridge,
+                bridge: new LocalBridge(bridge),
                 port,
+                owner: true,
                 close: () => closeServer(server, reaper),
             });
         });
@@ -87,6 +112,28 @@ async function handle(bridge, req, res) {
                 return await handleLatency(bridge, url, res);
             case "POST /transport":
                 return await handleTransport(bridge, url, res);
+            case "GET /identity":
+                // Answered so a second instance can tell us apart from whatever else
+                // might be squatting on the port. See probeOwner.
+                return send(res, 200, {
+                    server: "roblox-studio-mcp",
+                    protocolVersion: PROTOCOL_VERSION,
+                    pid: process.pid,
+                });
+            case "POST /call":
+                return await handlePeerCall(bridge, req, res);
+            case "GET /sessions": {
+                const clientId = peerId(req);
+                return send(res, 200, {
+                    list: bridge.list(),
+                    activeId: bridge.activeId(clientId),
+                    activeIsChosen: bridge.activeIsChosen(clientId),
+                });
+            }
+            case "POST /active":
+                return await handlePeerActive(bridge, req, res);
+            case "POST /place-name":
+                return await handlePeerPlaceName(bridge, req, res);
             case "POST /bye":
                 bridge.detach(url.searchParams.get("studioId") ?? "");
                 return send(res, 200, { ok: true });
@@ -136,11 +183,11 @@ async function handleLatency(bridge, url, res) {
     }
     // One warm-up that is not recorded: the first call after an idle period pays
     // for stream wake-up, which is real but is not what the tenth call costs.
-    await bridge.call("studio.ping", {}, { studioId: target.studioId });
+    await bridge.call("studio.ping", {}, { clientId: INTERNAL_CLIENT, studioId: target.studioId });
     const samples = [];
     for (let index = 0; index < count; index += 1) {
         const started = process.hrtime.bigint();
-        await bridge.call("studio.ping", {}, { studioId: target.studioId });
+        await bridge.call("studio.ping", {}, { clientId: INTERNAL_CLIENT, studioId: target.studioId });
         samples.push(Number(process.hrtime.bigint() - started) / 1e6);
     }
     const sorted = [...samples].sort((a, b) => a - b);
@@ -175,7 +222,7 @@ async function handleTransport(bridge, url, res) {
     if (target === undefined) {
         return send(res, 409, { error: "No Studio is connected." });
     }
-    const result = await bridge.call("studio.transport", { mode }, { studioId: target.studioId });
+    const result = await bridge.call("studio.transport", { mode }, { clientId: INTERNAL_CLIENT, studioId: target.studioId });
     send(res, 200, result);
 }
 async function handleConnect(bridge, req, res) {
@@ -278,4 +325,57 @@ function send(res, status, body) {
     });
     res.end(payload);
 }
+/**
+ * Runs a command on behalf of another instance of this server.
+ *
+ * The failure is returned as a body rather than an HTTP status, because the
+ * code and hint are the useful part and a 500 would throw them away — the peer
+ * rebuilds a ToolError from this and the agent sees the same text it would have
+ * seen had this process been the one it was talking to.
+ */
+/**
+ * Which peer is asking, so its chosen Studio does not become everyone's.
+ *
+ * A peer that sends no id is treated as one anonymous client rather than
+ * rejected: an older instance proxying to a newer one still works, it simply
+ * shares a target with any other peer that also predates the header.
+ */
+function peerId(req) {
+    const sent = req.headers[PEER_HEADER];
+    const value = Array.isArray(sent) ? sent[0] : sent;
+    return value && value.length > 0 ? value : "anonymous-peer";
+}
+async function handlePeerCall(bridge, req, res) {
+    const body = JSON.parse(await readBody(req));
+    if (typeof body.op !== "string")
+        return send(res, 400, { ok: false, error: { code: "BAD_PEER_CALL", message: "no op" } });
+    try {
+        const data = await bridge.call(body.op, body.params ?? {}, {
+            clientId: peerId(req),
+            studioId: body.studioId,
+            timeoutMs: body.timeoutMs,
+        });
+        return send(res, 200, { ok: true, data });
+    }
+    catch (cause) {
+        const error = toToolError(cause);
+        return send(res, 200, { ok: false, error: { code: error.code, message: error.message } });
+    }
+}
+async function handlePeerActive(bridge, req, res) {
+    const body = JSON.parse(await readBody(req));
+    try {
+        bridge.setActive(peerId(req), String(body.studioId ?? ""));
+        return send(res, 200, { ok: true });
+    }
+    catch (cause) {
+        const error = toToolError(cause);
+        return send(res, 200, { ok: false, error: { code: error.code, message: error.message } });
+    }
+}
+async function handlePeerPlaceName(bridge, req, res) {
+    const body = JSON.parse(await readBody(req));
+    bridge.notePlaceName(String(body.studioId ?? ""), String(body.placeName ?? ""), body.context);
+    return send(res, 200, { ok: true });
+}
 //# sourceMappingURL=server.js.map