@chrrxs/robloxstudio-mcp-inspector 2.8.0

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

@@ -0,0 +1,277 @@
+import { HttpService, LogService } from "@rbxts/services";
+
+const StudioTestService = game.GetService("StudioTestService");
+const ServerScriptService = game.GetService("ServerScriptService");
+const ScriptEditorService = game.GetService("ScriptEditorService");
+
+const STOP_SIGNAL = "__MCP_STOP__";
+const NAV_SIGNAL = "__MCP_NAV__";
+const NAV_RESULT = "__MCP_NAV_RESULT__";
+
+interface OutputEntry {
+	message: string;
+	messageType: string;
+	timestamp: number;
+}
+
+let testRunning = false;
+let outputBuffer: OutputEntry[] = [];
+let logConnection: RBXScriptConnection | undefined;
+let testResult: unknown;
+let testError: string | undefined;
+let stopListenerScript: Script | undefined;
+let navResultCallback: ((json: string) => void) | undefined;
+
+function buildCommandListenerSource(): string {
+	return `local LogService = game:GetService("LogService")
+local StudioTestService = game:GetService("StudioTestService")
+local PathfindingService = game:GetService("PathfindingService")
+local Players = game:GetService("Players")
+local HttpService = game:GetService("HttpService")
+local NAV_SIG = "${NAV_SIGNAL}"
+local NAV_RES = "${NAV_RESULT}"
+LogService.MessageOut:Connect(function(msg)
+	if msg == "${STOP_SIGNAL}" then
+		pcall(function() StudioTestService:EndTest("stopped_by_mcp") end)
+	elseif string.sub(msg, 1, #NAV_SIG + 1) == NAV_SIG .. ":" then
+		local json = string.sub(msg, #NAV_SIG + 2)
+		task.spawn(function()
+			local ok, d = pcall(function() return HttpService:JSONDecode(json) end)
+			if not ok or not d then
+				print(NAV_RES .. ':{"success":false,"error":"parse_error"}')
+				return
+			end
+			local ps = Players:GetPlayers()
+			if #ps == 0 then
+				print(NAV_RES .. ':{"success":false,"error":"no_players"}')
+				return
+			end
+			local char = ps[1].Character or ps[1].CharacterAdded:Wait()
+			local hum = char:FindFirstChildOfClass("Humanoid")
+			local root = char:FindFirstChild("HumanoidRootPart")
+			if not hum or not root then
+				print(NAV_RES .. ':{"success":false,"error":"no_humanoid"}')
+				return
+			end
+			local target
+			if d.instancePath then
+				local parts = string.split(d.instancePath, ".")
+				local cur = game
+				for i = 2, #parts do
+					cur = cur:FindFirstChild(parts[i])
+					if not cur then
+						print(NAV_RES .. ':{"success":false,"error":"instance_not_found"}')
+						return
+					end
+				end
+				if cur:IsA("BasePart") then target = cur.Position
+				elseif cur:IsA("Model") and cur.PrimaryPart then target = cur.PrimaryPart.Position
+				else target = cur:GetPivot().Position end
+			else
+				target = Vector3.new(d.x or 0, d.y or 0, d.z or 0)
+			end
+			local path = PathfindingService:CreatePath({AgentRadius=2,AgentHeight=5,AgentCanJump=true})
+			local pok = pcall(function() path:ComputeAsync(root.Position, target) end)
+			local method = "direct"
+			if pok and path.Status == Enum.PathStatus.Success then
+				method = "pathfinding"
+				for _, wp in ipairs(path:GetWaypoints()) do
+					hum:MoveTo(wp.Position)
+					if wp.Action == Enum.PathWaypointAction.Jump then hum.Jump = true end
+					hum.MoveToFinished:Wait()
+				end
+			else
+				hum:MoveTo(target)
+				hum.MoveToFinished:Wait()
+			end
+			local fp = root.Position
+			print(NAV_RES .. ':{"success":true,"method":"' .. method .. '","position":[' .. fp.X .. ',' .. fp.Y .. ',' .. fp.Z .. ']}')
+		end)
+	end
+end)`;
+}
+
+function injectStopListener() {
+	const listener = new Instance("Script");
+	listener.Name = "__MCP_CommandListener";
+	listener.Parent = ServerScriptService;
+
+	const source = buildCommandListenerSource();
+	const [seOk] = pcall(() => {
+		ScriptEditorService.UpdateSourceAsync(listener, () => source);
+	});
+	if (!seOk) {
+		(listener as unknown as { Source: string }).Source = source;
+	}
+
+	stopListenerScript = listener;
+}
+
+function cleanupStopListener() {
+	if (stopListenerScript) {
+		pcall(() => stopListenerScript!.Destroy());
+		stopListenerScript = undefined;
+	}
+}
+
+function startPlaytest(requestData: Record<string, unknown>) {
+	const mode = requestData.mode as string | undefined;
+	const numPlayers = requestData.numPlayers as number | undefined;
+
+	if (mode !== "play" && mode !== "run") {
+		return { error: 'mode must be "play" or "run"' };
+	}
+
+	if (testRunning) {
+		return { error: "A test is already running" };
+	}
+
+	testRunning = true;
+	outputBuffer = [];
+	testResult = undefined;
+	testError = undefined;
+
+	cleanupStopListener();
+
+	logConnection = LogService.MessageOut.Connect((message, messageType) => {
+		if (message === STOP_SIGNAL) return;
+		if (message.sub(1, NAV_SIGNAL.size()) === NAV_SIGNAL) return;
+		if (message.sub(1, NAV_RESULT.size() + 1) === `${NAV_RESULT}:`) {
+			if (navResultCallback) {
+				navResultCallback(message.sub(NAV_RESULT.size() + 2));
+			}
+			return;
+		}
+		outputBuffer.push({
+			message,
+			messageType: messageType.Name,
+			timestamp: tick(),
+		});
+	});
+
+	const [injected, injErr] = pcall(() => injectStopListener());
+	if (!injected) {
+		warn(`[MCP] Failed to inject stop listener: ${injErr}`);
+	}
+
+	if (numPlayers !== undefined && mode === "run") {
+		const TestService = game.GetService("TestService") as TestService & { NumberOfPlayers: number };
+		TestService.NumberOfPlayers = math.clamp(numPlayers, 1, 8);
+	}
+
+	task.spawn(() => {
+		const [ok, result] = pcall(() => {
+			if (mode === "play") {
+				return StudioTestService.ExecutePlayModeAsync({});
+			}
+			return StudioTestService.ExecuteRunModeAsync({});
+		});
+
+		if (ok) {
+			testResult = result;
+		} else {
+			testError = tostring(result);
+		}
+
+		if (logConnection) {
+			logConnection.Disconnect();
+			logConnection = undefined;
+		}
+		testRunning = false;
+
+		cleanupStopListener();
+	});
+
+	const msg = numPlayers !== undefined
+		? `Playtest started in ${mode} mode with ${numPlayers} player(s)`
+		: `Playtest started in ${mode} mode`;
+	return { success: true, message: msg };
+}
+
+function stopPlaytest(_requestData: Record<string, unknown>) {
+	// Stop requests are normally intercepted by the server-peer edit-proxy in
+	// modules/ClientBroker - that proxy runs inside the play server DM, the
+	// only DM where StudioTestService:EndTest is legal. If we reach this
+	// handler the broker either hasn't started yet or there's no active
+	// playtest. Try EndTest directly as a fallback (works for manually
+	// started playtests where the server-peer plugin happens to be polling).
+	const endTest = StudioTestService as unknown as Instance & { EndTest(reason: string): void };
+	const [endOk, endErr] = pcall(() => {
+		endTest.EndTest("stopped_by_mcp");
+	});
+	if (endOk) {
+		return {
+			success: true,
+			output: [...outputBuffer],
+			outputCount: outputBuffer.size(),
+			message: "Playtest stopped via StudioTestService.",
+		};
+	}
+
+	return {
+		error: `stopPlaytest fell through to edit DM (broker should have handled it). EndTest reported: ${tostring(endErr)}`,
+	};
+}
+
+function getPlaytestOutput(_requestData: Record<string, unknown>) {
+	return {
+		isRunning: testRunning,
+		output: [...outputBuffer],
+		outputCount: outputBuffer.size(),
+		testResult: testResult !== undefined ? tostring(testResult) : undefined,
+		testError,
+	};
+}
+
+function characterNavigation(requestData: Record<string, unknown>) {
+	if (!testRunning) {
+		return { error: "Playtest must be running. Start a playtest in 'play' mode first." };
+	}
+
+	const position = requestData.position as number[] | undefined;
+	const instancePath = requestData.instancePath as string | undefined;
+	const waitForCompletion = (requestData.waitForCompletion as boolean) ?? true;
+	const timeout = (requestData.timeout as number) ?? 25;
+
+	if (!position && !instancePath) {
+		return { error: "Either position [x, y, z] or instancePath is required" };
+	}
+
+	let navData: string;
+	if (position) {
+		navData = HttpService.JSONEncode({ x: position[0], y: position[1], z: position[2] });
+	} else {
+		navData = HttpService.JSONEncode({ instancePath });
+	}
+
+	warn(`${NAV_SIGNAL}:${navData}`);
+
+	if (!waitForCompletion) {
+		return { success: true, message: "Navigation command sent" };
+	}
+
+	let result: string | undefined;
+	navResultCallback = (json: string) => {
+		result = json;
+	};
+
+	const startTime = tick();
+	while (!result && tick() - startTime < timeout) {
+		task.wait(0.2);
+	}
+	navResultCallback = undefined;
+
+	if (result) {
+		const [ok, parsed] = pcall(() => HttpService.JSONDecode(result!));
+		if (ok) return parsed;
+		return { success: true, rawResult: result };
+	}
+	return { error: `Navigation timed out after ${timeout} seconds` };
+}
+
+export = {
+	startPlaytest,
+	stopPlaytest,
+	getPlaytestOutput,
+	characterNavigation,
+};

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

@@ -0,0 +1,63 @@
+import State from "../modules/State";
+import UI from "../modules/UI";
+import Communication from "../modules/Communication";
+import ClientBroker from "../modules/ClientBroker";
+
+
+UI.init(plugin);
+const elements = UI.getElements();
+
+
+const toolbar = plugin.CreateToolbar("__TOOLBAR_NAME__");
+const button = toolbar.CreateButton("__BUTTON_TITLE__", "__BUTTON_TOOLTIP__", "rbxassetid://__BUTTON_ICON_ID__");
+
+
+elements.connectButton.Activated.Connect(() => {
+	const conn = State.getActiveConnection();
+	if (conn && conn.isActive) {
+		Communication.deactivatePlugin(State.getActiveTabIndex());
+	} else {
+		Communication.activatePlugin(State.getActiveTabIndex());
+	}
+});
+
+
+button.Click.Connect(() => {
+	elements.screenGui.Enabled = !elements.screenGui.Enabled;
+});
+
+
+plugin.Unloading.Connect(() => {
+	Communication.deactivateAll();
+});
+
+
+UI.updateUIState();
+Communication.checkForUpdates();
+
+// Auto-activate per peer. The boshyxd plugin only registers with MCP when the
+// user clicks Connect in its UI, but that UI is invisible in play DMs - so
+// play peers' plugin instances load without ever registering. Run after a
+// short delay so the UI/State have a chance to initialize first.
+task.delay(2, () => {
+	const role = ClientBroker.forkRole();
+	if (role === "edit" || role === "server") {
+		pcall(() => {
+			const idx = State.getActiveTabIndex();
+			const conn = State.getConnection(idx);
+			if (conn && !conn.isActive) {
+				// Defensive default: in invisible play-DM UIs, the input field
+				// may not be populated by the time we activate.
+				if (conn.serverUrl === undefined || conn.serverUrl === "") {
+					conn.serverUrl = ClientBroker.MCP_URL;
+				}
+				Communication.activatePlugin(idx);
+			}
+		});
+	}
+	if (role === "server") {
+		ClientBroker.setupServerBroker();
+	} else if (role === "client") {
+		ClientBroker.setupClientBroker();
+	}
+});

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

@@ -0,0 +1,44 @@
+/// <reference types="@rbxts/types/plugin" />
+
+export interface Connection {
+	port: number;
+	serverUrl: string;
+	isActive: boolean;
+	pollInterval: number;
+	lastPoll: number;
+	consecutiveFailures: number;
+	maxFailuresBeforeError: number;
+	lastSuccessfulConnection: number;
+	currentRetryDelay: number;
+	maxRetryDelay: number;
+	retryBackoffMultiplier: number;
+	lastHttpOk: boolean;
+	lastMcpOk: boolean;
+	mcpWaitStartTime?: number;
+	isPolling: boolean;
+	heartbeatConnection?: RBXScriptConnection;
+}
+
+export interface RequestData {
+	[key: string]: unknown;
+}
+
+export interface RequestPayload {
+	endpoint: string;
+	data?: RequestData;
+}
+
+export interface PollResponse {
+	mcpConnected: boolean;
+	request?: RequestPayload;
+	requestId?: string;
+}
+
+export interface ReadyResponse {
+	success: boolean;
+	assignedRole?: string;
+}
+
+declare global {
+	function loadstring(code: string): LuaTuple<[(() => unknown) | undefined, string?]>;
+}

package/studio-plugin/tsconfig.json

@@ -0,0 +1,20 @@
+{
+  "compilerOptions": {
+    "allowSyntheticDefaultImports": true,
+    "downlevelIteration": true,
+    "jsx": "react",
+    "jsxFactory": "React.createElement",
+    "jsxFragmentFactory": "React.Fragment",
+    "module": "commonjs",
+    "moduleDetection": "force",
+    "moduleResolution": "node",
+    "noLib": true,
+    "resolveJsonModule": true,
+    "strict": true,
+    "target": "ESNext",
+    "typeRoots": ["node_modules/@rbxts"],
+    "rootDir": "src",
+    "outDir": "out",
+    "declaration": false
+  }
+}