@chrrxs/robloxstudio-mcp 2.17.1 → 2.18.0

package/dist/index.js

@@ -188,6 +188,14 @@ var init_bridge_service = __esm({
           }
         }
       }
+      unregisterInstanceId(instanceId) {
+        const matching = this.matchingInstancesForInstanceId(instanceId);
+        const removed = matching.map(toPublic);
+        for (const inst of matching) {
+          this.unregisterInstance(inst.pluginSessionId);
+        }
+        return removed;
+      }
       getInstances() {
         return Array.from(this.instances.values());
       }
@@ -889,8 +897,11 @@ var init_http_server = __esm({
       get_device_simulator_state: (tools, body) => tools.getDeviceSimulatorState(body.target, body.deviceId, body.includeDeviceList, body.instance_id),
       set_device_simulator: (tools, body) => tools.setDeviceSimulator(body.target, body.deviceId, body.orientation, body.resolution, body.pixelDensity, body.scalingMode, body.stopSimulation, body.instance_id),
       capture_device_matrix: (tools, body) => tools.captureDeviceMatrix(body.entries, body.target, body.format, body.quality, body.settleSeconds, body.restoreAfter, body.instance_id),
+      manage_instance: (tools, body) => tools.manageInstance(body),
+      solo_playtest: (tools, body) => tools.soloPlaytest(body.action, body.mode, body.timeout, body.instance_id),
       start_playtest: (tools, body) => tools.startPlaytest(body.mode, body.numPlayers, body.instance_id),
       stop_playtest: (tools, body) => tools.stopPlaytest(body.instance_id),
+      multiplayer_playtest: (tools, body) => tools.multiplayerPlaytest(body.action, body.numPlayers, body.target, body.testArgs, body.value, body.timeout, 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),
@@ -1469,6 +1480,14 @@ var init_opencloud_client = __esm({
       async getAssetDetails(assetId) {
         return this.request(`/toolbox-service/v2/assets/${assetId}`);
       }
+      async listAssetVersions(assetId, maxPageSize = 10, pageToken) {
+        return this.request(`/assets/v1/assets/${assetId}/versions`, {
+          params: {
+            maxPageSize,
+            pageToken
+          }
+        });
+      }
       async getAssetThumbnail(assetId, size = "420x420") {
         const url = `https://thumbnails.roblox.com/v1/assets?assetIds=${assetId}&size=${size}&format=Png`;
         try {
@@ -1697,6 +1716,254 @@ var init_roblox_cookie_client = __esm({
   }
 });
 
+// ../core/dist/studio-instance-manager.js
+import { execFileSync, spawn } from "child_process";
+import { existsSync, readdirSync, readFileSync, statSync } from "fs";
+import * as os from "os";
+import * as path from "path";
+function run(command, args, options = {}) {
+  return execFileSync(command, args, {
+    encoding: "utf8",
+    stdio: ["ignore", "pipe", "pipe"],
+    ...options
+  }).trim();
+}
+function isWsl() {
+  if (process.platform !== "linux")
+    return false;
+  try {
+    return /microsoft|wsl/i.test(readFileSync("/proc/version", "utf8"));
+  } catch {
+    return false;
+  }
+}
+function powershell(script) {
+  return run("powershell.exe", ["-NoProfile", "-Command", script], {
+    cwd: isWsl() && existsSync("/mnt/c/Windows") ? "/mnt/c/Windows" : process.cwd()
+  });
+}
+function windowsLocalAppData() {
+  if (process.platform === "win32")
+    return process.env.LOCALAPPDATA;
+  if (!isWsl())
+    return void 0;
+  try {
+    return run("cmd.exe", ["/c", "echo %LOCALAPPDATA%"], {
+      cwd: existsSync("/mnt/c/Windows") ? "/mnt/c/Windows" : process.cwd()
+    });
+  } catch {
+    return void 0;
+  }
+}
+function toWslPath(windowsPath) {
+  if (!isWsl())
+    return windowsPath;
+  return run("wslpath", ["-u", windowsPath]);
+}
+function toStudioLaunchArg(arg) {
+  if (!isWsl() || !path.isAbsolute(arg) || !existsSync(arg))
+    return arg;
+  return run("wslpath", ["-w", arg]);
+}
+function resolveStudioExe() {
+  if (process.env.ROBLOX_STUDIO_EXE)
+    return process.env.ROBLOX_STUDIO_EXE;
+  if (process.platform === "darwin") {
+    return "/Applications/RobloxStudio.app/Contents/MacOS/RobloxStudio";
+  }
+  if (process.platform !== "win32" && !isWsl()) {
+    throw new Error("Roblox Studio executable auto-discovery is only supported on Windows, WSL, and macOS. Set ROBLOX_STUDIO_EXE.");
+  }
+  const localAppData = windowsLocalAppData();
+  const root = localAppData ? path.join(toWslPath(localAppData), "Roblox", "Versions") : path.join(os.homedir(), "AppData", "Local", "Roblox", "Versions");
+  if (!existsSync(root)) {
+    throw new Error(`Roblox Studio Versions folder not found: ${root}. Set ROBLOX_STUDIO_EXE.`);
+  }
+  const candidates = readdirSync(root).filter((name) => name.startsWith("version-")).map((name) => path.join(root, name, "RobloxStudioBeta.exe")).filter((candidate) => existsSync(candidate)).sort((a, b) => statSync(b).mtimeMs - statSync(a).mtimeMs);
+  if (candidates.length === 0) {
+    throw new Error(`RobloxStudioBeta.exe not found under ${root}. Set ROBLOX_STUDIO_EXE.`);
+  }
+  return candidates[0];
+}
+function listStudioProcesses() {
+  if (process.platform === "darwin") {
+    let out2 = "";
+    try {
+      out2 = run("pgrep", ["-fl", "RobloxStudio"]);
+    } catch {
+      return [];
+    }
+    return out2.split("\n").filter(Boolean).map((line) => {
+      const [pid, ...rest] = line.trim().split(/\s+/);
+      return { Id: Number(pid), Path: rest.join(" "), MainWindowTitle: "" };
+    }).filter((proc) => Number.isFinite(proc.Id));
+  }
+  if (process.platform !== "win32" && !isWsl())
+    return [];
+  let out = "";
+  try {
+    out = powershell("Get-Process RobloxStudioBeta -ErrorAction SilentlyContinue | Select-Object Id,Path,MainWindowTitle | ConvertTo-Json -Compress");
+  } catch {
+    return [];
+  }
+  if (!out)
+    return [];
+  const parsed = JSON.parse(out);
+  return Array.isArray(parsed) ? parsed : [parsed];
+}
+function buildStudioLaunchArgs(options) {
+  switch (options.source) {
+    case "baseplate":
+      return [];
+    case "local_file":
+      if (!options.localPlaceFile)
+        throw new Error('local_place_file is required when source="local_file".');
+      return ["--task", "EditFile", "--localPlaceFile", options.localPlaceFile];
+    case "published_place":
+      if (!options.placeId)
+        throw new Error('place_id is required when source="published_place".');
+      if (!options.universeId)
+        throw new Error('universe_id is required when source="published_place".');
+      return ["--task", "EditPlace", "--placeId", String(options.placeId), "--universeId", String(options.universeId)];
+    case "place_revision":
+      if (!options.placeId)
+        throw new Error('place_id is required when source="place_revision".');
+      if (!options.universeId)
+        throw new Error('universe_id is required when source="place_revision".');
+      if (!options.placeVersion)
+        throw new Error('place_version is required when launching source="place_revision".');
+      return [
+        "--task",
+        "EditPlaceRevision",
+        "--placeId",
+        String(options.placeId),
+        "--universeId",
+        String(options.universeId),
+        "--placeVersion",
+        String(options.placeVersion)
+      ];
+  }
+}
+function delay(ms) {
+  return new Promise((resolve2) => setTimeout(resolve2, ms));
+}
+var StudioInstanceManager;
+var init_studio_instance_manager = __esm({
+  "../core/dist/studio-instance-manager.js"() {
+    "use strict";
+    StudioInstanceManager = class {
+      managedByInstanceId = /* @__PURE__ */ new Map();
+      pending = /* @__PURE__ */ new Set();
+      list() {
+        return [...this.managedByInstanceId.values(), ...this.pending].filter((instance, index, all) => all.indexOf(instance) === index);
+      }
+      get(instanceId) {
+        return this.managedByInstanceId.get(instanceId);
+      }
+      attachInstanceId(record, instanceId) {
+        record.instanceId = instanceId;
+        this.pending.delete(record);
+        this.managedByInstanceId.set(instanceId, record);
+      }
+      async launch(options) {
+        const before = new Set(listStudioProcesses().map((proc2) => proc2.Id));
+        const exe = resolveStudioExe();
+        const args = buildStudioLaunchArgs(options).map(toStudioLaunchArg);
+        const proc = spawn(exe, args, {
+          cwd: isWsl() && existsSync("/mnt/c/Windows") ? "/mnt/c/Windows" : process.cwd(),
+          detached: true,
+          stdio: "ignore"
+        });
+        proc.unref();
+        const record = {
+          source: options.source,
+          spawnPid: proc.pid,
+          exe,
+          args,
+          placeId: options.placeId,
+          universeId: options.universeId,
+          placeVersion: options.placeVersion,
+          localPlaceFile: options.localPlaceFile,
+          launchedAt: Date.now()
+        };
+        this.pending.add(record);
+        const deadline = Date.now() + 5e3;
+        while (Date.now() < deadline && record.nativeProcessId === void 0) {
+          const created = listStudioProcesses().find((candidate) => !before.has(candidate.Id));
+          if (created) {
+            record.nativeProcessId = created.Id;
+            break;
+          }
+          await delay(250);
+        }
+        if (record.nativeProcessId === void 0 && process.platform !== "win32" && !isWsl()) {
+          record.nativeProcessId = proc.pid;
+        }
+        return record;
+      }
+      close(record) {
+        const processId = record.nativeProcessId ?? record.spawnPid;
+        if (!processId) {
+          throw new Error(`Cannot close ${record.instanceId ?? "Studio launch"} because its process id was not detected.`);
+        }
+        if (process.platform === "win32" || isWsl()) {
+          powershell(`Stop-Process -Id ${Math.trunc(processId)} -Force -ErrorAction Stop`);
+        } else {
+          try {
+            process.kill(processId, "SIGTERM");
+          } catch (error) {
+            if (error.code !== "ESRCH")
+              throw error;
+          }
+        }
+        record.closedAt = Date.now();
+        if (record.instanceId)
+          this.managedByInstanceId.delete(record.instanceId);
+        this.pending.delete(record);
+      }
+      closeConnectedInstance(instance) {
+        const process2 = this.findProcessForConnectedInstance(instance);
+        if (!process2) {
+          throw new Error(`Could not find a Studio process for connected instance "${instance.instanceId}".`);
+        }
+        this.closeProcess(process2.Id);
+      }
+      closeProcess(processId) {
+        if (process.platform === "win32" || isWsl()) {
+          powershell(`Stop-Process -Id ${Math.trunc(processId)} -Force -ErrorAction Stop`);
+        } else {
+          try {
+            process.kill(processId, "SIGTERM");
+          } catch (error) {
+            if (error.code !== "ESRCH")
+              throw error;
+          }
+        }
+      }
+      findProcessForConnectedInstance(instance) {
+        const processes = listStudioProcesses();
+        if (processes.length === 0)
+          return void 0;
+        if (processes.length === 1)
+          return processes[0];
+        const names = [instance.dataModelName, instance.placeName].map((name) => name.trim()).filter((name, index, all) => name.length > 0 && all.indexOf(name) === index);
+        const candidates = processes.filter((proc) => {
+          const title = (proc.MainWindowTitle ?? "").trim();
+          if (!title)
+            return false;
+          return names.some((name) => title === `${name} - Roblox Studio` || title.startsWith(`${name} - `) || title.startsWith(`${name} (`));
+        });
+        if (candidates.length === 1)
+          return candidates[0];
+        if (candidates.length > 1) {
+          throw new Error(`Multiple Studio processes matched connected instance "${instance.instanceId}".`);
+        }
+        return void 0;
+      }
+    };
+  }
+});
+
 // ../core/dist/jpeg-encoder.js
 function rgbaToJpeg(rgba, width, height, quality = 80) {
   if (width <= 0 || height <= 0)
@@ -2715,8 +2982,8 @@ var init_png_encoder = __esm({
 
 // ../core/dist/tools/index.js
 import * as fs from "fs";
-import * as os from "os";
-import * as path from "path";
+import * as os2 from "os";
+import * as path2 from "path";
 function encodeImageFromRgbaResponse(response, format, quality) {
   if (!response.data || response.width === void 0 || response.height === void 0) {
     throw new Error("Render response missing data, width, or height");
@@ -3072,6 +3339,7 @@ var init_tools = __esm({
     init_build_executor();
     init_opencloud_client();
     init_roblox_cookie_client();
+    init_studio_instance_manager();
     init_jpeg_encoder();
     init_png_encoder();
     MAX_INLINE_IMAGE_BYTES = 6e6;
@@ -3129,11 +3397,34 @@ var init_tools = __esm({
       bridge;
       openCloudClient;
       cookieClient;
+      instanceManager;
       constructor(bridge) {
         this.client = new StudioHttpClient(bridge);
         this.bridge = bridge;
         this.openCloudClient = new OpenCloudClient();
         this.cookieClient = new RobloxCookieClient();
+        this.instanceManager = new StudioInstanceManager();
+      }
+      _textResult(body) {
+        return { content: [{ type: "text", text: JSON.stringify(body) }] };
+      }
+      _parseTextResult(result) {
+        const text = result?.content?.[0]?.text;
+        if (typeof text !== "string")
+          return {};
+        try {
+          const parsed = JSON.parse(text);
+          return parsed && typeof parsed === "object" && !Array.isArray(parsed) ? parsed : {};
+        } catch {
+          return {};
+        }
+      }
+      _briefRoles(instanceId, equivalentInstances = false) {
+        const roles = equivalentInstances ? this._rolesForEquivalentInstances(instanceId) : this._rolesForInstance(instanceId);
+        return {
+          roles,
+          runtimeRoles: roles.filter((role) => role === "server" || /^client-\d+$/.test(role))
+        };
       }
       // Resolve (instance_id, target-role) → concrete (instanceId, role) and
       // dispatch a single request. Throws RoutingFailure if the resolution is
@@ -3458,8 +3749,8 @@ var init_tools = __esm({
           timedOut: true
         };
       }
-      async getFileTree(path2 = "", instance_id) {
-        const response = await this._callSingle("/api/file-tree", { path: path2 }, void 0, instance_id);
+      async getFileTree(path3 = "", instance_id) {
+        const response = await this._callSingle("/api/file-tree", { path: path3 }, void 0, instance_id);
         return {
           content: [
             {
@@ -3576,9 +3867,9 @@ var init_tools = __esm({
           ]
         };
       }
-      async getProjectStructure(path2, maxDepth, scriptsOnly, instance_id) {
+      async getProjectStructure(path3, maxDepth, scriptsOnly, instance_id) {
         const response = await this._callSingle("/api/project-structure", {
-          path: path2,
+          path: path3,
           maxDepth,
           scriptsOnly
         }, void 0, instance_id);
@@ -4499,8 +4790,8 @@ ${code}`
           const rawJson = mutable.raw_json;
           if (typeof rawJson === "string") {
             if (typeof outputPath === "string" && outputPath !== "") {
-              const resolvedOutputPath = path.resolve(outputPath);
-              fs.mkdirSync(path.dirname(resolvedOutputPath), { recursive: true });
+              const resolvedOutputPath = path2.resolve(outputPath);
+              fs.mkdirSync(path2.dirname(resolvedOutputPath), { recursive: true });
               fs.writeFileSync(resolvedOutputPath, rawJson, "utf8");
               mutable.output_path = resolvedOutputPath;
             }
@@ -4536,12 +4827,272 @@ ${code}`
         const body = response !== null && typeof response === "object" && !Array.isArray(response) ? { ...response, target: resolved.targetRole } : response;
         return { content: [{ type: "text", text: JSON.stringify(body) }] };
       }
-      async startPlaytest(mode, numPlayers, instance_id) {
+      _positiveInteger(value, name) {
+        if (typeof value !== "number" || !Number.isFinite(value) || value <= 0) {
+          throw new Error(`${name} must be a positive number.`);
+        }
+        return Math.trunc(value);
+      }
+      _optionalPositiveInteger(value, name) {
+        if (value === void 0 || value === null)
+          return void 0;
+        return this._positiveInteger(value, name);
+      }
+      _publicInstanceKey(instance) {
+        return `${instance.instanceId}:${instance.role}:${instance.connectedAt}`;
+      }
+      _isLatestPublishedPlaceOpen(placeId) {
+        const publishedInstanceId2 = `place:${placeId}`;
+        return this.bridge.getPublicInstances().some((instance) => instance.placeId === placeId || instance.instanceId === publishedInstanceId2) || this.instanceManager.list().some((record) => record.closedAt === void 0 && record.source === "published_place" && record.placeId === placeId);
+      }
+      async _deriveUniverseId(placeId) {
+        const response = await fetch(`https://apis.roblox.com/universes/v1/places/${placeId}/universe`);
+        if (!response.ok) {
+          const body = await response.text().catch(() => "");
+          throw new Error(`Could not derive universe_id for place ${placeId} (${response.status}): ${body}`);
+        }
+        const data = await response.json();
+        if (typeof data.universeId !== "number" || !Number.isFinite(data.universeId)) {
+          throw new Error(`Could not derive universe_id for place ${placeId}.`);
+        }
+        return Math.trunc(data.universeId);
+      }
+      async _waitForManagedEditConnection(record, beforeKeys, timeoutMs) {
+        const deadline = Date.now() + timeoutMs;
+        while (Date.now() < deadline) {
+          const candidates = this.bridge.getPublicInstances().filter((instance) => instance.role === "edit").filter((instance) => !beforeKeys.has(this._publicInstanceKey(instance))).filter((instance) => instance.connectedAt >= record.launchedAt - 1e3).filter((instance) => {
+            if (record.source === "published_place") {
+              return record.placeId !== void 0 && instance.placeId === record.placeId;
+            }
+            return true;
+          }).sort((a, b) => b.connectedAt - a.connectedAt);
+          if (candidates[0])
+            return candidates[0];
+          await sleep(500);
+        }
+        return void 0;
+      }
+      _managedStatus(record) {
+        const connected = record.instanceId ? this.bridge.getPublicInstances().filter((instance) => instance.instanceId === record.instanceId) : [];
+        return {
+          instance_id: record.instanceId,
+          source: record.source,
+          place_id: record.placeId,
+          place_version: record.placeVersion,
+          connected: connected.length > 0,
+          roles: connected.map((instance) => instance.role).sort()
+        };
+      }
+      _versionNumberFromPath(pathValue) {
+        const match = pathValue.match(/\/versions\/(\d+)$/);
+        return match ? Number(match[1]) : void 0;
+      }
+      async manageInstance(request) {
+        const action = request.action;
+        const instance_id = typeof request.instance_id === "string" ? request.instance_id : void 0;
+        if (action !== "launch" && action !== "close" && action !== "status" && action !== "list_place_versions") {
+          throw new Error("manage_instance requires action=launch|close|status|list_place_versions");
+        }
+        if (action === "list_place_versions") {
+          if (!this.openCloudClient.hasApiKey()) {
+            return this._textResult({
+              error: "ROBLOX_OPEN_CLOUD_API_KEY is required to list place versions."
+            });
+          }
+          const placeId2 = this._positiveInteger(request.place_id, "place_id");
+          const rawMaxPageSize = this._optionalPositiveInteger(request.max_page_size, "max_page_size") ?? 10;
+          const maxPageSize = Math.max(1, Math.min(50, rawMaxPageSize));
+          const pageToken = typeof request.page_token === "string" ? request.page_token : void 0;
+          const response = await this.openCloudClient.listAssetVersions(placeId2, maxPageSize, pageToken);
+          const body = {
+            versions: (response.assetVersions ?? []).map((version) => ({
+              version: this._versionNumberFromPath(version.path),
+              created_at: version.createTime,
+              path: version.path,
+              moderation_state: version.moderationResult?.moderationState
+            }))
+          };
+          if (response.nextPageToken)
+            body.next_page_token = response.nextPageToken;
+          return this._textResult(body);
+        }
+        if (action === "status") {
+          if (instance_id) {
+            const record2 = this.instanceManager.get(instance_id);
+            const connected2 = this.bridge.getPublicInstances().filter((instance) => instance.instanceId === instance_id);
+            if (!record2 && connected2.length === 0) {
+              return this._textResult({ error: "Instance is not connected or managed.", instance_id });
+            }
+            return this._textResult({
+              instance_id,
+              managed: !!record2,
+              source: record2?.source,
+              place_id: record2?.placeId ?? connected2[0]?.placeId,
+              place_version: record2?.placeVersion,
+              roles: connected2.map((instance) => instance.role).sort()
+            });
+          }
+          return this._textResult({
+            managed: this.instanceManager.list().filter((record2) => record2.closedAt === void 0).map((record2) => this._managedStatus(record2)),
+            connected: this.bridge.getPublicInstances().map((instance) => ({
+              instance_id: instance.instanceId,
+              role: instance.role,
+              place_id: instance.placeId,
+              place_name: instance.placeName
+            }))
+          });
+        }
+        if (action === "close") {
+          let record2;
+          if (instance_id) {
+            record2 = this.instanceManager.get(instance_id);
+            if (!record2) {
+              const connected2 = this.bridge.getPublicInstances().filter((instance) => instance.instanceId === instance_id);
+              const edit = connected2.find((instance) => instance.role === "edit");
+              if (!edit) {
+                return this._textResult({
+                  error: "Instance is not connected or managed.",
+                  instance_id
+                });
+              }
+              try {
+                this.instanceManager.closeConnectedInstance(edit);
+              } catch (error) {
+                return this._textResult({
+                  error: error instanceof Error ? error.message : String(error),
+                  instance_id
+                });
+              }
+              this.bridge.unregisterInstanceId(instance_id);
+              return this._textResult({
+                instance_id,
+                message: "Studio instance closed."
+              });
+            }
+          } else {
+            const active = this.instanceManager.list().filter((entry) => entry.closedAt === void 0);
+            if (active.length === 0) {
+              return this._textResult({ message: "No managed Studio instances are active." });
+            }
+            if (active.length > 1) {
+              return this._textResult({
+                error: "instance_id is required because multiple managed Studio instances are active.",
+                managed: active.map((entry) => this._managedStatus(entry))
+              });
+            }
+            record2 = active[0];
+          }
+          this.instanceManager.close(record2);
+          if (record2.instanceId)
+            this.bridge.unregisterInstanceId(record2.instanceId);
+          return this._textResult({
+            instance_id: record2.instanceId,
+            message: "Studio instance closed."
+          });
+        }
+        const source = request.source;
+        if (source !== "baseplate" && source !== "local_file" && source !== "published_place" && source !== "place_revision") {
+          throw new Error("manage_instance action=launch requires source=baseplate|local_file|published_place|place_revision");
+        }
+        const launchSource = source;
+        const placeId = launchSource === "published_place" || launchSource === "place_revision" ? this._positiveInteger(request.place_id, "place_id") : this._optionalPositiveInteger(request.place_id, "place_id");
+        const placeVersion = launchSource === "place_revision" ? this._positiveInteger(request.place_version, "place_version") : this._optionalPositiveInteger(request.place_version, "place_version");
+        const localPlaceFile = typeof request.local_place_file === "string" ? request.local_place_file : void 0;
+        if (launchSource === "published_place" && placeId !== void 0 && this._isLatestPublishedPlaceOpen(placeId)) {
+          return this._textResult({
+            error: "Place is already open.",
+            message: `place_id ${placeId} is already connected. Use the existing instance or launch a specific place_revision.`
+          });
+        }
+        const universeId = launchSource === "published_place" || launchSource === "place_revision" ? this._optionalPositiveInteger(request.universe_id, "universe_id") ?? await this._deriveUniverseId(placeId) : this._optionalPositiveInteger(request.universe_id, "universe_id");
+        const waitForConnection = request.wait_for_connection !== false;
+        const timeoutMs = this._optionalPositiveInteger(request.timeout_ms, "timeout_ms") ?? 12e4;
+        const beforeKeys = new Set(this.bridge.getPublicInstances().map((instance) => this._publicInstanceKey(instance)));
+        const record = await this.instanceManager.launch({
+          source: launchSource,
+          localPlaceFile,
+          placeId,
+          universeId,
+          placeVersion
+        });
+        if (!waitForConnection) {
+          return this._textResult({ message: "Studio launch requested." });
+        }
+        const connected = await this._waitForManagedEditConnection(record, beforeKeys, timeoutMs);
+        if (!connected) {
+          try {
+            this.instanceManager.close(record);
+          } catch {
+          }
+          return this._textResult({
+            error: "Studio launched, but the MCP plugin did not connect before timeout."
+          });
+        }
+        this.instanceManager.attachInstanceId(record, connected.instanceId);
+        return this._textResult({
+          instance_id: connected.instanceId,
+          message: launchSource === "place_revision" ? `Studio opened place revision ${placeVersion}.` : "Studio opened."
+        });
+      }
+      async soloPlaytest(action, mode, timeout, instance_id) {
+        if (action !== "start" && action !== "stop" && action !== "status") {
+          throw new Error("solo_playtest requires action=start|stop|status");
+        }
+        if (action === "status") {
+          const instanceId = this._resolveInstanceIdOnly(instance_id);
+          const { roles, runtimeRoles } = this._briefRoles(instanceId, true);
+          return this._textResult({
+            success: true,
+            action,
+            running: runtimeRoles.length > 0,
+            roles
+          });
+        }
+        if (action === "start") {
+          if (mode !== "play" && mode !== "run") {
+            throw new Error("solo_playtest action=start requires mode=play|run");
+          }
+          const body2 = this._parseTextResult(await this.startPlaytest(mode, void 0, instance_id, timeout));
+          if (body2.success === true && body2.runtimeReady !== false) {
+            return this._textResult({
+              success: true,
+              action,
+              message: "Playtest started.",
+              roles: Array.isArray(body2.roles) ? body2.roles : void 0
+            });
+          }
+          return this._textResult({
+            success: false,
+            action,
+            error: body2.error ?? "start_failed",
+            message: body2.success === true ? "Playtest did not become ready before timeout." : body2.message ?? "Playtest did not start.",
+            roles: Array.isArray(body2.roles) ? body2.roles : void 0
+          });
+        }
+        const body = this._parseTextResult(await this.stopPlaytest(instance_id, timeout));
+        if (body.success === true && body.runtimeStopped !== false) {
+          return this._textResult({
+            success: true,
+            action,
+            message: "Playtest stopped."
+          });
+        }
+        return this._textResult({
+          success: false,
+          action,
+          error: body.error ?? "stop_failed",
+          message: body.message ?? "Playtest did not stop.",
+          roles: Array.isArray(body.roles) ? body.roles : void 0,
+          requiresBuiltInMcp: body.requiresBuiltInMcp === true ? true : void 0,
+          recoveryHint: typeof body.recoveryHint === "string" ? body.recoveryHint : void 0
+        });
+      }
+      async startPlaytest(mode, numPlayers, instance_id, timeout = 60) {
         if (mode !== "play" && mode !== "run") {
           throw new Error('mode must be "play" or "run"');
         }
         if (numPlayers !== void 0) {
-          throw new Error("start_playtest is single-player only. Use multiplayer_test_start for multi-client StudioTestService sessions.");
+          throw new Error('start_playtest is single-player only. Use multiplayer_playtest action="start" for multi-client StudioTestService sessions.');
         }
         const data = { mode };
         const startedAt = Date.now();
@@ -4580,7 +5131,7 @@ ${code}`
         let wait;
         if (response?.success === true) {
           const requiredRoles = mode === "play" ? ["server", "client-1"] : ["server"];
-          wait = await this._waitForRuntimeRolesFresh(resolved.targetInstanceId, startedAt, requiredRoles, 60, true);
+          wait = await this._waitForRuntimeRolesFresh(resolved.targetInstanceId, startedAt, requiredRoles, timeout, true);
         }
         const body = wait ? {
           ...response,
@@ -4597,7 +5148,7 @@ ${code}`
           ]
         };
       }
-      async stopPlaytest(instance_id) {
+      async stopPlaytest(instance_id, timeout = 15) {
         const { instanceId } = this._resolveSingleTarget("edit", instance_id);
         let response;
         let stopRequestError;
@@ -4613,7 +5164,7 @@ ${code}`
         }
         let wait;
         if (response?.success === true) {
-          wait = await this._waitForRuntimeRoles(instanceId, { noRuntime: true }, 15, true);
+          wait = await this._waitForRuntimeRoles(instanceId, { noRuntime: true }, timeout, true);
         } else if (this._runtimeTargetsForEquivalentInstances(instanceId).length > 0) {
           wait = {
             ok: false,
@@ -4738,6 +5289,94 @@ ${code}`
         }
         return { ok: false, roles: this._rolesForInstance(instanceId), timedOut: true };
       }
+      async multiplayerPlaytest(action, numPlayers, target, testArgs, value, timeout, instance_id) {
+        if (action !== "start" && action !== "status" && action !== "add_players" && action !== "leave_client" && action !== "end") {
+          throw new Error("multiplayer_playtest requires action=start|status|add_players|leave_client|end");
+        }
+        const briefState = async (instanceId) => {
+          const state = await this._buildMultiplayerState(this._resolveInstanceIdOnly(instanceId));
+          return {
+            phase: state.phase,
+            roles: Array.isArray(state.peers) ? state.peers.map((peer) => peer.role).filter((role) => typeof role === "string") : [],
+            clientRoles: Array.isArray(state.clientRoles) ? state.clientRoles : [],
+            playerCount: typeof state.playerCount === "number" ? state.playerCount : void 0,
+            error: typeof state.error === "string" ? state.error : void 0
+          };
+        };
+        if (action === "status") {
+          return this._textResult({
+            success: true,
+            action,
+            ...await briefState(instance_id)
+          });
+        }
+        if (action === "start") {
+          const body2 = this._parseTextResult(await this.multiplayerTestStart(numPlayers, testArgs, timeout, instance_id));
+          const state = body2.state && typeof body2.state === "object" ? body2.state : {};
+          const success = body2.success === true && body2.ready === true;
+          return this._textResult(success ? {
+            success: true,
+            action,
+            message: "Multiplayer playtest started.",
+            roles: Array.isArray(body2.roles) ? body2.roles : void 0,
+            clientRoles: Array.isArray(state.clientRoles) ? state.clientRoles : void 0,
+            playerCount: typeof state.playerCount === "number" ? state.playerCount : void 0
+          } : {
+            success: false,
+            action,
+            error: body2.error ?? body2.wait?.error ?? "start_failed",
+            message: body2.success === true ? "Multiplayer playtest did not become ready before timeout." : body2.message ?? "Multiplayer playtest did not start.",
+            roles: Array.isArray(body2.roles) ? body2.roles : void 0
+          });
+        }
+        if (action === "add_players") {
+          const body2 = this._parseTextResult(await this.multiplayerTestAddPlayers(numPlayers, timeout, instance_id));
+          const state = body2.state && typeof body2.state === "object" ? body2.state : {};
+          const success = body2.success === true && body2.ready === true;
+          return this._textResult(success ? {
+            success: true,
+            action,
+            message: "Players added.",
+            roles: Array.isArray(body2.roles) ? body2.roles : void 0,
+            clientRoles: Array.isArray(state.clientRoles) ? state.clientRoles : void 0,
+            playerCount: typeof state.playerCount === "number" ? state.playerCount : void 0
+          } : {
+            success: false,
+            action,
+            error: body2.error ?? "add_players_failed",
+            message: body2.success === true ? "Players did not finish joining before timeout." : body2.message ?? "Players were not added.",
+            roles: Array.isArray(body2.roles) ? body2.roles : void 0
+          });
+        }
+        if (action === "leave_client") {
+          const body2 = this._parseTextResult(await this.multiplayerTestLeaveClient(target ?? "client-1", timeout, instance_id));
+          return this._textResult(body2.success === true && body2.left === true ? {
+            success: true,
+            action,
+            message: "Client left.",
+            roles: Array.isArray(body2.roles) ? body2.roles : void 0
+          } : {
+            success: false,
+            action,
+            error: body2.error ?? "leave_client_failed",
+            message: body2.message ?? "Client did not leave.",
+            roles: Array.isArray(body2.roles) ? body2.roles : void 0
+          });
+        }
+        const body = this._parseTextResult(await this.multiplayerTestEnd(value, timeout, instance_id));
+        return this._textResult(body.success === true && body.ended === true ? {
+          success: true,
+          action,
+          message: "Multiplayer playtest ended."
+        } : {
+          success: false,
+          action,
+          error: body.error ?? "end_failed",
+          message: body.message ?? "Multiplayer playtest did not end.",
+          roles: Array.isArray(body.roles) ? body.roles : void 0,
+          editDone: body.editDone === false ? false : void 0
+        });
+      }
       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");
@@ -4875,14 +5514,14 @@ ${code}`
         };
       }
       static findProjectRoot(startDir) {
-        let dir = path.resolve(startDir);
+        let dir = path2.resolve(startDir);
         let previous = "";
         while (dir !== previous) {
-          if (fs.existsSync(path.join(dir, ".git")) || fs.existsSync(path.join(dir, "package.json"))) {
+          if (fs.existsSync(path2.join(dir, ".git")) || fs.existsSync(path2.join(dir, "package.json"))) {
             return dir;
           }
           previous = dir;
-          dir = path.dirname(dir);
+          dir = path2.dirname(dir);
         }
         return null;
       }
@@ -4896,7 +5535,7 @@ ${code}`
         }
       }
       static ensureWritableDirectory(candidate, label) {
-        const resolved = path.resolve(candidate);
+        const resolved = path2.resolve(candidate);
         try {
           fs.mkdirSync(resolved, { recursive: true });
         } catch (error) {
@@ -4917,11 +5556,11 @@ ${code}`
         if (_RobloxStudioTools._cachedLibraryPath)
           return _RobloxStudioTools._cachedLibraryPath;
         const overridePath = process.env.ROBLOXSTUDIO_MCP_BUILD_LIBRARY || process.env.BUILD_LIBRARY_PATH;
-        const cwd = path.resolve(process.cwd());
+        const cwd = path2.resolve(process.cwd());
         const projectRoot = _RobloxStudioTools.findProjectRoot(cwd);
-        const homeLibraryPath = path.join(os.homedir(), ".robloxstudio-mcp", "build-library");
-        const projectLibraryPath = projectRoot ? path.join(projectRoot, "build-library") : null;
-        const cwdLibraryPath = path.join(cwd, "build-library");
+        const homeLibraryPath = path2.join(os2.homedir(), ".robloxstudio-mcp", "build-library");
+        const projectLibraryPath = projectRoot ? path2.join(projectRoot, "build-library") : null;
+        const cwdLibraryPath = path2.join(cwd, "build-library");
         let result;
         if (overridePath) {
           result = _RobloxStudioTools.ensureWritableDirectory(overridePath, "override");
@@ -4935,7 +5574,7 @@ ${code}`
             }
           })());
           if (existing) {
-            result = path.resolve(existing);
+            result = path2.resolve(existing);
           } else if (projectLibraryPath) {
             try {
               result = _RobloxStudioTools.ensureWritableDirectory(projectLibraryPath, "project-root");
@@ -4962,8 +5601,8 @@ ${code}`
         if (response && response.success && response.buildData) {
           const buildData = response.buildData;
           const buildId = buildData.id || `${style}/exported`;
-          const filePath = path.join(_RobloxStudioTools.findLibraryPath(), `${buildId}.json`);
-          const dirPath = path.dirname(filePath);
+          const filePath = path2.join(_RobloxStudioTools.findLibraryPath(), `${buildId}.json`);
+          const dirPath = path2.dirname(filePath);
           if (!fs.existsSync(dirPath)) {
             fs.mkdirSync(dirPath, { recursive: true });
           }
@@ -5064,8 +5703,8 @@ ${code}`
         const normalizedParts = this.normalizeBuildParts(parts, new Set(Object.keys(normalizedPalette)));
         const computedBounds = bounds || this.computeBounds(normalizedParts);
         const buildData = { id, style, bounds: computedBounds, palette: normalizedPalette, parts: normalizedParts };
-        const filePath = path.join(_RobloxStudioTools.findLibraryPath(), `${id}.json`);
-        const dirPath = path.dirname(filePath);
+        const filePath = path2.join(_RobloxStudioTools.findLibraryPath(), `${id}.json`);
+        const dirPath = path2.dirname(filePath);
         if (!fs.existsSync(dirPath)) {
           fs.mkdirSync(dirPath, { recursive: true });
         }
@@ -5123,8 +5762,8 @@ ${code}`
         };
         if (seed !== void 0)
           buildData.generatorSeed = seed;
-        const filePath = path.join(_RobloxStudioTools.findLibraryPath(), `${id}.json`);
-        const dirPath = path.dirname(filePath);
+        const filePath = path2.join(_RobloxStudioTools.findLibraryPath(), `${id}.json`);
+        const dirPath = path2.dirname(filePath);
         if (!fs.existsSync(dirPath)) {
           fs.mkdirSync(dirPath, { recursive: true });
         }
@@ -5152,13 +5791,13 @@ ${code}`
         }
         let resolved;
         if (typeof buildData === "string") {
-          const filePath = path.join(_RobloxStudioTools.findLibraryPath(), `${buildData}.json`);
+          const filePath = path2.join(_RobloxStudioTools.findLibraryPath(), `${buildData}.json`);
           if (!fs.existsSync(filePath)) {
             throw new Error(`Build not found in library: ${buildData}`);
           }
           resolved = JSON.parse(fs.readFileSync(filePath, "utf-8"));
         } else if (buildData.id && !buildData.parts) {
-          const filePath = path.join(_RobloxStudioTools.findLibraryPath(), `${buildData.id}.json`);
+          const filePath = path2.join(_RobloxStudioTools.findLibraryPath(), `${buildData.id}.json`);
           if (!fs.existsSync(filePath)) {
             throw new Error(`Build not found in library: ${buildData.id}`);
           }
@@ -5185,13 +5824,13 @@ ${code}`
         const styles = style ? [style] : ["medieval", "modern", "nature", "scifi", "misc"];
         const builds = [];
         for (const s of styles) {
-          const dirPath = path.join(libraryPath, s);
+          const dirPath = path2.join(libraryPath, s);
           if (!fs.existsSync(dirPath))
             continue;
           const files = fs.readdirSync(dirPath).filter((f) => f.endsWith(".json"));
           for (const file of files) {
             try {
-              const content = fs.readFileSync(path.join(dirPath, file), "utf-8");
+              const content = fs.readFileSync(path2.join(dirPath, file), "utf-8");
               const data = JSON.parse(content);
               builds.push({
                 id: data.id || `${s}/${file.replace(".json", "")}`,
@@ -5230,7 +5869,7 @@ ${code}`
         if (!id) {
           throw new Error("Build ID is required for get_build");
         }
-        const filePath = path.join(_RobloxStudioTools.findLibraryPath(), `${id}.json`);
+        const filePath = path2.join(_RobloxStudioTools.findLibraryPath(), `${id}.json`);
         if (!fs.existsSync(filePath)) {
           throw new Error(`Build not found in library: ${id}`);
         }
@@ -5317,7 +5956,7 @@ ${code}`
           if (!buildId) {
             throw new Error(`Invalid ${validatedKeyPath}: model key "${modelKey}" is not defined in sceneData.models`);
           }
-          const filePath = path.join(libraryPath, `${buildId}.json`);
+          const filePath = path2.join(libraryPath, `${buildId}.json`);
           if (!fs.existsSync(filePath)) {
             throw new Error(`Build not found in library: ${buildId}`);
           }
@@ -5500,7 +6139,7 @@ ${code}`
           throw new Error(`File not found: ${filePath}`);
         }
         const fileContent = fs.readFileSync(filePath);
-        const fileName = path.basename(filePath);
+        const fileName = path2.basename(filePath);
         if (assetType === "Decal" && this.cookieClient.hasCookie()) {
           const result2 = await this.cookieClient.uploadDecal(fileContent, displayName, description || "");
           return {
@@ -5725,9 +6364,9 @@ ${code}`
           return { content: [{ type: "text", text: JSON.stringify({ error: "plugin returned no base64 payload" }) }] };
         }
         const bytes = Buffer.from(response.base64, "base64");
-        const resolved = path.resolve(outputPath);
+        const resolved = path2.resolve(outputPath);
         try {
-          fs.mkdirSync(path.dirname(resolved), { recursive: true });
+          fs.mkdirSync(path2.dirname(resolved), { recursive: true });
           fs.writeFileSync(resolved, bytes);
         } catch (err) {
           return { content: [{ type: "text", text: JSON.stringify({ error: `failed to write ${resolved}: ${err.message}` }) }] };
@@ -5761,7 +6400,7 @@ ${code}`
         let bytes;
         let sourceLabel;
         if (source.path !== void 0) {
-          const resolved = path.resolve(source.path);
+          const resolved = path2.resolve(source.path);
           try {
             bytes = fs.readFileSync(resolved);
           } catch (err) {
@@ -5830,7 +6469,7 @@ ${code}`
         if (response.error) {
           let text = response.error;
           if (targetRole.startsWith("client-") && 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}`;
+            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 solo_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 { success: false, error: text };
         }
@@ -6003,7 +6642,7 @@ var init_server = __esm({
       config;
       constructor(config) {
         this.config = config;
-        this.allowedToolNames = new Set(config.tools.map((t) => t.name));
+        this.allowedToolNames = new Set((config.callableTools ?? config.tools).map((t) => t.name));
         this.server = new Server2({
           name: config.name,
           version: config.version
@@ -6176,7 +6815,7 @@ var init_server = __esm({
 });
 
 // ../core/dist/tools/definitions.js
-var TOOL_DEFINITIONS, getAllTools;
+var TOOL_DEFINITIONS, DEPRECATED_TOOL_DEFINITIONS, getAllTools, getAllCallableTools;
 var init_definitions = __esm({
   "../core/dist/tools/definitions.js"() {
     "use strict";
@@ -7142,43 +7781,92 @@ var init_definitions = __esm({
           required: ["pattern"]
         }
       },
-      // === Playtest ===
+      // === Studio Instance Management ===
       {
-        name: "start_playtest",
+        name: "manage_instance",
         category: "write",
-        description: "Start a simple single-player Studio playtest in play or run mode, waiting until a runtime peer registers with MCP. Read print/warn/error output with get_runtime_logs, then end with stop_playtest. For multi-client testing use multiplayer_test_start instead.",
+        description: 'Launch, close, inspect, and find revisions for Studio instances. Use action="list_place_versions" with place_id to retrieve version numbers through Open Cloud asset versions, then action="launch" with source="place_revision" and place_version to open an older revision. action="close" can close an MCP-managed instance or an explicitly connected edit instance by instance_id. action="launch" source="published_place" opens the latest published place and is blocked if that place_id is already connected; source="place_revision" is allowed because Studio opens explicit past revisions as anonymous local copies. Requires ROBLOX_OPEN_CLOUD_API_KEY with asset:read for list_place_versions.',
         inputSchema: {
           type: "object",
           properties: {
-            mode: {
+            action: {
               type: "string",
-              enum: ["play", "run"],
-              description: "Play mode"
+              enum: ["launch", "close", "status", "list_place_versions"],
+              description: "Instance management action."
             },
-            numPlayers: {
+            source: {
+              type: "string",
+              enum: ["baseplate", "local_file", "published_place", "place_revision"],
+              description: 'Required for action="launch". published_place opens the latest place; place_revision opens a specific older version as an anonymous local copy.'
+            },
+            local_place_file: {
+              type: "string",
+              description: 'Required for source="local_file". Path to a .rbxl/.rbxlx place file.'
+            },
+            place_id: {
+              type: "number",
+              description: 'Required for source="published_place", source="place_revision", and action="list_place_versions".'
+            },
+            universe_id: {
+              type: "number",
+              description: "Optional for published_place/place_revision launches; derived from place_id when omitted."
+            },
+            place_version: {
+              type: "number",
+              description: 'Required for source="place_revision". Use action="list_place_versions" to discover available version numbers.'
+            },
+            wait_for_connection: {
+              type: "boolean",
+              description: 'For action="launch": wait until the MCP plugin connects and return instance_id (default true).'
+            },
+            timeout_ms: {
               type: "number",
-              description: "Deprecated and rejected. Use multiplayer_test_start for multi-client testing."
+              description: 'For action="launch": max milliseconds to wait for plugin connection (default 120000).'
+            },
+            max_page_size: {
+              type: "number",
+              description: 'For action="list_place_versions": number of versions to return, clamped to 1-50 (default 10).'
+            },
+            page_token: {
+              type: "string",
+              description: 'For action="list_place_versions": pagination token returned by a prior call.'
             },
             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."
+              description: 'For action="close" or action="status": Studio instance to inspect or close. close accepts MCP-managed instances and explicitly connected edit instances.'
             }
           },
-          required: ["mode"]
+          required: ["action"]
         }
       },
+      // === Playtest ===
       {
-        name: "stop_playtest",
+        name: "solo_playtest",
         category: "write",
-        description: "Stop playtest and wait for runtime peers to disconnect.",
+        description: 'Start, stop, or inspect a single-player Studio playtest. Use action="start" with mode="play" or "run", action="stop" to end the playtest, and action="status" to inspect active runtime roles. Returns brief lifecycle status only; read script output with get_runtime_logs. Ordinary start/eval/stop workflows do not need reset_simulation_state; use simulation reset only for network or device-simulator tests. For multi-client testing use multiplayer_playtest.',
         inputSchema: {
           type: "object",
           properties: {
+            action: {
+              type: "string",
+              enum: ["start", "stop", "status"],
+              description: "Lifecycle action to run."
+            },
+            mode: {
+              type: "string",
+              enum: ["play", "run"],
+              description: 'Required for action="start".'
+            },
+            timeout: {
+              type: "number",
+              description: "Max seconds to wait for start readiness or stop teardown. Defaults: start 60, stop 15."
+            },
             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: ["action"]
         }
       },
       {
@@ -7247,7 +7935,7 @@ var init_definitions = __esm({
       {
         name: "get_simulation_state",
         category: "read",
-        description: 'Inspect current NetworkSettings and/or StudioDeviceSimulatorService state for edit and connected playtest clients only. Defaults to include="both" and target="edit-and-clients"; server peers are skipped. Use before diagnosing network or device-sensitive tests, especially because normal Play can write client simulator changes back to edit and StudioTestService clients can inherit stale device simulator state.',
+        description: 'Inspect current NetworkSettings and/or StudioDeviceSimulatorService state for edit and connected clients only. Defaults to include="both" and target="edit-and-clients"; server peers are skipped. Use when a task explicitly involves simulated network/device behavior or when you suspect stale simulator state. This is not part of ordinary playtest lifecycle.',
         inputSchema: {
           type: "object",
           properties: {
@@ -7270,7 +7958,7 @@ var init_definitions = __esm({
       {
         name: "reset_simulation_state",
         category: "write",
-        description: 'Reset reachable simulation state to a clean baseline for deterministic tests. Defaults to target="edit-and-clients" and resets both network and device simulator state. Network reset sets all six simulated NetworkSettings fields to 0; device reset calls StopSimulationAsync(). Call before tests, after starting Play or multiplayer, before stopping, and again on edit after stopping.',
+        description: 'Reset reachable NetworkSettings and/or StudioDeviceSimulatorService state for deterministic network/device tests. Defaults to target="edit-and-clients" and resets both network and device simulator state. Network reset sets all six simulated NetworkSettings fields to 0; device reset calls StopSimulationAsync(). Do not call as routine Studio lifecycle hygiene. Use it after intentionally changing simulation settings, when get_simulation_state shows dirty state, or when a task explicitly requires a clean network/device baseline.',
         inputSchema: {
           type: "object",
           properties: {
@@ -7456,109 +8144,41 @@ var init_definitions = __esm({
         }
       },
       {
-        name: "multiplayer_test_start",
+        name: "multiplayer_playtest",
         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.",
+        description: 'Start, inspect, add players to, remove a client from, or end a StudioTestService multiplayer playtest. Use action="start" with numPlayers, action="status", action="add_players" with numPlayers, action="leave_client" with target="client-N", or action="end". Returns brief lifecycle status only; read script output with get_runtime_logs.',
         inputSchema: {
           type: "object",
           properties: {
-            instance_id: {
+            action: {
               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: {
+              enum: ["start", "status", "add_players", "leave_client", "end"],
+              description: "Lifecycle action to run."
+            },
             numPlayers: {
               type: "number",
-              description: "Number of additional client players to add (1-8)."
+              description: 'Required for action="start" and action="add_players". Number of client players (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.'
+              description: 'Client target for action="leave_client", such as "client-1". Defaults to "client-1".'
             },
-            timeout: {
-              type: "number",
-              description: "Max seconds to wait for the client peer to disconnect (default 30)."
+            testArgs: {
+              description: 'For action="start": JSON-compatible table passed to StudioTestService:GetTestArgs() on server and clients.'
             },
-            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."
+              description: 'For action="end": 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)."
+              description: "Max seconds to wait for action completion. Defaults to 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: ["action"]
         }
       },
       {
@@ -8586,20 +9206,168 @@ part(0,2,0,2,1,1,"b")`,
         }
       }
     ];
+    DEPRECATED_TOOL_DEFINITIONS = [
+      // === Deprecated Playtest API ===
+      {
+        name: "start_playtest",
+        category: "write",
+        description: 'Deprecated. Use solo_playtest with action="start" instead. Starts a simple single-player Studio playtest in play or run mode.',
+        inputSchema: {
+          type: "object",
+          properties: {
+            mode: {
+              type: "string",
+              enum: ["play", "run"],
+              description: "Play mode"
+            },
+            numPlayers: {
+              type: "number",
+              description: 'Deprecated and rejected. Use multiplayer_playtest action="start" for multi-client testing.'
+            },
+            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: ["mode"]
+        }
+      },
+      {
+        name: "stop_playtest",
+        category: "write",
+        description: 'Deprecated. Use solo_playtest with action="stop" instead. Stops a single-player Studio playtest and waits for runtime peers to disconnect.',
+        inputSchema: {
+          type: "object",
+          properties: {
+            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_start",
+        category: "write",
+        description: 'Deprecated. Use multiplayer_playtest with action="start" instead. Starts a StudioTestService multiplayer test.',
+        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: 'Deprecated. Use multiplayer_playtest with action="status" instead. Gets the active multiplayer StudioTestService state.',
+        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: 'Deprecated. Use multiplayer_playtest with action="add_players" instead. Adds client players to a running StudioTestService multiplayer test.',
+        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: 'Deprecated. Use multiplayer_playtest with action="leave_client" instead. Disconnects a specific client from a running StudioTestService multiplayer test.',
+        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: 'Deprecated. Use multiplayer_playtest with action="end" instead. Ends a running StudioTestService multiplayer test.',
+        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."
+            }
+          }
+        }
+      }
+    ];
     getAllTools = () => [...TOOL_DEFINITIONS];
+    getAllCallableTools = () => [...TOOL_DEFINITIONS, ...DEPRECATED_TOOL_DEFINITIONS];
   }
 });
 
 // ../core/dist/install-plugin-helpers.js
-import { existsSync as existsSync2, readFileSync as readFileSync2, unlinkSync } from "fs";
+import { existsSync as existsSync3, readFileSync as readFileSync3, unlinkSync } from "fs";
 import { execSync } from "child_process";
-import { join as join2 } from "path";
-import { homedir as homedir2 } from "os";
+import { join as join3 } from "path";
+import { homedir as homedir3 } from "os";
 function isWSL() {
   if (process.platform !== "linux")
     return false;
   try {
-    const v = readFileSync2("/proc/version", "utf8");
+    const v = readFileSync3("/proc/version", "utf8");
     return /microsoft|wsl/i.test(v);
   } catch {
     return false;
@@ -8617,7 +9385,7 @@ function getWindowsUserPluginsDir() {
     }).toString().trim();
     if (!linuxPath)
       return null;
-    return join2(linuxPath, "Roblox", "Plugins");
+    return join3(linuxPath, "Roblox", "Plugins");
   } catch {
     return null;
   }
@@ -8626,7 +9394,7 @@ function getPluginsFolder() {
   if (process.env.MCP_PLUGINS_DIR)
     return process.env.MCP_PLUGINS_DIR;
   if (process.platform === "win32") {
-    return join2(process.env.LOCALAPPDATA || join2(homedir2(), "AppData", "Local"), "Roblox", "Plugins");
+    return join3(process.env.LOCALAPPDATA || join3(homedir3(), "AppData", "Local"), "Roblox", "Plugins");
   }
   if (isWSL()) {
     const win = getWindowsUserPluginsDir();
@@ -8634,11 +9402,11 @@ function getPluginsFolder() {
       return win;
     console.warn("[install-plugin] WSL detected but could not resolve Windows %LOCALAPPDATA%. Falling back to ~/Documents/Roblox/Plugins/ - you will likely need to copy the rbxmx to /mnt/c/Users/<you>/AppData/Local/Roblox/Plugins/ manually. Set MCP_PLUGINS_DIR to skip detection.");
   }
-  return join2(homedir2(), "Documents", "Roblox", "Plugins");
+  return join3(homedir3(), "Documents", "Roblox", "Plugins");
 }
 function handleVariantConflict({ pluginsFolder, otherAssetName, replace, log = console.log, warn = console.warn }) {
-  const otherDest = join2(pluginsFolder, otherAssetName);
-  if (!existsSync2(otherDest))
+  const otherDest = join3(pluginsFolder, otherAssetName);
+  if (!existsSync3(otherDest))
     return;
   if (replace) {
     try {
@@ -8683,8 +9451,8 @@ __export(install_plugin_exports, {
   installBundledPlugin: () => installBundledPlugin,
   installPlugin: () => installPlugin
 });
-import { copyFileSync, createWriteStream, existsSync as existsSync3, mkdirSync as mkdirSync2, readFileSync as readFileSync3, unlinkSync as unlinkSync2 } from "fs";
-import { dirname as dirname2, join as join3 } from "path";
+import { copyFileSync, createWriteStream, existsSync as existsSync4, mkdirSync as mkdirSync2, readFileSync as readFileSync4, unlinkSync as unlinkSync2 } from "fs";
+import { dirname as dirname2, join as join4 } from "path";
 import { fileURLToPath } from "url";
 import { get } from "https";
 function httpsGet(url) {
@@ -8754,7 +9522,7 @@ function prepareInstall({
   warn
 }) {
   const pluginsFolder = getPluginsFolder();
-  if (!existsSync3(pluginsFolder)) {
+  if (!existsSync4(pluginsFolder)) {
     mkdirSync2(pluginsFolder, { recursive: true });
   }
   handleVariantConflict({
@@ -8769,21 +9537,21 @@ function prepareInstall({
 function bundledAssetPath() {
   const currentDir = dirname2(fileURLToPath(import.meta.url));
   const candidates = [
-    join3(currentDir, "..", "studio-plugin", ASSET_NAME),
-    join3(currentDir, "..", "..", "..", "studio-plugin", ASSET_NAME)
+    join4(currentDir, "..", "studio-plugin", ASSET_NAME),
+    join4(currentDir, "..", "..", "..", "studio-plugin", ASSET_NAME)
   ];
-  return candidates.find((candidate) => existsSync3(candidate)) ?? null;
+  return candidates.find((candidate) => existsSync4(candidate)) ?? null;
 }
 function packageVersion() {
   const currentDir = dirname2(fileURLToPath(import.meta.url));
-  const pkg = JSON.parse(readFileSync3(join3(currentDir, "..", "package.json"), "utf8"));
+  const pkg = JSON.parse(readFileSync4(join4(currentDir, "..", "package.json"), "utf8"));
   if (!pkg.version) {
     throw new Error("Package version not found");
   }
   return pkg.version;
 }
 function bundledPluginVersion(source) {
-  const match = readFileSync3(source, "utf8").match(/local CURRENT_VERSION = "([^"]+)"/);
+  const match = readFileSync4(source, "utf8").match(/local CURRENT_VERSION = "([^"]+)"/);
   return match ? match[1] : null;
 }
 function assertBundledPluginVersion(source) {
@@ -8796,9 +9564,9 @@ function assertBundledPluginVersion(source) {
   }
 }
 function filesMatch(a, b) {
-  if (!existsSync3(b)) return false;
-  const aBytes = readFileSync3(a);
-  const bBytes = readFileSync3(b);
+  if (!existsSync4(b)) return false;
+  const aBytes = readFileSync4(a);
+  const bBytes = readFileSync4(b);
   return aBytes.length === bBytes.length && aBytes.equals(bBytes);
 }
 async function installBundledPlugin(options = {}) {
@@ -8811,7 +9579,7 @@ async function installBundledPlugin(options = {}) {
   }
   assertBundledPluginVersion(source);
   const pluginsFolder = prepareInstall({ replaceVariant, log, warn });
-  const dest = join3(pluginsFolder, ASSET_NAME);
+  const dest = join4(pluginsFolder, ASSET_NAME);
   if (filesMatch(source, dest)) return;
   copyFileSync(source, dest);
   log(`Installed ${ASSET_NAME} to ${dest}`);
@@ -8825,7 +9593,7 @@ async function installPlugin(options = {}) {
   const bundled = bundledAssetPath();
   if (bundled) {
     assertBundledPluginVersion(bundled);
-    const dest2 = join3(pluginsFolder, ASSET_NAME);
+    const dest2 = join4(pluginsFolder, ASSET_NAME);
     if (filesMatch(bundled, dest2)) {
       log(`${ASSET_NAME} already installed.`);
       return;
@@ -8840,7 +9608,7 @@ async function installPlugin(options = {}) {
   if (!asset) {
     throw new Error(`${ASSET_NAME} not found in release ${release.tag_name}`);
   }
-  const dest = join3(pluginsFolder, ASSET_NAME);
+  const dest = join4(pluginsFolder, ASSET_NAME);
   log(`Downloading ${ASSET_NAME} from ${release.tag_name}...`);
   await download(asset.browser_download_url, dest);
   log(`Installed to ${dest}`);
@@ -8894,7 +9662,8 @@ if (process.argv.includes("--install-plugin")) {
   const server = new RobloxStudioMCPServer({
     name: "robloxstudio-mcp",
     version: VERSION,
-    tools: getAllTools()
+    tools: getAllTools(),
+    callableTools: getAllCallableTools()
   });
   server.run().catch((error) => {
     console.error("Server failed to start:", error);