@chrrxs/robloxstudio-mcp-inspector 2.22.2 → 2.22.3

package/dist/index.js

@@ -889,6 +889,7 @@ function requiredClosedLineRange(body, toolName) {
 }
 function createHttpServer(tools, bridge, allowedTools, serverConfig, security) {
   const app = express();
+  const studioLifecycleCallable = !allowedTools || allowedTools.has("manage_instance");
   let mcpServerActive = false;
   let lastMCPActivity = 0;
   let mcpServerStartTime = 0;
@@ -968,8 +969,15 @@ function createHttpServer(tools, bridge, allowedTools, serverConfig, security) {
     res.json({
       status: "ok",
       service: "robloxstudio-mcp",
+      serverName: serverConfig?.name ?? "robloxstudio-mcp",
       version: serverConfig?.version,
       serverVersion: serverConfig?.version,
+      capabilities: studioLifecycleCallable ? {
+        studioLifecycle: {
+          protocolVersion: 1,
+          endpoint: "/mcp/manage_instance"
+        }
+      } : {},
       pluginConnected: instances.length > 0,
       instanceCount: instances.length,
       instances: publicInstances,
@@ -3426,6 +3434,65 @@ function toStudioLaunchArg(arg) {
 function powershellStringLiteral(value) {
   return `'${value.replace(/'/g, "''")}'`;
 }
+function parseStudioProcessEnvironmentPatch(value) {
+  if (value === void 0)
+    return void 0;
+  if (value === null || typeof value !== "object" || Array.isArray(value)) {
+    throw new Error("process_environment must be an object when provided.");
+  }
+  const raw = value;
+  const unsupported = Object.keys(raw).filter((key) => key !== "set" && key !== "remove");
+  if (unsupported.length > 0) {
+    throw new Error(`process_environment contains unsupported field(s): ${unsupported.join(", ")}.`);
+  }
+  let set;
+  if (raw.set !== void 0) {
+    if (raw.set === null || typeof raw.set !== "object" || Array.isArray(raw.set)) {
+      throw new Error("process_environment.set must be an object mapping names to string values.");
+    }
+    set = {};
+    for (const [name, setting] of Object.entries(raw.set)) {
+      if (!ENVIRONMENT_VARIABLE_NAME.test(name)) {
+        throw new Error(`Invalid process environment variable name "${name}".`);
+      }
+      if (typeof setting !== "string") {
+        throw new Error(`process_environment.set.${name} must be a string.`);
+      }
+      if (setting.includes("\0")) {
+        throw new Error(`process_environment.set.${name} must not contain a null character.`);
+      }
+      set[name] = setting;
+    }
+  }
+  let remove;
+  if (raw.remove !== void 0) {
+    if (!Array.isArray(raw.remove) || raw.remove.some((name) => typeof name !== "string")) {
+      throw new Error("process_environment.remove must be an array of environment variable names.");
+    }
+    remove = [...new Set(raw.remove)];
+    for (const name of remove) {
+      if (!ENVIRONMENT_VARIABLE_NAME.test(name)) {
+        throw new Error(`Invalid process environment variable name "${name}".`);
+      }
+    }
+  }
+  return { set, remove };
+}
+function patchedProcessEnvironment(patch) {
+  const environment = { ...process.env };
+  for (const name of patch.remove ?? [])
+    delete environment[name];
+  for (const [name, value] of Object.entries(patch.set ?? {}))
+    environment[name] = value;
+  return environment;
+}
+function powershellEnvironmentPatchStatements(patch) {
+  const target = "[EnvironmentVariableTarget]::Process";
+  return [
+    ...(patch.remove ?? []).map((name) => `[Environment]::SetEnvironmentVariable(${powershellStringLiteral(name)}, $null, ${target})`),
+    ...Object.entries(patch.set ?? {}).map(([name, value]) => `[Environment]::SetEnvironmentVariable(${powershellStringLiteral(name)}, ${powershellStringLiteral(value)}, ${target})`)
+  ];
+}
 function quoteWindowsCommandLineArg(value) {
   if (value.length > 0 && !/[\s"]/u.test(value))
     return value;
@@ -3446,10 +3513,12 @@ function quoteWindowsCommandLineArg(value) {
   }
   return `${quoted}${"\\".repeat(backslashes * 2)}"`;
 }
-function buildWindowsStudioStartScript(exe, args) {
+function buildWindowsStudioStartScript(exe, args, processEnvironment) {
+  const environmentPatch = parseStudioProcessEnvironmentPatch(processEnvironment);
   const windowsExe = toStudioLaunchArg(exe);
   const commandLine = args.map(quoteWindowsCommandLineArg).join(" ");
   return [
+    ...environmentPatch ? powershellEnvironmentPatchStatements(environmentPatch) : [],
     "$psi = New-Object System.Diagnostics.ProcessStartInfo",
     `$psi.FileName = ${powershellStringLiteral(windowsExe)}`,
     `$psi.Arguments = ${powershellStringLiteral(commandLine)}`,
@@ -3463,8 +3532,8 @@ function buildWindowsStudioStartScript(exe, args) {
     'if ($null -eq $studio) { throw "Roblox Studio process did not start." }'
   ].join("; ");
 }
-function spawnWindowsStudioFromWsl(exe, args) {
-  const script = buildWindowsStudioStartScript(exe, args);
+function spawnWindowsStudioFromWsl(exe, args, processEnvironment) {
+  const script = buildWindowsStudioStartScript(exe, args, processEnvironment);
   const output = powershell(`${script}; [PSCustomObject]@{ pid = $studio.Id; started = $studio.StartTime.ToUniversalTime().ToFileTimeUtc().ToString() } | ConvertTo-Json -Compress`);
   const parsed = JSON.parse(output);
   const nativePid = Number(parsed.pid);
@@ -3674,7 +3743,7 @@ function delay(ms) {
 function basenameAny(filePath) {
   return path2.basename(filePath.replace(/\\/g, "/"));
 }
-var BASEPLATE_TEMP_DIR, BASEPLATE_TEMP_NAME, BASEPLATE_TEMPLATE_NAME, STALE_BASEPLATE_MAX_AGE_MS, BASEPLATE_TEMP_SWEEP_NAME, StudioInstanceManager;
+var BASEPLATE_TEMP_DIR, BASEPLATE_TEMP_NAME, BASEPLATE_TEMPLATE_NAME, ENVIRONMENT_VARIABLE_NAME, STALE_BASEPLATE_MAX_AGE_MS, BASEPLATE_TEMP_SWEEP_NAME, StudioInstanceManager;
 var init_studio_instance_manager = __esm({
   "../core/dist/studio-instance-manager.js"() {
     "use strict";
@@ -3682,6 +3751,7 @@ var init_studio_instance_manager = __esm({
     BASEPLATE_TEMP_DIR = path2.join(os2.tmpdir(), "robloxstudio-mcp-baseplates");
     BASEPLATE_TEMP_NAME = /^Baseplate-\d+-\d+\.rbxl$/;
     BASEPLATE_TEMPLATE_NAME = "Baseplate.rbxl";
+    ENVIRONMENT_VARIABLE_NAME = /^[A-Za-z_][A-Za-z0-9_]*$/u;
     STALE_BASEPLATE_MAX_AGE_MS = 24 * 60 * 60 * 1e3;
     BASEPLATE_TEMP_SWEEP_NAME = /^Baseplate-(\d+)-\d+\.rbxl(\.lock)?$/;
     StudioInstanceManager = class {
@@ -3782,22 +3852,27 @@ var init_studio_instance_manager = __esm({
       }
       async launch(options) {
         this.sweepRegistry();
+        const processEnvironment = parseStudioProcessEnvironmentPatch(options.processEnvironment);
+        if (options.studioExecutable !== void 0 && (typeof options.studioExecutable !== "string" || options.studioExecutable.length === 0 || options.studioExecutable.includes("\0"))) {
+          throw new Error("studio_executable must be a non-empty string without null characters.");
+        }
         const preparedOptions = prepareStudioLaunchOptions(options);
         const bootId = this.getCurrentBootId();
         const before = new Set(this.listStudioProcesses().map((proc2) => proc2.Id));
-        const exe = this.processAdapter.resolveStudioExe?.() ?? resolveStudioExe();
+        const exe = preparedOptions.studioExecutable ?? this.processAdapter.resolveStudioExe?.() ?? resolveStudioExe();
         const args = buildStudioLaunchArgs(preparedOptions).map(toStudioLaunchArg);
         const spawnOptions = {
           cwd: isWsl() && existsSync2("/mnt/c/Windows") ? "/mnt/c/Windows" : process.cwd(),
           detached: true,
-          stdio: "ignore"
+          stdio: "ignore",
+          ...processEnvironment ? { env: patchedProcessEnvironment(processEnvironment) } : {}
         };
         let proc;
         try {
           if (this.processAdapter.spawnStudio) {
             proc = this.processAdapter.spawnStudio(exe, args, spawnOptions);
           } else if (isWsl()) {
-            proc = spawnWindowsStudioFromWsl(exe, args);
+            proc = spawnWindowsStudioFromWsl(exe, args, processEnvironment);
           } else {
             const child = spawn(exe, args, spawnOptions);
             proc = {
@@ -8730,6 +8805,7 @@ ${code}`
             }
             return this._textResult({
               ...this._managedStatus(record2),
+              close_status: closeResult2.status,
               message: closeResult2.status === "already_closed" ? "Studio instance was already closed." : "Studio instance closed."
             });
           }
@@ -8743,6 +8819,7 @@ ${code}`
               const closedRecord = recordBeforeClose ?? (managedClose.launchId ? this.instanceManager.getByLaunchId(managedClose.launchId) : void 0);
               return this._textResult({
                 ...closedRecord ? this._managedStatus(closedRecord) : { instance_id },
+                close_status: managedClose.status,
                 message: managedClose.status === "already_closed" ? "Studio instance was already closed." : "Studio instance closed."
               });
             }
@@ -8766,6 +8843,7 @@ ${code}`
             await this.bridge.unregisterInstanceIdEverywhere(instance_id);
             return this._textResult({
               instance_id,
+              close_status: "closed",
               message: "Studio instance closed."
             });
           } else {
@@ -8790,6 +8868,7 @@ ${code}`
           }
           return this._textResult({
             ...this._managedStatus(record2),
+            close_status: closeResult.status,
             message: closeResult.status === "already_closed" ? "Studio instance was already closed." : "Studio instance closed."
           });
         }
@@ -8801,6 +8880,14 @@ ${code}`
         const placeId = launchSource === "published_place" || launchSource === "place_revision" ? this._positiveInteger(request.place_id, "place_id") : void 0;
         const placeVersion = launchSource === "place_revision" ? this._positiveInteger(request.place_version, "place_version") : void 0;
         const localPlaceFile = typeof request.local_place_file === "string" ? request.local_place_file : void 0;
+        let studioExecutable;
+        if (request.studio_executable !== void 0) {
+          if (typeof request.studio_executable !== "string" || request.studio_executable.length === 0) {
+            throw new Error("studio_executable must be a non-empty string when provided.");
+          }
+          studioExecutable = request.studio_executable;
+        }
+        const processEnvironment = parseStudioProcessEnvironmentPatch(request.process_environment);
         if (launchSource === "published_place" && placeId !== void 0 && this._isLatestPublishedPlaceOpen(placeId)) {
           return this._textResult({
             error: "Place is already open.",
@@ -8817,7 +8904,9 @@ ${code}`
           placeId,
           universeId,
           placeVersion,
-          connectionTimeoutMs: timeoutMs
+          connectionTimeoutMs: timeoutMs,
+          studioExecutable,
+          processEnvironment
         });
         if (!waitForConnection) {
           return this._textResult({
@@ -11874,6 +11963,35 @@ var init_definitions = __esm({
               type: "number",
               description: 'For action="launch": max milliseconds for plugin connection (default 120000). The deadline also applies asynchronously when wait_for_connection=false.'
             },
+            studio_executable: {
+              type: "string",
+              description: 'For action="launch": exact Roblox Studio executable to launch instead of auto-discovering a version.'
+            },
+            process_environment: {
+              type: "object",
+              description: 'For action="launch": process-scoped environment patch applied only while creating Studio. Values are never retained in the managed-instance registry.',
+              properties: {
+                set: {
+                  type: "object",
+                  description: "Environment variables to set for the Studio process.",
+                  propertyNames: {
+                    pattern: "^[A-Za-z_][A-Za-z0-9_]*$"
+                  },
+                  additionalProperties: {
+                    type: "string"
+                  }
+                },
+                remove: {
+                  type: "array",
+                  description: "Environment variables to remove from the Studio process environment.",
+                  items: {
+                    type: "string",
+                    pattern: "^[A-Za-z_][A-Za-z0-9_]*$"
+                  }
+                }
+              },
+              additionalProperties: false
+            },
             max_page_size: {
               type: "number",
               description: 'For action="list_place_versions": number of versions to return, clamped to 1-50 (default 10).'
@@ -12243,7 +12361,7 @@ var init_definitions = __esm({
       {
         name: "get_runtime_logs",
         category: "read",
-        description: "Read the in-memory log buffers captured by Studio plugin peers. Each buffer captures ~64 KB of recent LogService output; runtime peers seed from LogService:GetLogHistory() at plugin load so early startup logs emitted before the plugin finishes loading can still be returned, then continue capturing LogService.MessageOut entries. Oldest entries drop when over budget. Entries include capturedBy for the plugin buffer that observed the log. In ordinary Studio play/run sessions, LogService reflects logs across edit/server/client, so script-origin peer is not reliable and entries omit peer. In StudioTestService multiplayer sessions only, peer attribution is reliable and entries also include peer. target=all (default) merges buffers and dedups same-message-and-level entries captured within 2s across different buffers.",
+        description: "Read the in-memory log buffers captured by Studio plugin peers. Each buffer captures ~64 KB of recent LogService output; runtime peers seed from LogService:GetLogHistory() at plugin load so early startup logs emitted before the plugin finishes loading can still be returned, then continue capturing LogService.MessageOut entries. Live structured LogService entries include their context dictionary as optional data; Roblox GetLogHistory does not expose context for entries seeded at plugin load. Oldest entries drop when over budget. Entries include capturedBy for the plugin buffer that observed the log. In ordinary Studio play/run sessions, LogService reflects logs across edit/server/client, so script-origin peer is not reliable and entries omit peer. In StudioTestService multiplayer sessions only, peer attribution is reliable and entries also include peer. target=all (default) merges buffers and dedups same-message-and-level entries captured within 2s across different buffers.",
         inputSchema: {
           type: "object",
           properties: {

package/package.json

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

package/studio-plugin/MCPInspectorPlugin.rbxmx

@@ -1439,9 +1439,9 @@ local function computeBridgeStamp()
 	for i = 1, #combined do
 		h = (h * 33 + (string.byte(combined, i))) % 2147483647
 	end
-	-- "2.22.2" is replaced with the package version at package time
+	-- "2.22.3" is replaced with the package version at package time
 	-- (scripts/build-plugin.mjs injectVersion), so a release bump also restamps.
-	return `{tostring(h)}-2.22.2`
+	return `{tostring(h)}-2.22.3`
 end
 local BRIDGE_STAMP = computeBridgeStamp()
 local function setSource(scriptInst, source)
@@ -10493,7 +10493,7 @@ local function dropOldestUntilFits(incomingBytes)
 		totalDropped += 1
 	end
 end
-local function pushEntry(msg, t, ts)
+local function pushEntry(msg, t, ts, data)
 	if ts == nil then
 		ts = nowSec()
 	end
@@ -10505,6 +10505,7 @@ local function pushEntry(msg, t, ts)
 		ts = ts,
 		level = levelTag(t),
 		message = safeMessage,
+		data = data,
 	}
 	table.insert(entries, _arg0)
 	nextSeq += 1
@@ -10549,8 +10550,8 @@ local function install()
 	-- Seed from per-DataModel LogHistory so get_runtime_logs can still see them;
 	-- edit history is bounded to the current Studio process above.
 	seedRuntimeHistory()
-	LogService.MessageOut:Connect(function(msg, t)
-		pushEntry(msg, t)
+	LogService.MessageOut:Connect(function(msg, t, context)
+		pushEntry(msg, t, nil, context)
 	end)
 end
 local function detectPeer()
@@ -10813,7 +10814,7 @@ return {
         <Properties>
           <string name="Name">State</string>
           <string name="Source"><![CDATA[-- Compiled with roblox-ts v3.0.0
-local CURRENT_VERSION = "2.22.2"
+local CURRENT_VERSION = "2.22.3"
 local PLUGIN_VARIANT = "inspector"
 local BASE_PORT = 58741
 local function createConnection(port)

package/studio-plugin/MCPPlugin.rbxmx

@@ -1439,9 +1439,9 @@ local function computeBridgeStamp()
 	for i = 1, #combined do
 		h = (h * 33 + (string.byte(combined, i))) % 2147483647
 	end
-	-- "2.22.2" is replaced with the package version at package time
+	-- "2.22.3" is replaced with the package version at package time
 	-- (scripts/build-plugin.mjs injectVersion), so a release bump also restamps.
-	return `{tostring(h)}-2.22.2`
+	return `{tostring(h)}-2.22.3`
 end
 local BRIDGE_STAMP = computeBridgeStamp()
 local function setSource(scriptInst, source)
@@ -10493,7 +10493,7 @@ local function dropOldestUntilFits(incomingBytes)
 		totalDropped += 1
 	end
 end
-local function pushEntry(msg, t, ts)
+local function pushEntry(msg, t, ts, data)
 	if ts == nil then
 		ts = nowSec()
 	end
@@ -10505,6 +10505,7 @@ local function pushEntry(msg, t, ts)
 		ts = ts,
 		level = levelTag(t),
 		message = safeMessage,
+		data = data,
 	}
 	table.insert(entries, _arg0)
 	nextSeq += 1
@@ -10549,8 +10550,8 @@ local function install()
 	-- Seed from per-DataModel LogHistory so get_runtime_logs can still see them;
 	-- edit history is bounded to the current Studio process above.
 	seedRuntimeHistory()
-	LogService.MessageOut:Connect(function(msg, t)
-		pushEntry(msg, t)
+	LogService.MessageOut:Connect(function(msg, t, context)
+		pushEntry(msg, t, nil, context)
 	end)
 end
 local function detectPeer()
@@ -10813,7 +10814,7 @@ return {
         <Properties>
           <string name="Name">State</string>
           <string name="Source"><![CDATA[-- Compiled with roblox-ts v3.0.0
-local CURRENT_VERSION = "2.22.2"
+local CURRENT_VERSION = "2.22.3"
 local PLUGIN_VARIANT = "main"
 local BASE_PORT = 58741
 local function createConnection(port)

package/studio-plugin/src/modules/RuntimeLogBuffer.ts

@@ -24,6 +24,7 @@ interface RuntimeLogEntry {
 	ts: number; // wall-clock seconds via DateTime, coherent across peers
 	level: LogLevel;
 	message: string;
+	data?: Record<string, unknown>;
 }
 
 const MAX_BYTES = 64 * 1024;
@@ -88,7 +89,12 @@ function dropOldestUntilFits(incomingBytes: number): void {
 	}
 }
 
-function pushEntry(msg: string, t: Enum.MessageType, ts = nowSec()): void {
+function pushEntry(
+	msg: string,
+	t: Enum.MessageType,
+	ts = nowSec(),
+	data?: Record<string, unknown>,
+): void {
 	const safeMessage = escapeInvalidUtf8(msg);
 	const bytes = safeMessage.size();
 	dropOldestUntilFits(bytes);
@@ -97,6 +103,7 @@ function pushEntry(msg: string, t: Enum.MessageType, ts = nowSec()): void {
 		ts,
 		level: levelTag(t),
 		message: safeMessage,
+		data,
 	});
 	nextSeq += 1;
 	totalBytes += bytes;
@@ -135,8 +142,8 @@ function install(): void {
 	// Seed from per-DataModel LogHistory so get_runtime_logs can still see them;
 	// edit history is bounded to the current Studio process above.
 	seedRuntimeHistory();
-	LogService.MessageOut.Connect((msg, t) => {
-		pushEntry(msg, t);
+	LogService.MessageOut.Connect((msg, t, context?: Record<string, unknown>) => {
+		pushEntry(msg, t, undefined, context);
 	});
 }