roblox-mcp-pro 0.2.1 → 0.2.3

package/plugin/RobloxMcpPro.rbxmx

@@ -0,0 +1,3513 @@
+<roblox version="4">
+  <Item class="Script" referent="0">
+    <Properties>
+      <string name="Name">RobloxMcpPro</string>
+      <token name="RunContext">0</token>
+      <string name="Source"><![CDATA[--!strict
+-- roblox-mcp-pro Studio plugin entry point.
+-- Adds a toolbar toggle that connects to the local MCP bridge and long-polls
+-- for commands, dispatching each to its handler.
+
+local HttpService = game:GetService("HttpService")
+
+local Bridge = require(script.Bridge)
+local Dispatcher = require(script.Dispatcher)
+local UI = require(script.UI)
+
+local DEFAULT_URL = "http://127.0.0.1:3690"
+local SETTING_URL = "roblox_mcp_pro_url"
+local SETTING_TOKEN = "roblox_mcp_pro_token"
+local SETTING_AUTOCONNECT = "roblox_mcp_pro_autoconnect"
+local SETTING_SYNCMODE = "roblox_mcp_pro_syncmode"
+
+-- Resolve config from saved plugin settings (falls back to defaults).
+local url = plugin:GetSetting(SETTING_URL) or DEFAULT_URL
+local token = plugin:GetSetting(SETTING_TOKEN)
+local autoConnect = plugin:GetSetting(SETTING_AUTOCONNECT) == true
+local syncMode = plugin:GetSetting(SETTING_SYNCMODE) or "two-way"
+Bridge.configure(url, token)
+
+local toolbar = plugin:CreateToolbar("Roblox MCP Pro")
+local button = toolbar:CreateButton(
+	"RobloxMcpProToggle",
+	"Toggle the Roblox MCP Pro control panel panel",
+	"",
+	"MCP"
+)
+button.ClickableWhenViewportHidden = true
+
+-- Initialize DockWidget GUI
+local widgetInfo = DockWidgetPluginGuiInfo.new(
+	Enum.InitialDockState.Right, -- initial dock state
+	false, -- initially disabled (closed by default)
+	false, -- override previous enabled state (remember layout)
+	300, -- default width
+	300, -- default height
+	250, -- minimum width
+	200  -- minimum height
+)
+local widget = plugin:CreateDockWidgetPluginGui("RobloxMcpProPanel", widgetInfo)
+
+-- Create the UI panel inside the widget
+UI.create(widget, { url = url, token = token, autoConnect = autoConnect, syncMode = syncMode })
+
+local connected = false
+local isSyncing = false
+
+local function log(message: string)
+	print("[roblox-mcp-pro] " .. message)
+end
+
+local RETRY_WAIT = 5 -- seconds to back off while the server is unreachable
+
+local function pollLoop()
+	-- Best-effort enable HTTP for localhost requests.
+	pcall(function()
+		HttpService.HttpEnabled = true
+	end)
+
+	-- Track reachability so we only log on state changes (no per-cycle spam).
+	local reachable = true
+	local announcedDown = false
+
+	-- Reflect reachability immediately. Otherwise the panel sits on "Connecting"
+	-- until the first /dequeue returns, which the long-poll can hold open for up
+	-- to ~25s when no command is waiting.
+	if connected and Bridge.health() then
+		UI.setStatus("Connected")
+	end
+
+	while connected do
+		local command, err = Bridge.dequeue()
+		if not connected then break end -- Safeguard against connection closed while yielding
+		
+		if command then
+			if not reachable then
+				log("reconnected to " .. url)
+			end
+			reachable = true
+			announcedDown = false
+			UI.setStatus("Connected")
+			
+			local ok, result, errMsg = Dispatcher.dispatch(command.tool, command.args)
+			Bridge.respond(command.id, ok, result, errMsg)
+
+			-- Feed execution result to UI console (but not broker-internal probes
+			-- like the dashboard's periodic system_info — only real agent commands).
+			if not command.internal then
+				UI.addLog(command.tool, ok, if ok then nil else errMsg)
+			end
+		elseif err then
+			-- Transport error (server down, HTTP disabled). Warn once per outage.
+			reachable = false
+			UI.setStatus("Offline")
+			if not announcedDown then
+				announcedDown = true
+				warn(
+					"[roblox-mcp-pro] MCP server unreachable at "
+						.. url
+						.. " — retrying every "
+						.. RETRY_WAIT
+						.. "s. Start it (node dist/index.js) and ensure 'Allow HTTP Requests' is on."
+				)
+			end
+			task.wait(RETRY_WAIT)
+		else
+			-- nil command, no error = long-poll timed out; server is up. Loop again.
+			if not reachable then
+				log("reconnected to " .. url)
+			end
+			reachable = true
+			announcedDown = false
+			UI.setStatus("Connected")
+		end
+	end
+end
+
+-- Reflect a sync-status result from the broker in the UI.
+local function applySyncResult(result: any)
+	isSyncing = result.running == true
+	UI.setSyncStatus(isSyncing, result.mode, result.scriptCount)
+end
+
+-- While connected, poll the broker's sync status so the Sync card stays in step
+-- (including sync started by an AI agent rather than this panel).
+local function startSyncRefresher()
+	task.spawn(function()
+		while connected do
+			local st = Bridge.syncStatus()
+			if st then
+				applySyncResult(st)
+			end
+			task.wait(5)
+		end
+	end)
+end
+
+local function setConnected(value: boolean)
+	connected = value
+	-- Tell the broker right away so the dashboard reflects it within ~1s.
+	task.spawn(function()
+		Bridge.notifyPresence(value)
+	end)
+	if value then
+		log("connecting to " .. url)
+		UI.setStatus("Connecting")
+		task.spawn(pollLoop)
+		startSyncRefresher()
+	else
+		log("disconnected")
+		UI.setStatus("Disconnected")
+		isSyncing = false
+		UI.setSyncStatus(false, syncMode, 0)
+	end
+end
+
+-- Connect UI Callbacks
+UI.onConnectionToggled = function(connect: boolean)
+	setConnected(connect)
+end
+
+UI.onAutoConnectChanged = function(enabled: boolean)
+	plugin:SetSetting(SETTING_AUTOCONNECT, enabled)
+	log("auto-connect " .. (if enabled then "enabled" else "disabled"))
+end
+
+UI.onSyncModeChanged = function(mode: string)
+	syncMode = mode
+	plugin:SetSetting(SETTING_SYNCMODE, mode)
+	-- If sync is already running, restart it in the new direction.
+	if connected and isSyncing then
+		task.spawn(function()
+			local result, err = Bridge.syncControl("start", mode)
+			if result then
+				applySyncResult(result)
+			else
+				warn("[roblox-mcp-pro] sync mode change failed: " .. tostring(err))
+			end
+		end)
+	end
+end
+
+UI.onSyncToggled = function(enabled: boolean, mode: string)
+	if not connected then
+		UI.setSyncStatus(false, mode, 0)
+		warn("[roblox-mcp-pro] Connect to the server before enabling sync.")
+		return
+	end
+	task.spawn(function()
+		local action = if enabled then "start" else "stop"
+		local result, err = Bridge.syncControl(action, mode)
+		if result then
+			applySyncResult(result)
+		else
+			isSyncing = false
+			UI.setSyncStatus(false, mode, 0)
+			warn("[roblox-mcp-pro] sync " .. action .. " failed: " .. tostring(err))
+		end
+	end)
+end
+
+UI.onSettingsSaved = function(newUrl: string, newToken: string?)
+	url = newUrl
+	token = newToken
+	plugin:SetSetting(SETTING_URL, newUrl)
+	plugin:SetSetting(SETTING_TOKEN, newToken)
+	Bridge.configure(newUrl, newToken)
+	log("settings updated, URL: " .. newUrl)
+	
+	-- Restart connection if active to apply new URL/Token
+	if connected then
+		setConnected(false)
+		task.wait(0.1)
+		setConnected(true)
+	end
+end
+
+-- Toggle widget visibility via toolbar button
+button.Click:Connect(function()
+	widget.Enabled = not widget.Enabled
+end)
+
+-- Sync button state with widget visibility
+widget:GetPropertyChangedSignal("Enabled"):Connect(function()
+	button:SetActive(widget.Enabled)
+end)
+button:SetActive(widget.Enabled)
+
+plugin.Unloading:Connect(function()
+	-- Best-effort: tell the broker we're going so the dashboard updates fast
+	-- (Studio closing may cut this off; the liveness timeout is the fallback).
+	if connected then
+		Bridge.notifyPresence(false)
+	end
+	connected = false
+end)
+
+-- Auto-connect only when the user opted in (default off). Fixes the old
+-- behavior where the plugin reconnected on its own after a single connect.
+log(("loaded %d tools."):format(Dispatcher.toolCount))
+if autoConnect then
+	log("auto-connect is on; connecting…")
+	setConnected(true)
+else
+	log("click the 'MCP' button on the toolbar or open the panel to connect.")
+	UI.setStatus("Disconnected")
+end
+]]></string>
+    </Properties>
+    <Item class="ModuleScript" referent="1">
+      <Properties>
+        <string name="Name">Bridge</string>
+        <string name="Source"><![CDATA[--!strict
+-- Bridge: HTTP client that talks to the local roblox-mcp-pro server.
+-- Long-polls GET /dequeue for commands and POSTs results to /respond.
+
+local HttpService = game:GetService("HttpService")
+
+local Bridge = {}
+
+local baseUrl = "http://127.0.0.1:3690"
+local authToken: string? = nil
+
+function Bridge.configure(url: string, token: string?)
+	baseUrl = url
+	authToken = token
+end
+
+local function headers(): { [string]: string }
+	local h = { ["Content-Type"] = "application/json" }
+	if authToken and authToken ~= "" then
+		h["x-auth-token"] = authToken
+	end
+	return h
+end
+
+-- Long-poll for the next command.
+-- Returns: command table, or nil if the poll timed out (204), or false + message on error.
+function Bridge.dequeue(): (any, string?)
+	local ok, response = pcall(function()
+		return HttpService:RequestAsync({
+			Url = baseUrl .. "/dequeue",
+			Method = "GET",
+			Headers = headers(),
+		})
+	end)
+	if not ok then
+		return false, tostring(response)
+	end
+	if response.StatusCode == 200 then
+		local decoded = HttpService:JSONDecode(response.Body)
+		return decoded, nil
+	elseif response.StatusCode == 204 then
+		return nil, nil
+	else
+		return false, ("HTTP %d: %s"):format(response.StatusCode, tostring(response.Body))
+	end
+end
+
+-- Post a command result back to the server.
+function Bridge.respond(id: string, success: boolean, result: any, errMsg: string?)
+	local payload = {
+		id = id,
+		ok = success,
+		result = result,
+		error = errMsg,
+	}
+	pcall(function()
+		HttpService:RequestAsync({
+			Url = baseUrl .. "/respond",
+			Method = "POST",
+			Headers = headers(),
+			Body = HttpService:JSONEncode(payload),
+		})
+	end)
+end
+
+-- Push a Studio->server change event (used by sync).
+function Bridge.postEvent(event: { [string]: any })
+	pcall(function()
+		HttpService:RequestAsync({
+			Url = baseUrl .. "/event",
+			Method = "POST",
+			Headers = headers(),
+			Body = HttpService:JSONEncode(event),
+		})
+	end)
+end
+
+-- Drive the shared sync engine on the broker from the plugin UI.
+--   action = "start" | "stop" | "status" | "pull" | "push"
+--   mode   = "two-way" | "studio-to-disk" | "disk-to-studio"  (for "start")
+-- Returns: result table (sync status) on success, or nil + error message.
+function Bridge.syncControl(action: string, mode: string?, roots: { string }?): (any, string?)
+	local ok, response = pcall(function()
+		return HttpService:RequestAsync({
+			Url = baseUrl .. "/plugin/sync",
+			Method = "POST",
+			Headers = headers(),
+			Body = HttpService:JSONEncode({ action = action, mode = mode, roots = roots }),
+		})
+	end)
+	if not ok then
+		return nil, tostring(response)
+	end
+	if response.StatusCode == 200 then
+		local decoded = HttpService:JSONDecode(response.Body)
+		if decoded.ok then
+			return decoded.result, nil
+		end
+		return nil, tostring(decoded.error)
+	elseif response.StatusCode == 404 then
+		return nil, "This server version doesn't support plugin-driven sync (update the MCP server)."
+	end
+	return nil, ("HTTP %d"):format(response.StatusCode)
+end
+
+-- Fetch current sync status from the broker.
+function Bridge.syncStatus(): (any, string?)
+	local ok, response = pcall(function()
+		return HttpService:RequestAsync({
+			Url = baseUrl .. "/plugin/sync",
+			Method = "GET",
+			Headers = headers(),
+		})
+	end)
+	if not ok then
+		return nil, tostring(response)
+	end
+	if response.StatusCode == 200 then
+		local decoded = HttpService:JSONDecode(response.Body)
+		return decoded.result, nil
+	end
+	return nil, ("HTTP %d"):format(response.StatusCode)
+end
+
+-- Tell the broker we just connected/disconnected so the dashboard updates
+-- immediately instead of waiting out the long-poll liveness window.
+function Bridge.notifyPresence(connected: boolean)
+	pcall(function()
+		HttpService:RequestAsync({
+			Url = baseUrl .. "/plugin/status",
+			Method = "POST",
+			Headers = headers(),
+			Body = HttpService:JSONEncode({ connected = connected }),
+		})
+	end)
+end
+
+-- Check server reachability. Returns true if /health responds.
+function Bridge.health(): boolean
+	local ok, response = pcall(function()
+		return HttpService:RequestAsync({
+			Url = baseUrl .. "/health",
+			Method = "GET",
+			Headers = headers(),
+		})
+	end)
+	return ok and response.StatusCode == 200
+end
+
+return Bridge
+]]></string>
+      </Properties>
+    </Item>
+    <Item class="ModuleScript" referent="2">
+      <Properties>
+        <string name="Name">Dispatcher</string>
+        <string name="Source"><![CDATA[--!strict
+-- Dispatcher: route an incoming command to its handler.
+-- Handlers are loaded defensively: one broken handler disables only its own
+-- tool rather than breaking the whole plugin.
+
+local Handlers = script.Parent.Handlers
+
+local HANDLER_NAMES = {
+	execute_luau = "Execute",
+	query_instances = "Query",
+	find_instances = "FindInstances",
+	scene_overview = "SceneOverview",
+	describe_instance = "DescribeInstance",
+	mutate_instances = "Mutate",
+	manage_properties = "Properties",
+	system_info = "System",
+	sync_snapshot = "SyncSnapshot",
+	sync_watch = "SyncWatch",
+	sync_apply = "SyncApply",
+	batch_execute = "Batch",
+	spatial_query = "Spatial",
+	manage_terrain = "Terrain",
+	manage_ui = "UI",
+	ui_preview = "UIPreview",
+	manage_audio = "Audio",
+	manage_animation = "Animation",
+	manage_lighting = "Lighting",
+	manage_effects = "Effects",
+	manage_physics = "Physics",
+	manage_camera = "Camera",
+	manage_tween = "Tween",
+	manage_assets = "Assets",
+	manage_scripts = "Scripts",
+	manage_selection = "Selection",
+	manage_studio = "Studio",
+	manage_logs = "Logs",
+	workspace_state = "WorkspaceState",
+}
+
+local map: { [string]: (any) -> any } = {}
+for tool, moduleName in HANDLER_NAMES do
+	local ok, handler = pcall(function()
+		return require(Handlers[moduleName])
+	end)
+	if ok and type(handler) == "function" then
+		map[tool] = handler
+	else
+		warn(("[roblox-mcp-pro] failed to load handler '%s': %s"):format(moduleName, tostring(handler)))
+	end
+end
+
+local Dispatcher = {}
+
+-- Number of tools successfully loaded (for startup diagnostics).
+Dispatcher.toolCount = 0
+for _ in map do
+	Dispatcher.toolCount += 1
+end
+
+-- Returns: success (boolean), result (any), errorMessage (string?)
+function Dispatcher.dispatch(tool: string, args: any): (boolean, any, string?)
+	local handler = map[tool]
+	if not handler then
+		return false, nil, "Unknown or unavailable tool: " .. tostring(tool)
+	end
+	local ok, result = pcall(handler, args)
+	if ok then
+		return true, result, nil
+	else
+		return false, nil, tostring(result)
+	end
+end
+
+return Dispatcher
+]]></string>
+      </Properties>
+    </Item>
+    <Item class="Folder" referent="3">
+      <Properties>
+        <string name="Name">Handlers</string>
+      </Properties>
+      <Item class="ModuleScript" referent="4">
+        <Properties>
+          <string name="Name">Animation</string>
+          <string name="Source"><![CDATA[--!strict
+-- Handler for manage_animation: manage Animation instances and best-effort preview.
+
+local ChangeHistoryService = game:GetService("ChangeHistoryService")
+local Serialize = require(script.Parent.Parent.Serialize)
+
+return function(args: any): any
+	local action = args.action or "create"
+
+	if action == "create" then
+		local recording = ChangeHistoryService:TryBeginRecording("MCP manage_animation create")
+		local parent = Serialize.resolve(args.parent or "ReplicatedStorage")
+		if not parent then
+			return { ok = false, error = "parent not found: " .. tostring(args.parent) }
+		end
+		local anim = Instance.new("Animation")
+		if args.name then
+			anim.Name = args.name
+		end
+		if args.animation_id then
+			anim.AnimationId = tostring(args.animation_id)
+		end
+		local err = Serialize.applyProperties(anim, args.properties)
+		anim.Parent = parent
+		if recording then
+			ChangeHistoryService:FinishRecording(recording, Enum.FinishRecordingOperation.Commit)
+		end
+		return { ok = err == nil, path = Serialize.path(anim), error = err }
+	elseif action == "set" then
+		local inst = args.path and Serialize.resolve(args.path) or nil
+		if not inst then
+			return { ok = false, error = "path not found: " .. tostring(args.path) }
+		end
+		local err = Serialize.applyProperties(inst, args.properties)
+		return { ok = err == nil, path = Serialize.path(inst), error = err }
+	elseif action == "play" then
+		-- Best effort: load+play on a Humanoid/AnimationController's Animator.
+		local target = args.target_path and Serialize.resolve(args.target_path) or nil
+		if not target then
+			return { ok = false, error = "target_path (a Humanoid or model) not found" }
+		end
+		local animator = target:FindFirstChildWhichIsA("Animator", true)
+		if not animator then
+			local humanoid = target:FindFirstChildWhichIsA("Humanoid")
+			if humanoid then
+				animator = humanoid:FindFirstChildWhichIsA("Animator")
+			end
+		end
+		if not animator then
+			return { ok = false, error = "no Animator found under target; play requires a rig with a Humanoid/Animator" }
+		end
+		local anim = Instance.new("Animation")
+		anim.AnimationId = tostring(args.animation_id or "")
+		local ok, track = pcall(function()
+			return (animator :: Animator):LoadAnimation(anim)
+		end)
+		if not ok or not track then
+			return { ok = false, error = "failed to load animation (check AnimationId): " .. tostring(track) }
+		end
+		track:Play()
+		return {
+			ok = true,
+			note = "Playing. Visible preview of programmatic playback may require Play mode.",
+			length = track.Length,
+		}
+	else
+		return { ok = false, error = "unknown manage_animation action: " .. tostring(action) }
+	end
+end
+]]></string>
+        </Properties>
+      </Item>
+      <Item class="ModuleScript" referent="5">
+        <Properties>
+          <string name="Name">Assets</string>
+          <string name="Source"><![CDATA[--!strict
+-- Handler for manage_assets: insert marketplace assets by id.
+
+local InsertService = game:GetService("InsertService")
+local MarketplaceService = game:GetService("MarketplaceService")
+local ChangeHistoryService = game:GetService("ChangeHistoryService")
+local Serialize = require(script.Parent.Parent.Serialize)
+
+return function(args: any): any
+	local action = args.action or "insert"
+
+	if action == "insert" then
+		local assetId = tonumber(args.asset_id)
+		if not assetId then
+			return { ok = false, error = "asset_id (a number) is required" }
+		end
+		local parent = Serialize.resolve(args.parent or "Workspace") or workspace
+		local recording = ChangeHistoryService:TryBeginRecording("MCP manage_assets insert")
+		local ok, model = pcall(function()
+			return InsertService:LoadAsset(assetId)
+		end)
+		if not ok or not model then
+			if recording then
+				ChangeHistoryService:FinishRecording(recording, Enum.FinishRecordingOperation.Cancel)
+			end
+			return { ok = false, error = "LoadAsset failed (check id/permissions): " .. tostring(model) }
+		end
+		local inserted = {}
+		for _, child in model:GetChildren() do
+			child.Parent = parent
+			table.insert(inserted, Serialize.path(child))
+		end
+		model:Destroy()
+		if recording then
+			ChangeHistoryService:FinishRecording(recording, Enum.FinishRecordingOperation.Commit)
+		end
+		return { ok = true, inserted = inserted }
+	elseif action == "info" then
+		local assetId = tonumber(args.asset_id)
+		if not assetId then
+			return { ok = false, error = "asset_id (a number) is required" }
+		end
+		local ok, info = pcall(function()
+			return MarketplaceService:GetProductInfo(assetId)
+		end)
+		if not ok then
+			return { ok = false, error = "GetProductInfo failed: " .. tostring(info) }
+		end
+		return { ok = true, info = { name = info.Name, description = info.Description, creator = info.Creator and info.Creator.Name } }
+	else
+		return { ok = false, error = "unknown manage_assets action: " .. tostring(action) }
+	end
+end
+]]></string>
+        </Properties>
+      </Item>
+      <Item class="ModuleScript" referent="6">
+        <Properties>
+          <string name="Name">Audio</string>
+          <string name="Source"><![CDATA[--!strict
+-- Handler for manage_audio: create, configure, and preview Sound instances.
+
+local ChangeHistoryService = game:GetService("ChangeHistoryService")
+local Serialize = require(script.Parent.Parent.Serialize)
+
+return function(args: any): any
+	local action = args.action or "create"
+
+	if action == "create" then
+		local recording = ChangeHistoryService:TryBeginRecording("MCP manage_audio create")
+		local parent = Serialize.resolve(args.parent or "Workspace")
+		if not parent then
+			return { ok = false, error = "parent not found: " .. tostring(args.parent) }
+		end
+		local sound = Instance.new("Sound")
+		if args.name then
+			sound.Name = args.name
+		end
+		local err = Serialize.applyProperties(sound, args.properties)
+		sound.Parent = parent
+		if recording then
+			ChangeHistoryService:FinishRecording(recording, Enum.FinishRecordingOperation.Commit)
+		end
+		return { ok = err == nil, path = Serialize.path(sound), error = err }
+	end
+
+	-- Remaining actions operate on an existing Sound.
+	local inst = args.path and Serialize.resolve(args.path) or nil
+	if not inst or not inst:IsA("Sound") then
+		return { ok = false, error = "Sound not found at: " .. tostring(args.path) }
+	end
+	local sound = inst :: Sound
+
+	if action == "set" then
+		local err = Serialize.applyProperties(sound, args.properties)
+		return { ok = err == nil, path = Serialize.path(sound), error = err }
+	elseif action == "play" then
+		sound:Play()
+		return { ok = true, path = Serialize.path(sound), isPlaying = sound.IsPlaying }
+	elseif action == "stop" then
+		sound:Stop()
+		return { ok = true, path = Serialize.path(sound) }
+	elseif action == "pause" then
+		sound:Pause()
+		return { ok = true, path = Serialize.path(sound) }
+	elseif action == "resume" then
+		sound:Resume()
+		return { ok = true, path = Serialize.path(sound) }
+	else
+		return { ok = false, error = "unknown manage_audio action: " .. tostring(action) }
+	end
+end
+]]></string>
+        </Properties>
+      </Item>
+      <Item class="ModuleScript" referent="7">
+        <Properties>
+          <string name="Name">Batch</string>
+          <string name="Source"><![CDATA[--!strict
+-- Handler for batch_execute: run several sub-commands in one round-trip,
+-- wrapped in a single undo recording.
+
+local ChangeHistoryService = game:GetService("ChangeHistoryService")
+
+return function(args: any): any
+	-- Deferred require avoids a load-time cycle (Dispatcher requires this module).
+	local Dispatcher = require(script.Parent.Parent.Dispatcher)
+
+	local operations = args.operations or {}
+	local stopOnError = args.stop_on_error == true
+
+	local recording = ChangeHistoryService:TryBeginRecording("MCP batch_execute")
+	local results: { any } = {}
+	for _, op in operations do
+		local ok, result, errMsg = Dispatcher.dispatch(op.tool, op.args)
+		table.insert(results, { ok = ok, result = result, error = errMsg })
+		if not ok and stopOnError then
+			break
+		end
+	end
+	if recording then
+		ChangeHistoryService:FinishRecording(recording, Enum.FinishRecordingOperation.Commit)
+	end
+	return { results = results }
+end
+]]></string>
+        </Properties>
+      </Item>
+      <Item class="ModuleScript" referent="8">
+        <Properties>
+          <string name="Name">Camera</string>
+          <string name="Source"><![CDATA[--!strict
+-- Handler for manage_camera: read/control Workspace.CurrentCamera.
+
+local Workspace = game:GetService("Workspace")
+local Serialize = require(script.Parent.Parent.Serialize)
+
+local function toVector3(t: any, default: Vector3?): Vector3
+	if type(t) == "table" then
+		return Vector3.new(t.x or t[1] or 0, t.y or t[2] or 0, t.z or t[3] or 0)
+	end
+	return default or Vector3.zero
+end
+
+return function(args: any): any
+	local camera = Workspace.CurrentCamera
+	if not camera then
+		return { ok = false, error = "no CurrentCamera" }
+	end
+	local action = args.action or "get"
+
+	if action == "get" then
+		return {
+			ok = true,
+			cframe = Serialize.value(camera.CFrame),
+			position = Serialize.value(camera.CFrame.Position),
+			fieldOfView = camera.FieldOfView,
+			cameraType = camera.CameraType.Name,
+		}
+	elseif action == "set" then
+		local err = Serialize.applyProperties(camera, args.properties)
+		return { ok = err == nil, error = err }
+	elseif action == "focus" then
+		-- Point the camera from `position` toward a target point or instance.
+		local targetPos: Vector3
+		if args.target_path then
+			local inst = Serialize.resolve(args.target_path)
+			if inst and inst:IsA("BasePart") then
+				targetPos = inst.Position
+			elseif inst and inst:IsA("Model") then
+				targetPos = inst:GetPivot().Position
+			else
+				return { ok = false, error = "target_path not found or has no position" }
+			end
+		else
+			targetPos = toVector3(args.look_at)
+		end
+		local fromPos = args.position and toVector3(args.position) or (targetPos + Vector3.new(0, 10, 20))
+		camera.CFrame = CFrame.lookAt(fromPos, targetPos)
+		return { ok = true, cframe = Serialize.value(camera.CFrame) }
+	else
+		return { ok = false, error = "unknown manage_camera action: " .. tostring(action) }
+	end
+end
+]]></string>
+        </Properties>
+      </Item>
+      <Item class="ModuleScript" referent="9">
+        <Properties>
+          <string name="Name">DescribeInstance</string>
+          <string name="Source"><![CDATA[--!strict
+-- Handler for describe_instance: everything about one instance in a single call —
+-- properties (optionally projected), child list, and ancestry — so an agent
+-- doesn't need separate query/property/parent round-trips.
+
+local Serialize = require(script.Parent.Parent.Serialize)
+
+return function(args: any): any
+	local path = args.path
+	if not path then
+		error("path is required")
+	end
+	local inst = Serialize.resolve(path)
+	if not inst then
+		error("Path not found: " .. tostring(path))
+	end
+
+	local props = args.props
+	local hasProjection = type(props) == "table" and #props > 0
+
+	local out: any = {
+		path = Serialize.path(inst),
+		name = inst.Name,
+		className = inst.ClassName,
+		childCount = #inst:GetChildren(),
+		properties = Serialize.properties(inst, if hasProjection then props else nil),
+	}
+
+	-- Ancestry chain (name + class), root-first, excluding `game`.
+	local ancestors: { any } = {}
+	local cur: Instance? = inst.Parent
+	while cur and cur ~= game do
+		table.insert(ancestors, 1, { name = cur.Name, class = cur.ClassName })
+		cur = cur.Parent
+	end
+	out.ancestors = ancestors
+
+	if args.children ~= false then
+		local kids = inst:GetChildren()
+		local maxKids = args.max_children or 100
+		local children: { any } = {}
+		for i = 1, math.min(#kids, maxKids) do
+			local k = kids[i]
+			table.insert(children, { name = k.Name, class = k.ClassName, n = #k:GetChildren() })
+		end
+		out.children = children
+		if #kids > maxKids then
+			out.moreChildren = #kids - maxKids
+		end
+	end
+
+	return out
+end
+]]></string>
+        </Properties>
+      </Item>
+      <Item class="ModuleScript" referent="10">
+        <Properties>
+          <string name="Name">Effects</string>
+          <string name="Source"><![CDATA[--!strict
+-- Handler for manage_effects: create/configure post-processing & atmosphere
+-- effects (BloomEffect, BlurEffect, ColorCorrectionEffect, DepthOfFieldEffect,
+-- SunRaysEffect, Atmosphere, Sky) under Lighting by default.
+
+local Lighting = game:GetService("Lighting")
+local ChangeHistoryService = game:GetService("ChangeHistoryService")
+local Serialize = require(script.Parent.Parent.Serialize)
+
+return function(args: any): any
+	local action = args.action or "create"
+	local recording = ChangeHistoryService:TryBeginRecording("MCP manage_effects")
+	local result: any
+
+	if action == "create" then
+		local parent = Serialize.resolve(args.parent or "Lighting") or Lighting
+		local okNew, inst = pcall(function()
+			return Instance.new(args.effect_type)
+		end)
+		if not okNew or not inst then
+			result = { ok = false, error = "invalid effect_type: " .. tostring(args.effect_type) }
+		else
+			if args.name then
+				inst.Name = args.name
+			end
+			local err = Serialize.applyProperties(inst, args.properties)
+			inst.Parent = parent
+			result = { ok = err == nil, path = Serialize.path(inst), error = err }
+		end
+	elseif action == "set" then
+		local inst = args.path and Serialize.resolve(args.path) or nil
+		if not inst then
+			result = { ok = false, error = "path not found: " .. tostring(args.path) }
+		else
+			local err = Serialize.applyProperties(inst, args.properties)
+			result = { ok = err == nil, path = Serialize.path(inst), error = err }
+		end
+	elseif action == "delete" then
+		local inst = args.path and Serialize.resolve(args.path) or nil
+		if not inst then
+			result = { ok = false, error = "path not found: " .. tostring(args.path) }
+		else
+			inst:Destroy()
+			result = { ok = true }
+		end
+	else
+		result = { ok = false, error = "unknown manage_effects action: " .. tostring(action) }
+	end
+
+	if recording then
+		ChangeHistoryService:FinishRecording(
+			recording,
+			result.ok and Enum.FinishRecordingOperation.Commit or Enum.FinishRecordingOperation.Cancel
+		)
+	end
+	return result
+end
+]]></string>
+        </Properties>
+      </Item>
+      <Item class="ModuleScript" referent="11">
+        <Properties>
+          <string name="Name">Execute</string>
+          <string name="Source"><![CDATA[--!strict
+-- Handler for execute_luau: compile and run Luau, capturing output and returns.
+
+local LogService = game:GetService("LogService")
+local Serialize = require(script.Parent.Parent.Serialize)
+
+return function(args: any): any
+	local code = args.code
+	local timeoutMs = args.timeout_ms or 5000
+
+	if type(code) ~= "string" or code == "" then
+		return { ok = false, returns = {}, output = "", error = "No code provided" }
+	end
+	if type(loadstring) ~= "function" then
+		return {
+			ok = false,
+			returns = {},
+			output = "",
+			error = "loadstring is unavailable in this Studio session. Enable it or run a different action.",
+		}
+	end
+
+	local chunk, compileErr = loadstring(code)
+	if not chunk then
+		return { ok = false, returns = {}, output = "", error = "Compile error: " .. tostring(compileErr) }
+	end
+
+	-- Capture print/warn output for the duration of execution.
+	local logs: { string } = {}
+	local conn = LogService.MessageOut:Connect(function(message: string)
+		table.insert(logs, message)
+	end)
+
+	local results: { any } = {}
+	local runOk = false
+	local runErr: string? = nil
+	local finished = false
+
+	local co = coroutine.create(function()
+		local packed = table.pack(pcall(chunk))
+		runOk = packed[1]
+		if runOk then
+			for i = 2, packed.n do
+				table.insert(results, packed[i])
+			end
+		else
+			runErr = tostring(packed[2])
+		end
+		finished = true
+	end)
+
+	coroutine.resume(co)
+
+	-- Wait up to the deadline for non-yielding or briefly-yielding code.
+	local deadline = os.clock() + (timeoutMs / 1000)
+	while not finished and os.clock() < deadline do
+		task.wait()
+	end
+
+	conn:Disconnect()
+
+	if not finished then
+		return {
+			ok = false,
+			returns = {},
+			output = table.concat(logs, "\n"),
+			error = ("Execution exceeded %dms (the code may be yielding)."):format(timeoutMs),
+		}
+	end
+
+	local serialized: { any } = {}
+	for _, v in results do
+		table.insert(serialized, Serialize.value(v))
+	end
+
+	return {
+		ok = runOk,
+		returns = serialized,
+		output = table.concat(logs, "\n"),
+		error = runErr,
+	}
+end
+]]></string>
+        </Properties>
+      </Item>
+      <Item class="ModuleScript" referent="12">
+        <Properties>
+          <string name="Name">FindInstances</string>
+          <string name="Source"><![CDATA[--!strict
+-- Handler for find_instances: a targeted search that cuts round-trips by
+-- filtering on several criteria at once and returning a compact, grouped result
+-- (or paths / full) instead of dumping every match.
+
+local CollectionService = game:GetService("CollectionService")
+local Serialize = require(script.Parent.Parent.Serialize)
+
+-- Compare a live property value against a JSON-supplied expected value.
+-- Only primitives are compared directly; everything else goes through
+-- Serialize.value so e.g. Material "Neon" or Color [r,g,b] can match.
+local function propMatches(inst: Instance, key: string, expected: any): boolean
+	local ok, val = pcall(function()
+		return (inst :: any)[key]
+	end)
+	if not ok then
+		return false
+	end
+	local t = typeof(val)
+	if t == "boolean" or t == "number" or t == "string" then
+		return val == expected
+	end
+	-- Structured value: compare serialized form (string compare via JSON-ish).
+	local sv = Serialize.value(val)
+	return Serialize.shallowEqual(sv, expected)
+end
+
+return function(args: any): any
+	local rootPath = args.path or "game"
+	local className = args.class_name
+	local nameSub = args.name
+	local namePattern = args.name_pattern
+	local tag = args.tag
+	local matchProps = args.match_props
+	local recursive = args.recursive
+	if recursive == nil then
+		recursive = true
+	end
+	local mode = args.mode or "grouped"
+	local limit = args.limit or 200
+	local projection = args.props
+
+	local root = Serialize.resolve(rootPath)
+	if not root then
+		error("Path not found: " .. tostring(rootPath))
+	end
+
+	local candidates: { Instance }
+	if tag then
+		-- Tag search is global; intersect with the root subtree below.
+		candidates = CollectionService:GetTagged(tag)
+	else
+		candidates = recursive and root:GetDescendants() or root:GetChildren()
+	end
+
+	local matched: { Instance } = {}
+	for _, inst in candidates do
+		if tag and inst ~= root and not inst:IsDescendantOf(root) then
+			continue
+		end
+		if className and inst.ClassName ~= className then
+			continue
+		end
+		if nameSub and not string.find(inst.Name, nameSub, 1, true) then
+			continue
+		end
+		if namePattern and not string.match(inst.Name, namePattern) then
+			continue
+		end
+		if matchProps then
+			local allOk = true
+			for k, expected in matchProps do
+				if not propMatches(inst, k, expected) then
+					allOk = false
+					break
+				end
+			end
+			if not allOk then
+				continue
+			end
+		end
+		table.insert(matched, inst)
+	end
+
+	local total = #matched
+
+	if mode == "count" then
+		local byClass: { [string]: number } = {}
+		for _, inst in matched do
+			byClass[inst.ClassName] = (byClass[inst.ClassName] or 0) + 1
+		end
+		return { total = total, byClass = byClass }
+	elseif mode == "paths" then
+		local paths: { string } = {}
+		for i = 1, math.min(limit, total) do
+			table.insert(paths, Serialize.path(matched[i]))
+		end
+		return { total = total, paths = paths, truncated = total > limit }
+	elseif mode == "full" then
+		local instances: { any } = {}
+		local hasProj = type(projection) == "table" and #projection > 0
+		for i = 1, math.min(limit, total) do
+			local inst = matched[i]
+			table.insert(instances, {
+				path = Serialize.path(inst),
+				name = inst.Name,
+				className = inst.ClassName,
+				properties = Serialize.properties(inst, if hasProj then projection else nil),
+			})
+		end
+		return { total = total, instances = instances, truncated = total > limit }
+	else
+		-- grouped (default): collapse by (parent path + class) -> count + sample.
+		local order: { string } = {}
+		local groups: { [string]: any } = {}
+		for _, inst in matched do
+			local parent = inst.Parent and Serialize.path(inst.Parent) or "?"
+			local key = parent .. "\0" .. inst.ClassName
+			local g = groups[key]
+			if g then
+				g.count += 1
+			else
+				g = { parent = parent, class = inst.ClassName, count = 1, sample = inst.Name }
+				groups[key] = g
+				table.insert(order, key)
+			end
+		end
+		local out: { any } = {}
+		for i = 1, math.min(limit, #order) do
+			table.insert(out, groups[order[i]])
+		end
+		return { total = total, groups = out, truncated = #order > limit }
+	end
+end
+]]></string>
+        </Properties>
+      </Item>
+      <Item class="ModuleScript" referent="13">
+        <Properties>
+          <string name="Name">Lighting</string>
+          <string name="Source"><![CDATA[--!strict
+-- Handler for manage_lighting: read/write Lighting service properties.
+
+local Lighting = game:GetService("Lighting")
+local ChangeHistoryService = game:GetService("ChangeHistoryService")
+local Serialize = require(script.Parent.Parent.Serialize)
+
+local LIGHTING_PROPS = {
+	"Ambient", "OutdoorAmbient", "Brightness", "ClockTime", "GeographicLatitude",
+	"FogColor", "FogStart", "FogEnd", "ExposureCompensation", "EnvironmentDiffuseScale",
+	"EnvironmentSpecularScale", "GlobalShadows", "ShadowSoftness", "Technology",
+}
+
+return function(args: any): any
+	local action = args.action or "get"
+	if action == "get" then
+		local props = {}
+		for _, name in LIGHTING_PROPS do
+			local ok, val = pcall(function()
+				return (Lighting :: any)[name]
+			end)
+			if ok then
+				props[name] = Serialize.value(val)
+			end
+		end
+		return { ok = true, properties = props }
+	elseif action == "set" then
+		local recording = ChangeHistoryService:TryBeginRecording("MCP manage_lighting")
+		local err = Serialize.applyProperties(Lighting, args.properties)
+		if recording then
+			ChangeHistoryService:FinishRecording(
+				recording,
+				err == nil and Enum.FinishRecordingOperation.Commit or Enum.FinishRecordingOperation.Cancel
+			)
+		end
+		return { ok = err == nil, error = err }
+	else
+		return { ok = false, error = "unknown manage_lighting action: " .. tostring(action) }
+	end
+end
+]]></string>
+        </Properties>
+      </Item>
+      <Item class="ModuleScript" referent="14">
+        <Properties>
+          <string name="Name">Logs</string>
+          <string name="Source"><![CDATA[--!strict
+-- Handler for manage_logs: return recent Studio output log history.
+
+local LogService = game:GetService("LogService")
+
+local TYPE_NAMES = {
+	[Enum.MessageType.MessageOutput] = "output",
+	[Enum.MessageType.MessageInfo] = "info",
+	[Enum.MessageType.MessageWarning] = "warning",
+	[Enum.MessageType.MessageError] = "error",
+}
+
+return function(args: any): any
+	local limit = args.limit or 100
+	local filter = args.message_type -- optional: "output"|"info"|"warning"|"error"
+
+	local history = LogService:GetLogHistory()
+	local out = {}
+	-- Walk newest-first.
+	for i = #history, 1, -1 do
+		local entry = history[i]
+		local typeName = TYPE_NAMES[entry.messageType] or "output"
+		if not filter or typeName == filter then
+			table.insert(out, { message = entry.message, type = typeName, timestamp = entry.timestamp })
+			if #out >= limit then
+				break
+			end
+		end
+	end
+	return { ok = true, count = #out, logs = out }
+end
+]]></string>
+        </Properties>
+      </Item>
+      <Item class="ModuleScript" referent="15">
+        <Properties>
+          <string name="Name">Mutate</string>
+          <string name="Source"><![CDATA[--!strict
+-- Handler for mutate_instances: create/edit/move/clone/delete instances.
+
+local ChangeHistoryService = game:GetService("ChangeHistoryService")
+local Serialize = require(script.Parent.Parent.Serialize)
+
+local PROTECTED = {
+	CoreGui = true,
+	CorePackages = true,
+	CoreScripts = true,
+}
+
+local function isProtected(inst: Instance?): boolean
+	local current = inst
+	while current and current ~= game do
+		if PROTECTED[current.Name] then
+			return true
+		end
+		current = current.Parent
+	end
+	return false
+end
+
+local applyProperties = Serialize.applyProperties
+
+local function doOperation(op: any): any
+	local action = op.action
+
+	if action == "create" then
+		local className = op.class_name
+		if type(className) ~= "string" then
+			return { ok = false, action = action, error = "create requires class_name" }
+		end
+		local parentPath = op.parent or op.path
+		local parent = parentPath and Serialize.resolve(parentPath) or nil
+		if not parent then
+			return { ok = false, action = action, error = "parent not found: " .. tostring(parentPath) }
+		end
+		if isProtected(parent) then
+			return { ok = false, action = action, error = "parent is a protected service" }
+		end
+		local okNew, inst = pcall(function()
+			return Instance.new(className)
+		end)
+		if not okNew then
+			return { ok = false, action = action, error = "invalid ClassName: " .. tostring(className) }
+		end
+		if op.name then
+			inst.Name = op.name
+		end
+		local propErr = applyProperties(inst, op.properties)
+		inst.Parent = parent
+		return {
+			ok = propErr == nil,
+			action = action,
+			resultPath = Serialize.path(inst),
+			error = propErr,
+		}
+	end
+
+	-- All other actions need an existing target.
+	local target = op.path and Serialize.resolve(op.path) or nil
+	if not target then
+		return { ok = false, action = action, error = "path not found: " .. tostring(op.path) }
+	end
+	if isProtected(target) then
+		return { ok = false, action = action, path = op.path, error = "target is a protected service" }
+	end
+
+	if action == "set_properties" then
+		local err = applyProperties(target, op.properties)
+		return { ok = err == nil, action = action, path = Serialize.path(target), error = err }
+	elseif action == "rename" then
+		if type(op.name) ~= "string" then
+			return { ok = false, action = action, error = "rename requires name" }
+		end
+		target.Name = op.name
+		return { ok = true, action = action, resultPath = Serialize.path(target) }
+	elseif action == "reparent" then
+		local newParent = op.parent and Serialize.resolve(op.parent) or nil
+		if not newParent then
+			return { ok = false, action = action, error = "parent not found: " .. tostring(op.parent) }
+		end
+		target.Parent = newParent
+		return { ok = true, action = action, resultPath = Serialize.path(target) }
+	elseif action == "delete" then
+		local p = Serialize.path(target)
+		target:Destroy()
+		return { ok = true, action = action, path = p }
+	elseif action == "clone" then
+		local clone = target:Clone()
+		if not clone then
+			return { ok = false, action = action, error = "instance is not Archivable" }
+		end
+		if op.name then
+			clone.Name = op.name
+		end
+		local newParent = (op.parent and Serialize.resolve(op.parent)) or target.Parent
+		clone.Parent = newParent
+		return { ok = true, action = action, resultPath = Serialize.path(clone) }
+	else
+		return { ok = false, action = action, error = "unknown action: " .. tostring(action) }
+	end
+end
+
+return function(args: any): any
+	local operations = args.operations or {}
+	local recording = ChangeHistoryService:TryBeginRecording("MCP mutate_instances")
+	local results: { any } = {}
+	for _, op in operations do
+		local ok, res = pcall(doOperation, op)
+		if ok then
+			table.insert(results, res)
+		else
+			table.insert(results, { ok = false, action = op.action, error = tostring(res) })
+		end
+	end
+	if recording then
+		ChangeHistoryService:FinishRecording(recording, Enum.FinishRecordingOperation.Commit)
+	end
+	return { results = results }
+end
+]]></string>
+        </Properties>
+      </Item>
+      <Item class="ModuleScript" referent="16">
+        <Properties>
+          <string name="Name">Physics</string>
+          <string name="Source"><![CDATA[--!strict
+-- Handler for manage_physics: physical properties and simple welds.
+
+local ChangeHistoryService = game:GetService("ChangeHistoryService")
+local Serialize = require(script.Parent.Parent.Serialize)
+
+return function(args: any): any
+	local action = args.action or "set"
+	local recording = ChangeHistoryService:TryBeginRecording("MCP manage_physics")
+	local result: any
+
+	if action == "set" then
+		local inst = args.path and Serialize.resolve(args.path) or nil
+		if not inst or not inst:IsA("BasePart") then
+			result = { ok = false, error = "BasePart not found at: " .. tostring(args.path) }
+		else
+			local part = inst :: BasePart
+			local err = Serialize.applyProperties(part, args.properties)
+			-- Optional custom physical properties.
+			local pp = args.physical_properties
+			if not err and type(pp) == "table" then
+				local okPP = pcall(function()
+					part.CustomPhysicalProperties = PhysicalProperties.new(
+						pp.density or 0.7,
+						pp.friction or 0.3,
+						pp.elasticity or 0.5,
+						pp.frictionWeight or 1,
+						pp.elasticityWeight or 1
+					)
+				end)
+				if not okPP then
+					err = "failed to set CustomPhysicalProperties"
+				end
+			end
+			result = { ok = err == nil, path = Serialize.path(part), error = err }
+		end
+	elseif action == "weld" then
+		local a = args.part0 and Serialize.resolve(args.part0) or nil
+		local b = args.part1 and Serialize.resolve(args.part1) or nil
+		if not a or not a:IsA("BasePart") or not b or not b:IsA("BasePart") then
+			result = { ok = false, error = "part0 and part1 must both be BaseParts" }
+		else
+			local weld = Instance.new("WeldConstraint")
+			weld.Part0 = a :: BasePart
+			weld.Part1 = b :: BasePart
+			weld.Parent = a
+			result = { ok = true, path = Serialize.path(weld) }
+		end
+	else
+		result = { ok = false, error = "unknown manage_physics action: " .. tostring(action) }
+	end
+
+	if recording then
+		ChangeHistoryService:FinishRecording(
+			recording,
+			result.ok and Enum.FinishRecordingOperation.Commit or Enum.FinishRecordingOperation.Cancel
+		)
+	end
+	return result
+end
+]]></string>
+        </Properties>
+      </Item>
+      <Item class="ModuleScript" referent="17">
+        <Properties>
+          <string name="Name">Properties</string>
+          <string name="Source"><![CDATA[--!strict
+-- Handler for manage_properties: read/write properties on any instance.
+
+local ChangeHistoryService = game:GetService("ChangeHistoryService")
+local Serialize = require(script.Parent.Parent.Serialize)
+
+return function(args: any): any
+	local inst = args.path and Serialize.resolve(args.path) or nil
+	if not inst then
+		return { ok = false, error = "path not found: " .. tostring(args.path) }
+	end
+	local action = args.action or "get"
+
+	if action == "get" then
+		if type(args.names) == "table" then
+			local props: { [string]: any } = {}
+			for _, name in args.names do
+				local ok, val = pcall(function()
+					return (inst :: any)[name]
+				end)
+				props[name] = ok and Serialize.value(val) or nil
+			end
+			return { ok = true, path = Serialize.path(inst), properties = props }
+		end
+		return { ok = true, path = Serialize.path(inst), properties = Serialize.properties(inst) }
+	elseif action == "set" then
+		local recording = ChangeHistoryService:TryBeginRecording("MCP manage_properties")
+		local err = Serialize.applyProperties(inst, args.properties)
+		if recording then
+			ChangeHistoryService:FinishRecording(
+				recording,
+				err == nil and Enum.FinishRecordingOperation.Commit or Enum.FinishRecordingOperation.Cancel
+			)
+		end
+		return { ok = err == nil, path = Serialize.path(inst), error = err }
+	else
+		return { ok = false, error = "unknown manage_properties action: " .. tostring(action) }
+	end
+end
+]]></string>
+        </Properties>
+      </Item>
+      <Item class="ModuleScript" referent="18">
+        <Properties>
+          <string name="Name">Query</string>
+          <string name="Source"><![CDATA[--!strict
+-- Handler for query_instances: search the DataModel and serialize matches.
+
+local Serialize = require(script.Parent.Parent.Serialize)
+
+return function(args: any): any
+	local path = args.path or "game"
+	local className = args.class_name
+	local nameFilter = args.name
+	local recursive = args.recursive
+	if recursive == nil then
+		recursive = true
+	end
+	local props = args.props -- optional { string } projection
+	local hasProjection = type(props) == "table" and #props > 0
+	local includeProps = args.include_properties == true or hasProjection
+	local limit = args.limit or 100
+	local offset = args.offset or 0
+
+	local root = Serialize.resolve(path)
+	if not root then
+		error("Path not found: " .. tostring(path))
+	end
+
+	local candidates: { Instance } = recursive and root:GetDescendants() or root:GetChildren()
+
+	local matched: { Instance } = {}
+	for _, inst in candidates do
+		if className and inst.ClassName ~= className then
+			continue
+		end
+		if nameFilter and not string.find(inst.Name, nameFilter, 1, true) then
+			continue
+		end
+		table.insert(matched, inst)
+	end
+
+	local total = #matched
+	local instances: { any } = {}
+	for i = offset + 1, math.min(offset + limit, total) do
+		local inst = matched[i]
+		local dto: any = {
+			path = Serialize.path(inst),
+			name = inst.Name,
+			className = inst.ClassName,
+			childCount = #inst:GetChildren(),
+		}
+		if includeProps then
+			dto.properties = Serialize.properties(inst, if hasProjection then props else nil)
+		end
+		table.insert(instances, dto)
+	end
+
+	return { total = total, instances = instances }
+end
+]]></string>
+        </Properties>
+      </Item>
+      <Item class="ModuleScript" referent="19">
+        <Properties>
+          <string name="Name">SceneOverview</string>
+          <string name="Source"><![CDATA[--!strict
+-- Handler for scene_overview: one-call summary of the DataModel so an agent can
+-- orient itself without many query_instances round-trips. Returns a class
+-- histogram (counting only — cheap) plus a shallow, breadth-capped tree whose
+-- duplicate leaves are collapsed (Tile x50 -> one entry with count).
+
+local Serialize = require(script.Parent.Parent.Serialize)
+
+-- User-facing services worth summarizing by default. The dozens of internal
+-- Studio services (StatsItem, MemStorageConnection, ...) just bloat the output,
+-- so at game root we scope to these unless include_internal is set.
+local USER_SERVICES = {
+	"Workspace", "Players", "Lighting", "ReplicatedFirst", "ReplicatedStorage",
+	"ServerScriptService", "ServerStorage", "StarterGui", "StarterPack",
+	"StarterPlayer", "SoundService", "Teams", "TextChatService", "MaterialService",
+}
+
+return function(args: any): any
+	local path = args.path or "game"
+	local depth = args.depth or 2
+	local maxPer = args.max_per_level or 50
+	local includeInternal = args.include_internal == true
+
+	local root = Serialize.resolve(path)
+	if not root then
+		error("Path not found: " .. tostring(path))
+	end
+
+	-- Decide the set of roots to summarize. At `game` we default to user
+	-- services; elsewhere (or with include_internal) we use the resolved root.
+	local scopeRoots: { Instance } = {}
+	local scopedToServices = false
+	if root == game and not includeInternal then
+		scopedToServices = true
+		for _, name in USER_SERVICES do
+			local ok, svc = pcall(function()
+				return game:GetService(name :: any)
+			end)
+			if ok and svc then
+				table.insert(scopeRoots, svc)
+			end
+		end
+	else
+		table.insert(scopeRoots, root)
+	end
+
+	-- Class histogram across the chosen scope (count only, no serialization).
+	local classCounts: { [string]: number } = {}
+	local total = 0
+	for _, sr in scopeRoots do
+		for _, d in sr:GetDescendants() do
+			classCounts[d.ClassName] = (classCounts[d.ClassName] or 0) + 1
+			total += 1
+		end
+	end
+
+	-- Build a node for one instance, collapsing duplicate leaf children.
+	local function buildNode(inst: Instance, d: number): any
+		local kids = inst:GetChildren()
+		local node: any = {
+			name = inst.Name,
+			class = inst.ClassName,
+			n = #kids,
+		}
+		if d <= 0 or #kids == 0 then
+			return node
+		end
+
+		-- Split children: branches (have their own children) are recursed and
+		-- listed individually; leaves (no children) of identical class+name are
+		-- collapsed into one entry carrying a `count`.
+		local branches: { any } = {}
+		local leafKeys: { string } = {}
+		local leafGroups: { [string]: any } = {}
+		for _, k in kids do
+			if #k:GetChildren() > 0 then
+				table.insert(branches, k)
+			else
+				local key = k.ClassName .. "\0" .. k.Name
+				local g = leafGroups[key]
+				if g then
+					g.count += 1
+				else
+					g = { name = k.Name, class = k.ClassName, count = 1 }
+					leafGroups[key] = g
+					table.insert(leafKeys, key)
+				end
+			end
+		end
+
+		local children: { any } = {}
+		local shown = 0
+		for _, b in branches do
+			if shown >= maxPer then
+				break
+			end
+			table.insert(children, buildNode(b, d - 1))
+			shown += 1
+		end
+		for _, key in leafKeys do
+			if shown >= maxPer then
+				break
+			end
+			local g = leafGroups[key]
+			if g.count == 1 then
+				g.count = nil -- singletons read like a normal node
+			end
+			table.insert(children, g)
+			shown += 1
+		end
+
+		node.children = children
+		local groupTotal = #branches + #leafKeys
+		if groupTotal > shown then
+			node.more = groupTotal - shown
+		end
+		return node
+	end
+
+	local tree: any
+	if scopedToServices then
+		-- Synthetic game node whose children are the user services.
+		local children: { any } = {}
+		for _, sr in scopeRoots do
+			table.insert(children, buildNode(sr, depth - 1))
+		end
+		tree = { name = "game", class = "DataModel", n = #children, children = children, scoped = "user-services" }
+	else
+		tree = buildNode(root, depth)
+	end
+
+	return { total = total, classCounts = classCounts, tree = tree }
+end
+]]></string>
+        </Properties>
+      </Item>
+      <Item class="ModuleScript" referent="20">
+        <Properties>
+          <string name="Name">Scripts</string>
+          <string name="Source"><![CDATA[--!strict
+-- Handler for manage_scripts: read/write script source and create scripts.
+
+local ScriptEditorService = game:GetService("ScriptEditorService")
+local ChangeHistoryService = game:GetService("ChangeHistoryService")
+local Serialize = require(script.Parent.Parent.Serialize)
+
+local SCRIPT_CLASSES = { Script = true, LocalScript = true, ModuleScript = true }
+
+local function readSource(inst: Instance): string?
+	local ok, src = pcall(function()
+		return ScriptEditorService:GetEditorSource(inst)
+	end)
+	if ok and type(src) == "string" then
+		return src
+	end
+	local ok2, src2 = pcall(function()
+		return (inst :: any).Source
+	end)
+	return ok2 and src2 or nil
+end
+
+local function writeSource(inst: Instance, source: string): (boolean, string?)
+	local ok = pcall(function()
+		ScriptEditorService:UpdateSourceAsync(inst, function()
+			return source
+		end)
+	end)
+	if ok then
+		return true, nil
+	end
+	local ok2, err = pcall(function()
+		(inst :: any).Source = source
+	end)
+	return ok2, ok2 and nil or tostring(err)
+end
+
+return function(args: any): any
+	local action = args.action or "get_source"
+
+	if action == "get_source" then
+		local inst = args.path and Serialize.resolve(args.path) or nil
+		if not inst or not SCRIPT_CLASSES[inst.ClassName] then
+			return { ok = false, error = "script not found at: " .. tostring(args.path) }
+		end
+		return { ok = true, path = Serialize.path(inst), className = inst.ClassName, source = readSource(inst) }
+	elseif action == "set_source" then
+		local inst = args.path and Serialize.resolve(args.path) or nil
+		if not inst or not SCRIPT_CLASSES[inst.ClassName] then
+			return { ok = false, error = "script not found at: " .. tostring(args.path) }
+		end
+		local recording = ChangeHistoryService:TryBeginRecording("MCP manage_scripts set_source")
+		local ok, err = writeSource(inst, tostring(args.source))
+		if recording then
+			ChangeHistoryService:FinishRecording(
+				recording,
+				ok and Enum.FinishRecordingOperation.Commit or Enum.FinishRecordingOperation.Cancel
+			)
+		end
+		return { ok = ok, path = Serialize.path(inst), error = err }
+	elseif action == "create" then
+		local className = args.class_name or "ModuleScript"
+		if not SCRIPT_CLASSES[className] then
+			return { ok = false, error = "class_name must be Script/LocalScript/ModuleScript" }
+		end
+		local parent = args.parent and Serialize.resolve(args.parent) or nil
+		if not parent then
+			return { ok = false, error = "parent not found: " .. tostring(args.parent) }
+		end
+		local recording = ChangeHistoryService:TryBeginRecording("MCP manage_scripts create")
+		local inst = Instance.new(className)
+		if args.name then
+			inst.Name = args.name
+		end
+		if args.source then
+			pcall(function()
+				(inst :: any).Source = tostring(args.source)
+			end)
+		end
+		inst.Parent = parent
+		if recording then
+			ChangeHistoryService:FinishRecording(recording, Enum.FinishRecordingOperation.Commit)
+		end
+		return { ok = true, path = Serialize.path(inst) }
+	else
+		return { ok = false, error = "unknown manage_scripts action: " .. tostring(action) }
+	end
+end
+]]></string>
+        </Properties>
+      </Item>
+      <Item class="ModuleScript" referent="21">
+        <Properties>
+          <string name="Name">Selection</string>
+          <string name="Source"><![CDATA[--!strict
+-- Handler for manage_selection: read/control the Studio Explorer selection.
+
+local Selection = game:GetService("Selection")
+local Serialize = require(script.Parent.Parent.Serialize)
+
+local function resolveMany(paths: any): { Instance }
+	local out: { Instance } = {}
+	if type(paths) == "table" then
+		for _, p in paths do
+			local inst = Serialize.resolve(p)
+			if inst then
+				table.insert(out, inst)
+			end
+		end
+	end
+	return out
+end
+
+local function currentPaths(): { string }
+	local out = {}
+	for _, inst in Selection:Get() do
+		table.insert(out, Serialize.path(inst))
+	end
+	return out
+end
+
+return function(args: any): any
+	local action = args.action or "get"
+
+	if action == "get" then
+		return { ok = true, selection = currentPaths() }
+	elseif action == "set" then
+		Selection:Set(resolveMany(args.paths))
+		return { ok = true, selection = currentPaths() }
+	elseif action == "add" then
+		local current = Selection:Get()
+		for _, inst in resolveMany(args.paths) do
+			table.insert(current, inst)
+		end
+		Selection:Set(current)
+		return { ok = true, selection = currentPaths() }
+	elseif action == "clear" then
+		Selection:Set({})
+		return { ok = true, selection = {} }
+	else
+		return { ok = false, error = "unknown manage_selection action: " .. tostring(action) }
+	end
+end
+]]></string>
+        </Properties>
+      </Item>
+      <Item class="ModuleScript" referent="22">
+        <Properties>
+          <string name="Name">Spatial</string>
+          <string name="Source"><![CDATA[--!strict
+-- Handler for spatial_query: spatial searches over Workspace.
+
+local Workspace = game:GetService("Workspace")
+local Serialize = require(script.Parent.Parent.Serialize)
+
+local function toVector3(t: any, default: Vector3?): Vector3
+	if type(t) == "table" then
+		return Vector3.new(t.x or t[1] or 0, t.y or t[2] or 0, t.z or t[3] or 0)
+	end
+	return default or Vector3.zero
+end
+
+local function serializePart(part: BasePart): any
+	return {
+		path = Serialize.path(part),
+		name = part.Name,
+		className = part.ClassName,
+		position = Serialize.value(part.Position),
+		size = Serialize.value(part.Size),
+	}
+end
+
+return function(args: any): any
+	local query = args.query or "in_radius"
+	local limit = args.limit or 100
+
+	if query == "in_box" then
+		local cf = CFrame.new(toVector3(args.center))
+		local size = toVector3(args.size, Vector3.new(10, 10, 10))
+		local parts = Workspace:GetPartBoundsInBox(cf, size)
+		local out = {}
+		for i, p in parts do
+			if i > limit then
+				break
+			end
+			table.insert(out, serializePart(p))
+		end
+		return { query = query, count = #out, parts = out }
+	elseif query == "in_radius" then
+		local center = toVector3(args.center)
+		local radius = args.radius or 10
+		local parts = Workspace:GetPartBoundsInRadius(center, radius)
+		local out = {}
+		for i, p in parts do
+			if i > limit then
+				break
+			end
+			table.insert(out, serializePart(p))
+		end
+		return { query = query, count = #out, parts = out }
+	elseif query == "raycast" then
+		local origin = toVector3(args.origin)
+		local direction = toVector3(args.direction, Vector3.new(0, -100, 0))
+		local result = Workspace:Raycast(origin, direction)
+		if not result then
+			return { query = query, hit = false }
+		end
+		return {
+			query = query,
+			hit = true,
+			instance = Serialize.path(result.Instance),
+			position = Serialize.value(result.Position),
+			normal = Serialize.value(result.Normal),
+			distance = result.Distance,
+			material = result.Material.Name,
+		}
+	elseif query == "nearest" then
+		local point = toVector3(args.point)
+		local className = args.class_name
+		local maxDistance = args.max_distance or math.huge
+		local best: BasePart? = nil
+		local bestDist = maxDistance
+		for _, inst in Workspace:GetDescendants() do
+			if inst:IsA("BasePart") and (not className or inst.ClassName == className) then
+				local dist = (inst.Position - point).Magnitude
+				if dist < bestDist then
+					bestDist = dist
+					best = inst
+				end
+			end
+		end
+		if not best then
+			return { query = query, found = false }
+		end
+		return {
+			query = query,
+			found = true,
+			instance = Serialize.path(best),
+			distance = bestDist,
+			position = Serialize.value(best.Position),
+		}
+	else
+		error("unknown spatial query: " .. tostring(query))
+	end
+end
+]]></string>
+        </Properties>
+      </Item>
+      <Item class="ModuleScript" referent="23">
+        <Properties>
+          <string name="Name">Studio</string>
+          <string name="Source"><![CDATA[--!strict
+-- Handler for manage_studio: read Studio environment info and theme.
+
+local RunService = game:GetService("RunService")
+
+return function(args: any): any
+	local action = args.action or "info"
+
+	if action == "info" then
+		local themeName: string? = nil
+		pcall(function()
+			themeName = settings().Studio.Theme.Name
+		end)
+		return {
+			ok = true,
+			studioVersion = version(),
+			theme = themeName,
+			isRunning = RunService:IsRunning(),
+			isEdit = RunService:IsEdit(),
+			placeId = game.PlaceId,
+			gameId = game.GameId,
+		}
+	else
+		return { ok = false, error = "unknown manage_studio action: " .. tostring(action) }
+	end
+end
+]]></string>
+        </Properties>
+      </Item>
+      <Item class="ModuleScript" referent="24">
+        <Properties>
+          <string name="Name">SyncApply</string>
+          <string name="Source"><![CDATA[--!strict
+-- Handler for sync_apply: apply a single filesystem->Studio change.
+-- Currently supports setting a script's source.
+
+local ScriptEditorService = game:GetService("ScriptEditorService")
+local ChangeHistoryService = game:GetService("ChangeHistoryService")
+local Serialize = require(script.Parent.Parent.Serialize)
+
+local function setSource(inst: Instance, source: string): (boolean, string?)
+	-- Prefer the editor service so open documents stay consistent.
+	local ok = pcall(function()
+		ScriptEditorService:UpdateSourceAsync(inst, function()
+			return source
+		end)
+	end)
+	if ok then
+		return true, nil
+	end
+	-- Fall back to a direct assignment.
+	local ok2, err = pcall(function()
+		(inst :: any).Source = source
+	end)
+	if ok2 then
+		return true, nil
+	end
+	return false, tostring(err)
+end
+
+return function(args: any): any
+	local action = args.action or "set_source"
+	local inst = args.path and Serialize.resolve(args.path) or nil
+	if not inst then
+		return { ok = false, error = "path not found: " .. tostring(args.path) }
+	end
+
+	if action == "set_source" then
+		local recording = ChangeHistoryService:TryBeginRecording("MCP sync set_source")
+		local ok, err = setSource(inst, tostring(args.source))
+		if recording then
+			ChangeHistoryService:FinishRecording(
+				recording,
+				ok and Enum.FinishRecordingOperation.Commit or Enum.FinishRecordingOperation.Cancel
+			)
+		end
+		return { ok = ok, path = Serialize.path(inst), error = err }
+	end
+
+	return { ok = false, error = "unknown sync_apply action: " .. tostring(action) }
+end
+]]></string>
+        </Properties>
+      </Item>
+      <Item class="ModuleScript" referent="25">
+        <Properties>
+          <string name="Name">SyncSnapshot</string>
+          <string name="Source"><![CDATA[--!strict
+-- Handler for sync_snapshot: serialize whole subtrees (including script Source)
+-- into a nested tree the server can mirror to disk.
+
+local ScriptEditorService = game:GetService("ScriptEditorService")
+local Serialize = require(script.Parent.Parent.Serialize)
+
+local SCRIPT_CLASSES = {
+	Script = true,
+	LocalScript = true,
+	ModuleScript = true,
+}
+
+local function isValueObject(className: string): boolean
+	return string.sub(className, -5) == "Value"
+end
+
+local function readSource(inst: Instance): string?
+	local ok, src = pcall(function()
+		return ScriptEditorService:GetEditorSource(inst)
+	end)
+	if ok and type(src) == "string" then
+		return src
+	end
+	local ok2, src2 = pcall(function()
+		return (inst :: any).Source
+	end)
+	if ok2 and type(src2) == "string" then
+		return src2
+	end
+	return nil
+end
+
+local function serializeNode(inst: Instance): any
+	local node: any = {
+		name = inst.Name,
+		className = inst.ClassName,
+		properties = Serialize.properties(inst),
+	}
+	if SCRIPT_CLASSES[inst.ClassName] then
+		node.source = readSource(inst)
+	elseif isValueObject(inst.ClassName) then
+		local ok, val = pcall(function()
+			return (inst :: any).Value
+		end)
+		if ok then
+			node.value = Serialize.value(val)
+		end
+	end
+	local children = {}
+	for _, child in inst:GetChildren() do
+		table.insert(children, serializeNode(child))
+	end
+	node.children = children
+	return node
+end
+
+return function(args: any): any
+	local roots = args.roots or {}
+	local result: { any } = {}
+	for _, rootPath in roots do
+		local inst = Serialize.resolve(rootPath)
+		if inst then
+			table.insert(result, {
+				path = Serialize.path(inst),
+				tree = serializeNode(inst),
+			})
+		end
+	end
+	return { roots = result }
+end
+]]></string>
+        </Properties>
+      </Item>
+      <Item class="ModuleScript" referent="26">
+        <Properties>
+          <string name="Name">SyncWatch</string>
+          <string name="Source"><![CDATA[--!strict
+-- Handler for sync_watch: emit Studio->server change events so the server can
+-- mirror live edits to disk. action = "watch" | "unwatch".
+
+local ScriptEditorService = game:GetService("ScriptEditorService")
+local Serialize = require(script.Parent.Parent.Serialize)
+local Bridge = require(script.Parent.Parent.Bridge)
+
+local connections: { RBXScriptConnection } = {}
+local watchedRoots: { Instance } = {}
+
+local function isUnderRoots(inst: Instance): boolean
+	for _, root in watchedRoots do
+		if inst == root or inst:IsDescendantOf(root) then
+			return true
+		end
+	end
+	return false
+end
+
+local function clear()
+	for _, conn in connections do
+		conn:Disconnect()
+	end
+	table.clear(connections)
+	table.clear(watchedRoots)
+end
+
+local function watch(roots: { string })
+	clear()
+	for _, rootPath in roots do
+		local inst = Serialize.resolve(rootPath)
+		if inst then
+			table.insert(watchedRoots, inst)
+			table.insert(
+				connections,
+				inst.DescendantAdded:Connect(function(desc: Instance)
+					Bridge.postEvent({ kind = "added", path = Serialize.path(desc), data = { className = desc.ClassName } })
+				end)
+			)
+			table.insert(
+				connections,
+				inst.DescendantRemoving:Connect(function(desc: Instance)
+					Bridge.postEvent({ kind = "removing", path = Serialize.path(desc) })
+				end)
+			)
+		end
+	end
+
+	-- Live script edits (fires as the user types in the Script Editor).
+	table.insert(
+		connections,
+		ScriptEditorService.TextDocumentDidChange:Connect(function(document: ScriptDocument)
+			local ok, scriptInst = pcall(function()
+				return document:GetScript()
+			end)
+			if not ok or not scriptInst or not isUnderRoots(scriptInst) then
+				return
+			end
+			local text = document:GetText()
+			Bridge.postEvent({
+				kind = "source_changed",
+				path = Serialize.path(scriptInst),
+				data = { className = scriptInst.ClassName, source = text },
+			})
+		end)
+	)
+end
+
+return function(args: any): any
+	local action = args.action or "watch"
+	if action == "unwatch" then
+		clear()
+		return { watching = false }
+	end
+	watch(args.roots or {})
+	return { watching = true, roots = #watchedRoots }
+end
+]]></string>
+        </Properties>
+      </Item>
+      <Item class="ModuleScript" referent="27">
+        <Properties>
+          <string name="Name">System</string>
+          <string name="Source"><![CDATA[--!strict
+-- Handler for system_info: report basic Studio session details.
+
+local RunService = game:GetService("RunService")
+
+return function(_args: any): any
+	local placeName: string? = nil
+	pcall(function()
+		placeName = game.Name
+	end)
+	return {
+		placeId = game.PlaceId,
+		placeName = placeName,
+		studioVersion = version(),
+		isRunning = RunService:IsRunning(),
+	}
+end
+]]></string>
+        </Properties>
+      </Item>
+      <Item class="ModuleScript" referent="28">
+        <Properties>
+          <string name="Name">Terrain</string>
+          <string name="Source"><![CDATA[--!strict
+-- Handler for manage_terrain: generate and edit Workspace.Terrain.
+
+local Workspace = game:GetService("Workspace")
+local ChangeHistoryService = game:GetService("ChangeHistoryService")
+
+local function toVector3(t: any, default: Vector3?): Vector3
+	if type(t) == "table" then
+		return Vector3.new(t.x or t[1] or 0, t.y or t[2] or 0, t.z or t[3] or 0)
+	end
+	return default or Vector3.zero
+end
+
+local function material(name: any): Enum.Material
+	if type(name) == "string" then
+		for _, m in Enum.Material:GetEnumItems() do
+			if m.Name == name then
+				return m
+			end
+		end
+	end
+	return Enum.Material.Grass
+end
+
+return function(args: any): any
+	local terrain = Workspace.Terrain
+	local action = args.action or "fill_block"
+	local recording = ChangeHistoryService:TryBeginRecording("MCP manage_terrain")
+
+	local result: any
+	if action == "fill_block" then
+		local cf = CFrame.new(toVector3(args.position))
+		local size = toVector3(args.size, Vector3.new(16, 16, 16))
+		terrain:FillBlock(cf, size, material(args.material))
+		result = { ok = true, action = action }
+	elseif action == "fill_ball" then
+		terrain:FillBall(toVector3(args.center), args.radius or 8, material(args.material))
+		result = { ok = true, action = action }
+	elseif action == "fill_region" then
+		local min = toVector3(args.min)
+		local max = toVector3(args.max)
+		local region = Region3.new(min, max):ExpandToGrid(4)
+		terrain:FillRegion(region, 4, material(args.material))
+		result = { ok = true, action = action }
+	elseif action == "clear" then
+		terrain:Clear()
+		result = { ok = true, action = action }
+	else
+		result = { ok = false, action = action, error = "unknown terrain action" }
+	end
+
+	if recording then
+		ChangeHistoryService:FinishRecording(
+			recording,
+			result.ok and Enum.FinishRecordingOperation.Commit or Enum.FinishRecordingOperation.Cancel
+		)
+	end
+	return result
+end
+]]></string>
+        </Properties>
+      </Item>
+      <Item class="ModuleScript" referent="29">
+        <Properties>
+          <string name="Name">Tween</string>
+          <string name="Source"><![CDATA[--!strict
+-- Handler for manage_tween: animate an instance's properties with TweenService.
+
+local TweenService = game:GetService("TweenService")
+local Serialize = require(script.Parent.Parent.Serialize)
+
+local function enumFrom(enumType: Enum, name: any, default: EnumItem): EnumItem
+	if type(name) == "string" then
+		for _, item in enumType:GetEnumItems() do
+			if item.Name == name then
+				return item
+			end
+		end
+	end
+	return default
+end
+
+return function(args: any): any
+	local inst = args.path and Serialize.resolve(args.path) or nil
+	if not inst then
+		return { ok = false, error = "path not found: " .. tostring(args.path) }
+	end
+	if type(args.properties) ~= "table" then
+		return { ok = false, error = "tween requires a 'properties' goal map" }
+	end
+
+	-- Coerce each goal value to the property's current type.
+	local goal: { [string]: any } = {}
+	for key, raw in pairs(args.properties) do
+		local ok, coerced = Serialize.coerce(inst, key, raw)
+		if not ok then
+			return { ok = false, error = ("goal '%s': %s"):format(key, tostring(coerced)) }
+		end
+		goal[key] = coerced
+	end
+
+	local info = TweenInfo.new(
+		args.duration or 1,
+		enumFrom(Enum.EasingStyle, args.easing_style, Enum.EasingStyle.Quad) :: Enum.EasingStyle,
+		enumFrom(Enum.EasingDirection, args.easing_direction, Enum.EasingDirection.Out) :: Enum.EasingDirection,
+		args.repeat_count or 0,
+		args.reverses == true,
+		args.delay_time or 0
+	)
+
+	local okCreate, tween = pcall(function()
+		return TweenService:Create(inst, info, goal)
+	end)
+	if not okCreate or not tween then
+		return { ok = false, error = "failed to create tween: " .. tostring(tween) }
+	end
+	tween:Play()
+	return { ok = true, path = Serialize.path(inst), duration = args.duration or 1 }
+end
+]]></string>
+        </Properties>
+      </Item>
+      <Item class="ModuleScript" referent="30">
+        <Properties>
+          <string name="Name">UI</string>
+          <string name="Source"><![CDATA[--!strict
+-- Handler for manage_ui: build and edit GUI hierarchies.
+
+local ChangeHistoryService = game:GetService("ChangeHistoryService")
+local Serialize = require(script.Parent.Parent.Serialize)
+
+-- Recursively build a UI node spec: { className, name?, properties?, children? }
+local function build(spec: any, parent: Instance): (Instance?, string?)
+	local okNew, inst = pcall(function()
+		return Instance.new(spec.className)
+	end)
+	if not okNew or not inst then
+		return nil, "invalid ClassName: " .. tostring(spec.className)
+	end
+	if spec.name then
+		inst.Name = spec.name
+	end
+	local propErr = Serialize.applyProperties(inst, spec.properties)
+	if propErr then
+		inst:Destroy()
+		return nil, propErr
+	end
+	for _, childSpec in spec.children or {} do
+		local _, childErr = build(childSpec, inst)
+		if childErr then
+			inst:Destroy()
+			return nil, childErr
+		end
+	end
+	inst.Parent = parent
+	return inst, nil
+end
+
+return function(args: any): any
+	local action = args.action or "create"
+	local recording = ChangeHistoryService:TryBeginRecording("MCP manage_ui")
+	local result: any
+
+	if action == "create" then
+		local parentPath = args.parent or "StarterGui"
+		local parent = Serialize.resolve(parentPath)
+		if not parent then
+			result = { ok = false, error = "parent not found: " .. tostring(parentPath) }
+		elseif type(args.tree) ~= "table" then
+			result = { ok = false, error = "create requires a 'tree' spec" }
+		else
+			-- Optional clean rebuild: drop an existing same-named child first.
+			if args.replace and args.tree.name then
+				local existing = parent:FindFirstChild(args.tree.name)
+				if existing then
+					existing:Destroy()
+				end
+			end
+			local inst, err = build(args.tree, parent)
+			result = inst and { ok = true, rootPath = Serialize.path(inst) }
+				or { ok = false, error = err }
+		end
+	elseif action == "set" then
+		local inst = args.path and Serialize.resolve(args.path) or nil
+		if not inst then
+			result = { ok = false, error = "path not found: " .. tostring(args.path) }
+		else
+			local err = Serialize.applyProperties(inst, args.properties)
+			result = { ok = err == nil, path = Serialize.path(inst), error = err }
+		end
+	elseif action == "delete" then
+		local inst = args.path and Serialize.resolve(args.path) or nil
+		if not inst then
+			result = { ok = false, error = "path not found: " .. tostring(args.path) }
+		else
+			local p = Serialize.path(inst)
+			inst:Destroy()
+			result = { ok = true, path = p }
+		end
+	else
+		result = { ok = false, error = "unknown manage_ui action: " .. tostring(action) }
+	end
+
+	if recording then
+		ChangeHistoryService:FinishRecording(
+			recording,
+			result.ok and Enum.FinishRecordingOperation.Commit or Enum.FinishRecordingOperation.Cancel
+		)
+	end
+	return result
+end
+]]></string>
+        </Properties>
+      </Item>
+      <Item class="ModuleScript" referent="31">
+        <Properties>
+          <string name="Name">UIPreview</string>
+          <string name="Source"><![CDATA[--!strict
+-- Handler for ui_preview: render a GUI full-screen in EDIT mode on a solid
+-- backdrop (via CoreGui) so capture_studio gets a clean, isolated shot to
+-- compare against a mockup — without the 3D viewport behind it. Plugins are
+-- allowed to parent a ScreenGui into CoreGui, and it renders over the viewport.
+--   action = "show" (clone target onto backdrop) | "hide" (remove preview)
+
+local CoreGui = game:GetService("CoreGui")
+local Serialize = require(script.Parent.Parent.Serialize)
+
+local PREVIEW_NAME = "MCP_UIPreview"
+
+local function clearPreview()
+	local existing = CoreGui:FindFirstChild(PREVIEW_NAME)
+	if existing then
+		existing:Destroy()
+	end
+end
+
+return function(args: any): any
+	local action = args.action or "show"
+	if action == "hide" then
+		clearPreview()
+		return { ok = true, showing = false }
+	end
+
+	local path = args.path
+	if not path then
+		return { ok = false, error = "ui_preview 'show' needs a path to a GUI (ScreenGui/Frame/...)" }
+	end
+	local target = Serialize.resolve(path)
+	if not target then
+		return { ok = false, error = "path not found: " .. tostring(path) }
+	end
+	if not (target:IsA("LayerCollector") or target:IsA("GuiObject")) then
+		return { ok = false, error = "target is not a GUI (need ScreenGui/Frame/TextLabel/...)" }
+	end
+
+	clearPreview()
+
+	local holder = Instance.new("ScreenGui")
+	holder.Name = PREVIEW_NAME
+	holder.ResetOnSpawn = false
+	holder.IgnoreGuiInset = true
+	holder.DisplayOrder = 1000000 -- sit above other UI
+	holder.ZIndexBehavior = Enum.ZIndexBehavior.Sibling
+
+	local bg = Instance.new("Frame")
+	bg.Name = "Backdrop"
+	bg.Size = UDim2.fromScale(1, 1)
+	bg.BorderSizePixel = 0
+	local c = args.background -- optional [r,g,b] 0-1
+	if type(c) == "table" then
+		bg.BackgroundColor3 = Color3.new(tonumber(c[1]) or 0.12, tonumber(c[2]) or 0.12, tonumber(c[3]) or 0.14)
+	else
+		bg.BackgroundColor3 = Color3.fromRGB(30, 30, 36)
+	end
+	bg.Parent = holder
+
+	-- Clone the visual content onto the backdrop (originals stay untouched).
+	local cloned = 0
+	if target:IsA("LayerCollector") then
+		for _, child in target:GetChildren() do
+			if child:IsA("GuiObject") then
+				local copy = child:Clone()
+				copy.Parent = bg
+				cloned += 1
+			end
+		end
+	else
+		local copy = target:Clone()
+		copy.Parent = bg
+		cloned += 1
+	end
+
+	holder.Parent = CoreGui
+	return { ok = true, showing = true, name = PREVIEW_NAME, cloned = cloned }
+end
+]]></string>
+        </Properties>
+      </Item>
+      <Item class="ModuleScript" referent="32">
+        <Properties>
+          <string name="Name">WorkspaceState</string>
+          <string name="Source"><![CDATA[--!strict
+-- Handler for workspace_state: a high-level read-only snapshot of the session.
+
+local Workspace = game:GetService("Workspace")
+local Selection = game:GetService("Selection")
+local RunService = game:GetService("RunService")
+local Serialize = require(script.Parent.Parent.Serialize)
+
+local SUMMARY_SERVICES = {
+	"Workspace", "ServerScriptService", "ServerStorage", "ReplicatedStorage",
+	"ReplicatedFirst", "StarterGui", "StarterPack", "StarterPlayer", "Lighting",
+}
+
+return function(_args: any): any
+	local services = {}
+	for _, name in SUMMARY_SERVICES do
+		local ok, svc = pcall(function()
+			return game:GetService(name :: any)
+		end)
+		if ok and svc then
+			services[name] = #svc:GetChildren()
+		end
+	end
+
+	local camera = Workspace.CurrentCamera
+	local selectionCount = #Selection:Get()
+
+	return {
+		ok = true,
+		placeId = game.PlaceId,
+		placeName = game.Name,
+		isRunning = RunService:IsRunning(),
+		gravity = Workspace.Gravity,
+		childCounts = services,
+		selectionCount = selectionCount,
+		camera = camera and {
+			position = Serialize.value(camera.CFrame.Position),
+			fieldOfView = camera.FieldOfView,
+		} or nil,
+	}
+end
+]]></string>
+        </Properties>
+      </Item>
+    </Item>
+    <Item class="ModuleScript" referent="33">
+      <Properties>
+        <string name="Name">Serialize</string>
+        <string name="Source"><![CDATA[--!strict
+-- Serialize: convert between Roblox instances/datatypes and JSON-safe tables,
+-- and resolve dotted instance paths.
+
+local Serialize = {}
+
+-- Common properties we attempt to read when include_properties is requested.
+local CANDIDATE_PROPS = {
+	"Anchored", "CanCollide", "Transparency", "Reflectance",
+	"Size", "Position", "Orientation", "CFrame",
+	"Color", "BrickColor", "Material",
+	"Value", "Text", "Enabled", "Visible",
+	"Locked", "CastShadow", "Massless",
+}
+
+-- Round to ~4 decimals to drop float noise (0.14901961... -> 0.149,
+-- 6.199999809 -> 6.2). Whole numbers stay exact. Big token saver: a float
+-- component shrinks from ~18 chars to ~5 with no meaningful precision loss.
+local function r(n: number): number
+	if n ~= n or n == math.huge or n == -math.huge then
+		return n -- leave NaN/inf as-is
+	end
+	return math.floor(n * 10000 + 0.5) / 10000
+end
+
+-- Convert a Roblox value into something JSON-encodable.
+function Serialize.value(v: any): any
+	local t = typeof(v)
+	if t == "number" then
+		return r(v)
+	elseif t == "nil" or t == "boolean" or t == "string" then
+		return v
+	elseif t == "Vector3" then
+		return { r(v.X), r(v.Y), r(v.Z) } -- compact [x,y,z]; coerce accepts this back
+	elseif t == "Vector2" then
+		return { r(v.X), r(v.Y) } -- [x,y]
+	elseif t == "CFrame" then
+		local c = { v:GetComponents() }
+		for i, n in c do
+			c[i] = r(n)
+		end
+		return c
+	elseif t == "Color3" then
+		return { r(v.R), r(v.G), r(v.B) } -- [r,g,b]
+	elseif t == "BrickColor" then
+		return v.Name
+	elseif t == "UDim" then
+		return { scale = r(v.Scale), offset = v.Offset }
+	elseif t == "UDim2" then
+		return { { r(v.X.Scale), v.X.Offset }, { r(v.Y.Scale), v.Y.Offset } }
+	elseif t == "EnumItem" then
+		return v.Name
+	elseif t == "Instance" then
+		return Serialize.path(v)
+	else
+		return tostring(v)
+	end
+end
+
+-- Shallow structural equality for comparing a serialized value to an expected
+-- JSON value (used by find_instances match_props). Handles primitives and
+-- flat arrays like [r,g,b] / [x,y,z].
+function Serialize.shallowEqual(a: any, b: any): boolean
+	if type(a) ~= type(b) then
+		return false
+	end
+	if type(a) ~= "table" then
+		return a == b
+	end
+	if #a ~= #b then
+		return false
+	end
+	for i = 1, #a do
+		if a[i] ~= b[i] then
+			return false
+		end
+	end
+	return true
+end
+
+-- Build the full dotted path of an instance, rooted at "game".
+function Serialize.path(inst: Instance): string
+	local segments = {}
+	local current: Instance? = inst
+	while current and current ~= game do
+		table.insert(segments, 1, current.Name)
+		current = current.Parent
+	end
+	return "game." .. table.concat(segments, ".")
+end
+
+-- Resolve a dotted path to an instance, or nil. Accepts an optional leading "game".
+function Serialize.resolve(path: string): Instance?
+	local segments = string.split(path, ".")
+	local current: Instance = game
+	local startIndex = 1
+	if segments[1] == "game" then
+		startIndex = 2
+	end
+	for i = startIndex, #segments do
+		local name = segments[i]
+		local nextInst: Instance?
+		-- Try service first (handles Workspace, ServerStorage, etc.).
+		local ok, svc = pcall(function()
+			return game:GetService(name :: any)
+		end)
+		if current == game and ok and svc then
+			nextInst = svc
+		else
+			nextInst = current:FindFirstChild(name)
+		end
+		if not nextInst then
+			return nil
+		end
+		current = nextInst
+	end
+	return current
+end
+
+-- Read readable properties from an instance. Pass `propList` to read only those
+-- (field projection — fewer tokens); otherwise a curated common set is read.
+function Serialize.properties(inst: Instance, propList: { string }?): { [string]: any }
+	local names = (propList and #propList > 0) and propList or CANDIDATE_PROPS
+	local out: { [string]: any } = {}
+	for _, name in names do
+		local ok, val = pcall(function()
+			return (inst :: any)[name]
+		end)
+		if ok and val ~= nil then
+			out[name] = Serialize.value(val)
+		end
+	end
+	return out
+end
+
+-- Coerce a JSON value into the right Roblox type for setting `prop` on `inst`.
+-- Uses the current property value's type as the target.
+function Serialize.coerce(inst: Instance, prop: string, raw: any): (boolean, any)
+	local ok, current = pcall(function()
+		return (inst :: any)[prop]
+	end)
+	if not ok then
+		-- Property doesn't exist or isn't readable; pass raw through.
+		return true, raw
+	end
+	local t = typeof(current)
+	if t == "Vector3" and type(raw) == "table" then
+		local x = raw.x or raw[1] or 0
+		local y = raw.y or raw[2] or 0
+		local z = raw.z or raw[3] or 0
+		return true, Vector3.new(x, y, z)
+	elseif t == "Color3" and type(raw) == "table" then
+		local r = raw.r or raw[1] or 0
+		local g = raw.g or raw[2] or 0
+		local b = raw.b or raw[3] or 0
+		return true, Color3.new(r, g, b)
+	elseif t == "BrickColor" and type(raw) == "string" then
+		return true, BrickColor.new(raw)
+	elseif t == "EnumItem" and type(raw) == "string" then
+		-- Match against the current enum's items.
+		local enumType = (current :: EnumItem).EnumType
+		for _, item in enumType:GetEnumItems() do
+			if item.Name == raw then
+				return true, item
+			end
+		end
+		return false, ("'%s' is not a valid %s"):format(raw, tostring(enumType))
+	elseif t == "UDim2" and type(raw) == "table" then
+		local xs, xo, ys, yo
+		if type(raw[1]) == "table" then
+			xs, xo = raw[1][1] or 0, raw[1][2] or 0
+			ys, yo = raw[2][1] or 0, raw[2][2] or 0
+		else
+			xs, xo, ys, yo = raw[1] or 0, raw[2] or 0, raw[3] or 0, raw[4] or 0
+		end
+		return true, UDim2.new(xs, xo, ys, yo)
+	elseif t == "UDim" and type(raw) == "table" then
+		return true, UDim.new(raw.scale or raw[1] or 0, raw.offset or raw[2] or 0)
+	elseif t == "Vector2" and type(raw) == "table" then
+		return true, Vector2.new(raw.x or raw[1] or 0, raw.y or raw[2] or 0)
+	elseif t == "CFrame" and type(raw) == "table" and type(raw[1]) == "number" then
+		local ok2, cf = pcall(function()
+			return CFrame.new(table.unpack(raw, 1, #raw))
+		end)
+		if ok2 then
+			return true, cf
+		end
+		return false, "invalid CFrame components"
+	elseif t == "number" and type(raw) == "number" then
+		return true, raw
+	elseif t == "boolean" and type(raw) == "boolean" then
+		return true, raw
+	elseif t == "string" and type(raw) == "string" then
+		return true, raw
+	else
+		-- Best effort: pass raw through and let the assignment validate.
+		return true, raw
+	end
+end
+
+-- Apply a property map to an instance. Returns an error string, or nil on success.
+function Serialize.applyProperties(inst: Instance, properties: any): string?
+	if type(properties) ~= "table" then
+		return nil
+	end
+	for key, raw in pairs(properties) do
+		local okCoerce, coerced = Serialize.coerce(inst, key, raw)
+		if not okCoerce then
+			return ("property '%s': %s"):format(key, tostring(coerced))
+		end
+		local okSet, setErr = pcall(function()
+			(inst :: any)[key] = coerced
+		end)
+		if not okSet then
+			return ("property '%s': %s"):format(key, tostring(setErr))
+		end
+	end
+	return nil
+end
+
+return Serialize
+]]></string>
+      </Properties>
+    </Item>
+    <Item class="ModuleScript" referent="34">
+      <Properties>
+        <string name="Name">UI</string>
+        <string name="Source"><![CDATA[--!strict
+-- UI: builds the Roblox MCP Pro plugin panel inside a DockWidget.
+--
+-- The root is a ScrollingFrame stacking cards: Connection, Settings, Sync,
+-- Activity, plus a footer. Cards auto-size to content; the whole panel scrolls
+-- when the dock is short. Colors come from the live Studio theme (so it matches
+-- dark/light) with one accent color for primary actions and active states, kept
+-- in sync with the web dashboard.
+
+local StudioService = game:GetService("StudioService")
+local HttpService = game:GetService("HttpService")
+
+local UI = {}
+
+-- Accent (matches the web dashboard's blue). Theme-independent on purpose.
+local ACCENT = Color3.fromRGB(88, 166, 255)
+local ACCENT_HOVER = Color3.fromRGB(115, 184, 255)
+local WHITE = Color3.fromRGB(255, 255, 255)
+
+-- Direction labels shown in the Sync card.
+local MODE_LABELS: { [string]: string } = {
+	["two-way"] = "Two-way",
+	["studio-to-disk"] = "Studio → Disk",
+	["disk-to-studio"] = "Disk → Studio",
+}
+
+-- State callbacks (wired up by init.server.luau)
+UI.onSettingsSaved = nil :: ((url: string, token: string?) -> ())?
+UI.onConnectionToggled = nil :: ((connect: boolean) -> ())?
+UI.onAutoConnectChanged = nil :: ((enabled: boolean) -> ())?
+UI.onSyncToggled = nil :: ((enabled: boolean, mode: string) -> ())?
+UI.onSyncModeChanged = nil :: ((mode: string) -> ())?
+
+-- UI references
+local statusIndicator: Frame? = nil
+local statusLabel: TextLabel? = nil
+local toggleButton: TextButton? = nil
+local urlInput: TextBox? = nil
+local tokenInput: TextBox? = nil
+local statsLabel: TextLabel? = nil
+local logContainer: ScrollingFrame? = nil
+local syncStatusLabel: TextLabel? = nil
+local setSyncToggleVisual: ((on: boolean) -> ())? = nil
+local setSegmentedVisual: ((value: string) -> ())? = nil
+
+-- Activity stats
+local isConnected = false
+local syncRunning = false
+local syncMode = "two-way"
+local totalRequests = 0
+local successRequests = 0
+
+local MAX_LOG_ROWS = 60
+
+-- ── Theme registry ────────────────────────────────────────────────────────────
+type ThemeItem = {
+	element: Instance,
+	property: string,
+	styleColor: Enum.StudioStyleGuideColor,
+	modifier: Enum.StudioStyleGuideModifier?,
+}
+local themeRegistry: { ThemeItem } = {}
+
+local function registerTheme(
+	element: Instance,
+	property: string,
+	styleColor: Enum.StudioStyleGuideColor,
+	modifier: Enum.StudioStyleGuideModifier?
+)
+	table.insert(themeRegistry, {
+		element = element,
+		property = property,
+		styleColor = styleColor,
+		modifier = modifier,
+	})
+end
+
+local function themeColor(styleColor: Enum.StudioStyleGuideColor, modifier: Enum.StudioStyleGuideModifier?): Color3
+	return settings().Studio.Theme:GetColor(styleColor, modifier or Enum.StudioStyleGuideModifier.Default)
+end
+
+local function applyTheme()
+	for _, item in themeRegistry do
+		local ok, color = pcall(themeColor, item.styleColor, item.modifier)
+		if ok then
+			(item.element :: any)[item.property] = color
+		end
+	end
+end
+
+settings().Studio.ThemeChanged:Connect(applyTheme)
+
+-- ── Small builder helpers ───────────────────────────────────────────────────────
+local function fill(element: GuiObject): UIFlexItem
+	local flex = Instance.new("UIFlexItem")
+	flex.FlexMode = Enum.UIFlexMode.Fill
+	flex.Parent = element
+	return flex
+end
+
+local function listLayout(
+	parent: Instance,
+	direction: Enum.FillDirection,
+	padding: number,
+	vAlign: Enum.VerticalAlignment?
+): UIListLayout
+	local layout = Instance.new("UIListLayout")
+	layout.FillDirection = direction
+	layout.SortOrder = Enum.SortOrder.LayoutOrder
+	layout.Padding = UDim.new(0, padding)
+	if vAlign then
+		layout.VerticalAlignment = vAlign
+	end
+	layout.Parent = parent
+	return layout
+end
+
+local function uiPadding(parent: Instance, amount: number)
+	local pad = Instance.new("UIPadding")
+	pad.PaddingTop = UDim.new(0, amount)
+	pad.PaddingBottom = UDim.new(0, amount)
+	pad.PaddingLeft = UDim.new(0, amount)
+	pad.PaddingRight = UDim.new(0, amount)
+	pad.Parent = parent
+end
+
+local function corner(parent: Instance, radius: number)
+	local c = Instance.new("UICorner")
+	c.CornerRadius = UDim.new(0, radius)
+	c.Parent = parent
+end
+
+-- A transparent row container (its own list layout) that auto-sizes its height.
+local function row(parent: Instance, layoutOrder: number, height: number?): Frame
+	local r = Instance.new("Frame")
+	r.Name = "Row"
+	r.BackgroundTransparency = 1
+	r.BorderSizePixel = 0
+	r.LayoutOrder = layoutOrder
+	if height then
+		r.Size = UDim2.new(1, 0, 0, height)
+	else
+		r.Size = UDim2.new(1, 0, 0, 0)
+		r.AutomaticSize = Enum.AutomaticSize.Y
+	end
+	r.Parent = parent
+	return r
+end
+
+local function label(
+	parent: Instance,
+	text: string,
+	fontSize: number,
+	font: Enum.Font,
+	styleColor: Enum.StudioStyleGuideColor,
+	layoutOrder: number?
+): TextLabel
+	local l = Instance.new("TextLabel")
+	l.Text = text
+	l.TextSize = fontSize
+	l.Font = font
+	l.BackgroundTransparency = 1
+	l.BorderSizePixel = 0
+	l.AutomaticSize = Enum.AutomaticSize.XY
+	l.Size = UDim2.new(0, 0, 0, 0)
+	l.TextXAlignment = Enum.TextXAlignment.Left
+	l.TextYAlignment = Enum.TextYAlignment.Center
+	if layoutOrder then
+		l.LayoutOrder = layoutOrder
+	end
+	l.Parent = parent
+	registerTheme(l, "TextColor3", styleColor)
+	return l
+end
+
+local function spacer(parent: Instance, layoutOrder: number): Frame
+	local s = Instance.new("Frame")
+	s.Name = "Spacer"
+	s.BackgroundTransparency = 1
+	s.BorderSizePixel = 0
+	s.Size = UDim2.new(0, 0, 1, 0)
+	s.LayoutOrder = layoutOrder
+	s.Parent = parent
+	fill(s)
+	return s
+end
+
+local function button(parent: Instance, text: string, width: number, layoutOrder: number): TextButton
+	local b = Instance.new("TextButton")
+	b.Text = text
+	b.TextSize = 12
+	b.Font = Enum.Font.GothamMedium
+	b.BorderSizePixel = 0
+	b.AutoButtonColor = false
+	b.Size = UDim2.new(0, width, 0, 26)
+	b.LayoutOrder = layoutOrder
+	b.Parent = parent
+	corner(b, 5)
+	registerTheme(b, "BackgroundColor3", Enum.StudioStyleGuideColor.Button)
+	registerTheme(b, "TextColor3", Enum.StudioStyleGuideColor.ButtonText)
+
+	b.MouseEnter:Connect(function()
+		b.BackgroundColor3 = themeColor(Enum.StudioStyleGuideColor.Button, Enum.StudioStyleGuideModifier.Hover)
+	end)
+	b.MouseLeave:Connect(function()
+		b.BackgroundColor3 = themeColor(Enum.StudioStyleGuideColor.Button, Enum.StudioStyleGuideModifier.Default)
+	end)
+	b.MouseButton1Down:Connect(function()
+		b.BackgroundColor3 = themeColor(Enum.StudioStyleGuideColor.Button, Enum.StudioStyleGuideModifier.Pressed)
+	end)
+	return b
+end
+
+-- A full-width accent button for the primary action.
+local function primaryButton(parent: Instance, text: string, layoutOrder: number): TextButton
+	local b = Instance.new("TextButton")
+	b.Text = text
+	b.TextSize = 13
+	b.Font = Enum.Font.GothamBold
+	b.BorderSizePixel = 0
+	b.AutoButtonColor = false
+	b.Size = UDim2.new(1, 0, 0, 32)
+	b.LayoutOrder = layoutOrder
+	b.BackgroundColor3 = ACCENT
+	b.TextColor3 = WHITE
+	b.Parent = parent
+	corner(b, 6)
+	b.MouseEnter:Connect(function()
+		b.BackgroundColor3 = ACCENT_HOVER
+	end)
+	b.MouseLeave:Connect(function()
+		b.BackgroundColor3 = ACCENT
+	end)
+	return b
+end
+
+local function input(parent: Instance, placeholder: string, layoutOrder: number): TextBox
+	local box = Instance.new("TextBox")
+	box.Text = ""
+	box.PlaceholderText = placeholder
+	box.TextSize = 12
+	box.Font = Enum.Font.Code
+	box.BorderSizePixel = 0
+	box.ClearTextOnFocus = false
+	box.TextXAlignment = Enum.TextXAlignment.Left
+	box.TextTruncate = Enum.TextTruncate.AtEnd
+	box.Size = UDim2.new(1, 0, 0, 28)
+	box.LayoutOrder = layoutOrder
+	box.Parent = parent
+	corner(box, 5)
+	local pad = Instance.new("UIPadding")
+	pad.PaddingLeft = UDim.new(0, 8)
+	pad.PaddingRight = UDim.new(0, 8)
+	pad.Parent = box
+	registerTheme(box, "BackgroundColor3", Enum.StudioStyleGuideColor.InputFieldBackground)
+	registerTheme(box, "TextColor3", Enum.StudioStyleGuideColor.MainText)
+	registerTheme(box, "PlaceholderColor3", Enum.StudioStyleGuideColor.DimmedText)
+	return box
+end
+
+-- A bordered card with a vertical inner layout, auto-sizing to its content.
+local function card(parent: Instance, layoutOrder: number): Frame
+	local c = Instance.new("Frame")
+	c.Name = "Card"
+	c.BorderSizePixel = 0
+	c.LayoutOrder = layoutOrder
+	c.Size = UDim2.new(1, 0, 0, 0)
+	c.AutomaticSize = Enum.AutomaticSize.Y
+	c.Parent = parent
+	registerTheme(c, "BackgroundColor3", Enum.StudioStyleGuideColor.MainBackground)
+
+	corner(c, 8)
+	local stroke = Instance.new("UIStroke")
+	stroke.Thickness = 1
+	stroke.Parent = c
+	registerTheme(stroke, "Color", Enum.StudioStyleGuideColor.Border)
+
+	uiPadding(c, 12)
+	listLayout(c, Enum.FillDirection.Vertical, 9)
+	return c
+end
+
+-- A sliding on/off switch. Returns a setter to update its visual state.
+local function toggleSwitch(
+	parent: Instance,
+	layoutOrder: number,
+	initialOn: boolean,
+	onChange: (boolean) -> ()
+): (boolean) -> ()
+	local track = Instance.new("Frame")
+	track.Name = "Toggle"
+	track.Size = UDim2.new(0, 40, 0, 22)
+	track.BorderSizePixel = 0
+	track.LayoutOrder = layoutOrder
+	track.Parent = parent
+	corner(track, 11)
+
+	local knob = Instance.new("Frame")
+	knob.Name = "Knob"
+	knob.Size = UDim2.new(0, 16, 0, 16)
+	knob.BorderSizePixel = 0
+	knob.BackgroundColor3 = WHITE
+	knob.Parent = track
+	corner(knob, 8)
+
+	local state = initialOn
+
+	local function apply()
+		if state then
+			track.BackgroundColor3 = ACCENT
+			knob.Position = UDim2.new(1, -19, 0.5, -8)
+		else
+			track.BackgroundColor3 = themeColor(Enum.StudioStyleGuideColor.Border)
+			knob.Position = UDim2.new(0, 3, 0.5, -8)
+		end
+	end
+	apply()
+
+	local hit = Instance.new("TextButton")
+	hit.Text = ""
+	hit.BackgroundTransparency = 1
+	hit.Size = UDim2.new(1, 0, 1, 0)
+	hit.Parent = track
+	hit.MouseButton1Click:Connect(function()
+		state = not state
+		apply()
+		onChange(state)
+	end)
+
+	return function(on: boolean)
+		state = on
+		apply()
+	end
+end
+
+-- A segmented (single-choice) control. Returns a setter to update the selection.
+local function segmented(
+	parent: Instance,
+	layoutOrder: number,
+	options: { { label: string, value: string } },
+	initial: string,
+	onChange: (string) -> ()
+): (string) -> ()
+	local bar = Instance.new("Frame")
+	bar.Name = "Segmented"
+	bar.BackgroundTransparency = 1
+	bar.BorderSizePixel = 0
+	bar.Size = UDim2.new(1, 0, 0, 28)
+	bar.LayoutOrder = layoutOrder
+	bar.Parent = parent
+	listLayout(bar, Enum.FillDirection.Horizontal, 6)
+
+	local buttons: { [string]: TextButton } = {}
+	local current = initial
+
+	local function apply()
+		for value, btn in buttons do
+			if value == current then
+				btn.BackgroundColor3 = ACCENT
+				btn.TextColor3 = WHITE
+			else
+				btn.BackgroundColor3 = themeColor(Enum.StudioStyleGuideColor.Button)
+				btn.TextColor3 = themeColor(Enum.StudioStyleGuideColor.ButtonText)
+			end
+		end
+	end
+
+	for i, opt in options do
+		local b = Instance.new("TextButton")
+		b.Text = opt.label
+		b.TextSize = 11
+		b.Font = Enum.Font.GothamMedium
+		b.BorderSizePixel = 0
+		b.AutoButtonColor = false
+		b.Size = UDim2.new(0, 0, 1, 0)
+		b.LayoutOrder = i
+		b.Parent = bar
+		corner(b, 5)
+		fill(b)
+		buttons[opt.value] = b
+		b.MouseButton1Click:Connect(function()
+			current = opt.value
+			apply()
+			onChange(opt.value)
+		end)
+	end
+	apply()
+
+	return function(value: string)
+		current = value
+		apply()
+	end
+end
+
+-- ── Build the panel ─────────────────────────────────────────────────────────────
+function UI.create(
+	widget: DockWidgetPluginGui,
+	initialSettings: { url: string, token: string?, autoConnect: boolean?, syncMode: string? }
+)
+	widget.Title = "Roblox MCP Pro"
+	themeRegistry = {}
+	syncMode = initialSettings.syncMode or "two-way"
+
+	-- Clear any previous build (Studio reloads re-run this module).
+	for _, child in widget:GetChildren() do
+		child:Destroy()
+	end
+
+	local root = Instance.new("ScrollingFrame")
+	root.Name = "Root"
+	root.Size = UDim2.new(1, 0, 1, 0)
+	root.BorderSizePixel = 0
+	root.ScrollBarThickness = 6
+	root.CanvasSize = UDim2.new(0, 0, 0, 0)
+	root.AutomaticCanvasSize = Enum.AutomaticSize.Y
+	root.ScrollingDirection = Enum.ScrollingDirection.Y
+	root.Parent = widget
+	registerTheme(root, "BackgroundColor3", Enum.StudioStyleGuideColor.MainBackground)
+	registerTheme(root, "ScrollBarImageColor3", Enum.StudioStyleGuideColor.ScrollBar)
+	uiPadding(root, 10)
+	listLayout(root, Enum.FillDirection.Vertical, 10)
+
+	-- ── Header ──
+	local header = row(root, 0, 24)
+	listLayout(header, Enum.FillDirection.Horizontal, 8, Enum.VerticalAlignment.Center)
+	label(header, "Roblox MCP Pro", 15, Enum.Font.GothamBold, Enum.StudioStyleGuideColor.MainText, 1)
+
+	-- ── Connection card ──
+	local connCard = card(root, 1)
+	local connRow = row(connCard, 1, 24)
+	listLayout(connRow, Enum.FillDirection.Horizontal, 8, Enum.VerticalAlignment.Center)
+
+	statusIndicator = Instance.new("Frame")
+	local dot = statusIndicator :: Frame
+	dot.Name = "Dot"
+	dot.Size = UDim2.new(0, 10, 0, 10)
+	dot.BorderSizePixel = 0
+	dot.BackgroundColor3 = Color3.fromRGB(149, 165, 166)
+	dot.LayoutOrder = 1
+	dot.Parent = connRow
+	corner(dot, 5)
+
+	statusLabel = label(connRow, "Disconnected", 14, Enum.Font.GothamMedium, Enum.StudioStyleGuideColor.MainText, 2)
+
+	toggleButton = primaryButton(connCard, "Connect", 2)
+	;(toggleButton :: TextButton).MouseButton1Click:Connect(function()
+		if UI.onConnectionToggled then
+			UI.onConnectionToggled(not isConnected)
+		end
+	end)
+
+	-- ── Settings card ──
+	local settingsCard = card(root, 2)
+	label(settingsCard, "SETTINGS", 10, Enum.Font.GothamBold, Enum.StudioStyleGuideColor.DimmedText, 1)
+
+	local autoRow = row(settingsCard, 2, 24)
+	listLayout(autoRow, Enum.FillDirection.Horizontal, 8, Enum.VerticalAlignment.Center)
+	label(autoRow, "Auto-connect on startup", 12, Enum.Font.Gotham, Enum.StudioStyleGuideColor.MainText, 1)
+	spacer(autoRow, 2)
+	toggleSwitch(autoRow, 3, initialSettings.autoConnect == true, function(on: boolean)
+		if UI.onAutoConnectChanged then
+			UI.onAutoConnectChanged(on)
+		end
+	end)
+
+	label(settingsCard, "Server URL", 11, Enum.Font.Gotham, Enum.StudioStyleGuideColor.DimmedText, 3)
+	urlInput = input(settingsCard, "http://127.0.0.1:3690", 4)
+	;(urlInput :: TextBox).Text = initialSettings.url
+
+	label(settingsCard, "Auth Token (optional)", 11, Enum.Font.Gotham, Enum.StudioStyleGuideColor.DimmedText, 5)
+	tokenInput = input(settingsCard, "shared secret", 6)
+	;(tokenInput :: TextBox).Text = initialSettings.token or ""
+
+	local applyRow = row(settingsCard, 7, 26)
+	listLayout(applyRow, Enum.FillDirection.Horizontal, 8, Enum.VerticalAlignment.Center)
+	spacer(applyRow, 1)
+	local applyBtn = button(applyRow, "Apply", 80, 2)
+	applyBtn.MouseButton1Click:Connect(function()
+		if UI.onSettingsSaved and urlInput and tokenInput then
+			local t = tokenInput.Text
+			UI.onSettingsSaved(urlInput.Text, if t == "" then nil else t)
+		end
+	end)
+
+	-- ── Sync card ──
+	local syncCard = card(root, 3)
+	label(syncCard, "FILE SYNC", 10, Enum.Font.GothamBold, Enum.StudioStyleGuideColor.DimmedText, 1)
+
+	local syncRow = row(syncCard, 2, 24)
+	listLayout(syncRow, Enum.FillDirection.Horizontal, 8, Enum.VerticalAlignment.Center)
+	label(syncRow, "Enable sync", 12, Enum.Font.Gotham, Enum.StudioStyleGuideColor.MainText, 1)
+	spacer(syncRow, 2)
+	setSyncToggleVisual = toggleSwitch(syncRow, 3, false, function(on: boolean)
+		if UI.onSyncToggled then
+			UI.onSyncToggled(on, syncMode)
+		end
+	end)
+
+	label(syncCard, "Direction", 11, Enum.Font.Gotham, Enum.StudioStyleGuideColor.DimmedText, 3)
+	setSegmentedVisual = segmented(syncCard, 4, {
+		{ label = "Two-way", value = "two-way" },
+		{ label = "Studio→Disk", value = "studio-to-disk" },
+		{ label = "Disk→Studio", value = "disk-to-studio" },
+	}, syncMode, function(value: string)
+		syncMode = value
+		if UI.onSyncModeChanged then
+			UI.onSyncModeChanged(value)
+		end
+	end)
+
+	syncStatusLabel = label(syncCard, "Off", 11, Enum.Font.Gotham, Enum.StudioStyleGuideColor.DimmedText, 5)
+
+	-- ── Activity card ──
+	local activityCard = card(root, 4)
+
+	local activityHeader = row(activityCard, 1, 18)
+	listLayout(activityHeader, Enum.FillDirection.Horizontal, 8, Enum.VerticalAlignment.Center)
+	label(activityHeader, "ACTIVITY", 10, Enum.Font.GothamBold, Enum.StudioStyleGuideColor.DimmedText, 1)
+	spacer(activityHeader, 2)
+	statsLabel = label(activityHeader, "0 reqs · 100%", 10, Enum.Font.Gotham, Enum.StudioStyleGuideColor.DimmedText, 3)
+	local clearBtn = button(activityHeader, "Clear", 52, 4)
+	clearBtn.Size = UDim2.new(0, 52, 0, 18)
+	clearBtn.TextSize = 10
+	clearBtn.MouseButton1Click:Connect(function()
+		UI.clearLogs()
+	end)
+
+	logContainer = Instance.new("ScrollingFrame")
+	local log = logContainer :: ScrollingFrame
+	log.Name = "Log"
+	log.Size = UDim2.new(1, 0, 0, 150)
+	log.BorderSizePixel = 0
+	log.ScrollBarThickness = 6
+	log.CanvasSize = UDim2.new(0, 0, 0, 0)
+	log.AutomaticCanvasSize = Enum.AutomaticSize.Y
+	log.ScrollingDirection = Enum.ScrollingDirection.Y
+	log.LayoutOrder = 2
+	log.Parent = activityCard
+	corner(log, 5)
+	registerTheme(log, "BackgroundColor3", Enum.StudioStyleGuideColor.InputFieldBackground)
+	registerTheme(log, "ScrollBarImageColor3", Enum.StudioStyleGuideColor.ScrollBar)
+	local logLayout = listLayout(log, Enum.FillDirection.Vertical, 3)
+	logLayout.Padding = UDim.new(0, 3)
+	uiPadding(log, 6)
+
+	-- ── Footer (config helpers) ──
+	local footer = row(root, 5, 26)
+	listLayout(footer, Enum.FillDirection.Horizontal, 8, Enum.VerticalAlignment.Center)
+
+	local copyJsonBtn = button(footer, "Copy config", 96, 1)
+	copyJsonBtn.MouseButton1Click:Connect(function()
+		local configTable = {
+			mcpServers = {
+				["roblox-mcp-pro"] = { command = "npx", args = { "-y", "roblox-mcp-pro" } },
+			},
+		}
+		local okEncode, json = pcall(function()
+			return HttpService:JSONEncode(configTable)
+		end)
+		if okEncode then
+			pcall(function()
+				StudioService:CopyToClipboard(json)
+				print("[roblox-mcp-pro] Config JSON copied to clipboard.")
+			end)
+		end
+	end)
+
+	local copyCliBtn = button(footer, "Copy install cmd", 120, 2)
+	copyCliBtn.MouseButton1Click:Connect(function()
+		local cmd = 'gh api repos/PeerapolSelanon/roblox-mcp-pro/contents/install.ps1 -H "Accept: application/vnd.github.v3.raw" | Out-String | iex'
+		pcall(function()
+			StudioService:CopyToClipboard(cmd)
+			print("[roblox-mcp-pro] Install command copied to clipboard.")
+		end)
+	end)
+
+	applyTheme()
+end
+
+-- ── Public API ──────────────────────────────────────────────────────────────────
+
+-- Update the connection status shown in the UI. statusLabel color is driven manually
+-- here (not via registerTheme) so we never grow themeRegistry on repeated calls.
+function UI.setStatus(status: string)
+	if not statusLabel or not statusIndicator or not toggleButton then
+		return
+	end
+	local lbl = statusLabel :: TextLabel
+	local ind = statusIndicator :: Frame
+	local btn = toggleButton :: TextButton
+
+	lbl.Text = status
+
+	if status == "Connected" then
+		isConnected = true
+		ind.BackgroundColor3 = Color3.fromRGB(46, 204, 113) -- green
+		lbl.TextColor3 = Color3.fromRGB(46, 204, 113)
+		btn.Text = "Disconnect"
+	elseif status == "Connecting" or status == "Reconnecting" then
+		isConnected = true
+		ind.BackgroundColor3 = Color3.fromRGB(241, 196, 15) -- amber
+		lbl.TextColor3 = Color3.fromRGB(241, 196, 15)
+		btn.Text = "Disconnect"
+	elseif status == "Offline" then
+		-- Server unreachable but the poll loop is still retrying, so keep "Disconnect".
+		isConnected = true
+		ind.BackgroundColor3 = Color3.fromRGB(231, 76, 60) -- red
+		lbl.TextColor3 = Color3.fromRGB(231, 76, 60)
+		btn.Text = "Disconnect"
+	else
+		isConnected = false
+		ind.BackgroundColor3 = Color3.fromRGB(149, 165, 166) -- muted
+		lbl.TextColor3 = themeColor(Enum.StudioStyleGuideColor.DimmedText)
+		btn.Text = "Connect"
+	end
+end
+
+-- Reflect the broker's sync state in the Sync card.
+function UI.setSyncStatus(running: boolean, mode: string?, scriptCount: number?)
+	syncRunning = running
+	if mode then
+		syncMode = mode
+		if setSegmentedVisual then
+			(setSegmentedVisual :: (string) -> ())(mode)
+		end
+	end
+	if setSyncToggleVisual then
+		(setSyncToggleVisual :: (boolean) -> ())(running)
+	end
+	if syncStatusLabel then
+		local lbl = syncStatusLabel :: TextLabel
+		if running then
+			local count = scriptCount or 0
+			lbl.Text = ("Syncing %d scripts · %s"):format(count, MODE_LABELS[syncMode] or syncMode)
+			lbl.TextColor3 = Color3.fromRGB(46, 204, 113)
+		else
+			lbl.Text = "Off"
+			lbl.TextColor3 = themeColor(Enum.StudioStyleGuideColor.DimmedText)
+		end
+	end
+end
+
+function UI.updateStatsLabel()
+	if not statsLabel then
+		return
+	end
+	local rate = 100
+	if totalRequests > 0 then
+		rate = math.round((successRequests / totalRequests) * 100)
+	end
+	(statsLabel :: TextLabel).Text = ("%d reqs · %d%%"):format(totalRequests, rate)
+end
+
+-- Append a log entry to the activity console.
+function UI.addLog(toolName: string, success: boolean, detail: string?)
+	if not logContainer then
+		return
+	end
+	local log = logContainer :: ScrollingFrame
+
+	totalRequests += 1
+	if success then
+		successRequests += 1
+	end
+	UI.updateStatsLabel()
+
+	local logRow = Instance.new("Frame")
+	logRow.Name = "LogRow"
+	logRow.Size = UDim2.new(1, 0, 0, 16)
+	logRow.BackgroundTransparency = 1
+	logRow.BorderSizePixel = 0
+	logRow.Parent = log
+	listLayout(logRow, Enum.FillDirection.Horizontal, 6, Enum.VerticalAlignment.Center)
+
+	local badge = Instance.new("TextLabel")
+	badge.Name = "Badge"
+	badge.Size = UDim2.new(0, 28, 0, 13)
+	badge.BorderSizePixel = 0
+	badge.TextSize = 9
+	badge.Font = Enum.Font.GothamBold
+	badge.LayoutOrder = 1
+	badge.Parent = logRow
+	corner(badge, 3)
+	if success then
+		badge.Text = "OK"
+		badge.BackgroundColor3 = Color3.fromRGB(39, 174, 96)
+	else
+		badge.Text = "ERR"
+		badge.BackgroundColor3 = Color3.fromRGB(192, 57, 43)
+	end
+	badge.TextColor3 = WHITE
+
+	local timestamp = os.date("%H:%M:%S")
+	local entryText = ("[%s] %s"):format(timestamp, toolName)
+	if detail and detail ~= "" then
+		entryText = entryText .. " — " .. detail
+	end
+	-- Log rows are transient (trimmed after MAX_LOG_ROWS), so we set the color directly
+	-- instead of via registerTheme — otherwise every entry would leak a registry item.
+	local msg = Instance.new("TextLabel")
+	msg.Text = entryText
+	msg.TextSize = 11
+	msg.Font = Enum.Font.Code
+	msg.BackgroundTransparency = 1
+	msg.BorderSizePixel = 0
+	msg.TextXAlignment = Enum.TextXAlignment.Left
+	msg.TextYAlignment = Enum.TextYAlignment.Center
+	msg.TextTruncate = Enum.TextTruncate.AtEnd
+	msg.Size = UDim2.new(1, -34, 1, 0)
+	msg.LayoutOrder = 2
+	msg.TextColor3 = themeColor(
+		if success then Enum.StudioStyleGuideColor.MainText else Enum.StudioStyleGuideColor.WarningText
+	)
+	msg.Parent = logRow
+
+	-- Keep the newest entry in view.
+	task.defer(function()
+		if logContainer then
+			(logContainer :: ScrollingFrame).CanvasPosition =
+				Vector2.new(0, (logContainer :: ScrollingFrame).AbsoluteCanvasSize.Y)
+		end
+	end)
+
+	-- Trim old rows to bound memory.
+	local rows = {}
+	for _, child in log:GetChildren() do
+		if child.Name == "LogRow" then
+			table.insert(rows, child)
+		end
+	end
+	if #rows > MAX_LOG_ROWS then
+		for i = 1, #rows - MAX_LOG_ROWS do
+			rows[i]:Destroy()
+		end
+	end
+end
+
+function UI.clearLogs()
+	if not logContainer then
+		return
+	end
+	for _, child in (logContainer :: ScrollingFrame):GetChildren() do
+		if child.Name == "LogRow" then
+			child:Destroy()
+		end
+	end
+	totalRequests = 0
+	successRequests = 0
+	UI.updateStatsLabel()
+end
+
+return UI
+]]></string>
+      </Properties>
+    </Item>
+  </Item>
+</roblox>