@chrrxs/robloxstudio-mcp-inspector 2.14.0 → 2.15.1

package/dist/index.js

@@ -19,6 +19,10 @@ function toPublic(inst) {
     placeName: inst.placeName,
     dataModelName: inst.dataModelName,
     isRunning: inst.isRunning,
+    pluginVersion: inst.pluginVersion,
+    pluginVariant: inst.pluginVariant,
+    serverVersion: inst.serverVersion,
+    versionMismatch: inst.versionMismatch,
     lastActivity: inst.lastActivity,
     connectedAt: inst.connectedAt
   };
@@ -45,6 +49,10 @@ var init_bridge_service = __esm({
         const { pluginSessionId, instanceId, role } = input;
         const prior = this.instances.get(pluginSessionId);
         let assignedRole = role;
+        const pluginVersion = input.pluginVersion ?? "";
+        const pluginVariant = input.pluginVariant ?? "unknown";
+        const serverVersion = input.serverVersion ?? "";
+        const versionMismatch = pluginVersion !== "" && serverVersion !== "" && pluginVersion !== serverVersion;
         if (role === "client") {
           if (prior && prior.instanceId === instanceId && prior.role.match(/^client-\d+$/)) {
             assignedRole = prior.role;
@@ -82,6 +90,10 @@ var init_bridge_service = __esm({
           placeName: input.placeName ?? "",
           dataModelName: input.dataModelName ?? "",
           isRunning: input.isRunning ?? false,
+          pluginVersion,
+          pluginVariant,
+          serverVersion,
+          versionMismatch,
           lastActivity: Date.now(),
           connectedAt: prior?.connectedAt ?? Date.now()
         });
@@ -326,6 +338,7 @@ function createHttpServer(tools, bridge, allowedTools, serverConfig) {
   let lastMCPActivity = 0;
   let mcpServerStartTime = 0;
   const proxyInstances = /* @__PURE__ */ new Set();
+  const warnedVersionMismatches = /* @__PURE__ */ new Set();
   const setMCPServerActive = (active) => {
     mcpServerActive = active;
     if (active) {
@@ -354,13 +367,16 @@ function createHttpServer(tools, bridge, allowedTools, serverConfig) {
   app.use(express.urlencoded({ limit: "50mb", extended: true }));
   app.get("/health", (req, res) => {
     const instances = bridge.getInstances();
+    const publicInstances = instances.map(toPublic);
     res.json({
       status: "ok",
       service: "robloxstudio-mcp",
       version: serverConfig?.version,
+      serverVersion: serverConfig?.version,
       pluginConnected: instances.length > 0,
       instanceCount: instances.length,
-      instances: instances.map(toPublic),
+      instances: publicInstances,
+      versionMismatch: publicInstances.some((inst) => inst.versionMismatch),
       mcpServerActive: isMCPServerActive(),
       uptime: mcpServerActive ? Date.now() - mcpServerStartTime : 0,
       pendingRequests: bridge.getPendingRequestCount(),
@@ -369,7 +385,7 @@ function createHttpServer(tools, bridge, allowedTools, serverConfig) {
     });
   });
   app.post("/ready", (req, res) => {
-    const { pluginSessionId, instanceId, role, placeId, placeName, dataModelName, isRunning } = req.body;
+    const { pluginSessionId, instanceId, role, placeId, placeName, dataModelName, isRunning, pluginVersion, pluginVariant } = req.body;
     if (!pluginSessionId || !instanceId || !role) {
       res.status(400).json({
         success: false,
@@ -384,7 +400,10 @@ function createHttpServer(tools, bridge, allowedTools, serverConfig) {
       placeId: typeof placeId === "number" ? placeId : 0,
       placeName: typeof placeName === "string" ? placeName : "",
       dataModelName: typeof dataModelName === "string" ? dataModelName : "",
-      isRunning: !!isRunning
+      isRunning: !!isRunning,
+      pluginVersion: typeof pluginVersion === "string" ? pluginVersion : "",
+      pluginVariant: typeof pluginVariant === "string" ? pluginVariant : "unknown",
+      serverVersion: serverConfig?.version ?? ""
     });
     if (!result.ok) {
       res.status(409).json({
@@ -395,10 +414,17 @@ function createHttpServer(tools, bridge, allowedTools, serverConfig) {
       });
       return;
     }
+    const registered = bridge.getInstanceBySessionId(pluginSessionId);
+    if (registered?.versionMismatch && !warnedVersionMismatches.has(pluginSessionId)) {
+      warnedVersionMismatches.add(pluginSessionId);
+      console.error(`[version-mismatch] Studio plugin v${registered.pluginVersion} (${registered.pluginVariant}) does not match MCP server v${registered.serverVersion} for ${registered.instanceId}/${registered.role}`);
+    }
     res.json({
       success: true,
       assignedRole: result.assignedRole,
-      instanceId: result.instanceId
+      instanceId: result.instanceId,
+      serverVersion: serverConfig?.version,
+      versionMismatch: registered?.versionMismatch ?? false
     });
   });
   app.post("/disconnect", (req, res) => {
@@ -410,17 +436,25 @@ function createHttpServer(tools, bridge, allowedTools, serverConfig) {
   });
   app.get("/status", (req, res) => {
     const instances = bridge.getInstances();
+    const publicInstances = instances.map(toPublic);
     res.json({
       pluginConnected: instances.length > 0,
       instanceCount: instances.length,
-      instances: instances.map(toPublic),
+      instances: publicInstances,
+      serverVersion: serverConfig?.version,
+      versionMismatch: publicInstances.some((inst) => inst.versionMismatch),
       mcpServerActive: isMCPServerActive(),
       lastMCPActivity,
       uptime: mcpServerActive ? Date.now() - mcpServerStartTime : 0
     });
   });
   app.get("/instances", (req, res) => {
-    res.json({ instances: bridge.getInstances() });
+    const instances = bridge.getInstances();
+    res.json({
+      instances,
+      serverVersion: serverConfig?.version,
+      versionMismatch: instances.some((inst) => inst.versionMismatch)
+    });
   });
   app.get("/poll", (req, res) => {
     const pluginSessionId = req.query.pluginSessionId;
@@ -430,11 +464,17 @@ function createHttpServer(tools, bridge, allowedTools, serverConfig) {
     let callerInstanceId;
     let callerRole;
     let knownInstance = false;
+    let callerPluginVersion;
+    let callerPluginVariant;
+    let versionMismatch = false;
     if (pluginSessionId) {
       const inst = bridge.getInstanceBySessionId(pluginSessionId);
       if (inst) {
         callerInstanceId = inst.instanceId;
         callerRole = inst.role;
+        callerPluginVersion = inst.pluginVersion;
+        callerPluginVariant = inst.pluginVariant;
+        versionMismatch = inst.versionMismatch;
         knownInstance = true;
       }
     }
@@ -444,6 +484,10 @@ function createHttpServer(tools, bridge, allowedTools, serverConfig) {
         pluginConnected: true,
         mcpConnected: false,
         knownInstance,
+        serverVersion: serverConfig?.version,
+        pluginVersion: callerPluginVersion,
+        pluginVariant: callerPluginVariant,
+        versionMismatch,
         request: null
       });
       return;
@@ -456,6 +500,10 @@ function createHttpServer(tools, bridge, allowedTools, serverConfig) {
         mcpConnected: true,
         pluginConnected: true,
         knownInstance,
+        serverVersion: serverConfig?.version,
+        pluginVersion: callerPluginVersion,
+        pluginVariant: callerPluginVariant,
+        versionMismatch,
         proxyInstanceCount: proxyInstances.size
       });
     } else {
@@ -464,6 +512,10 @@ function createHttpServer(tools, bridge, allowedTools, serverConfig) {
         mcpConnected: true,
         pluginConnected: true,
         knownInstance,
+        serverVersion: serverConfig?.version,
+        pluginVersion: callerPluginVersion,
+        pluginVariant: callerPluginVariant,
+        versionMismatch,
         proxyInstanceCount: proxyInstances.size
       });
     }
@@ -721,6 +773,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, {
@@ -2884,6 +2937,19 @@ var init_tools = __esm({
         const clientCount = this._clientRolesForInstance(instanceId).length;
         return { ok: false, roles, timedOut: true, extraClients: clientCount > expectedClientCount, clientCount };
       }
+      async _waitForRuntimeRolesFresh(instanceId, connectedAfter, requiredRoles, timeoutSec = 60) {
+        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 {
@@ -3532,12 +3598,37 @@ ${code}`
           throw new Error("start_playtest is single-player only. Use multiplayer_test_start for multi-client StudioTestService sessions.");
         }
         const data = { mode };
-        const response = await this._callSingle("/api/start-playtest", data, void 0, instance_id);
+        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.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)
             }
           ]
         };
@@ -4602,6 +4693,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");
@@ -6032,7 +6156,7 @@ var init_definitions = __esm({
       {
         name: "start_playtest",
         category: "write",
-        description: "Start a simple single-player Studio playtest in play or run mode. Captures print/warn/error via LogService. Poll with get_playtest_output, end with stop_playtest. For multi-client testing use multiplayer_test_start instead.",
+        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: {
@@ -7010,6 +7134,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",
@@ -7178,20 +7335,20 @@ function getPluginsFolder() {
   }
   return join2(homedir2(), "Documents", "Roblox", "Plugins");
 }
-function handleVariantConflict({ pluginsFolder, otherAssetName, replace }) {
+function handleVariantConflict({ pluginsFolder, otherAssetName, replace, log = console.log, warn = console.warn }) {
   const otherDest = join2(pluginsFolder, otherAssetName);
   if (!existsSync2(otherDest))
     return;
   if (replace) {
     try {
       unlinkSync(otherDest);
-      console.log(`Removed conflicting ${otherAssetName}.`);
+      log(`Removed conflicting ${otherAssetName}.`);
     } catch (err) {
-      console.warn(`[install-plugin] Could not remove ${otherDest}: ${err}. Continuing.`);
+      warn(`[install-plugin] Could not remove ${otherDest}: ${err}. Continuing.`);
     }
     return;
   }
-  console.warn(`
+  warn(`
 [install-plugin] WARNING: ${otherAssetName} is already present in ${pluginsFolder}.
 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.
@@ -7222,10 +7379,12 @@ var init_dist = __esm({
 // src/install-plugin.ts
 var install_plugin_exports = {};
 __export(install_plugin_exports, {
+  installBundledPlugin: () => installBundledPlugin,
   installPlugin: () => installPlugin
 });
-import { createWriteStream, existsSync as existsSync3, mkdirSync as mkdirSync2, unlinkSync as unlinkSync2 } from "fs";
-import { join as join3 } from "path";
+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 { fileURLToPath } from "url";
 import { get } from "https";
 function httpsGet(url) {
   return new Promise((resolve2, reject) => {
@@ -7278,8 +7437,11 @@ async function fetchJson(url) {
   }
   return JSON.parse(Buffer.concat(chunks).toString());
 }
-async function installPlugin() {
-  const replaceVariant = process.argv.includes("--replace-variant");
+function prepareInstall({
+  replaceVariant,
+  log,
+  warn
+}) {
   const pluginsFolder = getPluginsFolder();
   if (!existsSync3(pluginsFolder)) {
     mkdirSync2(pluginsFolder, { recursive: true });
@@ -7287,18 +7449,55 @@ async function installPlugin() {
   handleVariantConflict({
     pluginsFolder,
     otherAssetName: OTHER_VARIANT,
-    replace: replaceVariant
+    replace: replaceVariant,
+    log,
+    warn
   });
-  console.log("Fetching latest release...");
+  return pluginsFolder;
+}
+function bundledAssetPath() {
+  const currentDir = dirname2(fileURLToPath(import.meta.url));
+  const candidates = [
+    join3(currentDir, "..", "studio-plugin", ASSET_NAME),
+    join3(currentDir, "..", "..", "..", "studio-plugin", ASSET_NAME)
+  ];
+  return candidates.find((candidate) => existsSync3(candidate)) ?? null;
+}
+function filesMatch(a, b) {
+  if (!existsSync3(b)) return false;
+  const aBytes = readFileSync3(a);
+  const bBytes = readFileSync3(b);
+  return aBytes.length === bBytes.length && aBytes.equals(bBytes);
+}
+async function installBundledPlugin(options = {}) {
+  const log = options.log ?? console.log;
+  const warn = options.warn ?? console.warn;
+  const replaceVariant = options.replaceVariant ?? process.argv.includes("--replace-variant");
+  const source = bundledAssetPath();
+  if (!source) {
+    throw new Error(`Bundled ${ASSET_NAME} not found in package`);
+  }
+  const pluginsFolder = prepareInstall({ replaceVariant, log, warn });
+  const dest = join3(pluginsFolder, ASSET_NAME);
+  if (filesMatch(source, dest)) return;
+  copyFileSync(source, dest);
+  log(`Installed ${ASSET_NAME} to ${dest}`);
+}
+async function installPlugin(options = {}) {
+  const replaceVariant = options.replaceVariant ?? process.argv.includes("--replace-variant");
+  const log = options.log ?? console.log;
+  const warn = options.warn ?? console.warn;
+  const pluginsFolder = prepareInstall({ replaceVariant, log, warn });
+  log("Fetching latest release...");
   const release = await fetchJson(`https://api.github.com/repos/${REPO}/releases/latest`);
   const asset = release.assets?.find((a) => a.name === ASSET_NAME);
   if (!asset) {
     throw new Error(`${ASSET_NAME} not found in release ${release.tag_name}`);
   }
   const dest = join3(pluginsFolder, ASSET_NAME);
-  console.log(`Downloading ${ASSET_NAME} from ${release.tag_name}...`);
+  log(`Downloading ${ASSET_NAME} from ${release.tag_name}...`);
   await download(asset.browser_download_url, dest);
-  console.log(`Installed to ${dest}`);
+  log(`Installed to ${dest}`);
 }
 var REPO, ASSET_NAME, OTHER_VARIANT, TIMEOUT_MS, MAX_REDIRECTS;
 var init_install_plugin = __esm({
@@ -7323,6 +7522,18 @@ if (process.argv.includes("--install-plugin")) {
     process.exitCode = 1;
   });
 } else {
+  if (process.argv.includes("--auto-install-plugin")) {
+    const { installBundledPlugin: installBundledPlugin2 } = await Promise.resolve().then(() => (init_install_plugin(), install_plugin_exports));
+    await installBundledPlugin2({
+      replaceVariant: process.argv.includes("--replace-variant"),
+      log: (message) => console.error(`[install-plugin] ${message}`),
+      warn: (message) => console.error(message)
+    }).catch((err) => {
+      console.error(
+        `[install-plugin] Auto-install skipped: ${err instanceof Error ? err.message : String(err)}`
+      );
+    });
+  }
   const require2 = createRequire(import.meta.url);
   const { version: VERSION } = require2("../package.json");
   const server = new RobloxStudioMCPServer({

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@chrrxs/robloxstudio-mcp-inspector",
-  "version": "2.14.0",
+  "version": "2.15.1",
   "description": "Read-only MCP server for inspecting and debugging Roblox Studio from AI coding tools",
   "main": "dist/index.js",
   "type": "module",
@@ -30,7 +30,7 @@
   "license": "MIT",
   "repository": {
     "type": "git",
-    "url": "https://github.com/chrrxs/robloxstudio-mcp.git"
+    "url": "git+https://github.com/chrrxs/robloxstudio-mcp.git"
   },
   "homepage": "https://github.com/chrrxs/robloxstudio-mcp#readme",
   "bugs": {

package/studio-plugin/INSTALLATION.md

@@ -15,6 +15,7 @@ Complete your AI assistant integration with this easy-to-install Studio plugin.
 ### Method 2: Direct Download
 1. **Download the plugin:**
    - **GitHub Release**: [Download MCPPlugin.rbxmx](https://github.com/chrrxs/robloxstudio-mcp/releases/latest/download/MCPPlugin.rbxmx)
+   - **CLI installer**: `npx -y @chrrxs/robloxstudio-mcp@latest --install-plugin`
    - This is the official Roblox plugin format
 
 2. **Install to plugins folder:**
@@ -54,7 +55,12 @@ Choose your AI assistant:
 
 **For Claude Code:**
 ```bash
-claude mcp add robloxstudio-mcp
+claude mcp add robloxstudio -- npx -y @chrrxs/robloxstudio-mcp@latest --auto-install-plugin
+```
+
+**For Codex CLI:**
+```bash
+codex mcp add robloxstudio -- npx -y @chrrxs/robloxstudio-mcp@latest --auto-install-plugin
 ```
 
 **For Claude Desktop/Others:**
@@ -63,12 +69,16 @@ claude mcp add robloxstudio-mcp
   "mcpServers": {
     "robloxstudio-mcp": {
       "command": "npx",
-      "args": ["-y", "@chrrxs/robloxstudio-mcp"]
+      "args": ["-y", "@chrrxs/robloxstudio-mcp@latest", "--auto-install-plugin"]
     }
   }
 }
 ```
 
+`@latest` floats the server package to the newest npm release. `--auto-install-plugin` copies the matching `.rbxmx` bundled with that package into Studio's Plugins folder when the server starts.
+
+If Studio shows a yellow plugin/server version mismatch banner, the connection remains usable. Restart the MCP server with `--auto-install-plugin`, then fully close and reopen Studio so it loads the matching plugin file.
+
 <details>
 <summary>Note for native Windows users</summary>
 If you encounter issues, you may need to run it through `cmd`. Update your configuration like this:
@@ -78,7 +88,7 @@ If you encounter issues, you may need to run it through `cmd`. Update your confi
   "mcpServers": {
     "robloxstudio-mcp": {
       "command": "cmd",
-      "args": ["/c", "npx", "-y", "@chrrxs/robloxstudio-mcp@latest"]
+      "args": ["/c", "npx", "-y", "@chrrxs/robloxstudio-mcp@latest", "--auto-install-plugin"]
     }
   }
 }