@chrrxs/robloxstudio-mcp-inspector 2.8.0

package/studio-plugin/package.json

@@ -0,0 +1,19 @@
+{
+  "name": "studio-plugin",
+  "version": "1.0.0",
+  "private": true,
+  "scripts": {
+    "build": "rbxtsc",
+    "watch": "rbxtsc -w",
+    "dev": "rbxtsc -w --project tsconfig.json"
+  },
+  "devDependencies": {
+    "@rbxts/compiler-types": "^3.0.0-types.0",
+    "@rbxts/types": "^1.0.906",
+    "roblox-ts": "^3.0.0",
+    "typescript": "^5.9.3"
+  },
+  "dependencies": {
+    "@rbxts/services": "^1.6.0"
+  }
+}

package/studio-plugin/plugin.json

@@ -0,0 +1,10 @@
+{
+  "Name": "Roblox Studio MCP Plugin",
+  "Description": "Provides AI tool access to Roblox Studio data through MCP protocol",
+  "Author": "MCP Integration",
+  "Version": "1.0.0",
+  "Id": "robloxstudio-mcp-plugin",
+  "Permissions": [
+    "HTTP"
+  ]
+}

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

@@ -0,0 +1,221 @@
+import { HttpService, Players, ReplicatedStorage, RunService } from "@rbxts/services";
+
+// The client peer cannot reach the MCP HTTP server - Roblox forbids
+// HttpService:RequestAsync from the client DM even under PluginSecurity, and
+// HttpEnabled reads as false there regardless of identity. So the server peer
+// brokers execute_luau requests to the client via a RemoteFunction it places
+// in ReplicatedStorage; each player gets a proxy "client" registration on the
+// MCP side, polled and dispatched by the server peer.
+//
+// The same server peer also registers an "edit" proxy that intercepts
+// /api/stop-playtest specifically - StudioTestService:EndTest only works from
+// the play server DM, so the real edit DM cannot satisfy stop requests on its
+// own. MCP returns the same pending request to multiple pollers until someone
+// /responds, so non-stop edit-targeted requests fall through to the actual
+// edit DM untouched.
+
+const MCP_URL = "http://localhost:58741";
+const BROKER_NAME = "__MCPClientBroker";
+
+interface ProxyEntry {
+	instanceId: string;
+	role: string;
+}
+
+interface ExecutePayload {
+	code?: string;
+}
+
+interface ExecuteResult {
+	success: boolean;
+	returnValue?: string;
+	message?: string;
+	error?: string;
+}
+
+interface ReadyResponseBody {
+	assignedRole?: string;
+}
+
+interface PollResponseBody {
+	requestId?: string;
+	request?: {
+		endpoint: string;
+		data?: Record<string, unknown>;
+	};
+}
+
+function forkRole(): "edit" | "server" | "client" {
+	if (!RunService.IsRunning()) return "edit";
+	if (RunService.IsServer()) return "server";
+	return "client";
+}
+
+function postJson(endpoint: string, body: Record<string, unknown>) {
+	return pcall(() =>
+		HttpService.RequestAsync({
+			Url: `${MCP_URL}${endpoint}`,
+			Method: "POST",
+			Headers: { "Content-Type": "application/json" },
+			Body: HttpService.JSONEncode(body),
+		}),
+	);
+}
+
+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" });
+		}
+		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",
+			});
+		}
+		return identity<ExecuteResult>({ success: false, error: tostring(result) });
+	};
+	print("[MCPFork] client broker ready");
+}
+
+const proxyByPlayer = new Map<Player, ProxyEntry>();
+
+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}`,
+				Method: "GET",
+				Headers: { "Content-Type": "application/json" },
+			}),
+		);
+		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" };
+					} else {
+						response = { success: false, error: `InvokeClient failed: ${tostring(invokeRes)}` };
+					}
+				} else {
+					response = { error: `Client-proxy only supports /api/execute-luau, got: ${tostring(request.endpoint)}` };
+				}
+				postJson("/response", { requestId: body.requestId, response });
+			}
+		}
+		task.wait(0.5);
+	}
+}
+
+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" });
+	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 });
+	print(`[MCPFork] proxy ${assigned} -> ${player.Name}`);
+	task.spawn(pollProxy, proxyId, player, rf);
+}
+
+function startEditProxyLoop() {
+	task.spawn(() => {
+		const proxyId = HttpService.GenerateGUID(false);
+		const [ok, res] = postJson("/ready", { instanceId: proxyId, role: "edit" });
+		if (!ok || !res || !res.Success) {
+			warn("[MCPFork] edit-proxy register failed");
+			return;
+		}
+		print("[MCPFork] edit-proxy ready (stop-playtest interceptor)");
+		while (true) {
+			const [okPoll, pollRes] = pcall(() =>
+				HttpService.RequestAsync({
+					Url: `${MCP_URL}/poll?instanceId=${proxyId}`,
+					Method: "GET",
+					Headers: { "Content-Type": "application/json" },
+				}),
+			);
+			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 });
+				}
+			}
+			task.wait(0.15);
+		}
+	});
+}
+
+function setupServerBroker() {
+	let rf = ReplicatedStorage.FindFirstChild(BROKER_NAME) as RemoteFunction | undefined;
+	if (!rf) {
+		rf = new Instance("RemoteFunction");
+		rf.Name = BROKER_NAME;
+		rf.Parent = ReplicatedStorage;
+	}
+	const broker = rf;
+	Players.PlayerAdded.Connect((p) => registerProxy(p, broker));
+	for (const p of Players.GetPlayers()) {
+		task.spawn(registerProxy, p, broker);
+	}
+	Players.PlayerRemoving.Connect((p) => {
+		const entry = proxyByPlayer.get(p);
+		if (entry) {
+			proxyByPlayer.delete(p);
+			postJson("/disconnect", { instanceId: entry.instanceId });
+		}
+	});
+	game.BindToClose(() => {
+		for (const [, entry] of proxyByPlayer) {
+			postJson("/disconnect", { instanceId: entry.instanceId });
+		}
+		proxyByPlayer.clear();
+	});
+	startEditProxyLoop();
+	print("[MCPFork] server broker ready");
+}
+
+export = {
+	MCP_URL,
+	forkRole,
+	setupClientBroker,
+	setupServerBroker,
+};

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

@@ -0,0 +1,399 @@
+import { HttpService, RunService } from "@rbxts/services";
+import State from "./State";
+import Utils from "./Utils";
+import UI from "./UI";
+import QueryHandlers from "./handlers/QueryHandlers";
+import PropertyHandlers from "./handlers/PropertyHandlers";
+import InstanceHandlers from "./handlers/InstanceHandlers";
+import ScriptHandlers from "./handlers/ScriptHandlers";
+import MetadataHandlers from "./handlers/MetadataHandlers";
+import TestHandlers from "./handlers/TestHandlers";
+import BuildHandlers from "./handlers/BuildHandlers";
+import AssetHandlers from "./handlers/AssetHandlers";
+import CaptureHandlers from "./handlers/CaptureHandlers";
+import InputHandlers from "./handlers/InputHandlers";
+import { Connection, RequestPayload, PollResponse, ReadyResponse } from "../types";
+
+const instanceId = HttpService.GenerateGUID(false);
+let assignedRole: string | undefined;
+
+function detectRole(): string {
+	if (!RunService.IsRunning()) return "edit";
+	if (RunService.IsServer()) return "server";
+	return "client";
+}
+
+type Handler = (data: Record<string, unknown>) => unknown;
+
+const routeMap: Record<string, Handler> = {
+
+	"/api/file-tree": QueryHandlers.getFileTree,
+	"/api/search-files": QueryHandlers.searchFiles,
+	"/api/place-info": QueryHandlers.getPlaceInfo,
+	"/api/services": QueryHandlers.getServices,
+	"/api/search-objects": QueryHandlers.searchObjects,
+	"/api/instance-properties": QueryHandlers.getInstanceProperties,
+	"/api/instance-children": QueryHandlers.getInstanceChildren,
+	"/api/search-by-property": QueryHandlers.searchByProperty,
+	"/api/class-info": QueryHandlers.getClassInfo,
+	"/api/project-structure": QueryHandlers.getProjectStructure,
+	"/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,
+	"/api/mass-set-property": PropertyHandlers.massSetProperty,
+	"/api/mass-get-property": PropertyHandlers.massGetProperty,
+	"/api/create-object": InstanceHandlers.createObject,
+	"/api/mass-create-objects": InstanceHandlers.massCreateObjects,
+	// Back-compat alias: pre-2.7.0 servers split this endpoint when properties were present.
+	"/api/mass-create-objects-with-properties": InstanceHandlers.massCreateObjects,
+	"/api/delete-object": InstanceHandlers.deleteObject,
+	"/api/smart-duplicate": InstanceHandlers.smartDuplicate,
+	"/api/mass-duplicate": InstanceHandlers.massDuplicate,
+	"/api/clone-object": InstanceHandlers.cloneObject,
+
+	"/api/get-script-source": ScriptHandlers.getScriptSource,
+	"/api/set-script-source": ScriptHandlers.setScriptSource,
+	"/api/edit-script-lines": ScriptHandlers.editScriptLines,
+	"/api/insert-script-lines": ScriptHandlers.insertScriptLines,
+	"/api/delete-script-lines": ScriptHandlers.deleteScriptLines,
+
+	"/api/set-attribute": MetadataHandlers.setAttribute,
+	"/api/get-attributes": MetadataHandlers.getAttributes,
+	"/api/delete-attribute": MetadataHandlers.deleteAttribute,
+	"/api/get-tags": MetadataHandlers.getTags,
+	"/api/add-tag": MetadataHandlers.addTag,
+	"/api/remove-tag": MetadataHandlers.removeTag,
+	"/api/get-tagged": MetadataHandlers.getTagged,
+	"/api/get-selection": MetadataHandlers.getSelection,
+	"/api/execute-luau": MetadataHandlers.executeLuau,
+	"/api/undo": MetadataHandlers.undo,
+	"/api/redo": MetadataHandlers.redo,
+	"/api/bulk-set-attributes": MetadataHandlers.bulkSetAttributes,
+
+	"/api/start-playtest": TestHandlers.startPlaytest,
+	"/api/stop-playtest": TestHandlers.stopPlaytest,
+	"/api/get-playtest-output": TestHandlers.getPlaytestOutput,
+	"/api/character-navigation": TestHandlers.characterNavigation,
+
+	"/api/export-build": BuildHandlers.exportBuild,
+	"/api/import-build": BuildHandlers.importBuild,
+	"/api/import-scene": BuildHandlers.importScene,
+	"/api/search-materials": BuildHandlers.searchMaterials,
+
+	"/api/insert-asset": AssetHandlers.insertAsset,
+	"/api/preview-asset": AssetHandlers.previewAsset,
+
+	"/api/capture-screenshot": CaptureHandlers.captureScreenshot,
+	"/api/simulate-mouse-input": InputHandlers.simulateMouseInput,
+	"/api/simulate-keyboard-input": InputHandlers.simulateKeyboardInput,
+
+	"/api/find-and-replace-in-scripts": ScriptHandlers.findAndReplaceInScripts,
+};
+
+function processRequest(request: RequestPayload): unknown {
+	const endpoint = request.endpoint;
+	const data = request.data ?? {};
+
+	const handler = routeMap[endpoint];
+	if (handler) {
+		return handler(data as Record<string, unknown>);
+	} else {
+		return { error: `Unknown endpoint: ${endpoint}` };
+	}
+}
+
+function sendResponse(conn: Connection, requestId: string, responseData: unknown) {
+	pcall(() => {
+		HttpService.RequestAsync({
+			Url: `${conn.serverUrl}/response`,
+			Method: "POST",
+			Headers: { "Content-Type": "application/json" },
+			Body: HttpService.JSONEncode({ requestId, response: responseData }),
+		});
+	});
+}
+
+function getConnectionStatus(connIndex: number): string {
+	const conn = State.getConnection(connIndex);
+	if (!conn || !conn.isActive) return "disconnected";
+	if (conn.consecutiveFailures >= conn.maxFailuresBeforeError) return "error";
+	if (conn.lastHttpOk) return "connected";
+	return "connecting";
+}
+
+function pollForRequests(connIndex: number) {
+	const conn = State.getConnection(connIndex);
+	if (!conn || !conn.isActive) return;
+	if (conn.isPolling) return;
+
+	conn.isPolling = true;
+
+	const [success, result] = pcall(() => {
+		return HttpService.RequestAsync({
+			Url: `${conn.serverUrl}/poll?instanceId=${instanceId}`,
+			Method: "GET",
+			Headers: { "Content-Type": "application/json" },
+		});
+	});
+
+	conn.isPolling = false;
+
+	const ui = UI.getElements();
+	UI.updateTabDot(connIndex);
+
+	if (success && (result.Success || result.StatusCode === 503)) {
+		conn.consecutiveFailures = 0;
+		conn.currentRetryDelay = 0.5;
+		conn.lastSuccessfulConnection = tick();
+
+		const data = HttpService.JSONDecode(result.Body) as PollResponse;
+		const mcpConnected = data.mcpConnected === true;
+		conn.lastHttpOk = true;
+		conn.lastMcpOk = mcpConnected;
+
+		if (connIndex === State.getActiveTabIndex()) {
+			const el = ui;
+			el.step1Dot.BackgroundColor3 = Color3.fromRGB(34, 197, 94);
+			el.step1Label.Text = "HTTP server (OK)";
+
+			if (mcpConnected && !el.statusLabel.Text.find("Connected")[0]) {
+				el.statusLabel.Text = "Connected";
+				el.statusLabel.TextColor3 = Color3.fromRGB(34, 197, 94);
+				el.statusIndicator.BackgroundColor3 = Color3.fromRGB(34, 197, 94);
+				el.statusPulse.BackgroundColor3 = Color3.fromRGB(34, 197, 94);
+				el.statusText.Text = "ONLINE";
+				el.detailStatusLabel.Text = "HTTP: OK  MCP: OK";
+				el.detailStatusLabel.TextColor3 = Color3.fromRGB(34, 197, 94);
+				el.step2Dot.BackgroundColor3 = Color3.fromRGB(34, 197, 94);
+				el.step2Label.Text = "MCP bridge (OK)";
+				el.step3Dot.BackgroundColor3 = Color3.fromRGB(34, 197, 94);
+				el.step3Label.Text = "Commands (OK)";
+				conn.mcpWaitStartTime = undefined;
+				el.troubleshootLabel.Visible = false;
+				UI.stopPulseAnimation();
+			} else if (!mcpConnected) {
+				el.statusLabel.Text = "Waiting for MCP server";
+				el.statusLabel.TextColor3 = Color3.fromRGB(245, 158, 11);
+				el.statusIndicator.BackgroundColor3 = Color3.fromRGB(245, 158, 11);
+				el.statusPulse.BackgroundColor3 = Color3.fromRGB(245, 158, 11);
+				el.statusText.Text = "WAITING";
+				el.detailStatusLabel.Text = "HTTP: OK  MCP: ...";
+				el.detailStatusLabel.TextColor3 = Color3.fromRGB(245, 158, 11);
+				el.step2Dot.BackgroundColor3 = Color3.fromRGB(245, 158, 11);
+				el.step2Label.Text = "MCP bridge (waiting...)";
+				el.step3Dot.BackgroundColor3 = Color3.fromRGB(245, 158, 11);
+				el.step3Label.Text = "Commands (waiting...)";
+				if (conn.mcpWaitStartTime === undefined) {
+					conn.mcpWaitStartTime = tick();
+				}
+				const elapsed = tick() - (conn.mcpWaitStartTime ?? tick());
+				el.troubleshootLabel.Visible = elapsed > 8;
+				UI.startPulseAnimation();
+			}
+		}
+
+		if (data.request && mcpConnected) {
+			task.spawn(() => {
+				const [ok, response] = pcall(() => processRequest(data.request!));
+				if (ok) {
+					sendResponse(conn, data.requestId!, response);
+				} else {
+					sendResponse(conn, data.requestId!, { error: tostring(response) });
+				}
+			});
+		}
+	} else if (conn.isActive) {
+		conn.consecutiveFailures++;
+
+		if (conn.consecutiveFailures > 1) {
+			conn.currentRetryDelay = math.min(
+				conn.currentRetryDelay * conn.retryBackoffMultiplier,
+				conn.maxRetryDelay,
+			);
+		}
+
+
+		if (connIndex === State.getActiveTabIndex()) {
+			const el = ui;
+			if (conn.consecutiveFailures >= conn.maxFailuresBeforeError) {
+				el.statusLabel.Text = "Server unavailable";
+				el.statusLabel.TextColor3 = Color3.fromRGB(239, 68, 68);
+				el.statusIndicator.BackgroundColor3 = Color3.fromRGB(239, 68, 68);
+				el.statusPulse.BackgroundColor3 = Color3.fromRGB(239, 68, 68);
+				el.statusText.Text = "ERROR";
+				el.detailStatusLabel.Text = "HTTP: X  MCP: X";
+				el.detailStatusLabel.TextColor3 = Color3.fromRGB(239, 68, 68);
+				el.step1Dot.BackgroundColor3 = Color3.fromRGB(239, 68, 68);
+				el.step1Label.Text = "HTTP server (error)";
+				el.step2Dot.BackgroundColor3 = Color3.fromRGB(239, 68, 68);
+				el.step2Label.Text = "MCP bridge (error)";
+				el.step3Dot.BackgroundColor3 = Color3.fromRGB(239, 68, 68);
+				el.step3Label.Text = "Commands (error)";
+				conn.mcpWaitStartTime = undefined;
+				el.troubleshootLabel.Visible = false;
+				UI.stopPulseAnimation();
+			} else if (conn.consecutiveFailures > 5) {
+				const waitTime = math.ceil(conn.currentRetryDelay);
+				el.statusLabel.Text = `Retrying (${waitTime}s)`;
+				el.statusLabel.TextColor3 = Color3.fromRGB(245, 158, 11);
+				el.statusIndicator.BackgroundColor3 = Color3.fromRGB(245, 158, 11);
+				el.statusPulse.BackgroundColor3 = Color3.fromRGB(245, 158, 11);
+				el.statusText.Text = "RETRY";
+				el.detailStatusLabel.Text = "HTTP: ...  MCP: ...";
+				el.detailStatusLabel.TextColor3 = Color3.fromRGB(245, 158, 11);
+				el.step1Dot.BackgroundColor3 = Color3.fromRGB(245, 158, 11);
+				el.step1Label.Text = "HTTP server (retrying...)";
+				el.step2Dot.BackgroundColor3 = Color3.fromRGB(245, 158, 11);
+				el.step2Label.Text = "MCP bridge (retrying...)";
+				el.step3Dot.BackgroundColor3 = Color3.fromRGB(245, 158, 11);
+				el.step3Label.Text = "Commands (retrying...)";
+				conn.mcpWaitStartTime = undefined;
+				el.troubleshootLabel.Visible = false;
+				UI.startPulseAnimation();
+			} else if (conn.consecutiveFailures > 1) {
+				el.statusLabel.Text = `Connecting (attempt ${conn.consecutiveFailures})`;
+				el.statusLabel.TextColor3 = Color3.fromRGB(245, 158, 11);
+				el.statusIndicator.BackgroundColor3 = Color3.fromRGB(245, 158, 11);
+				el.statusPulse.BackgroundColor3 = Color3.fromRGB(245, 158, 11);
+				el.statusText.Text = "CONNECTING";
+				el.detailStatusLabel.Text = "HTTP: ...  MCP: ...";
+				el.detailStatusLabel.TextColor3 = Color3.fromRGB(245, 158, 11);
+				el.step1Dot.BackgroundColor3 = Color3.fromRGB(245, 158, 11);
+				el.step1Label.Text = "HTTP server (connecting...)";
+				el.step2Dot.BackgroundColor3 = Color3.fromRGB(245, 158, 11);
+				el.step2Label.Text = "MCP bridge (connecting...)";
+				el.step3Dot.BackgroundColor3 = Color3.fromRGB(245, 158, 11);
+				el.step3Label.Text = "Commands (connecting...)";
+				conn.mcpWaitStartTime = undefined;
+				el.troubleshootLabel.Visible = false;
+				UI.startPulseAnimation();
+			}
+		}
+	}
+}
+
+
+function activatePlugin(connIndex?: number) {
+	const idx = connIndex ?? State.getActiveTabIndex();
+	const conn = State.getConnection(idx);
+	if (!conn) return;
+
+	const ui = UI.getElements();
+
+	conn.isActive = true;
+	conn.consecutiveFailures = 0;
+	conn.currentRetryDelay = 0.5;
+	ui.screenGui.Enabled = true;
+
+	if (idx === State.getActiveTabIndex()) {
+		conn.serverUrl = ui.urlInput.Text;
+		const [portStr] = conn.serverUrl.match(":(%d+)$");
+		if (portStr) conn.port = tonumber(portStr) ?? conn.port;
+		UI.updateTabLabel(idx);
+		UI.updateUIState();
+	}
+	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;
+			}
+		}
+	});
+}
+
+function deactivatePlugin(connIndex?: number) {
+	const idx = connIndex ?? State.getActiveTabIndex();
+	const conn = State.getConnection(idx);
+	if (!conn) return;
+
+	conn.isActive = false;
+	conn.lastMcpOk = false;
+
+	if (idx === State.getActiveTabIndex()) UI.updateUIState();
+	UI.updateTabDot(idx);
+
+	pcall(() => {
+		HttpService.RequestAsync({
+			Url: `${conn.serverUrl}/disconnect`,
+			Method: "POST",
+			Headers: { "Content-Type": "application/json" },
+			Body: HttpService.JSONEncode({ instanceId, timestamp: tick() }),
+		});
+	});
+
+	if (conn.heartbeatConnection) {
+		conn.heartbeatConnection.Disconnect();
+		conn.heartbeatConnection = undefined;
+	}
+
+	conn.consecutiveFailures = 0;
+	conn.currentRetryDelay = 0.5;
+}
+
+function deactivateAll() {
+	for (let i = 0; i < State.getConnections().size(); i++) {
+		if (State.getConnections()[i].isActive) {
+			deactivatePlugin(i);
+		}
+	}
+}
+
+function checkForUpdates() {
+	task.spawn(() => {
+		const [success, result] = pcall(() => {
+			return HttpService.RequestAsync({
+				Url: "https://registry.npmjs.org/@chrrxs/robloxstudio-mcp/latest",
+				Method: "GET",
+				Headers: { Accept: "application/json" },
+			});
+		});
+
+		if (success && result.Success) {
+			const [ok, data] = pcall(() => HttpService.JSONDecode(result.Body) as { version?: string });
+			if (ok && data?.version) {
+				const latestVersion = data.version;
+				if (Utils.compareVersions(State.CURRENT_VERSION, latestVersion) < 0) {
+					const ui = UI.getElements();
+					ui.updateBannerText.Text = `v${latestVersion} available - github.com/chrrxs/robloxstudio-mcp`;
+					ui.updateBanner.Visible = true;
+					ui.contentFrame.Position = new UDim2(0, 8, 0, 92);
+					ui.contentFrame.Size = new UDim2(1, -16, 1, -100);
+				}
+			}
+		}
+	});
+}
+
+export = {
+	getConnectionStatus,
+	activatePlugin,
+	deactivatePlugin,
+	deactivateAll,
+	checkForUpdates,
+};

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

@@ -0,0 +1,28 @@
+const ChangeHistoryService = game.GetService("ChangeHistoryService");
+
+type RecordingId = string | undefined;
+
+function beginRecording(actionName: string): RecordingId {
+	const [success, result] = pcall(() => ChangeHistoryService.TryBeginRecording(`MCP: ${actionName}`));
+	if (success) {
+		return result as RecordingId;
+	}
+	return undefined;
+}
+
+function finishRecording(recordingId: RecordingId, shouldCommit: boolean) {
+	if (recordingId === undefined) return;
+
+	const operation = shouldCommit
+		? Enum.FinishRecordingOperation.Commit
+		: Enum.FinishRecordingOperation.Cancel;
+
+	pcall(() => {
+		ChangeHistoryService.FinishRecording(recordingId, operation);
+	});
+}
+
+export = {
+	beginRecording,
+	finishRecording,
+};