@chrrxs/robloxstudio-mcp 2.13.0 → 2.15.0

package/dist/index.js

@@ -43,18 +43,25 @@ var init_bridge_service = __esm({
       requestTimeout = 3e4;
       registerInstance(input) {
         const { pluginSessionId, instanceId, role } = input;
+        const prior = this.instances.get(pluginSessionId);
         let assignedRole = role;
         if (role === "client") {
-          const used = /* @__PURE__ */ new Set();
-          for (const inst of this.instances.values()) {
-            const match = inst.role.match(/^client-(\d+)$/);
-            if (match)
-              used.add(Number(match[1]));
+          if (prior && prior.instanceId === instanceId && prior.role.match(/^client-\d+$/)) {
+            assignedRole = prior.role;
+          } else {
+            const used = /* @__PURE__ */ new Set();
+            for (const inst of this.instances.values()) {
+              if (inst.instanceId !== instanceId || inst.pluginSessionId === pluginSessionId)
+                continue;
+              const match = inst.role.match(/^client-(\d+)$/);
+              if (match)
+                used.add(Number(match[1]));
+            }
+            let idx = 1;
+            while (used.has(idx))
+              idx++;
+            assignedRole = `client-${idx}`;
           }
-          let idx = 1;
-          while (used.has(idx))
-            idx++;
-          assignedRole = `client-${idx}`;
         }
         const existing = Array.from(this.instances.values()).find((i) => i.instanceId === instanceId && i.role === assignedRole && i.pluginSessionId !== pluginSessionId);
         if (existing) {
@@ -76,7 +83,7 @@ var init_bridge_service = __esm({
           dataModelName: input.dataModelName ?? "",
           isRunning: input.isRunning ?? false,
           lastActivity: Date.now(),
-          connectedAt: Date.now()
+          connectedAt: prior?.connectedAt ?? Date.now()
         });
         return { ok: true, assignedRole, instanceId };
       }
@@ -214,7 +221,7 @@ var init_bridge_service = __esm({
         }
         if (distinctInstanceIds.size > 1) {
           const errorCode = role ? "ambiguous_target" : "multiple_instances_connected";
-          const msg = role ? `target=${role} is ambiguous: multiple places have this role. Pass instance_id.` : "Multiple Studio places are connected. Pass instance_id to disambiguate.";
+          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;
@@ -236,6 +243,7 @@ var init_bridge_service = __esm({
             targetInstanceId,
             targetRole,
             timestamp: Date.now(),
+            inFlight: false,
             resolve: resolve2,
             reject,
             timeoutId
@@ -250,11 +258,14 @@ var init_bridge_service = __esm({
             continue;
           if (request.targetRole !== callerRole)
             continue;
+          if (request.inFlight)
+            continue;
           if (!oldestRequest || request.timestamp < oldestRequest.timestamp) {
             oldestRequest = request;
           }
         }
         if (oldestRequest) {
+          oldestRequest.inFlight = true;
           return {
             requestId: oldestRequest.id,
             request: {
@@ -677,6 +688,11 @@ var init_http_server = __esm({
       start_playtest: (tools, body) => tools.startPlaytest(body.mode, body.numPlayers, body.instance_id),
       stop_playtest: (tools, body) => tools.stopPlaytest(body.instance_id),
       get_playtest_output: (tools, body) => tools.getPlaytestOutput(body.target, body.instance_id),
+      multiplayer_test_start: (tools, body) => tools.multiplayerTestStart(body.numPlayers, body.testArgs, body.timeout, body.instance_id),
+      multiplayer_test_state: (tools, body) => tools.multiplayerTestState(body.instance_id),
+      multiplayer_test_add_players: (tools, body) => tools.multiplayerTestAddPlayers(body.numPlayers, body.timeout, body.instance_id),
+      multiplayer_test_leave_client: (tools, body) => tools.multiplayerTestLeaveClient(body.target, body.timeout, body.instance_id),
+      multiplayer_test_end: (tools, body) => tools.multiplayerTestEnd(body.value, body.timeout, body.instance_id),
       get_runtime_logs: (tools, body) => tools.getRuntimeLogs(body.target, body.since, body.tail, body.filter, body.instance_id),
       get_connected_instances: (tools) => tools.getConnectedInstances(),
       export_build: (tools, body) => tools.exportBuild(body.instancePath, body.outputId, body.style, body.instance_id),
@@ -705,6 +721,7 @@ var init_http_server = __esm({
       simulate_keyboard_input: (tools, body) => tools.simulateKeyboardInput(body.keyCode, body.action, body.duration, body.text, body.target, body.instance_id),
       character_navigation: (tools, body) => tools.characterNavigation(body.position, body.instancePath, body.waitForCompletion, body.timeout, body.target, body.instance_id),
       get_memory_breakdown: (tools, body) => tools.getMemoryBreakdown(body.target, body.tags, body.instance_id),
+      get_scene_analysis: (tools, body) => tools.getSceneAnalysis(body.mode, body.target, body.topN, body.raw, body.instance_id),
       export_rbxm: (tools, body) => tools.exportRbxm(body.instance_paths, body.output_path, body.target, body.instance_id),
       import_rbxm: (tools, body) => tools.importRbxm(body.source, body.parent_path, body.target, body.instance_id),
       find_and_replace_in_scripts: (tools, body) => tools.findAndReplaceInScripts(body.pattern, body.replacement, {
@@ -2714,6 +2731,9 @@ function parseBridgeResponse(response) {
   }
   return JSON.stringify(response);
 }
+function sleep(ms) {
+  return new Promise((resolve2) => setTimeout(resolve2, ms));
+}
 var SERVER_LOCAL_NAME, CLIENT_LOCAL_NAME, EVAL_WRAPPER_LINE_OFFSET, RobloxStudioTools;
 var init_tools = __esm({
   "../core/dist/tools/index.js"() {
@@ -2774,6 +2794,110 @@ var init_tools = __esm({
         const clientRoles = roles.filter((role) => role.startsWith("client")).sort();
         return { instanceId: resolvedId, clientRole: clientRoles[0] };
       }
+      _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)) {
+            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;
+        }
+        const distinct = Array.from(new Set(instances.map((i) => i.instanceId)));
+        if (distinct.length === 0) {
+          throw new RoutingFailure({
+            code: "unrecognized_instance_id",
+            message: "No Studio plugin is connected.",
+            data: errorData
+          });
+        }
+        if (distinct.length > 1) {
+          throw new RoutingFailure({
+            code: "multiple_instances_connected",
+            message: "Multiple Studio places are connected. Pass instance_id to disambiguate.",
+            data: errorData
+          });
+        }
+        return distinct[0];
+      }
+      _resolveSingleTarget(target, instance_id) {
+        const resolved = this.bridge.resolveTarget({ instance_id, target });
+        if (!resolved.ok)
+          throw new RoutingFailure(resolved.error);
+        if (resolved.mode !== "single") {
+          throw new RoutingFailure({
+            code: "target_role_not_present_on_instance",
+            message: "Pick a specific target role for this tool.",
+            data: {
+              instances: this.bridge.getPublicInstances(),
+              count: this.bridge.getInstances().length
+            }
+          });
+        }
+        return { instanceId: resolved.targetInstanceId, role: resolved.targetRole };
+      }
+      _rolesForInstance(instanceId) {
+        return this.bridge.getInstances().filter((i) => i.instanceId === 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)));
+      }
+      async _waitForRuntimeRoles(instanceId, opts, timeoutSec = 30) {
+        const deadline = Date.now() + timeoutSec * 1e3;
+        while (Date.now() < deadline) {
+          const roles = this._rolesForInstance(instanceId);
+          const hasServer = !opts.server || roles.includes("server");
+          const hasClients = opts.clientCount === void 0 || this._clientRolesForInstance(instanceId).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) {
+            return { ok: true, roles, timedOut: false };
+          }
+          await sleep(250);
+        }
+        return { ok: false, roles: this._rolesForInstance(instanceId), timedOut: true };
+      }
+      async _waitForExactClientCount(instanceId, expectedClientCount, timeoutSec = 30, stableMs = 3e3) {
+        const deadline = Date.now() + timeoutSec * 1e3;
+        let exactSince;
+        while (Date.now() < deadline) {
+          const roles2 = this._rolesForInstance(instanceId);
+          const clientCount2 = this._clientRolesForInstance(instanceId).length;
+          if (clientCount2 > expectedClientCount) {
+            return { ok: false, roles: roles2, timedOut: false, extraClients: true, clientCount: clientCount2 };
+          }
+          if (roles2.includes("server") && clientCount2 === expectedClientCount) {
+            exactSince ??= Date.now();
+            if (Date.now() - exactSince >= stableMs) {
+              return { ok: true, roles: roles2, timedOut: false, extraClients: false, clientCount: clientCount2 };
+            }
+          } else {
+            exactSince = void 0;
+          }
+          await sleep(250);
+        }
+        const roles = this._rolesForInstance(instanceId);
+        const clientCount = this._clientRolesForInstance(instanceId).length;
+        return { ok: false, roles, timedOut: true, extraClients: clientCount > expectedClientCount, clientCount };
+      }
+      async _waitForRuntimeRolesFresh(instanceId, connectedAfter, requiredRoles, timeoutSec = 60) {
+        const deadline = Date.now() + timeoutSec * 1e3;
+        while (Date.now() < deadline) {
+          const instances = this.bridge.getInstances().filter((i) => i.instanceId === 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))) {
+            return { ok: true, roles, timedOut: false };
+          }
+          await sleep(250);
+        }
+        return { ok: false, roles: this._rolesForInstance(instanceId), timedOut: true };
+      }
       async getFileTree(path2 = "", instance_id) {
         const response = await this._callSingle("/api/file-tree", { path: path2 }, void 0, instance_id);
         return {
@@ -3418,16 +3542,41 @@ ${code}`
         if (mode !== "play" && mode !== "run") {
           throw new Error('mode must be "play" or "run"');
         }
-        const data = { mode };
         if (numPlayers !== void 0) {
-          data.numPlayers = numPlayers;
+          throw new Error("start_playtest is single-player only. Use multiplayer_test_start for multi-client StudioTestService sessions.");
+        }
+        const data = { mode };
+        const startedAt = Date.now();
+        const resolved = this.bridge.resolveTarget({ instance_id, target: void 0 });
+        if (!resolved.ok)
+          throw new RoutingFailure(resolved.error);
+        if (resolved.mode !== "single") {
+          throw new RoutingFailure({
+            code: "target_role_not_present_on_instance",
+            message: "This tool does not support target=all. Pick a specific role or omit target.",
+            data: {
+              instances: this.bridge.getPublicInstances(),
+              count: this.bridge.getInstances().length
+            }
+          });
         }
-        const response = await this._callSingle("/api/start-playtest", data, void 0, instance_id);
+        const response = await this.client.request("/api/start-playtest", data, resolved.targetInstanceId, resolved.targetRole);
+        let wait;
+        if (response?.success === true) {
+          const requiredRoles = mode === "play" ? ["server", "client-1"] : ["server"];
+          wait = await this._waitForRuntimeRolesFresh(resolved.targetInstanceId, startedAt, requiredRoles);
+        }
+        const body = wait ? {
+          ...response,
+          runtimeReady: wait.ok,
+          timedOut: wait.timedOut,
+          roles: wait.roles
+        } : response;
         return {
           content: [
             {
               type: "text",
-              text: JSON.stringify(response)
+              text: JSON.stringify(body)
             }
           ]
         };
@@ -3449,6 +3598,196 @@ ${code}`
           ]
         };
       }
+      async _buildMultiplayerState(instanceId) {
+        const peers = this.bridge.getPublicInstances().filter((i) => i.instanceId === instanceId).sort((a, b) => a.role.localeCompare(b.role));
+        const body = {
+          instanceId,
+          peers,
+          peerCount: peers.length
+        };
+        const edit = peers.find((p) => p.role === "edit");
+        const server = peers.find((p) => p.role === "server");
+        let editState;
+        let serverState;
+        if (edit) {
+          try {
+            editState = await this.client.request("/api/multiplayer-test-state", {}, instanceId, "edit");
+            body.edit = editState;
+          } catch (err) {
+            body.edit = { error: err instanceof Error ? err.message : String(err) };
+          }
+        }
+        if (server) {
+          try {
+            serverState = await this.client.request("/api/multiplayer-test-state", {}, instanceId, "server");
+            body.server = serverState;
+          } catch (err) {
+            body.server = { error: err instanceof Error ? err.message : String(err) };
+          }
+        }
+        const session = editState?.session;
+        const rawPhase = typeof session?.phase === "string" ? session.phase : void 0;
+        const hasRuntime = peers.some((p) => p.role === "server" || p.role.startsWith("client-"));
+        body.phase = rawPhase === "starting" && hasRuntime ? "running" : rawPhase ?? (hasRuntime ? "running" : "idle");
+        body.testId = session?.testId;
+        body.numPlayers = session?.numPlayers;
+        body.testArgs = session?.testArgs ?? serverState?.testArgs;
+        body.result = session?.result;
+        body.error = session?.error;
+        body.players = serverState?.players ?? [];
+        body.playerCount = serverState?.playerCount ?? 0;
+        body.clientRoles = this._clientRolesForInstance(instanceId);
+        return body;
+      }
+      async _waitForMultiplayerEditDone(instanceId, timeoutSec = 30) {
+        const deadline = Date.now() + timeoutSec * 1e3;
+        while (Date.now() < deadline) {
+          if (!this._rolesForInstance(instanceId).includes("edit"))
+            return false;
+          try {
+            const editState = await this.client.request("/api/multiplayer-test-state", {}, instanceId, "edit");
+            const phase = editState?.session?.phase;
+            if (phase === "completed" || phase === "failed")
+              return true;
+          } catch {
+          }
+          await sleep(250);
+        }
+        return false;
+      }
+      async _isMultiplayerTestRunning(instanceId) {
+        if (!this._rolesForInstance(instanceId).includes("edit"))
+          return false;
+        try {
+          const editState = await this.client.request("/api/multiplayer-test-state", {}, instanceId, "edit");
+          const phase = editState?.session?.phase;
+          return phase === "starting" || phase === "running";
+        } catch {
+          return false;
+        }
+      }
+      async _waitForMultiplayerStart(instanceId, clientCount, timeoutSec = 30) {
+        const deadline = Date.now() + timeoutSec * 1e3;
+        while (Date.now() < deadline) {
+          const exact = await this._waitForExactClientCount(instanceId, clientCount, 0.25, 0);
+          if (exact.ok || exact.extraClients) {
+            return { ok: exact.ok, roles: exact.roles, timedOut: false, error: exact.extraClients ? `Expected ${clientCount} client(s), but Studio registered ${exact.clientCount}.` : void 0 };
+          }
+          try {
+            const editState = await this.client.request("/api/multiplayer-test-state", {}, instanceId, "edit");
+            const session = editState?.session;
+            if (session?.phase === "failed" || session?.phase === "completed") {
+              return { ok: false, roles: this._rolesForInstance(instanceId), timedOut: false, phase: session.phase, error: session.error };
+            }
+          } catch {
+          }
+          await sleep(250);
+        }
+        return { ok: false, roles: this._rolesForInstance(instanceId), timedOut: true };
+      }
+      async multiplayerTestStart(numPlayers, testArgs, timeout, instance_id) {
+        if (!Number.isInteger(numPlayers) || numPlayers < 1 || numPlayers > 8) {
+          throw new Error("numPlayers must be an integer from 1 to 8");
+        }
+        const editTarget = this._resolveSingleTarget("edit", instance_id);
+        const response = await this.client.request("/api/multiplayer-test-start", { numPlayers, testArgs: testArgs ?? {} }, editTarget.instanceId, editTarget.role);
+        if (response?.error) {
+          return { content: [{ type: "text", text: JSON.stringify(response) }] };
+        }
+        const wait = await this._waitForMultiplayerStart(editTarget.instanceId, numPlayers, timeout ?? 30);
+        const state = await this._buildMultiplayerState(editTarget.instanceId);
+        return {
+          content: [{
+            type: "text",
+            text: JSON.stringify({
+              ...response,
+              ready: wait.ok,
+              timedOut: wait.timedOut,
+              wait,
+              roles: wait.roles,
+              state
+            })
+          }]
+        };
+      }
+      async multiplayerTestState(instance_id) {
+        const instanceId = this._resolveInstanceIdOnly(instance_id);
+        const state = await this._buildMultiplayerState(instanceId);
+        return { content: [{ type: "text", text: JSON.stringify(state) }] };
+      }
+      async multiplayerTestAddPlayers(numPlayers, timeout, instance_id) {
+        if (!Number.isInteger(numPlayers) || numPlayers < 1 || numPlayers > 8) {
+          throw new Error("numPlayers must be an integer from 1 to 8");
+        }
+        const serverTarget = this._resolveSingleTarget("server", instance_id);
+        const before = this._clientRolesForInstance(serverTarget.instanceId).length;
+        const response = await this.client.request("/api/multiplayer-test-add-players", { numPlayers, timeout: timeout ?? 10 }, serverTarget.instanceId, serverTarget.role);
+        if (response?.error) {
+          return { content: [{ type: "text", text: JSON.stringify(response) }] };
+        }
+        const wait = await this._waitForExactClientCount(serverTarget.instanceId, before + numPlayers, timeout ?? 30);
+        const state = await this._buildMultiplayerState(serverTarget.instanceId);
+        return {
+          content: [{
+            type: "text",
+            text: JSON.stringify({
+              ...response,
+              ready: wait.ok,
+              timedOut: wait.timedOut,
+              wait,
+              roles: wait.roles,
+              state
+            })
+          }]
+        };
+      }
+      async multiplayerTestLeaveClient(target = "client-1", timeout, instance_id) {
+        if (!/^client-\d+$/.test(target)) {
+          throw new Error(`multiplayer_test_leave_client requires target=client-N (got: ${target})`);
+        }
+        const clientTarget = this._resolveSingleTarget(target, instance_id);
+        const response = await this.client.request("/api/multiplayer-test-leave-client", {}, clientTarget.instanceId, clientTarget.role);
+        if (response?.error) {
+          return { content: [{ type: "text", text: JSON.stringify(response) }] };
+        }
+        const wait = await this._waitForRuntimeRoles(clientTarget.instanceId, { absentRole: clientTarget.role }, timeout ?? 30);
+        const state = await this._buildMultiplayerState(clientTarget.instanceId);
+        return {
+          content: [{
+            type: "text",
+            text: JSON.stringify({
+              ...response,
+              left: wait.ok,
+              timedOut: wait.timedOut,
+              roles: wait.roles,
+              state
+            })
+          }]
+        };
+      }
+      async multiplayerTestEnd(value, timeout, instance_id) {
+        const serverTarget = this._resolveSingleTarget("server", instance_id);
+        const response = await this.client.request("/api/multiplayer-test-end", { value: value ?? "ended_by_mcp" }, serverTarget.instanceId, serverTarget.role);
+        if (response?.error) {
+          return { content: [{ type: "text", text: JSON.stringify(response) }] };
+        }
+        const editDone = await this._waitForMultiplayerEditDone(serverTarget.instanceId, timeout ?? 30);
+        const wait = await this._waitForRuntimeRoles(serverTarget.instanceId, { noRuntime: true }, timeout ?? 30);
+        const state = await this._buildMultiplayerState(serverTarget.instanceId);
+        return {
+          content: [{
+            type: "text",
+            text: JSON.stringify({
+              ...response,
+              ended: wait.ok,
+              editDone,
+              timedOut: wait.timedOut,
+              roles: wait.roles,
+              state
+            })
+          }]
+        };
+      }
       async getConnectedInstances() {
         const instances = this.bridge.getPublicInstances();
         return {
@@ -3484,15 +3823,15 @@ ${code}`
       }
       static findProjectRoot(startDir) {
         let dir = path.resolve(startDir);
-        while (true) {
+        let previous = "";
+        while (dir !== previous) {
           if (fs.existsSync(path.join(dir, ".git")) || fs.existsSync(path.join(dir, "package.json"))) {
             return dir;
           }
-          const parent = path.dirname(dir);
-          if (parent === dir)
-            return null;
-          dir = parent;
+          previous = dir;
+          dir = path.dirname(dir);
         }
+        return null;
       }
       static isDirectory(candidate) {
         if (!candidate)
@@ -4302,6 +4641,39 @@ ${code}`
         }
         return { content: [{ type: "text", text: JSON.stringify(body) }] };
       }
+      async getSceneAnalysis(mode, target, topN, raw, instance_id) {
+        const tgt = target ?? "all";
+        const data = {};
+        if (mode !== void 0)
+          data.mode = mode;
+        if (topN !== void 0)
+          data.topN = topN;
+        if (raw !== void 0)
+          data.raw = raw;
+        const resolved = this.bridge.resolveTarget({ instance_id, target: tgt });
+        if (!resolved.ok)
+          throw new RoutingFailure(resolved.error);
+        if (resolved.mode === "single") {
+          const response = await this.client.request("/api/get-scene-analysis", data, resolved.targetInstanceId, resolved.targetRole);
+          return { content: [{ type: "text", text: JSON.stringify(response) }] };
+        }
+        const targets = resolved.targets.filter((t) => t.targetRole !== "edit-proxy");
+        const responses = await Promise.allSettled(targets.map(async (t) => ({
+          peer: t.targetRole,
+          result: await this.client.request("/api/get-scene-analysis", data, t.targetInstanceId, t.targetRole)
+        })));
+        const body = {};
+        for (let i = 0; i < responses.length; i++) {
+          const r = responses[i];
+          const peer = targets[i].targetRole;
+          if (r.status === "fulfilled") {
+            body[peer] = r.value.result;
+          } else {
+            body[peer] = { error: "disconnected" };
+          }
+        }
+        return { content: [{ type: "text", text: JSON.stringify(body) }] };
+      }
       async exportRbxm(instancePaths, outputPath, target, instance_id) {
         if (!Array.isArray(instancePaths) || instancePaths.length === 0) {
           throw new Error("instance_paths must be a non-empty array for export_rbxm");
@@ -4425,10 +4797,14 @@ ${code}`
           response = await this._callSingle("/api/capture-screenshot", {}, "edit", instanceId);
         }
         if (response.error) {
+          let text = response.error;
+          if (clientRole && response.error.includes("Failed to load texture, unexpected format") && await this._isMultiplayerTestRunning(instanceId)) {
+            text = `Screenshot capture reached the multiplayer client, but Roblox returned a temporary screenshot texture that the edit peer cannot read in StudioTestService multiplayer sessions. Regular start_playtest capture works because the temporary rbxtemp:// handle is readable from the edit process; multiplayer client handles appear to be scoped to the client process. Raw error: ${response.error}`;
+          }
           return {
             content: [{
               type: "text",
-              text: response.error
+              text
             }]
           };
         }
@@ -4440,7 +4816,9 @@ ${code}`
         const fmt = format === "png" ? "png" : "jpeg";
         const q = quality === void 0 ? 92 : Math.max(1, Math.min(100, Math.floor(quality)));
         const MAX_IMAGE_BYTES = 6e6;
-        let { buffer, mimeType } = encodeImageFromRgbaResponse(response, fmt, q);
+        const encoded = encodeImageFromRgbaResponse(response, fmt, q);
+        let { buffer } = encoded;
+        const { mimeType } = encoded;
         let usedQ = q;
         let note = "";
         if (buffer.length > MAX_IMAGE_BYTES) {
@@ -5607,7 +5985,7 @@ var init_definitions = __esm({
       {
         name: "execute_luau",
         category: "write",
-        description: "Execute Luau code in plugin context. Use print()/warn() for output. Return value is captured.",
+        description: 'Execute Luau code in plugin context. target="server" and target="client-N" run against live runtime DataModels with PluginSecurity permissions; use eval_*_runtime instead when you need the game Script/LocalScript VM require cache. Use print()/warn() for output. Return value is captured.',
         inputSchema: {
           type: "object",
           properties: {
@@ -5630,7 +6008,7 @@ var init_definitions = __esm({
       {
         name: "eval_server_runtime",
         category: "write",
-        description: "Execute Luau on the server peer in the running game's Script VM (shares require cache with user game scripts). Use this instead of execute_luau target=server when you need to see runtime-mutated module state. Requires a running playtest; the bridge is installed automatically (including for playtests started manually via the Studio Play button).",
+        description: "Execute Luau on the server peer in the running game's Script VM (shares require cache with user game scripts, unlike execute_luau target=server which runs in plugin context). Requires a running playtest; the bridge is installed automatically (including for playtests started manually via the Studio Play button).",
         inputSchema: {
           type: "object",
           properties: {
@@ -5649,7 +6027,7 @@ var init_definitions = __esm({
       {
         name: "eval_client_runtime",
         category: "write",
-        description: "Execute Luau on a client peer in the running game's LocalScript VM (shares require cache with user game scripts). Use this instead of execute_luau target=client-N when you need to see runtime-mutated module state. Requires a running playtest; the bridge is installed automatically (including for playtests started manually via the Studio Play button).",
+        description: "Execute Luau on a client peer in the running game's LocalScript VM (shares require cache with user game scripts, unlike execute_luau target=client-N which runs in plugin context). Requires a running playtest; the bridge is installed automatically (including for playtests started manually via the Studio Play button).",
         inputSchema: {
           type: "object",
           properties: {
@@ -5726,7 +6104,7 @@ var init_definitions = __esm({
       {
         name: "start_playtest",
         category: "write",
-        description: "Start playtest. Captures print/warn/error via LogService. Poll with get_playtest_output, end with stop_playtest. Use numPlayers for multi-client testing (server + N clients).",
+        description: "Start a simple single-player Studio playtest in play or run mode, waiting until a runtime peer registers with MCP. Captures print/warn/error via LogService. Poll with get_playtest_output, end with stop_playtest. For multi-client testing use multiplayer_test_start instead.",
         inputSchema: {
           type: "object",
           properties: {
@@ -5737,7 +6115,7 @@ var init_definitions = __esm({
             },
             numPlayers: {
               type: "number",
-              description: "Number of client players (1-8). Triggers server + clients mode via TestService."
+              description: "Deprecated and rejected. Use multiplayer_test_start for multi-client testing."
             },
             instance_id: {
               type: "string",
@@ -5779,6 +6157,112 @@ var init_definitions = __esm({
           }
         }
       },
+      {
+        name: "multiplayer_test_start",
+        category: "write",
+        description: "Start a StudioTestService multiplayer test and wait for the server plus requested client peers to connect. Use this for multi-client runtime testing.",
+        inputSchema: {
+          type: "object",
+          properties: {
+            numPlayers: {
+              type: "number",
+              description: "Number of client players to start (1-8)."
+            },
+            testArgs: {
+              description: "JSON-compatible table passed to StudioTestService:GetTestArgs() on server and clients."
+            },
+            timeout: {
+              type: "number",
+              description: "Max seconds to wait for server + clients to register (default 30)."
+            },
+            instance_id: {
+              type: "string",
+              description: "Which connected Studio place to target. Required when multiple places are connected; omit when one. Use get_connected_instances to list available IDs."
+            }
+          },
+          required: ["numPlayers"]
+        }
+      },
+      {
+        name: "multiplayer_test_state",
+        category: "read",
+        description: "Get the active multiplayer StudioTestService state for a place: phase, peers, players, original testArgs, result/error, and connected client roles.",
+        inputSchema: {
+          type: "object",
+          properties: {
+            instance_id: {
+              type: "string",
+              description: "Which connected Studio place to inspect. Required when multiple places are connected; omit when one. Use get_connected_instances to list available IDs."
+            }
+          }
+        }
+      },
+      {
+        name: "multiplayer_test_add_players",
+        category: "write",
+        description: "Add client players to a running StudioTestService multiplayer test and wait for the new clients to connect.",
+        inputSchema: {
+          type: "object",
+          properties: {
+            numPlayers: {
+              type: "number",
+              description: "Number of additional client players to add (1-8)."
+            },
+            timeout: {
+              type: "number",
+              description: "Max seconds to wait for new clients to register (default 30)."
+            },
+            instance_id: {
+              type: "string",
+              description: "Which connected Studio place to target. Required when multiple places are connected; omit when one. Use get_connected_instances to list available IDs."
+            }
+          },
+          required: ["numPlayers"]
+        }
+      },
+      {
+        name: "multiplayer_test_leave_client",
+        category: "write",
+        description: "Disconnect a specific client from a running StudioTestService multiplayer test, then wait for that client peer to leave.",
+        inputSchema: {
+          type: "object",
+          properties: {
+            target: {
+              type: "string",
+              description: 'Client target to leave: "client-1" (default), "client-2", etc.'
+            },
+            timeout: {
+              type: "number",
+              description: "Max seconds to wait for the client peer to disconnect (default 30)."
+            },
+            instance_id: {
+              type: "string",
+              description: "Which connected Studio place to target. Required when multiple places are connected; omit when one. Use get_connected_instances to list available IDs."
+            }
+          }
+        }
+      },
+      {
+        name: "multiplayer_test_end",
+        category: "write",
+        description: "End a running StudioTestService multiplayer test with an optional return value, then wait for all runtime peers to disconnect.",
+        inputSchema: {
+          type: "object",
+          properties: {
+            value: {
+              description: "JSON-compatible value returned to the edit-side ExecuteMultiplayerTestAsync call."
+            },
+            timeout: {
+              type: "number",
+              description: "Max seconds to wait for runtime peers to disconnect (default 30)."
+            },
+            instance_id: {
+              type: "string",
+              description: "Which connected Studio place to target. Required when multiple places are connected; omit when one. Use get_connected_instances to list available IDs."
+            }
+          }
+        }
+      },
       {
         name: "get_runtime_logs",
         category: "read",
@@ -6323,7 +6807,7 @@ part(0,2,0,2,1,1,"b")`,
       {
         name: "capture_screenshot",
         category: "read",
-        description: 'Capture the Roblox Studio viewport at native resolution and return it as an image, plus a text line stating the exact pixel dimensions. Works in Edit mode and during a playtest (auto-detects a running client and captures the live play viewport). The returned image is never downscaled, so its pixel grid is exactly the coordinate space simulate_mouse_input uses \u2014 read click positions straight off this image. For reading fine text/UI, use format="png" (lossless) or a higher quality; enlarging the Studio window raises resolution. Requires EditableImage API enabled (Game Settings > Security > "Allow Mesh / Image APIs") and the window to be visible.',
+        description: 'Capture the Roblox Studio viewport at native resolution and return it as an image, plus a text line stating the exact pixel dimensions. Works in Edit mode and regular playtests (auto-detects a running client and captures the live play viewport). StudioTestService multiplayer client screenshots are currently blocked by Roblox temporary-texture process scoping; the tool returns a clear error in that case. The returned image is never downscaled, so its pixel grid is exactly the coordinate space simulate_mouse_input uses \u2014 read click positions straight off this image. For reading fine text/UI, use format="png" (lossless) or a higher quality; enlarging the Studio window raises resolution. Requires EditableImage API enabled (Game Settings > Security > "Allow Mesh / Image APIs") and the window to be visible.',
         inputSchema: {
           type: "object",
           properties: {
@@ -6598,6 +7082,39 @@ part(0,2,0,2,1,1,"b")`,
           }
         }
       },
+      {
+        name: "get_scene_analysis",
+        category: "read",
+        description: 'Read Roblox SceneAnalysisService data for attribution-focused performance analysis. Complements get_memory_breakdown: returns compact top-N entries for instance composition, script memory, unparented instances, triangle composition, animation memory, and audio memory. Requires the Studio Scene Analysis beta feature; if disabled, returns scene_analysis_not_enabled with betaFeatureRequired=true. target="all" (default) returns per-peer data; single-peer targets return that peer directly. raw=true includes the full nested Scene Analysis tree.',
+        inputSchema: {
+          type: "object",
+          properties: {
+            mode: {
+              type: "string",
+              enum: ["all", "instance_composition", "script_memory", "unparented_instances", "triangle_composition", "animation_memory", "audio_memory"],
+              description: 'Scene analysis mode to read. Defaults to "all".'
+            },
+            target: {
+              type: "string",
+              description: 'Peer to read from: "edit", "server", "client-N", or "all" (default).'
+            },
+            topN: {
+              type: "number",
+              minimum: 1,
+              maximum: 100,
+              description: "Number of flattened top entries to include per mode. Defaults to 10; plugin clamps to 1-100."
+            },
+            raw: {
+              type: "boolean",
+              description: "Include the full nested SceneAnalysisService tree in each mode result. Defaults to false."
+            },
+            instance_id: {
+              type: "string",
+              description: "Which connected Studio place to target. Required when multiple places are connected; omit when one. Use get_connected_instances to list available IDs."
+            }
+          }
+        }
+      },
       // === SerializationService round-trip ===
       {
         name: "export_rbxm",
@@ -6781,7 +7298,7 @@ function handleVariantConflict({ pluginsFolder, otherAssetName, replace }) {
   }
   console.warn(`
 [install-plugin] WARNING: ${otherAssetName} is already present in ${pluginsFolder}.
-Both plugins will register with MCP at Studio launch, causing duplicate role registrations and unpredictable routing for stop_playtest and per-peer execute_luau.
+Only one MCP plugin variant should be present. If both variants are in the Studio Plugins folder, Studio loads both and runtime routing can become unpredictable.
 Re-run with --replace-variant to remove ${otherAssetName}, or delete it manually.
 `);
 }