@chrrxs/robloxstudio-mcp 2.9.1 → 2.10.0

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

@@ -1,4 +1,5 @@
 import { HttpService, Players, ReplicatedStorage, RunService } from "@rbxts/services";
+import RuntimeLogBuffer from "./RuntimeLogBuffer";
 
 // The client peer cannot reach the MCP HTTP server - Roblox forbids
 // HttpService:RequestAsync from the client DM even under PluginSecurity, and
@@ -22,7 +23,12 @@ interface ProxyEntry {
 	role: string;
 }
 
-interface ExecutePayload {
+interface BrokerEnvelope {
+	endpoint?: string;
+	data?: Record<string, unknown>;
+	// Backward-compat: older server-broker code (pre-v2.10) sent the raw
+	// {code} payload directly. If we see code at the top level and no
+	// endpoint, treat it as execute-luau.
 	code?: string;
 }
 
@@ -33,6 +39,14 @@ interface ExecuteResult {
 	error?: string;
 }
 
+// Endpoints the server-peer broker is allowed to forward to the client peer.
+// Each requires the client peer's plugin VM (because the buffer / require
+// cache / etc. lives there) so the server peer alone can't satisfy them.
+const CLIENT_BROKER_ALLOWED_ENDPOINTS = new Set<string>([
+	"/api/execute-luau",
+	"/api/get-runtime-logs",
+]);
+
 interface ReadyResponseBody {
 	assignedRole?: string;
 }
@@ -43,6 +57,22 @@ interface PollResponseBody {
 		endpoint: string;
 		data?: Record<string, unknown>;
 	};
+	// Server signals knownInstance=false when our proxy isn't in its
+	// in-memory instances map (typically after an MCP process restart).
+	// Triggers a re-register POST to /ready.
+	knownInstance?: boolean;
+}
+
+// Throttle re-ready calls per proxyId so a brief window of unknownInstance
+// polls doesn't cause a re-register stampede.
+const lastReadyByProxy = new Map<string, number>();
+
+function reRegisterProxy(proxyId: string, role: string): void {
+	const now = tick();
+	const last = lastReadyByProxy.get(proxyId) ?? 0;
+	if (now - last < 2) return;
+	lastReadyByProxy.set(proxyId, now);
+	pcall(() => postJson("/ready", { instanceId: proxyId, role }));
 }
 
 function forkRole(): "edit" | "server" | "client" {
@@ -62,37 +92,64 @@ function postJson(endpoint: string, body: Record<string, unknown>) {
 	);
 }
 
+function handleExecuteLuau(data: Record<string, unknown> | undefined): ExecuteResult {
+	const code = data && (data.code as string | undefined);
+	if (typeIs(code, "string") === false || code === "") {
+		return { success: false, error: "code is required" };
+	}
+	const m = new Instance("ModuleScript");
+	m.Name = "__MCPClientEval";
+	const [okSet, setErr] = pcall(() => {
+		(m as unknown as { Source: string }).Source = code as string;
+	});
+	if (!okSet) {
+		m.Destroy();
+		return { success: false, error: `Source set failed: ${tostring(setErr)}` };
+	}
+	m.Parent = game.Workspace;
+	const [okReq, result] = pcall(() => require(m));
+	m.Destroy();
+	if (okReq) {
+		return {
+			success: true,
+			returnValue: result !== undefined ? tostring(result) : undefined,
+			message: "Code executed successfully",
+		};
+	}
+	return { success: false, error: tostring(result) };
+}
+
+function handleGetRuntimeLogs(data: Record<string, unknown> | undefined): unknown {
+	const d = data ?? {};
+	const since = d.since as number | undefined;
+	const tail = d.tail as number | undefined;
+	const filter = d.filter as string | undefined;
+	// "client" is the generic peer tag; MCP-side aggregator overrides with
+	// the specific role (e.g. "client-1") on target=all fan-out.
+	return RuntimeLogBuffer.query({ since, tail, filter }, "client");
+}
+
 function setupClientBroker() {
 	const rf = ReplicatedStorage.WaitForChild(BROKER_NAME, 10);
 	if (!rf || !rf.IsA("RemoteFunction")) {
 		warn(`[MCPFork] client: ${BROKER_NAME} not found`);
 		return;
 	}
-	rf.OnClientInvoke = (payload: ExecutePayload | undefined) => {
-		const code = payload && payload.code;
-		if (typeIs(code, "string") === false || code === "") {
-			return identity<ExecuteResult>({ success: false, error: "code is required" });
+	rf.OnClientInvoke = (payload: BrokerEnvelope | undefined) => {
+		// Two payload shapes in the wild:
+		// - {endpoint, data} from v2.10+ server-peer broker (this is the new
+		//   discriminated form that lets us dispatch on endpoint)
+		// - {code} from pre-v2.10 server-peer broker (raw execute-luau payload)
+		// The shapes coexist gracefully because we fall back to execute-luau
+		// when endpoint is missing.
+		if (payload && payload.endpoint === "/api/get-runtime-logs") {
+			return handleGetRuntimeLogs(payload.data);
 		}
-		const m = new Instance("ModuleScript");
-		m.Name = "__MCPClientEval";
-		const [okSet, setErr] = pcall(() => {
-			(m as unknown as { Source: string }).Source = code as string;
-		});
-		if (!okSet) {
-			m.Destroy();
-			return identity<ExecuteResult>({ success: false, error: `Source set failed: ${tostring(setErr)}` });
-		}
-		m.Parent = game.Workspace;
-		const [okReq, result] = pcall(() => require(m));
-		m.Destroy();
-		if (okReq) {
-			return identity<ExecuteResult>({
-				success: true,
-				returnValue: result !== undefined ? tostring(result) : undefined,
-				message: "Code executed successfully",
-			});
+		if (payload && payload.endpoint === "/api/execute-luau") {
+			return handleExecuteLuau(payload.data);
 		}
-		return identity<ExecuteResult>({ success: false, error: tostring(result) });
+		// Legacy: raw execute-luau payload at the top level.
+		return handleExecuteLuau(payload as Record<string, unknown> | undefined);
 	};
 }
 
@@ -109,20 +166,34 @@ function pollProxy(proxyId: string, player: Player, rf: RemoteFunction) {
 		);
 		if (ok && res && (res.Success || res.StatusCode === 503)) {
 			const [okJson, body] = pcall(() => HttpService.JSONDecode(res.Body) as PollResponseBody);
-			if (okJson && body && body.request && body.requestId !== undefined) {
-				const request = body.request;
-				let response: unknown;
-				if (request.endpoint === "/api/execute-luau") {
-					const [okInvoke, invokeRes] = pcall(() => rf.InvokeClient(player, request.data));
-					if (okInvoke) {
-						response = invokeRes !== undefined ? invokeRes : { success: false, error: "nil response" };
+			if (okJson && body) {
+				// Server lost our proxy registration (process restart, etc.) -
+				// re-register so the next poll cycle starts routing again.
+				if (body.knownInstance === false) {
+					reRegisterProxy(proxyId, "client");
+				}
+				if (body.request && body.requestId !== undefined) {
+					const request = body.request;
+					let response: unknown;
+					if (CLIENT_BROKER_ALLOWED_ENDPOINTS.has(request.endpoint)) {
+						// Forward as a discriminated envelope so the client-side
+						// OnClientInvoke knows which endpoint it's serving.
+						const envelope = { endpoint: request.endpoint, data: request.data };
+						const [okInvoke, invokeRes] = pcall(() => rf.InvokeClient(player, envelope));
+						if (okInvoke) {
+							response = invokeRes !== undefined ? invokeRes : { success: false, error: "nil response" };
+						} else {
+							response = { success: false, error: `InvokeClient failed: ${tostring(invokeRes)}` };
+						}
 					} else {
-						response = { success: false, error: `InvokeClient failed: ${tostring(invokeRes)}` };
+						response = {
+							error:
+								`Client-proxy does not forward ${tostring(request.endpoint)}. ` +
+								`Allowed: /api/execute-luau, /api/get-runtime-logs.`,
+						};
 					}
-				} else {
-					response = { error: `Client-proxy only supports /api/execute-luau, got: ${tostring(request.endpoint)}` };
+					postJson("/response", { requestId: body.requestId, response });
 				}
-				postJson("/response", { requestId: body.requestId, response });
 			}
 		}
 		task.wait(0.5);
@@ -161,19 +232,25 @@ function startEditProxyLoop() {
 			);
 			if (okPoll && pollRes && (pollRes.Success || pollRes.StatusCode === 503)) {
 				const [okJson, body] = pcall(() => HttpService.JSONDecode(pollRes.Body) as PollResponseBody);
-				if (
-					okJson &&
-					body &&
-					body.request &&
-					body.request.endpoint === "/api/stop-playtest" &&
-					body.requestId !== undefined
-				) {
-					const sts = game.GetService("StudioTestService") as Instance & { EndTest(reason: string): void };
-					const [endOk, endErr] = pcall(() => sts.EndTest("stopped_by_mcp"));
-					const response = endOk
-						? { success: true, message: "Playtest stopped via edit-proxy/EndTest" }
-						: { success: false, error: `EndTest failed: ${tostring(endErr)}` };
-					postJson("/response", { requestId: body.requestId, response });
+				if (okJson && body) {
+					// Re-register if the server lost our edit-proxy registration.
+					if (body.knownInstance === false) {
+						reRegisterProxy(proxyId, "edit-proxy");
+					}
+					if (
+						body.request &&
+						body.request.endpoint === "/api/stop-playtest" &&
+						body.requestId !== undefined
+					) {
+						const sts = game.GetService("StudioTestService") as Instance & {
+							EndTest(reason: string): void;
+						};
+						const [endOk, endErr] = pcall(() => sts.EndTest("stopped_by_mcp"));
+						const response = endOk
+							? { success: true, message: "Playtest stopped via edit-proxy/EndTest" }
+							: { success: false, error: `EndTest failed: ${tostring(endErr)}` };
+						postJson("/response", { requestId: body.requestId, response });
+					}
 				}
 			}
 			task.wait(0.15);

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

@@ -12,6 +12,7 @@ import BuildHandlers from "./handlers/BuildHandlers";
 import AssetHandlers from "./handlers/AssetHandlers";
 import CaptureHandlers from "./handlers/CaptureHandlers";
 import InputHandlers from "./handlers/InputHandlers";
+import LogHandlers from "./handlers/LogHandlers";
 import { Connection, RequestPayload, PollResponse, ReadyResponse } from "../types";
 
 const instanceId = HttpService.GenerateGUID(false);
@@ -92,6 +93,8 @@ const routeMap: Record<string, Handler> = {
 	"/api/simulate-keyboard-input": InputHandlers.simulateKeyboardInput,
 
 	"/api/find-and-replace-in-scripts": ScriptHandlers.findAndReplaceInScripts,
+
+	"/api/get-runtime-logs": LogHandlers.getRuntimeLogs,
 };
 
 function processRequest(request: RequestPayload): unknown {
@@ -125,6 +128,40 @@ function getConnectionStatus(connIndex: number): string {
 	return "connecting";
 }
 
+// Throttle for re-issuing /ready after the server reports knownInstance=false.
+// Without this, every poll during the brief window where the server has just
+// restarted but hasn't seen our re-ready yet would fire a duplicate /ready.
+let lastReadyPostAt = 0;
+
+function sendReady(conn: Connection): void {
+	const now = tick();
+	if (now - lastReadyPostAt < 2) return; // throttle to ≤1 /ready every 2s
+	lastReadyPostAt = now;
+	task.spawn(() => {
+		const [readyOk, readyResult] = pcall(() => {
+			return HttpService.RequestAsync({
+				Url: `${conn.serverUrl}/ready`,
+				Method: "POST",
+				Headers: { "Content-Type": "application/json" },
+				Body: HttpService.JSONEncode({
+					instanceId,
+					role: detectRole(),
+					pluginReady: true,
+					timestamp: tick(),
+				}),
+			});
+		});
+		if (readyOk && readyResult.Success) {
+			const [parseOk, readyData] = pcall(
+				() => HttpService.JSONDecode(readyResult.Body) as ReadyResponse,
+			);
+			if (parseOk && readyData.assignedRole) {
+				assignedRole = readyData.assignedRole;
+			}
+		}
+	});
+}
+
 function pollForRequests(connIndex: number) {
 	const conn = State.getConnection(connIndex);
 	if (!conn || !conn.isActive) return;
@@ -155,6 +192,15 @@ function pollForRequests(connIndex: number) {
 		conn.lastHttpOk = true;
 		conn.lastMcpOk = mcpConnected;
 
+		// Server tells us when its in-memory instances map doesn't have us
+		// (e.g. after an MCP process restart). Re-issue /ready immediately so
+		// target=server/client-N start routing again. The throttle inside
+		// sendReady() prevents duplicate registrations while the server
+		// catches up.
+		if (data.knownInstance === false) {
+			sendReady(conn);
+		}
+
 		if (connIndex === State.getActiveTabIndex()) {
 			const el = ui;
 			el.step1Dot.BackgroundColor3 = Color3.fromRGB(34, 197, 94);
@@ -298,33 +344,20 @@ function activatePlugin(connIndex?: number) {
 	}
 	UI.updateTabDot(idx);
 
-	task.spawn(() => {
-		if (!conn.heartbeatConnection) {
-			conn.heartbeatConnection = RunService.Heartbeat.Connect(() => {
-				const now = tick();
-				const currentInterval = conn.consecutiveFailures > 5 ? conn.currentRetryDelay : conn.pollInterval;
-				if (now - conn.lastPoll > currentInterval) {
-					conn.lastPoll = now;
-					pollForRequests(idx);
-				}
-			});
-		}
-
-		const [readyOk, readyResult] = pcall(() => {
-			return HttpService.RequestAsync({
-				Url: `${conn.serverUrl}/ready`,
-				Method: "POST",
-				Headers: { "Content-Type": "application/json" },
-				Body: HttpService.JSONEncode({ instanceId, role: detectRole(), pluginReady: true, timestamp: tick() }),
-			});
-		});
-		if (readyOk && readyResult.Success) {
-			const [parseOk, readyData] = pcall(() => HttpService.JSONDecode(readyResult.Body) as ReadyResponse);
-			if (parseOk && readyData.assignedRole) {
-				assignedRole = readyData.assignedRole;
+	if (!conn.heartbeatConnection) {
+		conn.heartbeatConnection = RunService.Heartbeat.Connect(() => {
+			const now = tick();
+			const currentInterval = conn.consecutiveFailures > 5 ? conn.currentRetryDelay : conn.pollInterval;
+			if (now - conn.lastPoll > currentInterval) {
+				conn.lastPoll = now;
+				pollForRequests(idx);
 			}
-		}
-	});
+		});
+	}
+
+	// Initial /ready; pollForRequests will also re-fire ready if the server
+	// later reports knownInstance=false (process restart, etc).
+	sendReady(conn);
 }
 
 function deactivatePlugin(connIndex?: number) {

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

@@ -0,0 +1,138 @@
+// Per-peer in-memory ring buffer for LogService.MessageOut events.
+// Powers the get_runtime_logs MCP tool. Replaces the out-of-tree LogBuffer
+// primitives + StringValue approach from chrrxs/roblox-mcp-primitives.
+//
+// Each peer's plugin attaches a MessageOut listener at plugin load (edit DM,
+// play-server DM, play-client DM all run their own copy of this module).
+// Captured entries live in plugin module-state; nothing is parented to the
+// DataModel. The buffer is bounded by a message-byte budget; oldest entries
+// drop when over budget.
+//
+// Peer-tag caveat: returned entries reflect which peer's plugin CAPTURED the
+// entry, NOT which peer's script originated the print. LogService reflects
+// prints across peers in Studio Play (a server print ends up in both the
+// server and client LogService:GetLogHistory()) and origin is empirically
+// undetectable from inside MessageOut. The MCP-side aggregator handles
+// cross-peer dedup via a 2s timestamp window.
+
+import { LogService, RunService } from "@rbxts/services";
+
+type LogLevel = "OUT" | "WARN" | "ERR" | "INFO";
+
+interface RuntimeLogEntry {
+	seq: number;
+	ts: number; // wall-clock seconds via DateTime, coherent across peers
+	level: LogLevel;
+	message: string;
+}
+
+const MAX_BYTES = 64 * 1024;
+const HARD_ENTRY_CAP = 50_000;
+
+const entries: RuntimeLogEntry[] = [];
+let totalBytes = 0;
+let totalDropped = 0;
+let nextSeq = 1;
+let installed = false;
+
+function levelTag(t: Enum.MessageType): LogLevel {
+	if (t === Enum.MessageType.MessageWarning) return "WARN";
+	if (t === Enum.MessageType.MessageError) return "ERR";
+	if (t === Enum.MessageType.MessageInfo) return "INFO";
+	return "OUT";
+}
+
+function nowSec(): number {
+	return DateTime.now().UnixTimestampMillis / 1000;
+}
+
+function dropOldestUntilFits(incomingBytes: number): void {
+	while (
+		entries.size() > 0 &&
+		(totalBytes + incomingBytes > MAX_BYTES || entries.size() >= HARD_ENTRY_CAP)
+	) {
+		const dropped = entries.shift()!;
+		totalBytes -= dropped.message.size();
+		totalDropped += 1;
+	}
+}
+
+function install(): void {
+	if (installed) return;
+	if (!RunService.IsStudio()) return;
+	installed = true;
+	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;
+	});
+}
+
+function detectPeer(): "edit" | "server" | "client" {
+	if (!RunService.IsRunning()) return "edit";
+	if (RunService.IsServer()) return "server";
+	return "client";
+}
+
+interface QueryOptions {
+	since?: number;
+	tail?: number;
+	filter?: string; // Plain substring match, applied to message
+}
+
+interface QueryResult {
+	peer: string;
+	entries: RuntimeLogEntry[];
+	totalDropped: number;
+	nextSince: number;
+}
+
+function query(opts: QueryOptions, peer: string): QueryResult {
+	let result = opts.since !== undefined
+		? entries.filter((e) => e.seq > (opts.since as number))
+		: [...entries];
+
+	if (opts.filter !== undefined) {
+		// Plain substring search (4th arg = true). Pattern matching here was
+		// surprising in practice - Lua magic chars in messages would silently
+		// not match (e.g. filter="MARK-EDIT" against "MARK-EDIT-001" fails
+		// because '-' means "0+" in Lua patterns). Substring search matches
+		// most users' mental model of "filter messages containing this text".
+		const needle = opts.filter;
+		result = result.filter((e) => {
+			const [start] = string.find(e.message, needle, 1, true);
+			return start !== undefined;
+		});
+	}
+
+	if (opts.tail !== undefined && result.size() > opts.tail) {
+		// roblox-ts arrays don't expose .slice; manual tail copy.
+		const tailed: RuntimeLogEntry[] = [];
+		const start = result.size() - opts.tail;
+		for (let i = start; i < result.size(); i++) {
+			tailed.push(result[i]);
+		}
+		result = tailed;
+	}
+
+	const last = entries.size() > 0 ? entries[entries.size() - 1] : undefined;
+	return {
+		peer,
+		entries: result,
+		totalDropped,
+		nextSince: last ? last.seq : (opts.since ?? 0),
+	};
+}
+
+export = {
+	install,
+	detectPeer,
+	query,
+};

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

@@ -0,0 +1,15 @@
+import RuntimeLogBuffer from "../RuntimeLogBuffer";
+
+function getRuntimeLogs(requestData: Record<string, unknown>): unknown {
+	const since = requestData.since as number | undefined;
+	const tail = requestData.tail as number | undefined;
+	const filter = requestData.filter as string | undefined;
+	// Plugin-side peer tag is generic ("edit"|"server"|"client"). The MCP-side
+	// aggregator overrides it with the specific instance role (e.g. "client-1")
+	// during fan-out for target=all, so this value is only authoritative for
+	// the single-peer query path.
+	const peer = RuntimeLogBuffer.detectPeer();
+	return RuntimeLogBuffer.query({ since, tail, filter }, peer);
+}
+
+export = { getRuntimeLogs };

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

@@ -294,8 +294,19 @@ function executeLuau(requestData: Record<string, unknown>) {
 	const runViaModuleScript = () => {
 		const m = new Instance("ModuleScript");
 		m.Name = "__MCPExecLuauPayload";
+		// Wrap user code in an IIFE so require() always gets exactly one
+		// return value. Without this, code like `print("x")` errors with
+		// "Module code did not return exactly one value" because top-level
+		// ModuleScripts must return exactly one value.
+		//
+		// The DOUBLE parens around the call are load-bearing: in Luau,
+		// `return f()` propagates whatever multi-value tuple f returns,
+		// including zero values. Outer parens adjust the call to exactly
+		// one value (the first, or nil). So `return ((f)())` always
+		// returns exactly one value, regardless of what f does.
+		const wrapped = `return ((function()\n${code}\nend)())`;
 		const [okSet, setErr] = pcall(() => {
-			(m as unknown as { Source: string }).Source = code;
+			(m as unknown as { Source: string }).Source = wrapped;
 		});
 		if (!okSet) {
 			m.Destroy();

package/studio-plugin/src/server/index.server.ts

@@ -2,7 +2,12 @@ import State from "../modules/State";
 import UI from "../modules/UI";
 import Communication from "../modules/Communication";
 import ClientBroker from "../modules/ClientBroker";
+import RuntimeLogBuffer from "../modules/RuntimeLogBuffer";
 
+// Attach the per-peer LogService.MessageOut listener as early as possible so
+// boot-time prints from the user's place scripts are captured. Powers the
+// get_runtime_logs MCP tool. Idempotent; safe to call before UI.init().
+RuntimeLogBuffer.install();
 
 UI.init(plugin);
 const elements = UI.getElements();

package/studio-plugin/src/types/index.d.ts

@@ -32,6 +32,10 @@ export interface PollResponse {
 	mcpConnected: boolean;
 	request?: RequestPayload;
 	requestId?: string;
+	// Server signals knownInstance=false when its in-memory instances map
+	// doesn't contain our instanceId (typically after an MCP process restart).
+	// The plugin re-issues /ready when it sees this.
+	knownInstance?: boolean;
 }
 
 export interface ReadyResponse {