@chrrxs/robloxstudio-mcp-inspector 2.14.0 → 2.15.0

package/dist/index.js

@@ -721,6 +721,7 @@ var init_http_server = __esm({
       simulate_keyboard_input: (tools, body) => tools.simulateKeyboardInput(body.keyCode, body.action, body.duration, body.text, body.target, body.instance_id),
       character_navigation: (tools, body) => tools.characterNavigation(body.position, body.instancePath, body.waitForCompletion, body.timeout, body.target, body.instance_id),
       get_memory_breakdown: (tools, body) => tools.getMemoryBreakdown(body.target, body.tags, body.instance_id),
+      get_scene_analysis: (tools, body) => tools.getSceneAnalysis(body.mode, body.target, body.topN, body.raw, body.instance_id),
       export_rbxm: (tools, body) => tools.exportRbxm(body.instance_paths, body.output_path, body.target, body.instance_id),
       import_rbxm: (tools, body) => tools.importRbxm(body.source, body.parent_path, body.target, body.instance_id),
       find_and_replace_in_scripts: (tools, body) => tools.findAndReplaceInScripts(body.pattern, body.replacement, {
@@ -2884,6 +2885,19 @@ var init_tools = __esm({
         const clientCount = this._clientRolesForInstance(instanceId).length;
         return { ok: false, roles, timedOut: true, extraClients: clientCount > expectedClientCount, clientCount };
       }
+      async _waitForRuntimeRolesFresh(instanceId, connectedAfter, requiredRoles, timeoutSec = 60) {
+        const deadline = Date.now() + timeoutSec * 1e3;
+        while (Date.now() < deadline) {
+          const instances = this.bridge.getInstances().filter((i) => i.instanceId === instanceId);
+          const roles = instances.map((i) => i.role);
+          const freshRoles = new Set(instances.filter((i) => i.connectedAt >= connectedAfter).map((i) => i.role));
+          if (requiredRoles.every((role) => freshRoles.has(role))) {
+            return { ok: true, roles, timedOut: false };
+          }
+          await sleep(250);
+        }
+        return { ok: false, roles: this._rolesForInstance(instanceId), timedOut: true };
+      }
       async getFileTree(path2 = "", instance_id) {
         const response = await this._callSingle("/api/file-tree", { path: path2 }, void 0, instance_id);
         return {
@@ -3532,12 +3546,37 @@ ${code}`
           throw new Error("start_playtest is single-player only. Use multiplayer_test_start for multi-client StudioTestService sessions.");
         }
         const data = { mode };
-        const response = await this._callSingle("/api/start-playtest", data, void 0, instance_id);
+        const startedAt = Date.now();
+        const resolved = this.bridge.resolveTarget({ instance_id, target: void 0 });
+        if (!resolved.ok)
+          throw new RoutingFailure(resolved.error);
+        if (resolved.mode !== "single") {
+          throw new RoutingFailure({
+            code: "target_role_not_present_on_instance",
+            message: "This tool does not support target=all. Pick a specific role or omit target.",
+            data: {
+              instances: this.bridge.getPublicInstances(),
+              count: this.bridge.getInstances().length
+            }
+          });
+        }
+        const response = await this.client.request("/api/start-playtest", data, resolved.targetInstanceId, resolved.targetRole);
+        let wait;
+        if (response?.success === true) {
+          const requiredRoles = mode === "play" ? ["server", "client-1"] : ["server"];
+          wait = await this._waitForRuntimeRolesFresh(resolved.targetInstanceId, startedAt, requiredRoles);
+        }
+        const body = wait ? {
+          ...response,
+          runtimeReady: wait.ok,
+          timedOut: wait.timedOut,
+          roles: wait.roles
+        } : response;
         return {
           content: [
             {
               type: "text",
-              text: JSON.stringify(response)
+              text: JSON.stringify(body)
             }
           ]
         };
@@ -4602,6 +4641,39 @@ ${code}`
         }
         return { content: [{ type: "text", text: JSON.stringify(body) }] };
       }
+      async getSceneAnalysis(mode, target, topN, raw, instance_id) {
+        const tgt = target ?? "all";
+        const data = {};
+        if (mode !== void 0)
+          data.mode = mode;
+        if (topN !== void 0)
+          data.topN = topN;
+        if (raw !== void 0)
+          data.raw = raw;
+        const resolved = this.bridge.resolveTarget({ instance_id, target: tgt });
+        if (!resolved.ok)
+          throw new RoutingFailure(resolved.error);
+        if (resolved.mode === "single") {
+          const response = await this.client.request("/api/get-scene-analysis", data, resolved.targetInstanceId, resolved.targetRole);
+          return { content: [{ type: "text", text: JSON.stringify(response) }] };
+        }
+        const targets = resolved.targets.filter((t) => t.targetRole !== "edit-proxy");
+        const responses = await Promise.allSettled(targets.map(async (t) => ({
+          peer: t.targetRole,
+          result: await this.client.request("/api/get-scene-analysis", data, t.targetInstanceId, t.targetRole)
+        })));
+        const body = {};
+        for (let i = 0; i < responses.length; i++) {
+          const r = responses[i];
+          const peer = targets[i].targetRole;
+          if (r.status === "fulfilled") {
+            body[peer] = r.value.result;
+          } else {
+            body[peer] = { error: "disconnected" };
+          }
+        }
+        return { content: [{ type: "text", text: JSON.stringify(body) }] };
+      }
       async exportRbxm(instancePaths, outputPath, target, instance_id) {
         if (!Array.isArray(instancePaths) || instancePaths.length === 0) {
           throw new Error("instance_paths must be a non-empty array for export_rbxm");
@@ -6032,7 +6104,7 @@ var init_definitions = __esm({
       {
         name: "start_playtest",
         category: "write",
-        description: "Start a simple single-player Studio playtest in play or run mode. Captures print/warn/error via LogService. Poll with get_playtest_output, end with stop_playtest. For multi-client testing use multiplayer_test_start instead.",
+        description: "Start a simple single-player Studio playtest in play or run mode, waiting until a runtime peer registers with MCP. Captures print/warn/error via LogService. Poll with get_playtest_output, end with stop_playtest. For multi-client testing use multiplayer_test_start instead.",
         inputSchema: {
           type: "object",
           properties: {
@@ -7010,6 +7082,39 @@ part(0,2,0,2,1,1,"b")`,
           }
         }
       },
+      {
+        name: "get_scene_analysis",
+        category: "read",
+        description: 'Read Roblox SceneAnalysisService data for attribution-focused performance analysis. Complements get_memory_breakdown: returns compact top-N entries for instance composition, script memory, unparented instances, triangle composition, animation memory, and audio memory. Requires the Studio Scene Analysis beta feature; if disabled, returns scene_analysis_not_enabled with betaFeatureRequired=true. target="all" (default) returns per-peer data; single-peer targets return that peer directly. raw=true includes the full nested Scene Analysis tree.',
+        inputSchema: {
+          type: "object",
+          properties: {
+            mode: {
+              type: "string",
+              enum: ["all", "instance_composition", "script_memory", "unparented_instances", "triangle_composition", "animation_memory", "audio_memory"],
+              description: 'Scene analysis mode to read. Defaults to "all".'
+            },
+            target: {
+              type: "string",
+              description: 'Peer to read from: "edit", "server", "client-N", or "all" (default).'
+            },
+            topN: {
+              type: "number",
+              minimum: 1,
+              maximum: 100,
+              description: "Number of flattened top entries to include per mode. Defaults to 10; plugin clamps to 1-100."
+            },
+            raw: {
+              type: "boolean",
+              description: "Include the full nested SceneAnalysisService tree in each mode result. Defaults to false."
+            },
+            instance_id: {
+              type: "string",
+              description: "Which connected Studio place to target. Required when multiple places are connected; omit when one. Use get_connected_instances to list available IDs."
+            }
+          }
+        }
+      },
       // === SerializationService round-trip ===
       {
         name: "export_rbxm",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@chrrxs/robloxstudio-mcp-inspector",
-  "version": "2.14.0",
+  "version": "2.15.0",
   "description": "Read-only MCP server for inspecting and debugging Roblox Studio from AI coding tools",
   "main": "dist/index.js",
   "type": "module",

package/studio-plugin/MCPInspectorPlugin.rbxmx

@@ -102,6 +102,7 @@ local RunService = _services.RunService
 local ServerStorage = _services.ServerStorage
 local RuntimeLogBuffer = TS.import(script, script.Parent, "RuntimeLogBuffer")
 local MemoryHandlers = TS.import(script, script.Parent, "handlers", "MemoryHandlers")
+local SceneAnalysisHandlers = TS.import(script, script.Parent, "handlers", "SceneAnalysisHandlers")
 local CaptureHandlers = TS.import(script, script.Parent, "handlers", "CaptureHandlers")
 local InputHandlers = TS.import(script, script.Parent, "handlers", "InputHandlers")
 local LuauExec = TS.import(script, script.Parent, "LuauExec")
@@ -167,6 +168,7 @@ local CLIENT_BROKER_ALLOWED_ENDPOINTS = {
 	["/api/execute-luau"] = true,
 	["/api/get-runtime-logs"] = true,
 	["/api/get-memory-breakdown"] = true,
+	["/api/get-scene-analysis"] = true,
 	["/api/multiplayer-test-state"] = true,
 	["/api/multiplayer-test-leave-client"] = true,
 	["/api/capture-begin"] = true,
@@ -324,7 +326,7 @@ end
 local function setupClientBroker()
 	local rf = ReplicatedStorage:WaitForChild(BROKER_NAME, 10)
 	if not rf or not rf:IsA("RemoteFunction") then
-		warn(`[MCPFork] client: {BROKER_NAME} not found`)
+		warn(`[robloxstudio-mcp] client: {BROKER_NAME} not found`)
 		return nil
 	end
 	rf.OnClientInvoke = function(payload)
@@ -340,6 +342,9 @@ local function setupClientBroker()
 		if payload and payload.endpoint == "/api/get-memory-breakdown" then
 			return MemoryHandlers.getMemoryBreakdown(payload.data or {})
 		end
+		if payload and payload.endpoint == "/api/get-scene-analysis" then
+			return SceneAnalysisHandlers.getSceneAnalysis(payload.data or {})
+		end
 		if payload and payload.endpoint == "/api/multiplayer-test-state" then
 			return handleMultiplayerTestState()
 		end
@@ -453,7 +458,7 @@ local function registerProxy(player, rf)
 		isRunning = RunService:IsRunning(),
 	})
 	if not ok or not res or not res.Success then
-		warn(`[MCPFork] proxy register failed for {player.Name}`)
+		warn(`[robloxstudio-mcp] proxy register failed for {player.Name}`)
 		return nil
 	end
 	local body = HttpService:JSONDecode(res.Body)
@@ -551,6 +556,7 @@ local InputHandlers = TS.import(script, script.Parent, "handlers", "InputHandler
 local LogHandlers = TS.import(script, script.Parent, "handlers", "LogHandlers")
 local SerializationHandlers = TS.import(script, script.Parent, "handlers", "SerializationHandlers")
 local MemoryHandlers = TS.import(script, script.Parent, "handlers", "MemoryHandlers")
+local SceneAnalysisHandlers = TS.import(script, script.Parent, "handlers", "SceneAnalysisHandlers")
 -- Per-plugin-load random GUID. Used as the /poll URL param so the server
 -- can tell our polls apart from any other plugin's polls. Not user-facing —
 -- MCP tools and the LLM operate on instanceId (the place identifier).
@@ -683,6 +689,7 @@ local routeMap = {
 	["/api/export-rbxm"] = SerializationHandlers.exportRbxm,
 	["/api/import-rbxm"] = SerializationHandlers.importRbxm,
 	["/api/get-memory-breakdown"] = MemoryHandlers.getMemoryBreakdown,
+	["/api/get-scene-analysis"] = SceneAnalysisHandlers.getSceneAnalysis,
 }
 local function processRequest(request)
 	local endpoint = request.endpoint
@@ -1256,9 +1263,9 @@ local function computeBridgeStamp()
 	for i = 1, #combined do
 		h = (h * 33 + (string.byte(combined, i))) % 2147483647
 	end
-	-- "2.14.0" is replaced with the package version at package time
+	-- "2.15.0" is replaced with the package version at package time
 	-- (scripts/build-plugin.mjs injectVersion), so a release bump also restamps.
-	return `{tostring(h)}-2.14.0`
+	return `{tostring(h)}-2.15.0`
 end
 local BRIDGE_STAMP = computeBridgeStamp()
 local function setSource(scriptInst, source)
@@ -5070,6 +5077,255 @@ return {
           </Properties>
         </Item>
         <Item class="ModuleScript" referent="16">
+          <Properties>
+            <string name="Name">SceneAnalysisHandlers</string>
+            <string name="Source"><![CDATA[-- Compiled with roblox-ts v3.0.0
+local MODE_CONFIGS = {
+	instance_composition = {
+		method = "GetInstanceCompositionAsync",
+		query = function(service)
+			return service:GetInstanceCompositionAsync()
+		end,
+	},
+	script_memory = {
+		method = "GetScriptMemoryAsync",
+		query = function(service)
+			return service:GetScriptMemoryAsync()
+		end,
+	},
+	unparented_instances = {
+		method = "GetUnparentedInstancesAsync",
+		query = function(service)
+			return service:GetUnparentedInstancesAsync()
+		end,
+	},
+	triangle_composition = {
+		method = "GetTriangleCompositionAsync",
+		query = function(service)
+			return service:GetTriangleCompositionAsync()
+		end,
+		sortByTriangles = true,
+	},
+	animation_memory = {
+		method = "GetAnimationMemoryAsync",
+		query = function(service)
+			return service:GetAnimationMemoryAsync()
+		end,
+	},
+	audio_memory = {
+		method = "GetAudioMemoryAsync",
+		query = function(service)
+			return service:GetAudioMemoryAsync()
+		end,
+	},
+}
+local ALL_MODES = { "instance_composition", "script_memory", "unparented_instances", "triangle_composition", "animation_memory", "audio_memory" }
+local function betaDisabledError()
+	return {
+		error = "scene_analysis_not_enabled",
+		message = "SceneAnalysisService is not enabled. Enable Scene Analysis in Studio Beta Features and restart Studio.",
+		betaFeatureRequired = true,
+	}
+end
+local function isBetaDisabledError(value)
+	local _value = value
+	local _condition = type(_value) == "string"
+	if _condition then
+		_condition = (string.find(value, "SceneAnalysisService is not enabled", 1, true)) ~= nil
+	end
+	return _condition
+end
+local function getSceneAnalysisService()
+	local provider = game
+	local ok, service = pcall(function()
+		return provider:GetService("SceneAnalysisService")
+	end)
+	if not ok or not service then
+		return {
+			error = "scene_analysis_unavailable",
+			message = `SceneAnalysisService is unavailable: {tostring(service)}`,
+		}
+	end
+	return service
+end
+local function normalizeMode(mode)
+	if mode == nil or mode == "all" then
+		return "all"
+	end
+	local _mode = mode
+	local _condition = not (type(_mode) == "string")
+	if not _condition then
+		_condition = MODE_CONFIGS[mode] == nil
+	end
+	if _condition then
+		return {
+			error = "invalid_mode",
+			message = `mode must be one of: all, {table.concat(ALL_MODES, ", ")}`,
+		}
+	end
+	return mode
+end
+local function normalizeTopN(topN)
+	local _topN = topN
+	if not (type(_topN) == "number") then
+		return 10
+	end
+	return math.clamp(math.floor(topN), 1, 100)
+end
+local function countLeaves(node)
+	local children = node.Children
+	if children and #children > 0 then
+		local total = 0
+		for _, child in children do
+			total += countLeaves(child)
+		end
+		return total
+	end
+	return 1
+end
+local function flattenLeaves(node, out)
+	local children = node.Children
+	if children and #children > 0 then
+		for _, child in children do
+			flattenLeaves(child, out)
+		end
+		return nil
+	end
+	local _out = out
+	local _node = node
+	table.insert(_out, _node)
+end
+local function compactEntry(node)
+	local entry = {
+		name = node.Name,
+	}
+	if node.Size ~= nil then
+		entry.size = node.Size
+	end
+	if node.Sizes ~= nil then
+		entry.sizes = node.Sizes
+	end
+	if node.AssetId ~= nil then
+		entry.asset_id = node.AssetId
+	end
+	return entry
+end
+local function compactRoot(node, leafCount)
+	local children = node.Children
+	local root = {
+		name = node.Name,
+		child_count = if children then #children else 0,
+		leaf_count = leafCount,
+	}
+	if node.Size ~= nil then
+		root.size = node.Size
+	end
+	if node.Sizes ~= nil then
+		root.sizes = node.Sizes
+	end
+	return root
+end
+local function metric(node, sortByTriangles)
+	if sortByTriangles then
+		local sizes = node.Sizes
+		local triangles = if sizes then sizes.Triangles else nil
+		local _condition = triangles
+		if _condition == nil then
+			_condition = 0
+		end
+		return _condition
+	end
+	local _condition = node.Size
+	if _condition == nil then
+		_condition = 0
+	end
+	return _condition
+end
+local function summarizeMode(mode, config, service, topN, raw)
+	local started = os.clock()
+	local ok, result = pcall(function()
+		return config.query(service)
+	end)
+	local elapsedMs = math.floor((os.clock() - started) * 1000)
+	if not ok then
+		if isBetaDisabledError(result) then
+			return betaDisabledError()
+		end
+		return {
+			error = "scene_analysis_query_failed",
+			mode = mode,
+			method = config.method,
+			message = tostring(result),
+		}
+	end
+	local tree = result
+	local leaves = {}
+	flattenLeaves(tree, leaves)
+	table.sort(leaves, function(a, b)
+		return metric(a, config.sortByTriangles == true) > metric(b, config.sortByTriangles == true)
+	end)
+	local top = {}
+	do
+		local i = 0
+		local _shouldIncrement = false
+		while true do
+			if _shouldIncrement then
+				i += 1
+			else
+				_shouldIncrement = true
+			end
+			if not (i < math.min(topN, #leaves)) then
+				break
+			end
+			local _arg0 = compactEntry(leaves[i + 1])
+			table.insert(top, _arg0)
+		end
+	end
+	local body = {
+		mode = mode,
+		method = config.method,
+		elapsed_ms = elapsedMs,
+		root = compactRoot(tree, #leaves),
+		top = top,
+	}
+	if raw then
+		body.tree = tree
+	end
+	return body
+end
+local function getSceneAnalysis(requestData)
+	local mode = normalizeMode(requestData.mode)
+	if not (type(mode) == "string") then
+		return mode
+	end
+	local serviceOrError = getSceneAnalysisService()
+	local _value = serviceOrError.IsA
+	if not (_value ~= 0 and _value == _value and _value ~= "" and _value) then
+		return serviceOrError
+	end
+	local service = serviceOrError
+	local topN = normalizeTopN(requestData.topN)
+	local raw = requestData.raw == true
+	if mode ~= "all" then
+		return summarizeMode(mode, MODE_CONFIGS[mode], service, topN, raw)
+	end
+	local body = {}
+	for _, m in ALL_MODES do
+		local result = summarizeMode(m, MODE_CONFIGS[m], service, topN, raw)
+		if result.error == "scene_analysis_not_enabled" then
+			return result
+		end
+		body[m] = result
+	end
+	return body
+end
+return {
+	getSceneAnalysis = getSceneAnalysis,
+}
+]]></string>
+          </Properties>
+        </Item>
+        <Item class="ModuleScript" referent="17">
           <Properties>
             <string name="Name">ScriptHandlers</string>
             <string name="Source"><![CDATA[-- Compiled with roblox-ts v3.0.0
@@ -5765,7 +6021,7 @@ return {
 ]]></string>
           </Properties>
         </Item>
-        <Item class="ModuleScript" referent="17">
+        <Item class="ModuleScript" referent="18">
           <Properties>
             <string name="Name">SerializationHandlers</string>
             <string name="Source"><![CDATA[-- Compiled with roblox-ts v3.0.0
@@ -5951,7 +6207,7 @@ return {
 ]]></string>
           </Properties>
         </Item>
-        <Item class="ModuleScript" referent="18">
+        <Item class="ModuleScript" referent="19">
           <Properties>
             <string name="Name">TestHandlers</string>
             <string name="Source"><![CDATA[-- Compiled with roblox-ts v3.0.0
@@ -6584,7 +6840,7 @@ return {
           </Properties>
         </Item>
       </Item>
-      <Item class="ModuleScript" referent="19">
+      <Item class="ModuleScript" referent="20">
         <Properties>
           <string name="Name">LuauExec</string>
           <string name="Source"><![CDATA[-- Compiled with roblox-ts v3.0.0
@@ -6902,7 +7158,7 @@ return {
 ]]></string>
         </Properties>
       </Item>
-      <Item class="ModuleScript" referent="20">
+      <Item class="ModuleScript" referent="21">
         <Properties>
           <string name="Name">Recording</string>
           <string name="Source"><![CDATA[-- Compiled with roblox-ts v3.0.0
@@ -6932,7 +7188,7 @@ return {
 ]]></string>
         </Properties>
       </Item>
-      <Item class="ModuleScript" referent="21">
+      <Item class="ModuleScript" referent="22">
         <Properties>
           <string name="Name">RenderMonitor</string>
           <string name="Source"><![CDATA[-- Compiled with roblox-ts v3.0.0
@@ -7000,7 +7256,7 @@ return {
 ]]></string>
         </Properties>
       </Item>
-      <Item class="ModuleScript" referent="22">
+      <Item class="ModuleScript" referent="23">
         <Properties>
           <string name="Name">RuntimeLogBuffer</string>
           <string name="Source"><![CDATA[-- Compiled with roblox-ts v3.0.0
@@ -7181,11 +7437,11 @@ return {
 ]]></string>
         </Properties>
       </Item>
-      <Item class="ModuleScript" referent="23">
+      <Item class="ModuleScript" referent="24">
         <Properties>
           <string name="Name">State</string>
           <string name="Source"><![CDATA[-- Compiled with roblox-ts v3.0.0
-local CURRENT_VERSION = "2.14.0"
+local CURRENT_VERSION = "2.15.0"
 local MAX_CONNECTIONS = 5
 local BASE_PORT = 58741
 local activeTabIndex = 0
@@ -7277,7 +7533,7 @@ return {
 ]]></string>
         </Properties>
       </Item>
-      <Item class="ModuleScript" referent="24">
+      <Item class="ModuleScript" referent="25">
         <Properties>
           <string name="Name">StopPlayMonitor</string>
           <string name="Source"><![CDATA[-- Compiled with roblox-ts v3.0.0
@@ -7422,7 +7678,7 @@ return {
 ]]></string>
         </Properties>
       </Item>
-      <Item class="ModuleScript" referent="25">
+      <Item class="ModuleScript" referent="26">
         <Properties>
           <string name="Name">UI</string>
           <string name="Source"><![CDATA[-- Compiled with roblox-ts v3.0.0
@@ -8173,7 +8429,7 @@ return {
 ]]></string>
         </Properties>
       </Item>
-      <Item class="ModuleScript" referent="26">
+      <Item class="ModuleScript" referent="27">
         <Properties>
           <string name="Name">Utils</string>
           <string name="Source"><![CDATA[-- Compiled with roblox-ts v3.0.0
@@ -8703,11 +8959,11 @@ return {
         </Properties>
       </Item>
     </Item>
-    <Item class="Folder" referent="30">
+    <Item class="Folder" referent="31">
       <Properties>
         <string name="Name">include</string>
       </Properties>
-      <Item class="ModuleScript" referent="27">
+      <Item class="ModuleScript" referent="28">
         <Properties>
           <string name="Name">Promise</string>
           <string name="Source"><![CDATA[--[[
@@ -10781,7 +11037,7 @@ return Promise
 ]]></string>
         </Properties>
       </Item>
-      <Item class="ModuleScript" referent="28">
+      <Item class="ModuleScript" referent="29">
         <Properties>
           <string name="Name">RuntimeLib</string>
           <string name="Source"><![CDATA[local Promise = require(script.Parent.Promise)
@@ -11048,15 +11304,15 @@ return TS
         </Properties>
       </Item>
     </Item>
-    <Item class="Folder" referent="31">
+    <Item class="Folder" referent="32">
       <Properties>
         <string name="Name">node_modules</string>
       </Properties>
-      <Item class="Folder" referent="32">
+      <Item class="Folder" referent="33">
         <Properties>
           <string name="Name">@rbxts</string>
         </Properties>
-      <Item class="ModuleScript" referent="29">
+      <Item class="ModuleScript" referent="30">
         <Properties>
           <string name="Name">services</string>
           <string name="Source"><![CDATA[return setmetatable({}, {

package/studio-plugin/MCPPlugin.rbxmx

@@ -102,6 +102,7 @@ local RunService = _services.RunService
 local ServerStorage = _services.ServerStorage
 local RuntimeLogBuffer = TS.import(script, script.Parent, "RuntimeLogBuffer")
 local MemoryHandlers = TS.import(script, script.Parent, "handlers", "MemoryHandlers")
+local SceneAnalysisHandlers = TS.import(script, script.Parent, "handlers", "SceneAnalysisHandlers")
 local CaptureHandlers = TS.import(script, script.Parent, "handlers", "CaptureHandlers")
 local InputHandlers = TS.import(script, script.Parent, "handlers", "InputHandlers")
 local LuauExec = TS.import(script, script.Parent, "LuauExec")
@@ -167,6 +168,7 @@ local CLIENT_BROKER_ALLOWED_ENDPOINTS = {
 	["/api/execute-luau"] = true,
 	["/api/get-runtime-logs"] = true,
 	["/api/get-memory-breakdown"] = true,
+	["/api/get-scene-analysis"] = true,
 	["/api/multiplayer-test-state"] = true,
 	["/api/multiplayer-test-leave-client"] = true,
 	["/api/capture-begin"] = true,
@@ -324,7 +326,7 @@ end
 local function setupClientBroker()
 	local rf = ReplicatedStorage:WaitForChild(BROKER_NAME, 10)
 	if not rf or not rf:IsA("RemoteFunction") then
-		warn(`[MCPFork] client: {BROKER_NAME} not found`)
+		warn(`[robloxstudio-mcp] client: {BROKER_NAME} not found`)
 		return nil
 	end
 	rf.OnClientInvoke = function(payload)
@@ -340,6 +342,9 @@ local function setupClientBroker()
 		if payload and payload.endpoint == "/api/get-memory-breakdown" then
 			return MemoryHandlers.getMemoryBreakdown(payload.data or {})
 		end
+		if payload and payload.endpoint == "/api/get-scene-analysis" then
+			return SceneAnalysisHandlers.getSceneAnalysis(payload.data or {})
+		end
 		if payload and payload.endpoint == "/api/multiplayer-test-state" then
 			return handleMultiplayerTestState()
 		end
@@ -453,7 +458,7 @@ local function registerProxy(player, rf)
 		isRunning = RunService:IsRunning(),
 	})
 	if not ok or not res or not res.Success then
-		warn(`[MCPFork] proxy register failed for {player.Name}`)
+		warn(`[robloxstudio-mcp] proxy register failed for {player.Name}`)
 		return nil
 	end
 	local body = HttpService:JSONDecode(res.Body)
@@ -551,6 +556,7 @@ local InputHandlers = TS.import(script, script.Parent, "handlers", "InputHandler
 local LogHandlers = TS.import(script, script.Parent, "handlers", "LogHandlers")
 local SerializationHandlers = TS.import(script, script.Parent, "handlers", "SerializationHandlers")
 local MemoryHandlers = TS.import(script, script.Parent, "handlers", "MemoryHandlers")
+local SceneAnalysisHandlers = TS.import(script, script.Parent, "handlers", "SceneAnalysisHandlers")
 -- Per-plugin-load random GUID. Used as the /poll URL param so the server
 -- can tell our polls apart from any other plugin's polls. Not user-facing —
 -- MCP tools and the LLM operate on instanceId (the place identifier).
@@ -683,6 +689,7 @@ local routeMap = {
 	["/api/export-rbxm"] = SerializationHandlers.exportRbxm,
 	["/api/import-rbxm"] = SerializationHandlers.importRbxm,
 	["/api/get-memory-breakdown"] = MemoryHandlers.getMemoryBreakdown,
+	["/api/get-scene-analysis"] = SceneAnalysisHandlers.getSceneAnalysis,
 }
 local function processRequest(request)
 	local endpoint = request.endpoint
@@ -1256,9 +1263,9 @@ local function computeBridgeStamp()
 	for i = 1, #combined do
 		h = (h * 33 + (string.byte(combined, i))) % 2147483647
 	end
-	-- "2.14.0" is replaced with the package version at package time
+	-- "2.15.0" is replaced with the package version at package time
 	-- (scripts/build-plugin.mjs injectVersion), so a release bump also restamps.
-	return `{tostring(h)}-2.14.0`
+	return `{tostring(h)}-2.15.0`
 end
 local BRIDGE_STAMP = computeBridgeStamp()
 local function setSource(scriptInst, source)
@@ -5070,6 +5077,255 @@ return {
           </Properties>
         </Item>
         <Item class="ModuleScript" referent="16">
+          <Properties>
+            <string name="Name">SceneAnalysisHandlers</string>
+            <string name="Source"><![CDATA[-- Compiled with roblox-ts v3.0.0
+local MODE_CONFIGS = {
+	instance_composition = {
+		method = "GetInstanceCompositionAsync",
+		query = function(service)
+			return service:GetInstanceCompositionAsync()
+		end,
+	},
+	script_memory = {
+		method = "GetScriptMemoryAsync",
+		query = function(service)
+			return service:GetScriptMemoryAsync()
+		end,
+	},
+	unparented_instances = {
+		method = "GetUnparentedInstancesAsync",
+		query = function(service)
+			return service:GetUnparentedInstancesAsync()
+		end,
+	},
+	triangle_composition = {
+		method = "GetTriangleCompositionAsync",
+		query = function(service)
+			return service:GetTriangleCompositionAsync()
+		end,
+		sortByTriangles = true,
+	},
+	animation_memory = {
+		method = "GetAnimationMemoryAsync",
+		query = function(service)
+			return service:GetAnimationMemoryAsync()
+		end,
+	},
+	audio_memory = {
+		method = "GetAudioMemoryAsync",
+		query = function(service)
+			return service:GetAudioMemoryAsync()
+		end,
+	},
+}
+local ALL_MODES = { "instance_composition", "script_memory", "unparented_instances", "triangle_composition", "animation_memory", "audio_memory" }
+local function betaDisabledError()
+	return {
+		error = "scene_analysis_not_enabled",
+		message = "SceneAnalysisService is not enabled. Enable Scene Analysis in Studio Beta Features and restart Studio.",
+		betaFeatureRequired = true,
+	}
+end
+local function isBetaDisabledError(value)
+	local _value = value
+	local _condition = type(_value) == "string"
+	if _condition then
+		_condition = (string.find(value, "SceneAnalysisService is not enabled", 1, true)) ~= nil
+	end
+	return _condition
+end
+local function getSceneAnalysisService()
+	local provider = game
+	local ok, service = pcall(function()
+		return provider:GetService("SceneAnalysisService")
+	end)
+	if not ok or not service then
+		return {
+			error = "scene_analysis_unavailable",
+			message = `SceneAnalysisService is unavailable: {tostring(service)}`,
+		}
+	end
+	return service
+end
+local function normalizeMode(mode)
+	if mode == nil or mode == "all" then
+		return "all"
+	end
+	local _mode = mode
+	local _condition = not (type(_mode) == "string")
+	if not _condition then
+		_condition = MODE_CONFIGS[mode] == nil
+	end
+	if _condition then
+		return {
+			error = "invalid_mode",
+			message = `mode must be one of: all, {table.concat(ALL_MODES, ", ")}`,
+		}
+	end
+	return mode
+end
+local function normalizeTopN(topN)
+	local _topN = topN
+	if not (type(_topN) == "number") then
+		return 10
+	end
+	return math.clamp(math.floor(topN), 1, 100)
+end
+local function countLeaves(node)
+	local children = node.Children
+	if children and #children > 0 then
+		local total = 0
+		for _, child in children do
+			total += countLeaves(child)
+		end
+		return total
+	end
+	return 1
+end
+local function flattenLeaves(node, out)
+	local children = node.Children
+	if children and #children > 0 then
+		for _, child in children do
+			flattenLeaves(child, out)
+		end
+		return nil
+	end
+	local _out = out
+	local _node = node
+	table.insert(_out, _node)
+end
+local function compactEntry(node)
+	local entry = {
+		name = node.Name,
+	}
+	if node.Size ~= nil then
+		entry.size = node.Size
+	end
+	if node.Sizes ~= nil then
+		entry.sizes = node.Sizes
+	end
+	if node.AssetId ~= nil then
+		entry.asset_id = node.AssetId
+	end
+	return entry
+end
+local function compactRoot(node, leafCount)
+	local children = node.Children
+	local root = {
+		name = node.Name,
+		child_count = if children then #children else 0,
+		leaf_count = leafCount,
+	}
+	if node.Size ~= nil then
+		root.size = node.Size
+	end
+	if node.Sizes ~= nil then
+		root.sizes = node.Sizes
+	end
+	return root
+end
+local function metric(node, sortByTriangles)
+	if sortByTriangles then
+		local sizes = node.Sizes
+		local triangles = if sizes then sizes.Triangles else nil
+		local _condition = triangles
+		if _condition == nil then
+			_condition = 0
+		end
+		return _condition
+	end
+	local _condition = node.Size
+	if _condition == nil then
+		_condition = 0
+	end
+	return _condition
+end
+local function summarizeMode(mode, config, service, topN, raw)
+	local started = os.clock()
+	local ok, result = pcall(function()
+		return config.query(service)
+	end)
+	local elapsedMs = math.floor((os.clock() - started) * 1000)
+	if not ok then
+		if isBetaDisabledError(result) then
+			return betaDisabledError()
+		end
+		return {
+			error = "scene_analysis_query_failed",
+			mode = mode,
+			method = config.method,
+			message = tostring(result),
+		}
+	end
+	local tree = result
+	local leaves = {}
+	flattenLeaves(tree, leaves)
+	table.sort(leaves, function(a, b)
+		return metric(a, config.sortByTriangles == true) > metric(b, config.sortByTriangles == true)
+	end)
+	local top = {}
+	do
+		local i = 0
+		local _shouldIncrement = false
+		while true do
+			if _shouldIncrement then
+				i += 1
+			else
+				_shouldIncrement = true
+			end
+			if not (i < math.min(topN, #leaves)) then
+				break
+			end
+			local _arg0 = compactEntry(leaves[i + 1])
+			table.insert(top, _arg0)
+		end
+	end
+	local body = {
+		mode = mode,
+		method = config.method,
+		elapsed_ms = elapsedMs,
+		root = compactRoot(tree, #leaves),
+		top = top,
+	}
+	if raw then
+		body.tree = tree
+	end
+	return body
+end
+local function getSceneAnalysis(requestData)
+	local mode = normalizeMode(requestData.mode)
+	if not (type(mode) == "string") then
+		return mode
+	end
+	local serviceOrError = getSceneAnalysisService()
+	local _value = serviceOrError.IsA
+	if not (_value ~= 0 and _value == _value and _value ~= "" and _value) then
+		return serviceOrError
+	end
+	local service = serviceOrError
+	local topN = normalizeTopN(requestData.topN)
+	local raw = requestData.raw == true
+	if mode ~= "all" then
+		return summarizeMode(mode, MODE_CONFIGS[mode], service, topN, raw)
+	end
+	local body = {}
+	for _, m in ALL_MODES do
+		local result = summarizeMode(m, MODE_CONFIGS[m], service, topN, raw)
+		if result.error == "scene_analysis_not_enabled" then
+			return result
+		end
+		body[m] = result
+	end
+	return body
+end
+return {
+	getSceneAnalysis = getSceneAnalysis,
+}
+]]></string>
+          </Properties>
+        </Item>
+        <Item class="ModuleScript" referent="17">
           <Properties>
             <string name="Name">ScriptHandlers</string>
             <string name="Source"><![CDATA[-- Compiled with roblox-ts v3.0.0
@@ -5765,7 +6021,7 @@ return {
 ]]></string>
           </Properties>
         </Item>
-        <Item class="ModuleScript" referent="17">
+        <Item class="ModuleScript" referent="18">
           <Properties>
             <string name="Name">SerializationHandlers</string>
             <string name="Source"><![CDATA[-- Compiled with roblox-ts v3.0.0
@@ -5951,7 +6207,7 @@ return {
 ]]></string>
           </Properties>
         </Item>
-        <Item class="ModuleScript" referent="18">
+        <Item class="ModuleScript" referent="19">
           <Properties>
             <string name="Name">TestHandlers</string>
             <string name="Source"><![CDATA[-- Compiled with roblox-ts v3.0.0
@@ -6584,7 +6840,7 @@ return {
           </Properties>
         </Item>
       </Item>
-      <Item class="ModuleScript" referent="19">
+      <Item class="ModuleScript" referent="20">
         <Properties>
           <string name="Name">LuauExec</string>
           <string name="Source"><![CDATA[-- Compiled with roblox-ts v3.0.0
@@ -6902,7 +7158,7 @@ return {
 ]]></string>
         </Properties>
       </Item>
-      <Item class="ModuleScript" referent="20">
+      <Item class="ModuleScript" referent="21">
         <Properties>
           <string name="Name">Recording</string>
           <string name="Source"><![CDATA[-- Compiled with roblox-ts v3.0.0
@@ -6932,7 +7188,7 @@ return {
 ]]></string>
         </Properties>
       </Item>
-      <Item class="ModuleScript" referent="21">
+      <Item class="ModuleScript" referent="22">
         <Properties>
           <string name="Name">RenderMonitor</string>
           <string name="Source"><![CDATA[-- Compiled with roblox-ts v3.0.0
@@ -7000,7 +7256,7 @@ return {
 ]]></string>
         </Properties>
       </Item>
-      <Item class="ModuleScript" referent="22">
+      <Item class="ModuleScript" referent="23">
         <Properties>
           <string name="Name">RuntimeLogBuffer</string>
           <string name="Source"><![CDATA[-- Compiled with roblox-ts v3.0.0
@@ -7181,11 +7437,11 @@ return {
 ]]></string>
         </Properties>
       </Item>
-      <Item class="ModuleScript" referent="23">
+      <Item class="ModuleScript" referent="24">
         <Properties>
           <string name="Name">State</string>
           <string name="Source"><![CDATA[-- Compiled with roblox-ts v3.0.0
-local CURRENT_VERSION = "2.14.0"
+local CURRENT_VERSION = "2.15.0"
 local MAX_CONNECTIONS = 5
 local BASE_PORT = 58741
 local activeTabIndex = 0
@@ -7277,7 +7533,7 @@ return {
 ]]></string>
         </Properties>
       </Item>
-      <Item class="ModuleScript" referent="24">
+      <Item class="ModuleScript" referent="25">
         <Properties>
           <string name="Name">StopPlayMonitor</string>
           <string name="Source"><![CDATA[-- Compiled with roblox-ts v3.0.0
@@ -7422,7 +7678,7 @@ return {
 ]]></string>
         </Properties>
       </Item>
-      <Item class="ModuleScript" referent="25">
+      <Item class="ModuleScript" referent="26">
         <Properties>
           <string name="Name">UI</string>
           <string name="Source"><![CDATA[-- Compiled with roblox-ts v3.0.0
@@ -8173,7 +8429,7 @@ return {
 ]]></string>
         </Properties>
       </Item>
-      <Item class="ModuleScript" referent="26">
+      <Item class="ModuleScript" referent="27">
         <Properties>
           <string name="Name">Utils</string>
           <string name="Source"><![CDATA[-- Compiled with roblox-ts v3.0.0
@@ -8703,11 +8959,11 @@ return {
         </Properties>
       </Item>
     </Item>
-    <Item class="Folder" referent="30">
+    <Item class="Folder" referent="31">
       <Properties>
         <string name="Name">include</string>
       </Properties>
-      <Item class="ModuleScript" referent="27">
+      <Item class="ModuleScript" referent="28">
         <Properties>
           <string name="Name">Promise</string>
           <string name="Source"><![CDATA[--[[
@@ -10781,7 +11037,7 @@ return Promise
 ]]></string>
         </Properties>
       </Item>
-      <Item class="ModuleScript" referent="28">
+      <Item class="ModuleScript" referent="29">
         <Properties>
           <string name="Name">RuntimeLib</string>
           <string name="Source"><![CDATA[local Promise = require(script.Parent.Promise)
@@ -11048,15 +11304,15 @@ return TS
         </Properties>
       </Item>
     </Item>
-    <Item class="Folder" referent="31">
+    <Item class="Folder" referent="32">
       <Properties>
         <string name="Name">node_modules</string>
       </Properties>
-      <Item class="Folder" referent="32">
+      <Item class="Folder" referent="33">
         <Properties>
           <string name="Name">@rbxts</string>
         </Properties>
-      <Item class="ModuleScript" referent="29">
+      <Item class="ModuleScript" referent="30">
         <Properties>
           <string name="Name">services</string>
           <string name="Source"><![CDATA[return setmetatable({}, {

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

@@ -1,6 +1,7 @@
 import { HttpService, Players, ReplicatedStorage, RunService, ServerStorage } from "@rbxts/services";
 import RuntimeLogBuffer from "./RuntimeLogBuffer";
 import MemoryHandlers from "./handlers/MemoryHandlers";
+import SceneAnalysisHandlers from "./handlers/SceneAnalysisHandlers";
 import CaptureHandlers from "./handlers/CaptureHandlers";
 import InputHandlers from "./handlers/InputHandlers";
 import LuauExec from "./LuauExec";
@@ -87,6 +88,7 @@ const CLIENT_BROKER_ALLOWED_ENDPOINTS = new Set<string>([
 	"/api/execute-luau",
 	"/api/get-runtime-logs",
 	"/api/get-memory-breakdown",
+	"/api/get-scene-analysis",
 	"/api/multiplayer-test-state",
 	"/api/multiplayer-test-leave-client",
 	// Screenshot capture must run in the client peer (CaptureService captures
@@ -224,7 +226,7 @@ function handleMultiplayerTestLeaveClient(): unknown {
 function setupClientBroker() {
 	const rf = ReplicatedStorage.WaitForChild(BROKER_NAME, 10);
 	if (!rf || !rf.IsA("RemoteFunction")) {
-		warn(`[MCPFork] client: ${BROKER_NAME} not found`);
+		warn(`[robloxstudio-mcp] client: ${BROKER_NAME} not found`);
 		return;
 	}
 	rf.OnClientInvoke = (payload: BrokerEnvelope | undefined) => {
@@ -240,6 +242,9 @@ function setupClientBroker() {
 		if (payload && payload.endpoint === "/api/get-memory-breakdown") {
 			return MemoryHandlers.getMemoryBreakdown(payload.data ?? {});
 		}
+		if (payload && payload.endpoint === "/api/get-scene-analysis") {
+			return SceneAnalysisHandlers.getSceneAnalysis(payload.data ?? {});
+		}
 		if (payload && payload.endpoint === "/api/multiplayer-test-state") {
 			return handleMultiplayerTestState();
 		}
@@ -326,7 +331,7 @@ function registerProxy(player: Player, rf: RemoteFunction) {
 		isRunning: RunService.IsRunning(),
 	});
 	if (!ok || !res || !res.Success) {
-		warn(`[MCPFork] proxy register failed for ${player.Name}`);
+		warn(`[robloxstudio-mcp] proxy register failed for ${player.Name}`);
 		return;
 	}
 	const body = HttpService.JSONDecode(res.Body) as ReadyResponseBody;

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

@@ -16,6 +16,7 @@ import InputHandlers from "./handlers/InputHandlers";
 import LogHandlers from "./handlers/LogHandlers";
 import SerializationHandlers from "./handlers/SerializationHandlers";
 import MemoryHandlers from "./handlers/MemoryHandlers";
+import SceneAnalysisHandlers from "./handlers/SceneAnalysisHandlers";
 import { Connection, RequestPayload, PollResponse, ReadyResponse } from "../types";
 
 // Per-plugin-load random GUID. Used as the /poll URL param so the server
@@ -162,6 +163,7 @@ const routeMap: Record<string, Handler> = {
 	"/api/import-rbxm": SerializationHandlers.importRbxm,
 
 	"/api/get-memory-breakdown": MemoryHandlers.getMemoryBreakdown,
+	"/api/get-scene-analysis": SceneAnalysisHandlers.getSceneAnalysis,
 };
 
 function processRequest(request: RequestPayload): unknown {

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

@@ -0,0 +1,216 @@
+interface SceneAnalysisServiceLike extends Instance {
+	GetInstanceCompositionAsync(this: SceneAnalysisServiceLike): unknown;
+	GetScriptMemoryAsync(this: SceneAnalysisServiceLike): unknown;
+	GetUnparentedInstancesAsync(this: SceneAnalysisServiceLike): unknown;
+	GetTriangleCompositionAsync(this: SceneAnalysisServiceLike): unknown;
+	GetAnimationMemoryAsync(this: SceneAnalysisServiceLike): unknown;
+	GetAudioMemoryAsync(this: SceneAnalysisServiceLike): unknown;
+}
+
+interface SceneAnalysisNode {
+	Name?: string;
+	Size?: number;
+	Sizes?: Record<string, number>;
+	Children?: SceneAnalysisNode[];
+	AssetId?: string;
+}
+
+interface ModeConfig {
+	method: string;
+	query: (service: SceneAnalysisServiceLike) => unknown;
+	sortByTriangles?: boolean;
+}
+
+const MODE_CONFIGS: Record<string, ModeConfig> = {
+	instance_composition: {
+		method: "GetInstanceCompositionAsync",
+		query: (service) => service.GetInstanceCompositionAsync(),
+	},
+	script_memory: {
+		method: "GetScriptMemoryAsync",
+		query: (service) => service.GetScriptMemoryAsync(),
+	},
+	unparented_instances: {
+		method: "GetUnparentedInstancesAsync",
+		query: (service) => service.GetUnparentedInstancesAsync(),
+	},
+	triangle_composition: {
+		method: "GetTriangleCompositionAsync",
+		query: (service) => service.GetTriangleCompositionAsync(),
+		sortByTriangles: true,
+	},
+	animation_memory: {
+		method: "GetAnimationMemoryAsync",
+		query: (service) => service.GetAnimationMemoryAsync(),
+	},
+	audio_memory: {
+		method: "GetAudioMemoryAsync",
+		query: (service) => service.GetAudioMemoryAsync(),
+	},
+};
+
+const ALL_MODES = [
+	"instance_composition",
+	"script_memory",
+	"unparented_instances",
+	"triangle_composition",
+	"animation_memory",
+	"audio_memory",
+];
+
+function betaDisabledError(): Record<string, unknown> {
+	return {
+		error: "scene_analysis_not_enabled",
+		message: "SceneAnalysisService is not enabled. Enable Scene Analysis in Studio Beta Features and restart Studio.",
+		betaFeatureRequired: true,
+	};
+}
+
+function isBetaDisabledError(value: unknown): boolean {
+	return typeIs(value, "string") && string.find(value, "SceneAnalysisService is not enabled", 1, true)[0] !== undefined;
+}
+
+function getSceneAnalysisService(): SceneAnalysisServiceLike | Record<string, unknown> {
+	const provider = game as unknown as { GetService(serviceName: string): Instance };
+	const [ok, service] = pcall(() => provider.GetService("SceneAnalysisService") as SceneAnalysisServiceLike);
+	if (!ok || !service) {
+		return {
+			error: "scene_analysis_unavailable",
+			message: `SceneAnalysisService is unavailable: ${tostring(service)}`,
+		};
+	}
+	return service;
+}
+
+function normalizeMode(mode: unknown): string | Record<string, unknown> {
+	if (mode === undefined || mode === "all") return "all";
+	if (!typeIs(mode, "string") || MODE_CONFIGS[mode] === undefined) {
+		return {
+			error: "invalid_mode",
+			message: `mode must be one of: all, ${ALL_MODES.join(", ")}`,
+		};
+	}
+	return mode;
+}
+
+function normalizeTopN(topN: unknown): number {
+	if (!typeIs(topN, "number")) return 10;
+	return math.clamp(math.floor(topN), 1, 100);
+}
+
+function countLeaves(node: SceneAnalysisNode): number {
+	const children = node.Children;
+	if (children && children.size() > 0) {
+		let total = 0;
+		for (const child of children) total += countLeaves(child);
+		return total;
+	}
+	return 1;
+}
+
+function flattenLeaves(node: SceneAnalysisNode, out: SceneAnalysisNode[]): void {
+	const children = node.Children;
+	if (children && children.size() > 0) {
+		for (const child of children) flattenLeaves(child, out);
+		return;
+	}
+	out.push(node);
+}
+
+function compactEntry(node: SceneAnalysisNode): Record<string, unknown> {
+	const entry: Record<string, unknown> = {
+		name: node.Name,
+	};
+	if (node.Size !== undefined) entry.size = node.Size;
+	if (node.Sizes !== undefined) entry.sizes = node.Sizes;
+	if (node.AssetId !== undefined) entry.asset_id = node.AssetId;
+	return entry;
+}
+
+function compactRoot(node: SceneAnalysisNode, leafCount: number): Record<string, unknown> {
+	const children = node.Children;
+	const root: Record<string, unknown> = {
+		name: node.Name,
+		child_count: children ? children.size() : 0,
+		leaf_count: leafCount,
+	};
+	if (node.Size !== undefined) root.size = node.Size;
+	if (node.Sizes !== undefined) root.sizes = node.Sizes;
+	return root;
+}
+
+function metric(node: SceneAnalysisNode, sortByTriangles: boolean): number {
+	if (sortByTriangles) {
+		const sizes = node.Sizes;
+		const triangles = sizes ? sizes.Triangles : undefined;
+		return triangles ?? 0;
+	}
+	return node.Size ?? 0;
+}
+
+function summarizeMode(
+	mode: string,
+	config: ModeConfig,
+	service: SceneAnalysisServiceLike,
+	topN: number,
+	raw: boolean,
+): Record<string, unknown> {
+	const started = os.clock();
+	const [ok, result] = pcall(() => config.query(service) as SceneAnalysisNode);
+	const elapsedMs = math.floor((os.clock() - started) * 1000);
+
+	if (!ok) {
+		if (isBetaDisabledError(result)) return betaDisabledError();
+		return {
+			error: "scene_analysis_query_failed",
+			mode,
+			method: config.method,
+			message: tostring(result),
+		};
+	}
+
+	const tree = result as SceneAnalysisNode;
+	const leaves: SceneAnalysisNode[] = [];
+	flattenLeaves(tree, leaves);
+	leaves.sort((a, b) => metric(a, config.sortByTriangles === true) > metric(b, config.sortByTriangles === true));
+
+	const top: Record<string, unknown>[] = [];
+	for (let i = 0; i < math.min(topN, leaves.size()); i++) {
+		top.push(compactEntry(leaves[i]));
+	}
+
+	const body: Record<string, unknown> = {
+		mode,
+		method: config.method,
+		elapsed_ms: elapsedMs,
+		root: compactRoot(tree, leaves.size()),
+		top,
+	};
+	if (raw) body.tree = tree;
+	return body;
+}
+
+function getSceneAnalysis(requestData: Record<string, unknown>): unknown {
+	const mode = normalizeMode(requestData.mode);
+	if (!typeIs(mode, "string")) return mode;
+
+	const serviceOrError = getSceneAnalysisService();
+	if (!serviceOrError.IsA) return serviceOrError;
+	const service = serviceOrError as SceneAnalysisServiceLike;
+	const topN = normalizeTopN(requestData.topN);
+	const raw = requestData.raw === true;
+
+	if (mode !== "all") {
+		return summarizeMode(mode, MODE_CONFIGS[mode], service, topN, raw);
+	}
+
+	const body: Record<string, unknown> = {};
+	for (const m of ALL_MODES) {
+		const result = summarizeMode(m, MODE_CONFIGS[m], service, topN, raw);
+		if (result.error === "scene_analysis_not_enabled") return result;
+		body[m] = result;
+	}
+	return body;
+}
+
+export = { getSceneAnalysis };