@chrrxs/robloxstudio-mcp 2.11.4 → 2.13.0

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

@@ -1,6 +1,45 @@
-import { HttpService, Players, ReplicatedStorage, RunService } from "@rbxts/services";
+import { HttpService, Players, ReplicatedStorage, RunService, ServerStorage } from "@rbxts/services";
 import RuntimeLogBuffer from "./RuntimeLogBuffer";
 import MemoryHandlers from "./handlers/MemoryHandlers";
+import CaptureHandlers from "./handlers/CaptureHandlers";
+import InputHandlers from "./handlers/InputHandlers";
+import LuauExec from "./LuauExec";
+
+// Mirror of Communication.computeInstanceId() — duplicated here because the
+// client broker runs in the play-server DM where it can't easily import from
+// the edit-side module, and the place identifier must match what the edit-DM
+// plugin reports. Both use the same algorithm against the shared DataModel.
+function computeInstanceId(): string {
+	if (game.PlaceId !== 0) {
+		return `place:${tostring(game.PlaceId)}`;
+	}
+	const existing = ServerStorage.GetAttribute("__MCPPlaceId");
+	if (typeIs(existing, "string") && existing !== "") {
+		return `anon:${existing as string}`;
+	}
+	const fresh = HttpService.GenerateGUID(false);
+	pcall(() => ServerStorage.SetAttribute("__MCPPlaceId", fresh));
+	return `anon:${fresh}`;
+}
+
+let cachedPlaceName: string | undefined;
+function resolvePlaceName(): string {
+	if (cachedPlaceName !== undefined) return cachedPlaceName;
+	if (game.PlaceId === 0) {
+		cachedPlaceName = game.Name;
+		return cachedPlaceName;
+	}
+	const MarketplaceService = game.GetService("MarketplaceService");
+	const [ok, info] = pcall(() => MarketplaceService.GetProductInfo(game.PlaceId));
+	if (ok && info !== undefined) {
+		const name = (info as { Name?: string }).Name;
+		if (typeIs(name, "string") && name !== "") {
+			cachedPlaceName = name;
+			return cachedPlaceName;
+		}
+	}
+	return game.Name;
+}
 
 // The client peer cannot reach the MCP HTTP server - Roblox forbids
 // HttpService:RequestAsync from the client DM even under PluginSecurity, and
@@ -18,7 +57,7 @@ const MCP_URL = "http://localhost:58741";
 const BROKER_NAME = "__MCPClientBroker";
 
 interface ProxyEntry {
-	instanceId: string;
+	pluginSessionId: string;
 	role: string;
 }
 
@@ -31,12 +70,6 @@ interface BrokerEnvelope {
 	code?: string;
 }
 
-interface ExecuteResult {
-	success: boolean;
-	returnValue?: string;
-	message?: string;
-	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
@@ -45,6 +78,13 @@ const CLIENT_BROKER_ALLOWED_ENDPOINTS = new Set<string>([
 	"/api/execute-luau",
 	"/api/get-runtime-logs",
 	"/api/get-memory-breakdown",
+	// Screenshot capture must run in the client peer (CaptureService captures
+	// the play viewport there); the edit DM reads the temp id back separately.
+	"/api/capture-begin",
+	// Virtual input (CreateVirtualInput) drives the running client's input
+	// pipeline, so it must execute in the client peer's VM.
+	"/api/simulate-mouse-input",
+	"/api/simulate-keyboard-input",
 ]);
 
 interface ReadyResponseBody {
@@ -72,7 +112,17 @@ function reRegisterProxy(proxyId: string, role: string): void {
 	const last = lastReadyByProxy.get(proxyId) ?? 0;
 	if (now - last < 2) return;
 	lastReadyByProxy.set(proxyId, now);
-	pcall(() => postJson("/ready", { instanceId: proxyId, role }));
+	pcall(() =>
+		postJson("/ready", {
+			pluginSessionId: proxyId,
+			instanceId: computeInstanceId(),
+			role,
+			placeId: game.PlaceId,
+			placeName: resolvePlaceName(),
+			dataModelName: game.Name,
+			isRunning: RunService.IsRunning(),
+		}),
+	);
 }
 
 function forkRole(): "edit" | "server" | "client" {
@@ -92,31 +142,16 @@ function postJson(endpoint: string, body: Record<string, unknown>) {
 	);
 }
 
-function handleExecuteLuau(data: Record<string, unknown> | undefined): ExecuteResult {
+function handleExecuteLuau(data: Record<string, unknown> | undefined) {
 	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) };
+	// Shared with edit/server (MetadataHandlers.executeLuau). Adds the IIFE
+	// wrapper (so `print("hi")` with no return doesn't fail the
+	// ModuleScript's "must return one value" rule) and JSON-encodes table
+	// returns instead of yielding "table: 0xaddr".
+	return LuauExec.execute(code as string);
 }
 
 function handleGetRuntimeLogs(data: Record<string, unknown> | undefined): unknown {
@@ -148,6 +183,15 @@ function setupClientBroker() {
 		if (payload && payload.endpoint === "/api/get-memory-breakdown") {
 			return MemoryHandlers.getMemoryBreakdown(payload.data ?? {});
 		}
+		if (payload && payload.endpoint === "/api/capture-begin") {
+			return CaptureHandlers.captureBegin();
+		}
+		if (payload && payload.endpoint === "/api/simulate-mouse-input") {
+			return InputHandlers.simulateMouseInput(payload.data ?? {});
+		}
+		if (payload && payload.endpoint === "/api/simulate-keyboard-input") {
+			return InputHandlers.simulateKeyboardInput(payload.data ?? {});
+		}
 		if (payload && payload.endpoint === "/api/execute-luau") {
 			return handleExecuteLuau(payload.data);
 		}
@@ -162,7 +206,7 @@ function pollProxy(proxyId: string, player: Player, rf: RemoteFunction) {
 	while (player.Parent !== undefined && proxyByPlayer.has(player)) {
 		const [ok, res] = pcall(() =>
 			HttpService.RequestAsync({
-				Url: `${MCP_URL}/poll?instanceId=${proxyId}`,
+				Url: `${MCP_URL}/poll?pluginSessionId=${proxyId}`,
 				Method: "GET",
 				Headers: { "Content-Type": "application/json" },
 			}),
@@ -189,10 +233,12 @@ function pollProxy(proxyId: string, player: Player, rf: RemoteFunction) {
 							response = { success: false, error: `InvokeClient failed: ${tostring(invokeRes)}` };
 						}
 					} else {
+						const allowed: string[] = [];
+						for (const ep of CLIENT_BROKER_ALLOWED_ENDPOINTS) allowed.push(ep);
 						response = {
 							error:
 								`Client-proxy does not forward ${tostring(request.endpoint)}. ` +
-								`Allowed: /api/execute-luau, /api/get-runtime-logs.`,
+								`Allowed: ${allowed.join(", ")}.`,
 						};
 					}
 					postJson("/response", { requestId: body.requestId, response });
@@ -206,14 +252,22 @@ function pollProxy(proxyId: string, player: Player, rf: RemoteFunction) {
 function registerProxy(player: Player, rf: RemoteFunction) {
 	if (proxyByPlayer.has(player)) return;
 	const proxyId = HttpService.GenerateGUID(false);
-	const [ok, res] = postJson("/ready", { instanceId: proxyId, role: "client" });
+	const [ok, res] = postJson("/ready", {
+		pluginSessionId: proxyId,
+		instanceId: computeInstanceId(),
+		role: "client",
+		placeId: game.PlaceId,
+		placeName: resolvePlaceName(),
+		dataModelName: game.Name,
+		isRunning: RunService.IsRunning(),
+	});
 	if (!ok || !res || !res.Success) {
 		warn(`[MCPFork] proxy register failed for ${player.Name}`);
 		return;
 	}
 	const body = HttpService.JSONDecode(res.Body) as ReadyResponseBody;
 	const assigned = body.assignedRole ?? "client";
-	proxyByPlayer.set(player, { instanceId: proxyId, role: assigned });
+	proxyByPlayer.set(player, { pluginSessionId: proxyId, role: assigned });
 	task.spawn(pollProxy, proxyId, player, rf);
 }
 
@@ -238,12 +292,12 @@ function setupServerBroker() {
 		const entry = proxyByPlayer.get(p);
 		if (entry) {
 			proxyByPlayer.delete(p);
-			postJson("/disconnect", { instanceId: entry.instanceId });
+			postJson("/disconnect", { pluginSessionId: entry.pluginSessionId });
 		}
 	});
 	game.BindToClose(() => {
 		for (const [, entry] of proxyByPlayer) {
-			postJson("/disconnect", { instanceId: entry.instanceId });
+			postJson("/disconnect", { pluginSessionId: entry.pluginSessionId });
 		}
 		proxyByPlayer.clear();
 	});

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

@@ -1,7 +1,8 @@
-import { HttpService, RunService } from "@rbxts/services";
+import { HttpService, RunService, ServerStorage } from "@rbxts/services";
 import State from "./State";
 import Utils from "./Utils";
 import UI from "./UI";
+import { ensureBridgesInstalled } from "./EvalBridges";
 import QueryHandlers from "./handlers/QueryHandlers";
 import PropertyHandlers from "./handlers/PropertyHandlers";
 import InstanceHandlers from "./handlers/InstanceHandlers";
@@ -17,8 +18,60 @@ import SerializationHandlers from "./handlers/SerializationHandlers";
 import MemoryHandlers from "./handlers/MemoryHandlers";
 import { Connection, RequestPayload, PollResponse, ReadyResponse } from "../types";
 
-const instanceId = HttpService.GenerateGUID(false);
+// Per-plugin-load random GUID. Used as the /poll URL param so the server
+// can tell our polls apart from any other plugin's polls. Not user-facing —
+// MCP tools and the LLM operate on instanceId (the place identifier).
+const pluginSessionId = HttpService.GenerateGUID(false);
+
+// Place-level identifier shared by every plugin running in DataModels of
+// the same place file (edit DM + playtest server DM + playtest clients).
+// Format: "place:<PlaceId>" when published, "anon:<UUID>" for unpublished
+// places where the UUID lives on ServerStorage's __MCPPlaceId attribute
+// and travels with the .rbxl.
+const MCP_PLACE_ID_ATTRIBUTE = "__MCPPlaceId";
+
+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}`;
+}
+
+const instanceId = computeInstanceId();
 let assignedRole: string | undefined;
+let duplicateInstanceRole = false;
+
+// Cache the published place name from MarketplaceService:GetProductInfo so
+// /ready can carry a friendly identifier (e.g. "Natural Disasters") distinct
+// from game.Name (the DataModel name, often "Place1" in edit). We only fetch
+// once per plugin load; the published name doesn't change mid-session.
+let cachedPlaceName: string | undefined;
+
+function resolvePlaceName(): string {
+	if (cachedPlaceName !== undefined) return cachedPlaceName;
+	if (game.PlaceId === 0) {
+		cachedPlaceName = game.Name;
+		return cachedPlaceName;
+	}
+	const MarketplaceService = game.GetService("MarketplaceService");
+	const [ok, info] = pcall(() => MarketplaceService.GetProductInfo(game.PlaceId));
+	if (ok && info !== undefined) {
+		const name = (info as { Name?: string }).Name;
+		if (typeIs(name, "string") && name !== "") {
+			cachedPlaceName = name;
+			return cachedPlaceName;
+		}
+	}
+	// Don't cache failures — could be transient (offline, rate-limited).
+	// Next /ready will retry. Return game.Name as fallback.
+	return game.Name;
+}
 
 function detectRole(): string {
 	if (!RunService.IsRunning()) return "edit";
@@ -91,6 +144,8 @@ const routeMap: Record<string, Handler> = {
 	"/api/preview-asset": AssetHandlers.previewAsset,
 
 	"/api/capture-screenshot": CaptureHandlers.captureScreenshot,
+	"/api/capture-begin": CaptureHandlers.captureBegin,
+	"/api/capture-read": CaptureHandlers.captureRead,
 	"/api/simulate-mouse-input": InputHandlers.simulateMouseInput,
 	"/api/simulate-keyboard-input": InputHandlers.simulateKeyboardInput,
 
@@ -140,7 +195,25 @@ function getConnectionStatus(connIndex: number): string {
 // restarted but hasn't seen our re-ready yet would fire a duplicate /ready.
 let lastReadyPostAt = 0;
 
+// game.Name is sometimes "Place1" at plugin-load time and only settles to
+// the real DataModel name (e.g. "Game" once playtest spawns the play DM)
+// after Studio finishes wiring things up. Re-fire /ready when it changes so
+// get_connected_instances doesn't show a stale dataModelName forever. Set
+// up once per plugin load — the connection passed in is whichever was
+// active when activatePlugin was first called.
+let nameChangeConn: RBXScriptConnection | undefined;
+function ensureNameChangeWatcher(conn: Connection): void {
+	if (nameChangeConn) return;
+	const [okSig, signal] = pcall(() => game.GetPropertyChangedSignal("Name"));
+	if (!okSig || !signal) return;
+	nameChangeConn = signal.Connect(() => {
+		// sendReady has its own 2s throttle, so rapid burst changes coalesce.
+		sendReady(conn);
+	});
+}
+
 function sendReady(conn: Connection): void {
+	if (duplicateInstanceRole) return; // stop retrying once the server has rejected us
 	const now = tick();
 	if (now - lastReadyPostAt < 2) return; // throttle to ≤1 /ready every 2s
 	lastReadyPostAt = now;
@@ -151,14 +224,36 @@ function sendReady(conn: Connection): void {
 				Method: "POST",
 				Headers: { "Content-Type": "application/json" },
 				Body: HttpService.JSONEncode({
+					pluginSessionId,
 					instanceId,
 					role: detectRole(),
+					placeId: game.PlaceId,
+					placeName: resolvePlaceName(),
+					dataModelName: game.Name,
+					isRunning: RunService.IsRunning(),
 					pluginReady: true,
 					timestamp: tick(),
 				}),
 			});
 		});
-		if (readyOk && readyResult.Success) {
+		if (!readyOk) return;
+		// 409 = duplicate_instance_role. Surface in UI and stop polling.
+		if (readyResult.StatusCode === 409) {
+			duplicateInstanceRole = true;
+			conn.isActive = false;
+			const ui = UI.getElements();
+			if (State.getActiveTabIndex() === 0) {
+				ui.statusLabel.Text = "Duplicate instance";
+				ui.statusLabel.TextColor3 = Color3.fromRGB(239, 68, 68);
+				ui.detailStatusLabel.Text = "Another Studio is already connected as this place + role";
+				ui.detailStatusLabel.TextColor3 = Color3.fromRGB(239, 68, 68);
+			}
+			warn(
+				`[MCPPlugin] Another Studio is already connected as (${instanceId}, ${detectRole()}). Close the other Studio window or this one.`,
+			);
+			return;
+		}
+		if (readyResult.Success) {
 			const [parseOk, readyData] = pcall(
 				() => HttpService.JSONDecode(readyResult.Body) as ReadyResponse,
 			);
@@ -178,7 +273,7 @@ function pollForRequests(connIndex: number) {
 
 	const [success, result] = pcall(() => {
 		return HttpService.RequestAsync({
-			Url: `${conn.serverUrl}/poll?instanceId=${instanceId}`,
+			Url: `${conn.serverUrl}/poll?pluginSessionId=${pluginSessionId}`,
 			Method: "GET",
 			Headers: { "Content-Type": "application/json" },
 		});
@@ -365,6 +460,24 @@ function activatePlugin(connIndex?: number) {
 	// Initial /ready; pollForRequests will also re-fire ready if the server
 	// later reports knownInstance=false (process restart, etc).
 	sendReady(conn);
+
+	// Keep the eval bridges present in the edit DM so that ANY playtest —
+	// including one the dev starts manually via the Studio Play button —
+	// clones them into the play DMs and eval_*_runtime works with no setup
+	// roundtrip. Only the edit DM installs; play DMs already have the cloned
+	// copies. Idempotent, so reconnects don't re-dirty the place.
+	if (!RunService.IsRunning()) {
+		task.spawn(() => {
+			const result = ensureBridgesInstalled();
+			if (!result.installed) {
+				warn(`[MCPPlugin] Eval bridge install failed: ${result.error}`);
+			}
+		});
+	}
+
+	// Watch for game.Name updates so a stale "Place1" captured at first
+	// /ready gets refreshed once Studio settles on the real DM name.
+	ensureNameChangeWatcher(conn);
 }
 
 function deactivatePlugin(connIndex?: number) {
@@ -383,7 +496,7 @@ function deactivatePlugin(connIndex?: number) {
 			Url: `${conn.serverUrl}/disconnect`,
 			Method: "POST",
 			Headers: { "Content-Type": "application/json" },
-			Body: HttpService.JSONEncode({ instanceId, timestamp: tick() }),
+			Body: HttpService.JSONEncode({ pluginSessionId, timestamp: tick() }),
 		});
 	});
 

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

@@ -21,11 +21,16 @@
 // ServerScriptService.LoadStringEnabled, so eval_server_runtime works even
 // when LoadStringEnabled=false (the default in fresh places).
 //
-// Lifecycle: TestHandlers.startPlaytest inserts both scripts into the EDIT
-// DM right before ExecutePlayModeAsync. ExecutePlayModeAsync clones the
-// DataModel into the play DMs, so the scripts come along and run there.
-// TestHandlers cleans them up from the edit DM when ExecutePlayModeAsync
-// returns (test ended for any reason: stop_playtest, manual close, EndTest).
+// Lifecycle: the bridges live PERMANENTLY in the edit DM. Communication
+// installs them (ensureBridgesInstalled) when the plugin connects in edit,
+// and TestHandlers.startPlaytest force-refreshes them right before
+// ExecutePlayModeAsync. ExecutePlayModeAsync clones the DataModel into the
+// play DMs, so the scripts come along and run there. We keep them in the edit
+// DM after a playtest ends (rather than cleaning up) so that a playtest the
+// dev starts MANUALLY via the Studio Play button — not the MCP start_playtest
+// tool — also gets the bridges cloned in. This is intentionally a little
+// intrusive (two helper scripts visible in Explorer) in exchange for a
+// zero-roundtrip eval_*_runtime experience for devs working 1:1 with an agent.
 //
 // Archivable handling: ExecutePlayModeAsync's deep-clone SKIPS instances
 // with Archivable=false (verified empirically in v2.9.0 testing - bridges
@@ -61,9 +66,9 @@ export const BRIDGE_NAMES = {
 // Embedded Luau. The double `${...}` references our exported names so a
 // rename here propagates to both the script source and the tool wrappers.
 const SERVER_BRIDGE_SOURCE = `
--- Auto-installed by @chrrxs/robloxstudio-mcp at start_playtest, removed at
--- stop_playtest. Provides shared-require-cache eval on the server peer for
--- the eval_server_runtime MCP tool.
+-- Installed by @chrrxs/robloxstudio-mcp to power the eval_server_runtime MCP
+-- tool (shared-require-cache eval on the server during playtests). Inert
+-- outside Studio (no-ops in live games); safe to leave in place.
 
 local ServerScriptService = game:GetService("ServerScriptService")
 local RunService = game:GetService("RunService")
@@ -88,9 +93,9 @@ end
 `;
 
 const CLIENT_BRIDGE_SOURCE = `
--- Auto-installed by @chrrxs/robloxstudio-mcp at start_playtest, removed at
--- stop_playtest. Provides shared-require-cache eval on the client peer for
--- the eval_client_runtime MCP tool.
+-- Installed by @chrrxs/robloxstudio-mcp to power the eval_client_runtime MCP
+-- tool (shared-require-cache eval on the client during playtests). Inert
+-- outside Studio (no-ops in live games); safe to leave in place.
 
 local ReplicatedStorage = game:GetService("ReplicatedStorage")
 local RunService = game:GetService("RunService")
@@ -114,6 +119,28 @@ bf.OnInvoke = function(payload)
 end
 `;
 
+// Stamp written onto each installed bridge Script so we can tell whether the
+// bridge currently in the DM was produced by THIS plugin build. It's a djb2
+// hash of the actual bridge source plus the plugin version, so ANY change to
+// the source (or a version bump) yields a new stamp — which makes
+// ensureBridgesInstalled() force a refresh on the next plugin load instead of
+// keeping a stale bridge that happens to still be present (e.g. one saved into
+// the .rbxl from an older build).
+const STAMP_ATTR = "__MCPBridgeStamp";
+
+function computeBridgeStamp(): string {
+	const combined = `${SERVER_BRIDGE_SOURCE}|${CLIENT_BRIDGE_SOURCE}`;
+	let h = 5381;
+	for (let i = 1; i <= combined.size(); i++) {
+		h = (h * 33 + string.byte(combined, i)[0]) % 2147483647;
+	}
+	// "__VERSION__" is replaced with the package version at package time
+	// (scripts/build-plugin.mjs injectVersion), so a release bump also restamps.
+	return `${tostring(h)}-__VERSION__`;
+}
+
+const BRIDGE_STAMP = computeBridgeStamp();
+
 function setSource(scriptInst: Script | LocalScript, source: string): void {
 	// ScriptEditorService is the cleaner API and integrates with Studio's
 	// edit history; fall back to direct Source mutation (allowed in plugin
@@ -144,6 +171,26 @@ export function cleanupBridges(): void {
 	}
 }
 
+// Idempotent variant: install only if the bridge scripts aren't already
+// present in the edit DM. Used to keep the bridges always available (so a
+// playtest the dev starts manually — not via the MCP start_playtest tool —
+// still clones them into the play DMs). Cheap no-op when already installed,
+// which avoids re-dirtying the place on every plugin reconnect.
+export function ensureBridgesInstalled(): { installed: boolean; error?: string } {
+	const { server, client } = findBridges();
+	if (server && client) {
+		// Both present — but only skip the reinstall if they were produced by
+		// THIS build. A mismatched/absent stamp means a stale bridge (older
+		// plugin, or one persisted in the saved place), so force a refresh.
+		const sStamp = server.GetAttribute(STAMP_ATTR);
+		const cStamp = client.GetAttribute(STAMP_ATTR);
+		if (sStamp === BRIDGE_STAMP && cStamp === BRIDGE_STAMP) {
+			return { installed: true };
+		}
+	}
+	return installBridges();
+}
+
 export function installBridges(): { installed: boolean; error?: string } {
 	// Defensive: clear any stale bridges from a prior unclean exit before
 	// inserting fresh. The injected script also self-cleans its
@@ -158,6 +205,7 @@ export function installBridges(): { installed: boolean; error?: string } {
 		// script. cleanupBridges() removes it from the edit DM when the
 		// playtest ends.
 		setSource(serverScript, SERVER_BRIDGE_SOURCE);
+		serverScript.SetAttribute(STAMP_ATTR, BRIDGE_STAMP);
 		serverScript.Parent = ServerScriptService;
 
 		const sps = getStarterPlayerScripts();
@@ -167,6 +215,7 @@ export function installBridges(): { installed: boolean; error?: string } {
 		const clientScript = new Instance("LocalScript");
 		clientScript.Name = CLIENT_SCRIPT_NAME;
 		setSource(clientScript, CLIENT_BRIDGE_SOURCE);
+		clientScript.SetAttribute(STAMP_ATTR, BRIDGE_STAMP);
 		clientScript.Parent = sps;
 	});