@chrrxs/robloxstudio-mcp 2.16.3 → 2.17.0

package/dist/index.js

@@ -891,13 +891,23 @@ var init_http_server = __esm({
       capture_device_matrix: (tools, body) => tools.captureDeviceMatrix(body.entries, body.target, body.format, body.quality, body.settleSeconds, body.restoreAfter, 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),
-      get_playtest_output: (tools, body) => tools.getPlaytestOutput(body.target, body.instance_id),
       multiplayer_test_start: (tools, body) => tools.multiplayerTestStart(body.numPlayers, body.testArgs, body.timeout, body.instance_id),
       multiplayer_test_state: (tools, body) => tools.multiplayerTestState(body.instance_id),
       multiplayer_test_add_players: (tools, body) => tools.multiplayerTestAddPlayers(body.numPlayers, body.timeout, body.instance_id),
       multiplayer_test_leave_client: (tools, body) => tools.multiplayerTestLeaveClient(body.target, body.timeout, body.instance_id),
       multiplayer_test_end: (tools, body) => tools.multiplayerTestEnd(body.value, body.timeout, body.instance_id),
       get_runtime_logs: (tools, body) => tools.getRuntimeLogs(body.target, body.since, body.tail, body.filter, body.instance_id),
+      capture_script_profiler: (tools, body) => tools.captureScriptProfiler(body.target, {
+        duration_ms: body.duration_ms,
+        frequency: body.frequency,
+        max_functions: body.max_functions,
+        min_total_us: body.min_total_us,
+        filter: body.filter,
+        include_native: body.include_native,
+        include_plugin: body.include_plugin,
+        output_path: body.output_path
+      }, body.instance_id),
+      breakpoints: (tools, body) => tools.breakpoints(body.action, body, body.target, body.instance_id),
       get_connected_instances: (tools) => tools.getConnectedInstances(),
       export_build: (tools, body) => tools.exportBuild(body.instancePath, body.outputId, body.style, body.instance_id),
       create_build: (tools, body) => tools.createBuild(body.id, body.style, body.palette, body.parts, body.bounds),
@@ -918,7 +928,6 @@ var init_http_server = __esm({
       clone_object: (tools, body) => tools.cloneObject(body.instancePath, body.targetParentPath, body.instance_id),
       get_descendants: (tools, body) => tools.getDescendants(body.instancePath, body.maxDepth, body.classFilter, body.instance_id),
       compare_instances: (tools, body) => tools.compareInstances(body.instancePathA, body.instancePathB, body.instance_id),
-      get_output_log: (tools, body) => tools.getOutputLog(body.maxEntries, body.messageType, body.instance_id),
       bulk_set_attributes: (tools, body) => tools.bulkSetAttributes(body.instancePath, body.attributes, body.instance_id),
       capture_screenshot: (tools, body) => tools.captureScreenshot(body.instance_id, body.format, body.quality),
       simulate_mouse_input: (tools, body) => tools.simulateMouseInput(body.action, body.x, body.y, body.button, body.scrollDirection, body.target, body.instance_id),
@@ -3225,6 +3234,16 @@ var init_tools = __esm({
         const instanceIds = new Set(this.bridge.getEquivalentInstanceIds(instanceId));
         return this.bridge.getInstances().filter((i) => instanceIds.has(i.instanceId) && (i.role === "server" || /^client-\d+$/.test(i.role))).map((i) => ({ instanceId: i.instanceId, role: i.role }));
       }
+      _compactSimulationResetResult(result) {
+        const compact = {};
+        if ("network" in result)
+          compact.network = true;
+        if ("deviceSimulator" in result)
+          compact.deviceSimulator = true;
+        if (result.errors !== void 0)
+          compact.errors = result.errors;
+        return compact;
+      }
       _resolveDeviceSimulatorSingleTarget(target, instance_id, toolName) {
         const selectedTarget = target ?? "edit";
         if (selectedTarget === "server" || selectedTarget === "all" || selectedTarget === "all-clients" || selectedTarget === "edit-proxy") {
@@ -4137,10 +4156,12 @@ ${code}`
           }
           return { role, result };
         }));
+        const rawRoles = {};
         const roles = {};
         const failures = [];
         for (const entry of roleEntries) {
-          roles[entry.role] = entry.result;
+          rawRoles[entry.role] = entry.result;
+          roles[entry.role] = this._compactSimulationResetResult(entry.result);
           const errors = entry.result.errors;
           if (errors) {
             for (const [kind, message] of Object.entries(errors)) {
@@ -4149,15 +4170,15 @@ ${code}`
           }
         }
         const body = {
+          success: true,
           target: resolved.selectedTarget,
           network: resetNetwork,
           deviceSimulator: resetDeviceSimulator,
           roles,
-          warnings: resolved.warnings,
-          persistenceNotes: SIMULATION_PERSISTENCE_NOTES
+          warnings: resolved.warnings
         };
         if (failures.length > 0) {
-          throw new Error(`reset_simulation_state failed for ${failures.join("; ")}. Partial result: ${JSON.stringify(body)}`);
+          throw new Error(`reset_simulation_state failed for ${failures.join("; ")}. Partial result: ${JSON.stringify({ ...body, roles: rawRoles })}`);
         }
         return {
           content: [{
@@ -4446,6 +4467,76 @@ ${code}`
           content: [{ type: "text", text: JSON.stringify(body) }]
         };
       }
+      async captureScriptProfiler(target, request = {}, instance_id) {
+        const targetRole = target ?? "server";
+        const data = { ...request };
+        const outputPath = data.output_path;
+        delete data.output_path;
+        if (outputPath !== void 0 && typeof outputPath !== "string") {
+          throw new Error("output_path must be a string when provided");
+        }
+        if (outputPath) {
+          data.__mcp_include_raw_json = true;
+        }
+        const resolved = this.bridge.resolveTarget({ instance_id, target: targetRole });
+        if (!resolved.ok)
+          throw new RoutingFailure(resolved.error);
+        if (resolved.mode !== "single") {
+          throw new RoutingFailure({
+            code: "target_role_not_present_on_instance",
+            message: 'capture_script_profiler profiles one runtime peer at a time. Pick target="server" or a specific "client-N".',
+            data: {
+              instances: this.bridge.getPublicInstances(),
+              count: this.bridge.getInstances().length
+            }
+          });
+        }
+        data.__mcp_instance_id = resolved.targetInstanceId;
+        data.__mcp_target_role = resolved.targetRole;
+        const response = await this.client.request("/api/capture-script-profiler", data, resolved.targetInstanceId, resolved.targetRole);
+        const body = response !== null && typeof response === "object" && !Array.isArray(response) ? { ...response, target: resolved.targetRole } : response;
+        if (body !== null && typeof body === "object" && !Array.isArray(body)) {
+          const mutable = body;
+          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 });
+              fs.writeFileSync(resolvedOutputPath, rawJson, "utf8");
+              mutable.output_path = resolvedOutputPath;
+            }
+            delete mutable.raw_json;
+          }
+        }
+        return { content: [{ type: "text", text: JSON.stringify(body) }] };
+      }
+      async breakpoints(action, request = {}, target, instance_id) {
+        if (!action || typeof action !== "string") {
+          throw new Error("breakpoints requires action=set|remove|clear|list");
+        }
+        const targetRole = target ?? "edit";
+        const data = { ...request, action };
+        delete data.target;
+        delete data.instance_id;
+        const resolved = this.bridge.resolveTarget({ instance_id, target: targetRole });
+        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
+            }
+          });
+        }
+        data.__mcp_instance_id = resolved.targetInstanceId;
+        data.__mcp_target_role = resolved.targetRole;
+        const response = await this.client.request("/api/breakpoints", data, resolved.targetInstanceId, resolved.targetRole);
+        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) {
         if (mode !== "play" && mode !== "run") {
           throw new Error('mode must be "play" or "run"');
@@ -4468,6 +4559,24 @@ ${code}`
             }
           });
         }
+        const existingRuntime = this._runtimeTargetsForEquivalentInstances(resolved.targetInstanceId);
+        if (existingRuntime.length > 0) {
+          const roles = this._rolesForEquivalentInstances(resolved.targetInstanceId);
+          return {
+            content: [{
+              type: "text",
+              text: JSON.stringify({
+                success: false,
+                error: "Playtest already running.",
+                message: "A playtest is already running for this Studio place. Stop the current playtest before starting another.",
+                runtimeReady: true,
+                timedOut: false,
+                roles,
+                runtimeRoles: existingRuntime.map((target) => target.role)
+              })
+            }]
+          };
+        }
         const response = await this.client.request("/api/start-playtest", data, resolved.targetInstanceId, resolved.targetRole);
         let wait;
         if (response?.success === true) {
@@ -4539,17 +4648,6 @@ ${code}`
           content: [{ type: "text", text: JSON.stringify(body) }]
         };
       }
-      async getPlaytestOutput(target, instance_id) {
-        const response = await this._callSingle("/api/get-playtest-output", {}, target || "edit", instance_id);
-        return {
-          content: [
-            {
-              type: "text",
-              text: JSON.stringify(response)
-            }
-          ]
-        };
-      }
       async _buildMultiplayerState(instanceId) {
         const peers = this.bridge.getPublicInstances().filter((i) => i.instanceId === instanceId).sort((a, b) => a.role.localeCompare(b.role));
         const body = {
@@ -5538,10 +5636,6 @@ ${code}`
         const response = await this._callSingle("/api/compare-instances", { instancePathA, instancePathB }, void 0, instance_id);
         return { content: [{ type: "text", text: JSON.stringify(response) }] };
       }
-      async getOutputLog(maxEntries, messageType, instance_id) {
-        const response = await this._callSingle("/api/get-output-log", { maxEntries, messageType }, void 0, instance_id);
-        return { content: [{ type: "text", text: JSON.stringify(response) }] };
-      }
       async bulkSetAttributes(instancePath, attributes, instance_id) {
         if (!instancePath || !attributes) {
           throw new Error("instancePath and attributes are required for bulk_set_attributes");
@@ -7070,7 +7164,7 @@ var init_definitions = __esm({
       {
         name: "start_playtest",
         category: "write",
-        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.",
+        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.",
         inputSchema: {
           type: "object",
           properties: {
@@ -7094,7 +7188,7 @@ var init_definitions = __esm({
       {
         name: "stop_playtest",
         category: "write",
-        description: "Stop playtest and return all captured output.",
+        description: "Stop playtest and wait for runtime peers to disconnect.",
         inputSchema: {
           type: "object",
           properties: {
@@ -7105,24 +7199,6 @@ var init_definitions = __esm({
           }
         }
       },
-      {
-        name: "get_playtest_output",
-        category: "read",
-        description: "Poll output buffer without stopping. Returns isRunning and captured messages.",
-        inputSchema: {
-          type: "object",
-          properties: {
-            target: {
-              type: "string",
-              description: 'Instance target: "edit" (default), "server", "client-1", "client-2", etc.'
-            },
-            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: "set_network_profile",
         category: "write",
@@ -7506,7 +7582,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.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. 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: {
@@ -7533,6 +7609,120 @@ var init_definitions = __esm({
           }
         }
       },
+      {
+        name: "capture_script_profiler",
+        category: "read",
+        description: `Capture one short ScriptProfilerService sample on a running server or client peer and return a compact CPU summary. Use this for Luau/script optimization, not render, physics, networking, or engine microprofiler lanes. Minimal flow: start or reproduce the workload, call capture_script_profiler with target="server" or a specific "client-N", inspect top_functions, patch the suspected hot path, then capture again with the same target/workload/duration_ms/frequency/filter/min_total_us to compare. top_functions is sorted by descending total_us after native/plugin/min/filter exclusions; each row includes rank plus function_index, the 1-based index into the raw Roblox Functions array. Function and node TotalDuration values follow Roblox's exported Script Profiler JSON format and are reported in microseconds as total_us. total_us is cumulative profiler TotalDuration during the capture; nested labels/functions can overlap, so do not sum rows as total CPU time. source is the runtime script path reported by Roblox and may need mapping back to editable source with search tools. If function names are too broad, add debug.profilebegin("Area:SpecificStep") / debug.profileend() around suspected code and pass filter="Area:" or another label prefix; matching custom labels appear in debug_labels and top_functions with their script source and no line number. The result echoes effective options in applied and omitted.filtered_out counts rows removed by filter. Keep captures short while actively triggering the behavior; duration_ms defaults to 1000 and is clamped to 100-15000. Pass output_path when you need the raw Roblox Script Profiler JSON for offline comparison or deeper analysis. This tool owns the start/stop/request profiler lifecycle for one capture and does not expose long-lived profiler sessions.`,
+        inputSchema: {
+          type: "object",
+          properties: {
+            target: {
+              type: "string",
+              pattern: "^(server|client-[0-9]+)$",
+              description: 'Runtime peer to profile: "server" (default) or "client-N". Use get_connected_instances to discover available runtime roles. target="edit" is invalid because ScriptProfiler captures running code.'
+            },
+            duration_ms: {
+              type: "number",
+              default: 1e3,
+              minimum: 100,
+              maximum: 15e3,
+              description: "Sample duration in milliseconds. Defaults to 1000; clamped to 100-15000 so the Studio bridge does not hang on long captures."
+            },
+            frequency: {
+              type: "number",
+              default: 1e3,
+              minimum: 1,
+              maximum: 1e4,
+              description: "ScriptProfiler sampling frequency in samples per second (Hz). Defaults to 1000."
+            },
+            max_functions: {
+              type: "number",
+              default: 20,
+              minimum: 1,
+              maximum: 100,
+              description: "Maximum number of top_functions and debug_labels to return. Defaults to 20; clamped to 1-100."
+            },
+            min_total_us: {
+              type: "number",
+              default: 0,
+              minimum: 0,
+              description: "Omit functions below this TotalDuration in microseconds after capture. Defaults to 0."
+            },
+            filter: {
+              type: "string",
+              description: "Optional case-insensitive substring matched against function name and source before top_functions are returned. Useful for focusing on one module or debug.profilebegin label prefix."
+            },
+            include_native: {
+              type: "boolean",
+              description: "Include native Roblox frames in top_functions. Defaults to false to keep optimization output focused on game Luau and debug labels."
+            },
+            include_plugin: {
+              type: "boolean",
+              description: "Include plugin frames in top_functions. Defaults to false because the MCP capture implementation can otherwise add noise."
+            },
+            output_path: {
+              type: "string",
+              description: "Optional local path where the MCP server writes the raw Script Profiler JSON. The tool result then includes output_path instead of inlining the raw JSON."
+            },
+            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: "breakpoints",
+        category: "write",
+        description: 'Manage Studio debugger breakpoints through ScriptDebuggerService. Use this when the user asks to debug with Studio breakpoints. Prefer log breakpoints for agent debugging: pass log_message and let continue_execution default to true, reproduce the issue, then read get_runtime_logs filtered by "Breakpoint". Minimal flow: set a log breakpoint, run or trigger the behavior, call get_runtime_logs with filter="Breakpoint", then call action="clear" to remove MCP-managed breakpoints. Generated breakpoint logs are prefixed with "Breakpoint" plus script_path:line; Studio breakpoint errors also start with "Breakpoint", so this filter captures both successful breakpoint logs and breakpoint-related failures. Set breakpoints on target="edit" before starting a playtest when possible; for an already-running playtest target the runtime DataModel directly, such as "server" or "client-1". Do not set continue_execution=false unless the target DataModel already has a ScriptDebuggerService.OnStopped handler that returns Enum.DebuggerResumeType.Resume for breakpoint/non-exception stops; otherwise the playtest can get stuck and MCP can lose the server/client peers. Minimal OnStopped reference: local sds=game:GetService("ScriptDebuggerService"); sds.OnStopped=function(info) if info.Reason ~= Enum.ScriptStoppedReason.Exception then return Enum.DebuggerResumeType.Resume end print("EXCEPTION:", info.ExceptionText); return Enum.DebuggerResumeType.Resume end. MCP-managed breakpoints persist minimal script_path/line recovery data per place and target so action="list" and action="clear" can find tool-created edit/server/client breakpoints after MCP/plugin reloads. action="clear" removes only breakpoints created through this MCP tool by default; pass clear_all=true only when you intentionally want to clear every Studio breakpoint in the targeted DataModel, including user-created breakpoints. This tool only manages breakpoint lifecycle; it does not pause, resume, step, inspect variables, or install OnStopped callbacks. Requires Studio Debugger Luau API beta enabled.',
+        inputSchema: {
+          type: "object",
+          properties: {
+            action: {
+              type: "string",
+              enum: ["set", "remove", "clear", "list"],
+              description: "Breakpoint action to run. set/remove require script_path and line. clear removes MCP-managed breakpoints by default. list returns breakpoints created through this MCP tool in the targeted DataModel."
+            },
+            clear_all: {
+              type: "boolean",
+              description: 'Only applies to action="clear". Omit or set false to remove only MCP-managed breakpoints tracked by this tool. Set true to call ScriptDebuggerService:ClearBreakpoints() and clear every Studio breakpoint in the targeted DataModel, including user-created breakpoints.'
+            },
+            script_path: {
+              type: "string",
+              description: "Path to a LuaSourceContainer, for example game.ServerScriptService.Main. Required for set/remove."
+            },
+            line: {
+              type: "number",
+              description: "1-based line number for set/remove."
+            },
+            enabled: {
+              type: "boolean",
+              description: "Whether the breakpoint is enabled when set. Defaults to true."
+            },
+            condition: {
+              type: "string",
+              description: "Optional Luau condition expression for set."
+            },
+            log_message: {
+              type: "string",
+              description: `Optional Studio breakpoint log expression list for set, such as "'health', health". Literal text must be quoted as a Luau string. The tool prefixes this with "Breakpoint" and script_path:line. After reproducing, read get_runtime_logs with filter="Breakpoint" so breakpoint logs and Studio breakpoint errors are both visible.`
+            },
+            continue_execution: {
+              type: "boolean",
+              description: "Whether the breakpoint should log and continue without pausing. Defaults to true when log_message is provided; otherwise false. Only set false when you have first installed a ScriptDebuggerService.OnStopped handler on the same target that resumes breakpoint/non-exception stops with Enum.DebuggerResumeType.Resume; without that handler the playtest can get stuck and MCP can lose server/client peers."
+            },
+            target: {
+              type: "string",
+              description: 'Peer to target: "edit" (default), "server", or "client-N". Set edit breakpoints before playtests; target server/client-N for running play DataModels.'
+            },
+            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"]
+        }
+      },
       // === Multi-Instance ===
       {
         name: "get_connected_instances",
@@ -8251,29 +8441,6 @@ part(0,2,0,2,1,1,"b")`,
           required: ["instancePathA", "instancePathB"]
         }
       },
-      // === Output & Diagnostics ===
-      {
-        name: "get_output_log",
-        category: "read",
-        description: "Get the Studio output log history. Works in both edit and play mode.",
-        inputSchema: {
-          type: "object",
-          properties: {
-            maxEntries: {
-              type: "number",
-              description: "Maximum number of log entries to return (default: 100)"
-            },
-            messageType: {
-              type: "string",
-              description: 'Filter by message type (e.g. "Enum.MessageType.MessageOutput", "Enum.MessageType.MessageWarning", "Enum.MessageType.MessageError")'
-            },
-            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."
-            }
-          }
-        }
-      },
       // === Bulk Attributes ===
       {
         name: "bulk_set_attributes",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@chrrxs/robloxstudio-mcp",
-  "version": "2.16.3",
+  "version": "2.17.0",
   "description": "MCP server for testing, debugging, and controlling Roblox Studio from AI coding tools",
   "main": "dist/index.js",
   "type": "module",