@chrrxs/robloxstudio-mcp-inspector 2.16.4 → 2.17.0

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

@@ -5,6 +5,8 @@ import SceneAnalysisHandlers from "./handlers/SceneAnalysisHandlers";
 import CaptureHandlers from "./handlers/CaptureHandlers";
 import InputHandlers from "./handlers/InputHandlers";
 import EvalRuntimeHandlers from "./handlers/EvalRuntimeHandlers";
+import BreakpointHandlers from "./handlers/BreakpointHandlers";
+import ScriptProfilerHandlers from "./handlers/ScriptProfilerHandlers";
 import LuauExec from "./LuauExec";
 import State from "./State";
 import HttpDiagnostics from "./HttpDiagnostics";
@@ -94,6 +96,8 @@ const CLIENT_BROKER_ALLOWED_ENDPOINTS = new Set<string>([
 	"/api/get-runtime-logs",
 	"/api/get-memory-breakdown",
 	"/api/get-scene-analysis",
+	"/api/breakpoints",
+	"/api/capture-script-profiler",
 	"/api/multiplayer-test-state",
 	"/api/multiplayer-test-leave-client",
 	// Screenshot capture must run in the client peer (CaptureService captures
@@ -266,6 +270,12 @@ function setupClientBroker() {
 		if (payload && payload.endpoint === "/api/get-scene-analysis") {
 			return SceneAnalysisHandlers.getSceneAnalysis(payload.data ?? {});
 		}
+		if (payload && payload.endpoint === "/api/breakpoints") {
+			return BreakpointHandlers.breakpoints(payload.data ?? {});
+		}
+		if (payload && payload.endpoint === "/api/capture-script-profiler") {
+			return ScriptProfilerHandlers.captureScriptProfiler(payload.data ?? {});
+		}
 		if (payload && payload.endpoint === "/api/multiplayer-test-state") {
 			return handleMultiplayerTestState();
 		}

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

@@ -17,6 +17,8 @@ import LogHandlers from "./handlers/LogHandlers";
 import SerializationHandlers from "./handlers/SerializationHandlers";
 import MemoryHandlers from "./handlers/MemoryHandlers";
 import SceneAnalysisHandlers from "./handlers/SceneAnalysisHandlers";
+import BreakpointHandlers from "./handlers/BreakpointHandlers";
+import ScriptProfilerHandlers from "./handlers/ScriptProfilerHandlers";
 import EvalRuntimeHandlers from "./handlers/EvalRuntimeHandlers";
 import ClientBroker from "./ClientBroker";
 import ServerUrlSettings from "./ServerUrlSettings";
@@ -109,7 +111,6 @@ const routeMap: Record<string, Handler> = {
 	"/api/grep-scripts": QueryHandlers.grepScripts,
 	"/api/get-descendants": QueryHandlers.getDescendants,
 	"/api/compare-instances": QueryHandlers.compareInstances,
-	"/api/get-output-log": QueryHandlers.getOutputLog,
 
 	"/api/set-property": PropertyHandlers.setProperty,
 	"/api/set-properties": PropertyHandlers.setProperties,
@@ -146,7 +147,6 @@ const routeMap: Record<string, Handler> = {
 
 	"/api/start-playtest": TestHandlers.startPlaytest,
 	"/api/stop-playtest": TestHandlers.stopPlaytest,
-	"/api/get-playtest-output": TestHandlers.getPlaytestOutput,
 	"/api/multiplayer-test-start": TestHandlers.multiplayerTestStart,
 	"/api/multiplayer-test-state": TestHandlers.multiplayerTestState,
 	"/api/multiplayer-test-add-players": TestHandlers.multiplayerTestAddPlayers,
@@ -171,6 +171,8 @@ const routeMap: Record<string, Handler> = {
 	"/api/find-and-replace-in-scripts": ScriptHandlers.findAndReplaceInScripts,
 
 	"/api/get-runtime-logs": LogHandlers.getRuntimeLogs,
+	"/api/breakpoints": BreakpointHandlers.breakpoints,
+	"/api/capture-script-profiler": ScriptProfilerHandlers.captureScriptProfiler,
 
 	"/api/export-rbxm": SerializationHandlers.exportRbxm,
 	"/api/import-rbxm": SerializationHandlers.importRbxm,

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

@@ -57,21 +57,47 @@ function dropOldestUntilFits(incomingBytes: number): void {
 	}
 }
 
+function pushEntry(msg: string, t: Enum.MessageType, ts = nowSec()): void {
+	const bytes = msg.size();
+	dropOldestUntilFits(bytes);
+	entries.push({
+		seq: nextSeq,
+		ts,
+		level: levelTag(t),
+		message: msg,
+	});
+	nextSeq += 1;
+	totalBytes += bytes;
+}
+
+interface LogHistoryEntry {
+	message: string;
+	messageType: Enum.MessageType;
+	timestamp: number;
+}
+
+function seedRuntimeHistory(): void {
+	if (!RunService.IsRunning()) return;
+
+	const [ok, history] = pcall(() => LogService.GetLogHistory() as LogHistoryEntry[]);
+	if (!ok) return;
+
+	for (const entry of history) {
+		if (!typeIs(entry.message, "string")) continue;
+		pushEntry(entry.message, entry.messageType, typeIs(entry.timestamp, "number") ? entry.timestamp : undefined);
+	}
+}
+
 function install(): void {
 	if (installed) return;
 	if (!RunService.IsStudio()) return;
 	installed = true;
+	// Play peers can emit startup logs before the plugin finishes loading.
+	// Seed from per-DataModel LogHistory so get_runtime_logs can still see
+	// those early messages; skip edit mode to avoid stale prior-session logs.
+	seedRuntimeHistory();
 	LogService.MessageOut.Connect((msg, t) => {
-		const bytes = msg.size();
-		dropOldestUntilFits(bytes);
-		entries.push({
-			seq: nextSeq,
-			ts: nowSec(),
-			level: levelTag(t),
-			message: msg,
-		});
-		nextSeq += 1;
-		totalBytes += bytes;
+		pushEntry(msg, t);
 	});
 }
 

package/studio-plugin/src/modules/handlers/BreakpointHandlers.ts

@@ -0,0 +1,460 @@
+import Utils from "../Utils";
+
+const { getInstanceByPath } = Utils;
+
+const HttpService = game.GetService("HttpService");
+const RunService = game.GetService("RunService");
+const ServerStorage = game.GetService("ServerStorage");
+
+const LOG_PREFIX = "Breakpoint";
+const REGISTRY_KEY_PREFIX = "MCP_BREAKPOINTS_V1_";
+const MCP_PLACE_ID_ATTRIBUTE = "__MCPPlaceId";
+
+let pluginRef: Plugin | undefined;
+let loadedRegistryKey: string | undefined;
+let loadedRegistryFromSettings = false;
+
+interface ScriptBreakpointSpec {
+	Line: number;
+	Enabled?: boolean;
+	Condition?: string;
+	LogMessage?: string;
+	ContinueExecution?: boolean;
+}
+
+interface ScriptBreakpointResult {
+	Verified?: boolean;
+	Line?: number;
+	Message?: string;
+}
+
+interface ScriptDebuggerServiceLike extends Instance {
+	AddBreakpoint(this: ScriptDebuggerServiceLike, script: Instance, breakpoint: ScriptBreakpointSpec): ScriptBreakpointResult;
+	RemoveBreakpoint(this: ScriptDebuggerServiceLike, script: Instance, line: number): boolean;
+	ClearBreakpoints(this: ScriptDebuggerServiceLike): void;
+}
+
+interface BreakpointEntry {
+	script_path: string;
+	line: number;
+	requested_line?: number;
+	enabled?: boolean;
+	condition?: string;
+	log_message?: string;
+	continue_execution?: boolean;
+	verified?: false;
+	message?: string;
+	created_at?: number;
+}
+
+interface PersistedBreakpointEntry {
+	script_path: string;
+	line: number;
+}
+
+interface RegistryScope {
+	key: string;
+}
+
+const breakpoints = new Map<string, BreakpointEntry>();
+
+function init(p: Plugin): void {
+	pluginRef = p;
+}
+
+function breakpointKey(scriptPath: string, line: number): string {
+	return `${scriptPath}:${line}`;
+}
+
+function computeInstanceId(): string {
+	if (game.PlaceId !== 0) {
+		return `place:${tostring(game.PlaceId)}`;
+	}
+	const existing = ServerStorage.GetAttribute(MCP_PLACE_ID_ATTRIBUTE);
+	if (typeIs(existing, "string") && existing !== "") {
+		return `anon:${existing as string}`;
+	}
+	const fresh = HttpService.GenerateGUID(false);
+	pcall(() => ServerStorage.SetAttribute(MCP_PLACE_ID_ATTRIBUTE, fresh));
+	return `anon:${fresh}`;
+}
+
+function detectRole(): string {
+	if (!RunService.IsRunning()) return "edit";
+	if (RunService.IsServer()) return "server";
+	return "client";
+}
+
+function requestedRole(requestData: Record<string, unknown>): string {
+	return typeIs(requestData.__mcp_target_role, "string") && requestData.__mcp_target_role !== ""
+		? requestData.__mcp_target_role as string
+		: detectRole();
+}
+
+function registryScope(requestData: Record<string, unknown>): RegistryScope {
+	const instanceId = typeIs(requestData.__mcp_instance_id, "string") && requestData.__mcp_instance_id !== ""
+		? requestData.__mcp_instance_id as string
+		: computeInstanceId();
+	const role = requestedRole(requestData);
+	return {
+		key: `${REGISTRY_KEY_PREFIX}${instanceId}:${role}`,
+	};
+}
+
+function readSetting(key: string): unknown {
+	if (!pluginRef) return undefined;
+	const [ok, value] = pcall(() => pluginRef!.GetSetting(key));
+	return ok ? value : undefined;
+}
+
+function writeSetting(key: string, value: unknown): boolean {
+	if (!pluginRef) return false;
+	const [ok] = pcall(() => pluginRef!.SetSetting(key, value));
+	return ok;
+}
+
+function decodePersistedBreakpointEntry(value: unknown): BreakpointEntry | undefined {
+	if (!typeIs(value, "table")) return undefined;
+	const data = value as Record<string, unknown>;
+	if (!typeIs(data.script_path, "string") || data.script_path === "") return undefined;
+	if (!typeIs(data.line, "number") || data.line < 1) return undefined;
+
+	return {
+		script_path: data.script_path as string,
+		line: math.floor(data.line as number),
+	};
+}
+
+function loadRegistry(requestData: Record<string, unknown>): RegistryScope {
+	const scope = registryScope(requestData);
+	if (loadedRegistryKey !== scope.key) {
+		breakpoints.clear();
+		loadedRegistryKey = scope.key;
+		loadedRegistryFromSettings = false;
+	}
+
+	if (loadedRegistryFromSettings) return scope;
+	loadedRegistryFromSettings = true;
+
+	const stored = readSetting(scope.key);
+	if (stored === undefined) return scope;
+
+	let decoded: unknown = stored;
+	if (typeIs(stored, "string")) {
+		const [ok, result] = pcall(() => HttpService.JSONDecode(stored as string));
+		if (!ok) return scope;
+		decoded = result;
+	}
+	if (!typeIs(decoded, "table")) return scope;
+
+	breakpoints.clear();
+	for (const item of decoded as unknown[]) {
+		const entry = decodePersistedBreakpointEntry(item);
+		if (entry) {
+			breakpoints.set(breakpointKey(entry.script_path, entry.line), entry);
+		}
+	}
+	return scope;
+}
+
+interface PersistResult {
+	ok: boolean;
+	error?: string;
+}
+
+function persistRegistry(scope: RegistryScope): PersistResult {
+	if (!pluginRef) return { ok: false, error: "Plugin settings are unavailable; managed breakpoint registry is memory-only." };
+
+	const out: PersistedBreakpointEntry[] = [];
+	for (const [, entry] of breakpoints) {
+		out.push({
+			script_path: entry.script_path,
+			line: entry.line,
+		});
+	}
+
+	const [encodedOk, encoded] = pcall(() => HttpService.JSONEncode(out));
+	if (!encodedOk || !typeIs(encoded, "string")) {
+		return { ok: false, error: `Failed to encode managed breakpoint registry: ${tostring(encoded)}` };
+	}
+	if (!writeSetting(scope.key, encoded)) {
+		return { ok: false, error: "Failed to persist managed breakpoint registry with plugin:SetSetting." };
+	}
+	const stored = readSetting(scope.key);
+	if (stored !== encoded) {
+		return { ok: false, error: "Failed to verify managed breakpoint registry persistence after plugin:SetSetting." };
+	}
+	return { ok: true };
+}
+
+function attachPersistenceWarning(response: Record<string, unknown>, persist: PersistResult): Record<string, unknown> {
+	if (!persist.ok) {
+		response.managed_registry_persisted = false;
+		response.registry_error = persist.error;
+	}
+	return response;
+}
+
+function serviceError(message?: string): Record<string, unknown> {
+	return {
+		error: "script_debugger_unavailable",
+		message: message ?? "ScriptDebuggerService is unavailable. Enable the Studio Debugger Luau API beta feature and restart Studio.",
+		betaFeatureRequired: true,
+	};
+}
+
+function operationError(errorCode: string, operation: string, raw: unknown): Record<string, unknown> {
+	return {
+		error: errorCode,
+		message:
+			`${operation} failed. The breakpoints tool requires the Studio Debugger Luau API beta feature. ` +
+			"Enable it in Studio Beta Features and restart/reload Studio, then retry.",
+		rawMessage: tostring(raw),
+		betaFeatureRequired: true,
+	};
+}
+
+function getService(): ScriptDebuggerServiceLike | Record<string, unknown> {
+	const provider = game as unknown as { GetService(serviceName: string): Instance };
+	const [ok, service] = pcall(() => provider.GetService("ScriptDebuggerService") as ScriptDebuggerServiceLike);
+	if (!ok || !service) {
+		return serviceError(`ScriptDebuggerService unavailable: ${tostring(service)}`);
+	}
+	return service;
+}
+
+function luauStringLiteral(value: string): string {
+	let escaped = value.gsub("\\", "\\\\")[0];
+	escaped = escaped.gsub("\n", "\\n")[0];
+	escaped = escaped.gsub("\r", "\\r")[0];
+	escaped = escaped.gsub("\t", "\\t")[0];
+	escaped = escaped.gsub('"', '\\"')[0];
+	return `"${escaped}"`;
+}
+
+function buildLogMessage(scriptPath: string, line: number, logMessage: string | undefined): string {
+	const prefix = [
+		luauStringLiteral(LOG_PREFIX),
+		luauStringLiteral(`${scriptPath}:${line}`),
+	];
+	if (typeIs(logMessage, "string") && logMessage !== "") {
+		prefix.push(logMessage);
+	}
+	return prefix.join(", ");
+}
+
+function listBreakpoints(requestData: Record<string, unknown>): Record<string, unknown> {
+	loadRegistry(requestData);
+	const out: BreakpointEntry[] = [];
+	for (const [, entry] of breakpoints) {
+		out.push(entry);
+	}
+	return {
+		breakpoints: out,
+		count: out.size(),
+	};
+}
+
+function setBreakpoint(requestData: Record<string, unknown>): unknown {
+	const scope = loadRegistry(requestData);
+	const serviceOrError = getService();
+	if (!serviceOrError.IsA) return serviceOrError;
+	const service = serviceOrError as ScriptDebuggerServiceLike;
+
+	const scriptPath = requestData.script_path as string | undefined;
+	const lineRaw = requestData.line as number | undefined;
+	if (!typeIs(scriptPath, "string") || scriptPath === "" || !typeIs(lineRaw, "number")) {
+		return { error: "invalid_args", message: "breakpoints action=set requires script_path and line" };
+	}
+
+	const requestedLine = math.floor(lineRaw);
+	if (requestedLine < 1) {
+		return { error: "invalid_line", message: "line must be a 1-based positive number" };
+	}
+
+	const instance = getInstanceByPath(scriptPath);
+	if (!instance) return { error: "script_not_found", script_path: scriptPath };
+	if (!instance.IsA("LuaSourceContainer")) {
+		return {
+			error: "not_a_script",
+			message: `${scriptPath} is ${instance.ClassName}, not a LuaSourceContainer`,
+			script_path: scriptPath,
+		};
+	}
+
+	const rawLogMessage = typeIs(requestData.log_message, "string") ? requestData.log_message as string : undefined;
+	const hasLogMessage = rawLogMessage !== undefined && rawLogMessage !== "";
+	const continueExecution = typeIs(requestData.continue_execution, "boolean")
+		? requestData.continue_execution as boolean
+		: hasLogMessage;
+	const enabled = typeIs(requestData.enabled, "boolean") ? requestData.enabled as boolean : true;
+	const effectiveLogMessage = hasLogMessage || continueExecution ? buildLogMessage(scriptPath, requestedLine, rawLogMessage) : undefined;
+
+	const spec: ScriptBreakpointSpec = {
+		Line: requestedLine,
+		Enabled: enabled,
+		ContinueExecution: continueExecution,
+	};
+	if (typeIs(requestData.condition, "string") && requestData.condition !== "") {
+		spec.Condition = requestData.condition as string;
+	}
+	if (effectiveLogMessage !== undefined) {
+		spec.LogMessage = effectiveLogMessage;
+	}
+
+	const [ok, result] = pcall(() => service.AddBreakpoint(instance, spec));
+	if (!ok) return operationError("add_breakpoint_failed", "ScriptDebuggerService:AddBreakpoint", result);
+
+	const breakpointResult = result as ScriptBreakpointResult;
+	const actualLine = typeIs(breakpointResult.Line, "number") ? breakpointResult.Line : requestedLine;
+	const verified = typeIs(breakpointResult.Verified, "boolean") ? breakpointResult.Verified : undefined;
+	const message = typeIs(breakpointResult.Message, "string") ? breakpointResult.Message : undefined;
+	const entry: BreakpointEntry = {
+		script_path: scriptPath,
+		line: actualLine,
+		requested_line: actualLine !== requestedLine ? requestedLine : undefined,
+		enabled,
+		condition: spec.Condition,
+		log_message: rawLogMessage,
+		continue_execution: continueExecution,
+		verified: verified === false ? false : undefined,
+		message,
+		created_at: DateTime.now().UnixTimestampMillis,
+	};
+
+	breakpoints.set(breakpointKey(scriptPath, actualLine), entry);
+	return attachPersistenceWarning({
+		ok: true,
+		breakpoint: entry,
+	}, persistRegistry(scope));
+}
+
+function removeBreakpoint(requestData: Record<string, unknown>): unknown {
+	const scope = loadRegistry(requestData);
+	const serviceOrError = getService();
+	if (!serviceOrError.IsA) return serviceOrError;
+	const service = serviceOrError as ScriptDebuggerServiceLike;
+
+	const scriptPath = requestData.script_path as string | undefined;
+	const lineRaw = requestData.line as number | undefined;
+	if (!typeIs(scriptPath, "string") || scriptPath === "" || !typeIs(lineRaw, "number")) {
+		return { error: "invalid_args", message: "breakpoints action=remove requires script_path and line" };
+	}
+	const line = math.floor(lineRaw);
+	if (line < 1) {
+		return { error: "invalid_line", message: "line must be a 1-based positive number" };
+	}
+
+	const instance = getInstanceByPath(scriptPath);
+	if (!instance) return { error: "script_not_found", script_path: scriptPath };
+	if (!instance.IsA("LuaSourceContainer")) {
+		return {
+			error: "not_a_script",
+			message: `${scriptPath} is ${instance.ClassName}, not a LuaSourceContainer`,
+			script_path: scriptPath,
+		};
+	}
+
+	const [ok, removed] = pcall(() => service.RemoveBreakpoint(instance, line));
+	if (!ok) return operationError("remove_breakpoint_failed", "ScriptDebuggerService:RemoveBreakpoint", removed);
+
+	breakpoints.delete(breakpointKey(scriptPath, line));
+	return attachPersistenceWarning({
+		ok: true,
+		removed,
+		script_path: scriptPath,
+		line,
+	}, persistRegistry(scope));
+}
+
+function clearManagedBreakpoints(requestData: Record<string, unknown>): unknown {
+	const scope = loadRegistry(requestData);
+	const serviceOrError = getService();
+	if (!serviceOrError.IsA) return serviceOrError;
+	const service = serviceOrError as ScriptDebuggerServiceLike;
+
+	let cleared = 0;
+	const errors: Record<string, unknown>[] = [];
+
+	for (const [key, entry] of breakpoints) {
+		const instance = getInstanceByPath(entry.script_path);
+		if (!instance || !instance.IsA("LuaSourceContainer")) {
+			breakpoints.delete(key);
+			cleared += 1;
+			continue;
+		}
+
+		const [ok, removedOrError] = pcall(() => service.RemoveBreakpoint(instance, entry.line));
+		if (ok) {
+			breakpoints.delete(key);
+			cleared += 1;
+		} else {
+			errors.push({
+				script_path: entry.script_path,
+				line: entry.line,
+				error: tostring(removedOrError),
+			});
+		}
+	}
+
+	if (errors.size() > 0) {
+		return {
+			ok: false,
+			cleared,
+			errors,
+		};
+	}
+
+	return attachPersistenceWarning({
+		ok: true,
+		cleared,
+	}, persistRegistry(scope));
+}
+
+function clearAllBreakpoints(requestData: Record<string, unknown>): unknown {
+	const scope = loadRegistry(requestData);
+	const serviceOrError = getService();
+	if (!serviceOrError.IsA) return serviceOrError;
+	const service = serviceOrError as ScriptDebuggerServiceLike;
+
+	const managedCount = breakpoints.size();
+	const [ok, err] = pcall(() => service.ClearBreakpoints());
+	if (!ok) return operationError("clear_breakpoints_failed", "ScriptDebuggerService:ClearBreakpoints", err);
+	breakpoints.clear();
+	return attachPersistenceWarning({
+		ok: true,
+		cleared_managed: managedCount,
+	}, persistRegistry(scope));
+}
+
+function clearBreakpoints(requestData: Record<string, unknown>): unknown {
+	if (requestData.clear_all === true) {
+		return clearAllBreakpoints(requestData);
+	}
+	return clearManagedBreakpoints(requestData);
+}
+
+function breakpointsTool(requestData: Record<string, unknown>): unknown {
+	const action = requestData.action as string | undefined;
+	if (!typeIs(action, "string") || action === "") {
+		return { error: "invalid_args", message: "breakpoints requires action=set|remove|clear|list" };
+	}
+
+	switch (action) {
+		case "set":
+			return setBreakpoint(requestData);
+		case "remove":
+			return removeBreakpoint(requestData);
+		case "clear":
+			return clearBreakpoints(requestData);
+		case "list":
+			return listBreakpoints(requestData);
+		default:
+			return {
+				error: "unknown_action",
+				message: `breakpoints action must be one of: set, remove, clear, list (got ${action})`,
+			};
+	}
+}
+
+export = { breakpoints: breakpointsTool, init };

package/studio-plugin/src/modules/handlers/QueryHandlers.ts

@@ -792,38 +792,6 @@ function compareInstances(requestData: Record<string, unknown>) {
 	};
 }
 
-function getOutputLog(requestData: Record<string, unknown>) {
-	const maxEntries = (requestData.maxEntries as number) ?? 100;
-	const messageTypeFilter = requestData.messageType as string | undefined;
-
-	const [success, result] = pcall(() => {
-		const LogService = game.GetService("LogService");
-		const history = LogService.GetLogHistory();
-		const allEntries: Record<string, unknown>[] = [];
-
-		for (const entry of history) {
-			const msgType = tostring(entry.messageType);
-			if (messageTypeFilter && msgType !== messageTypeFilter) continue;
-			allEntries.push({
-				message: entry.message,
-				messageType: msgType,
-				timestamp: entry.timestamp,
-			});
-		}
-
-		const startIdx = math.max(0, allEntries.size() - maxEntries);
-		const finalEntries: Record<string, unknown>[] = [];
-		for (let i = startIdx; i < allEntries.size(); i++) {
-			finalEntries.push(allEntries[i]);
-		}
-
-		return { entries: finalEntries, count: finalEntries.size(), totalAvailable: allEntries.size() };
-	});
-
-	if (success) return result;
-	return { error: `Failed to get output log: ${result}` };
-}
-
 export = {
 	getFileTree,
 	searchFiles,
@@ -838,5 +806,4 @@ export = {
 	grepScripts,
 	getDescendants,
 	compareInstances,
-	getOutputLog,
 };