@chrrxs/robloxstudio-mcp-inspector 2.16.0 → 2.16.2

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) {
@@ -386,30 +502,60 @@ function createHttpServer(tools, bridge, allowedTools, serverConfig) {
   });
   app.post("/ready", (req, res) => {
     const { pluginSessionId, instanceId, role, placeId, placeName, dataModelName, isRunning, pluginVersion, pluginVariant } = req.body;
+    const requestContext = {
+      instanceId: typeof instanceId === "string" ? instanceId : void 0,
+      role: typeof role === "string" ? role : void 0,
+      placeId: typeof placeId === "number" ? placeId : void 0,
+      placeName: typeof placeName === "string" ? placeName : void 0,
+      dataModelName: typeof dataModelName === "string" ? dataModelName : void 0,
+      isRunning: typeof isRunning === "boolean" ? isRunning : void 0,
+      pluginVersion: typeof pluginVersion === "string" ? pluginVersion : void 0,
+      pluginVariant: typeof pluginVariant === "string" ? pluginVariant : void 0
+    };
     if (!pluginSessionId || !instanceId || !role) {
+      const missingFields = [
+        !pluginSessionId ? "pluginSessionId" : void 0,
+        !instanceId ? "instanceId" : void 0,
+        !role ? "role" : void 0
+      ].filter((field) => !!field);
       res.status(400).json({
         success: false,
-        error: "pluginSessionId, instanceId, and role are required"
+        error: "missing_ready_fields",
+        message: `/ready missing required field(s): ${missingFields.join(", ")}`,
+        missingFields,
+        request: requestContext
+      });
+      return;
+    }
+    let result;
+    try {
+      result = bridge.registerInstance({
+        pluginSessionId,
+        instanceId,
+        role,
+        placeId: typeof placeId === "number" ? placeId : 0,
+        placeName: typeof placeName === "string" ? placeName : "",
+        dataModelName: typeof dataModelName === "string" ? dataModelName : "",
+        isRunning: !!isRunning,
+        pluginVersion: typeof pluginVersion === "string" ? pluginVersion : "",
+        pluginVariant: typeof pluginVariant === "string" ? pluginVariant : "unknown",
+        serverVersion: serverConfig?.version ?? ""
+      });
+    } catch (err) {
+      res.status(500).json({
+        success: false,
+        error: "ready_registration_exception",
+        message: err instanceof Error ? err.message : String(err),
+        request: requestContext
       });
       return;
     }
-    const result = bridge.registerInstance({
-      pluginSessionId,
-      instanceId,
-      role,
-      placeId: typeof placeId === "number" ? placeId : 0,
-      placeName: typeof placeName === "string" ? placeName : "",
-      dataModelName: typeof dataModelName === "string" ? dataModelName : "",
-      isRunning: !!isRunning,
-      pluginVersion: typeof pluginVersion === "string" ? pluginVersion : "",
-      pluginVariant: typeof pluginVariant === "string" ? pluginVariant : "unknown",
-      serverVersion: serverConfig?.version ?? ""
-    });
     if (!result.ok) {
       res.status(409).json({
         success: false,
         error: result.error.code,
         message: result.error.message,
+        request: requestContext,
         existing: result.error.existing
       });
       return;
@@ -3012,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) {
@@ -3066,6 +3214,10 @@ 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)));
       }
@@ -3223,12 +3375,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) {
@@ -3236,7 +3389,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;
@@ -3261,10 +3418,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))) {
@@ -3272,7 +3430,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);
@@ -4306,7 +4468,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,
@@ -4324,9 +4486,20 @@ ${code}`
         };
       }
       async stopPlaytest(instance_id) {
-        const response = await this._callSingle("/api/stop-playtest", {}, "edit", instance_id);
+        const { instanceId } = this._resolveSingleTarget("edit", instance_id);
+        const response = await this.client.request("/api/stop-playtest", {}, instanceId, "edit");
+        let wait;
+        if (response?.success === true) {
+          wait = await this._waitForRuntimeRoles(instanceId, { noRuntime: true }, 15, true);
+        }
+        const body = wait ? {
+          ...response,
+          runtimeStopped: wait.ok,
+          timedOut: wait.timedOut,
+          roles: wait.roles
+        } : response;
         return {
-          content: [{ type: "text", text: JSON.stringify(response) }]
+          content: [{ type: "text", text: JSON.stringify(body) }]
         };
       }
       async getPlaytestOutput(target, instance_id) {

package/package.json

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