@chrrxs/robloxstudio-mcp-inspector 2.16.1 → 2.16.3

package/dist/index.js

@@ -27,7 +27,12 @@ function toPublic(inst) {
     connectedAt: inst.connectedAt
   };
 }
-var RoutingFailure, STALE_INSTANCE_MS, BridgeService;
+function publishedInstanceId(placeId) {
+  if (placeId === void 0 || !Number.isFinite(placeId) || placeId <= 0)
+    return void 0;
+  return `place:${Math.trunc(placeId)}`;
+}
+var RoutingFailure, STALE_INSTANCE_MS, INSTANCE_ALIAS_TTL_MS, BridgeService;
 var init_bridge_service = __esm({
   "../core/dist/bridge-service.js"() {
     "use strict";
@@ -40,21 +45,91 @@ var init_bridge_service = __esm({
       }
     };
     STALE_INSTANCE_MS = 3e4;
+    INSTANCE_ALIAS_TTL_MS = 5 * 60 * 1e3;
     BridgeService = class {
       pendingRequests = /* @__PURE__ */ new Map();
       // Keyed by pluginSessionId (the per-plugin GUID).
       instances = /* @__PURE__ */ new Map();
+      instanceAliases = /* @__PURE__ */ new Map();
       requestTimeout = 3e4;
+      canonicalInstanceId(instanceId, placeId) {
+        return publishedInstanceId(placeId) ?? instanceId;
+      }
+      rememberInstanceAlias(aliasInstanceId, targetInstanceId) {
+        if (aliasInstanceId === targetInstanceId)
+          return;
+        this.instanceAliases.set(aliasInstanceId, {
+          targetInstanceId,
+          lastSeen: Date.now()
+        });
+      }
+      resolveInstanceAlias(instanceId) {
+        const alias = this.instanceAliases.get(instanceId);
+        if (!alias)
+          return instanceId;
+        alias.lastSeen = Date.now();
+        return alias.targetInstanceId;
+      }
+      migratePendingRequests(fromInstanceId, toInstanceId) {
+        if (fromInstanceId === toInstanceId)
+          return;
+        for (const request of this.pendingRequests.values()) {
+          if (request.targetInstanceId === fromInstanceId) {
+            request.targetInstanceId = toInstanceId;
+          }
+        }
+      }
+      cleanupStaleAliases(now = Date.now()) {
+        for (const [alias, entry] of this.instanceAliases.entries()) {
+          const targetIsLive = this.getInstances().some((inst) => inst.instanceId === entry.targetInstanceId);
+          if (!targetIsLive && now - entry.lastSeen > INSTANCE_ALIAS_TTL_MS) {
+            this.instanceAliases.delete(alias);
+          }
+        }
+      }
+      routingKeyForInstance(inst) {
+        return publishedInstanceId(inst.placeId) ?? this.resolveInstanceAlias(inst.instanceId);
+      }
+      matchingInstancesForInstanceId(instanceId) {
+        const resolvedInstanceId = this.resolveInstanceAlias(instanceId);
+        const ids = /* @__PURE__ */ new Set([instanceId, resolvedInstanceId]);
+        const placeIds = /* @__PURE__ */ new Set();
+        const addPlaceId = (placeId) => {
+          const published = publishedInstanceId(placeId);
+          if (!published || placeId === void 0)
+            return;
+          ids.add(published);
+          placeIds.add(Math.trunc(placeId));
+        };
+        const placeMatch = resolvedInstanceId.match(/^place:(\d+)$/) ?? instanceId.match(/^place:(\d+)$/);
+        if (placeMatch)
+          addPlaceId(Number(placeMatch[1]));
+        for (const inst of this.getInstances()) {
+          if (ids.has(inst.instanceId))
+            addPlaceId(inst.placeId);
+        }
+        return this.getInstances().filter((inst) => ids.has(inst.instanceId) || inst.placeId > 0 && placeIds.has(Math.trunc(inst.placeId)));
+      }
+      resolveInstanceId(instanceId) {
+        return this.resolveInstanceAlias(instanceId);
+      }
       registerInstance(input) {
-        const { pluginSessionId, instanceId, role } = input;
+        const { pluginSessionId, role } = input;
+        const rawInstanceId = input.instanceId;
+        const instanceId = this.canonicalInstanceId(rawInstanceId, input.placeId);
         const prior = this.instances.get(pluginSessionId);
         let assignedRole = role;
         const pluginVersion = input.pluginVersion ?? "";
         const pluginVariant = input.pluginVariant ?? "unknown";
         const serverVersion = input.serverVersion ?? "";
         const versionMismatch = pluginVersion !== "" && serverVersion !== "" && pluginVersion !== serverVersion;
+        this.rememberInstanceAlias(rawInstanceId, instanceId);
+        if (prior && prior.instanceId !== instanceId) {
+          this.rememberInstanceAlias(prior.instanceId, instanceId);
+          this.migratePendingRequests(prior.instanceId, instanceId);
+        }
         if (role === "client") {
-          if (prior && prior.instanceId === instanceId && prior.role.match(/^client-\d+$/)) {
+          if (prior && prior.role.match(/^client-\d+$/)) {
             assignedRole = prior.role;
           } else {
             const used = /* @__PURE__ */ new Set();
@@ -135,6 +210,7 @@ var init_bridge_service = __esm({
         const inst = this.instances.get(pluginSessionId);
         if (!inst)
           return;
+        const priorInstanceId = inst.instanceId;
         if (metadata.placeId !== void 0)
           inst.placeId = metadata.placeId;
         if (metadata.placeName !== void 0)
@@ -143,6 +219,15 @@ var init_bridge_service = __esm({
           inst.dataModelName = metadata.dataModelName;
         if (metadata.isRunning !== void 0)
           inst.isRunning = metadata.isRunning;
+        const canonicalInstanceId = this.canonicalInstanceId(inst.instanceId, inst.placeId);
+        if (canonicalInstanceId !== inst.instanceId) {
+          const duplicate = Array.from(this.instances.values()).find((other) => other.pluginSessionId !== pluginSessionId && other.instanceId === canonicalInstanceId && other.role === inst.role);
+          if (!duplicate) {
+            this.rememberInstanceAlias(priorInstanceId, canonicalInstanceId);
+            this.migratePendingRequests(priorInstanceId, canonicalInstanceId);
+            inst.instanceId = canonicalInstanceId;
+          }
+        }
       }
       cleanupStaleInstances() {
         const now = Date.now();
@@ -151,6 +236,37 @@ var init_bridge_service = __esm({
             this.unregisterInstance(id);
           }
         }
+        this.cleanupStaleAliases(now);
+      }
+      getEquivalentInstanceIds(instanceId) {
+        const resolvedInstanceId = this.resolveInstanceAlias(instanceId);
+        const ids = /* @__PURE__ */ new Set([instanceId, resolvedInstanceId]);
+        const placeIds = /* @__PURE__ */ new Set();
+        const addPlaceId = (placeId) => {
+          const published = publishedInstanceId(placeId);
+          if (!published || placeId === void 0)
+            return;
+          ids.add(published);
+          placeIds.add(Math.trunc(placeId));
+        };
+        const placeMatch = resolvedInstanceId.match(/^place:(\d+)$/) ?? instanceId.match(/^place:(\d+)$/);
+        if (placeMatch)
+          addPlaceId(Number(placeMatch[1]));
+        for (const inst of this.getInstances()) {
+          if (ids.has(inst.instanceId)) {
+            addPlaceId(inst.placeId);
+          }
+        }
+        for (const inst of this.getInstances()) {
+          if (inst.placeId > 0 && placeIds.has(Math.trunc(inst.placeId))) {
+            ids.add(inst.instanceId);
+          }
+        }
+        for (const [alias, entry] of this.instanceAliases.entries()) {
+          if (ids.has(entry.targetInstanceId))
+            ids.add(alias);
+        }
+        return Array.from(ids);
       }
       // Resolves (instance_id, target-role) MCP arguments to a concrete
       // routing decision: either a single (instanceId, role) tuple or a fanout
@@ -164,7 +280,7 @@ var init_bridge_service = __esm({
         const isFanout = target === "all";
         const role = target && target !== "all" ? target : void 0;
         if (instance_id !== void 0) {
-          const matchingInstances = instances.filter((i) => i.instanceId === instance_id);
+          const matchingInstances = this.matchingInstancesForInstanceId(instance_id);
           if (matchingInstances.length === 0) {
             return {
               ok: false,
@@ -197,19 +313,19 @@ var init_bridge_service = __esm({
                 }
               };
             }
-            return { ok: true, mode: "single", targetInstanceId: instance_id, targetRole: role };
+            return { ok: true, mode: "single", targetInstanceId: exact.instanceId, targetRole: role };
           }
           if (matchingInstances.length === 1) {
             return {
               ok: true,
               mode: "single",
-              targetInstanceId: instance_id,
+              targetInstanceId: matchingInstances[0].instanceId,
               targetRole: matchingInstances[0].role
             };
           }
           const edit = matchingInstances.find((i) => i.role === "edit");
           if (edit) {
-            return { ok: true, mode: "single", targetInstanceId: instance_id, targetRole: "edit" };
+            return { ok: true, mode: "single", targetInstanceId: edit.instanceId, targetRole: "edit" };
           }
           return {
             ok: false,
@@ -220,7 +336,7 @@ var init_bridge_service = __esm({
             }
           };
         }
-        const distinctInstanceIds = new Set(instances.map((i) => i.instanceId));
+        const distinctInstanceIds = new Set(instances.map((i) => this.routingKeyForInstance(i)));
         if (distinctInstanceIds.size === 0) {
           return {
             ok: false,
@@ -236,7 +352,7 @@ var init_bridge_service = __esm({
           const msg = role ? `target=${role} is ambiguous because multiple Studio places are connected. Pass instance_id to choose a place.` : "Multiple Studio places are connected. Pass instance_id to disambiguate.";
           return { ok: false, error: { code: errorCode, message: msg, data: errorData } };
         }
-        const onlyInstanceId = instances[0].instanceId;
+        const onlyInstanceId = distinctInstanceIds.values().next().value;
         return this.resolveTarget({ instance_id: onlyInstanceId, target });
       }
       async sendRequest(endpoint, data, targetInstanceId, targetRole) {
@@ -3042,23 +3158,25 @@ var init_tools = __esm({
         if (!r.ok)
           throw new RoutingFailure(r.error);
         const resolvedId = r.targetInstanceId;
-        const roles = this.bridge.getInstances().filter((i) => i.instanceId === resolvedId).map((i) => i.role);
-        const clientRoles = roles.filter((role) => role.startsWith("client")).sort();
-        return { instanceId: resolvedId, clientRole: clientRoles[0] };
+        const equivalentIds = new Set(this.bridge.getEquivalentInstanceIds(resolvedId));
+        const instances = this.bridge.getInstances().filter((i) => equivalentIds.has(i.instanceId));
+        const client = instances.filter((inst) => inst.role.startsWith("client")).sort((a, b) => a.role.localeCompare(b.role))[0];
+        return { instanceId: client?.instanceId ?? resolvedId, clientRole: client?.role };
       }
       _resolveInstanceIdOnly(instance_id) {
         const instances = this.bridge.getInstances();
         const publicList = this.bridge.getPublicInstances();
         const errorData = { instances: publicList, count: publicList.length };
         if (instance_id !== void 0) {
-          if (!instances.some((i) => i.instanceId === instance_id)) {
+          const resolvedInstanceId = this.bridge.resolveInstanceId(instance_id);
+          if (!instances.some((i) => i.instanceId === resolvedInstanceId)) {
             throw new RoutingFailure({
               code: "unrecognized_instance_id",
               message: `instance_id "${instance_id}" is not connected. Pass one from data.instances.`,
               data: errorData
             });
           }
-          return instance_id;
+          return resolvedInstanceId;
         }
         const distinct = Array.from(new Set(instances.map((i) => i.instanceId)));
         if (distinct.length === 0) {
@@ -3096,9 +3214,17 @@ var init_tools = __esm({
       _rolesForInstance(instanceId) {
         return this.bridge.getInstances().filter((i) => i.instanceId === instanceId).map((i) => i.role);
       }
+      _rolesForEquivalentInstances(instanceId) {
+        const instanceIds = new Set(this.bridge.getEquivalentInstanceIds(instanceId));
+        return this.bridge.getInstances().filter((i) => instanceIds.has(i.instanceId)).map((i) => i.role);
+      }
       _clientRolesForInstance(instanceId) {
         return this._rolesForInstance(instanceId).filter((role) => /^client-\d+$/.test(role)).sort((a, b) => Number(a.slice("client-".length)) - Number(b.slice("client-".length)));
       }
+      _runtimeTargetsForEquivalentInstances(instanceId) {
+        const instanceIds = new Set(this.bridge.getEquivalentInstanceIds(instanceId));
+        return this.bridge.getInstances().filter((i) => instanceIds.has(i.instanceId) && (i.role === "server" || /^client-\d+$/.test(i.role))).map((i) => ({ instanceId: i.instanceId, role: i.role }));
+      }
       _resolveDeviceSimulatorSingleTarget(target, instance_id, toolName) {
         const selectedTarget = target ?? "edit";
         if (selectedTarget === "server" || selectedTarget === "all" || selectedTarget === "all-clients" || selectedTarget === "edit-proxy") {
@@ -3253,12 +3379,13 @@ var init_tools = __esm({
           throw new Error(`capture_device_matrix cannot safely restore active custom device "${s.activeDeviceId}". Switch the simulator to default or a built-in preset first, or pass restoreAfter=false only if you intentionally accept changing the simulator state.`);
         }
       }
-      async _waitForRuntimeRoles(instanceId, opts, timeoutSec = 30) {
+      async _waitForRuntimeRoles(instanceId, opts, timeoutSec = 30, equivalentInstances = false) {
         const deadline = Date.now() + timeoutSec * 1e3;
         while (Date.now() < deadline) {
-          const roles = this._rolesForInstance(instanceId);
+          const roles = equivalentInstances ? this._rolesForEquivalentInstances(instanceId) : this._rolesForInstance(instanceId);
+          const clientRoles = equivalentInstances ? roles.filter((role) => /^client-\d+$/.test(role)) : this._clientRolesForInstance(instanceId);
           const hasServer = !opts.server || roles.includes("server");
-          const hasClients = opts.clientCount === void 0 || this._clientRolesForInstance(instanceId).length >= opts.clientCount;
+          const hasClients = opts.clientCount === void 0 || clientRoles.length >= opts.clientCount;
           const absent = opts.absentRole === void 0 || !roles.includes(opts.absentRole);
           const runtimeAbsent = !opts.noRuntime || !roles.some((role) => role === "server" || /^client-\d+$/.test(role));
           if (hasServer && hasClients && absent && runtimeAbsent) {
@@ -3266,7 +3393,11 @@ var init_tools = __esm({
           }
           await sleep(250);
         }
-        return { ok: false, roles: this._rolesForInstance(instanceId), timedOut: true };
+        return {
+          ok: false,
+          roles: equivalentInstances ? this._rolesForEquivalentInstances(instanceId) : this._rolesForInstance(instanceId),
+          timedOut: true
+        };
       }
       async _waitForExactClientCount(instanceId, expectedClientCount, timeoutSec = 30, stableMs = 3e3) {
         const deadline = Date.now() + timeoutSec * 1e3;
@@ -3291,10 +3422,11 @@ var init_tools = __esm({
         const clientCount = this._clientRolesForInstance(instanceId).length;
         return { ok: false, roles, timedOut: true, extraClients: clientCount > expectedClientCount, clientCount };
       }
-      async _waitForRuntimeRolesFresh(instanceId, connectedAfter, requiredRoles, timeoutSec = 60) {
+      async _waitForRuntimeRolesFresh(instanceId, connectedAfter, requiredRoles, timeoutSec = 60, equivalentInstances = false) {
         const deadline = Date.now() + timeoutSec * 1e3;
         while (Date.now() < deadline) {
-          const instances = this.bridge.getInstances().filter((i) => i.instanceId === instanceId);
+          const instanceIds = equivalentInstances ? new Set(this.bridge.getEquivalentInstanceIds(instanceId)) : /* @__PURE__ */ new Set([instanceId]);
+          const instances = this.bridge.getInstances().filter((i) => instanceIds.has(i.instanceId));
           const roles = instances.map((i) => i.role);
           const freshRoles = new Set(instances.filter((i) => i.connectedAt >= connectedAfter).map((i) => i.role));
           if (requiredRoles.every((role) => freshRoles.has(role))) {
@@ -3302,7 +3434,11 @@ var init_tools = __esm({
           }
           await sleep(250);
         }
-        return { ok: false, roles: this._rolesForInstance(instanceId), timedOut: true };
+        return {
+          ok: false,
+          roles: equivalentInstances ? this._rolesForEquivalentInstances(instanceId) : this._rolesForInstance(instanceId),
+          timedOut: true
+        };
       }
       async getFileTree(path2 = "", instance_id) {
         const response = await this._callSingle("/api/file-tree", { path: path2 }, void 0, instance_id);
@@ -4336,7 +4472,7 @@ ${code}`
         let wait;
         if (response?.success === true) {
           const requiredRoles = mode === "play" ? ["server", "client-1"] : ["server"];
-          wait = await this._waitForRuntimeRolesFresh(resolved.targetInstanceId, startedAt, requiredRoles);
+          wait = await this._waitForRuntimeRolesFresh(resolved.targetInstanceId, startedAt, requiredRoles, 60, true);
         }
         const body = wait ? {
           ...response,
@@ -4355,10 +4491,27 @@ ${code}`
       }
       async stopPlaytest(instance_id) {
         const { instanceId } = this._resolveSingleTarget("edit", instance_id);
-        const response = await this.client.request("/api/stop-playtest", {}, instanceId, "edit");
+        let response;
+        let stopRequestError;
+        try {
+          response = await this.client.request("/api/stop-playtest", {}, instanceId, "edit");
+        } catch (error) {
+          stopRequestError = errorMessage(error);
+          response = {
+            success: false,
+            error: "Edit stop request failed.",
+            detail: stopRequestError
+          };
+        }
         let wait;
         if (response?.success === true) {
-          wait = await this._waitForRuntimeRoles(instanceId, { noRuntime: true }, 15);
+          wait = await this._waitForRuntimeRoles(instanceId, { noRuntime: true }, 15, true);
+        } else if (this._runtimeTargetsForEquivalentInstances(instanceId).length > 0) {
+          wait = {
+            ok: false,
+            roles: this._rolesForEquivalentInstances(instanceId),
+            timedOut: false
+          };
         }
         const body = wait ? {
           ...response,
@@ -4366,6 +4519,22 @@ ${code}`
           timedOut: wait.timedOut,
           roles: wait.roles
         } : response;
+        if (wait && !wait.ok) {
+          const runtimeRoles = wait.roles.filter((role) => role === "server" || /^client-\d+$/.test(role));
+          const failureBody = {
+            ...body,
+            success: false,
+            error: "Playtest teardown did not complete.",
+            message: response?.success === true ? wait.timedOut ? "Stop signal was accepted, but runtime peers did not disconnect before timeout." : "Stop signal was accepted, but runtime peers are still connected." : "Edit stop request failed, and runtime peers are still connected.",
+            stopSignalAccepted: response?.success === true,
+            stopRequestError,
+            runtimeRoles,
+            possibleCause: "A game shutdown hook such as BindToClose may be blocking Studio teardown. No runtime hard-stop or synthetic keyboard fallback was attempted."
+          };
+          return {
+            content: [{ type: "text", text: JSON.stringify(failureBody) }]
+          };
+        }
         return {
           content: [{ type: "text", text: JSON.stringify(body) }]
         };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@chrrxs/robloxstudio-mcp-inspector",
-  "version": "2.16.1",
+  "version": "2.16.3",
   "description": "Read-only MCP server for inspecting and debugging Roblox Studio from AI coding tools",
   "main": "dist/index.js",
   "type": "module",