@el4cteo/rbx-studio-mcp 0.1.0

package/plugin/src/handlers/Discover.luau

@@ -0,0 +1,289 @@
+--!strict
+--[[
+	Hierarchy exploration: tree, inspect and find.
+
+	These three replace roughly a dozen tools in competing servers
+	(get_file_tree, get_project_structure, get_instance_children, search_objects,
+	search_by_property, get_attributes, get_tags, get_tagged, get_class_info...).
+	Fewer, wider tools mean less schema in the agent's context and fewer chances
+	to pick the wrong one.
+
+	Traversal is bounded everywhere. A production place can hold hundreds of
+	thousands of instances, and an unbounded walk would either time out or return
+	something no context window can hold.
+]]
+
+local CollectionService = game:GetService("CollectionService")
+
+local Dispatch = require(script.Parent.Parent.Dispatch)
+local Paths = require(script.Parent.Parent.Paths)
+local Scope = require(script.Parent.Parent.Scope)
+local Serialize = require(script.Parent.Parent.Serialize)
+
+-- Ceiling on nodes visited in one call, independent of how many are returned.
+-- Protects against a `find` over a whole place blocking Studio's main thread.
+local MAX_VISITS = 200_000
+
+local Discover = {}
+
+-- Root-level noise filtering lives in Scope, which the script tools share.
+local isNoisy = Scope.isNoisy
+
+-- One memo per request keeps path formatting linear when many siblings share a
+-- name; see Paths.of.
+local function summarise(instance: Instance, memo: Paths.NameIndex): { [string]: any }
+	return {
+		path = Paths.of(instance, memo),
+		className = instance.ClassName,
+		childCount = #instance:GetChildren(),
+	}
+end
+
+--[[
+	Breadth-first walk to `depth`, newest level last, so a truncated result is
+	still a coherent picture of the top of the tree rather than one deep spur.
+]]
+function Discover.tree(params: { [string]: any }): { [string]: any }
+	local root = if params.path then Paths.resolve(params.path) else game
+	local depth = tonumber(params.depth) or 2
+	local limit = tonumber(params.limit) or 100
+	local offset = tonumber(params.offset) or 0
+	local classFilter = params.className
+	local nameFilter = if params.nameContains then string.lower(params.nameContains) else nil
+
+	local matched: { Instance } = {}
+	local hidden = 0
+	local visits = 0
+	local frontier: { Instance } = { root }
+
+	for level = 1, depth do
+		local nextFrontier: { Instance } = {}
+		for _, parent in frontier do
+			for _, child in parent:GetChildren() do
+				visits += 1
+				if visits > MAX_VISITS then
+					break
+				end
+				if isNoisy(child) then
+					if parent == game then
+						hidden += 1
+					end
+					continue
+				end
+
+				local keep = true
+				if classFilter and not child:IsA(classFilter) then
+					keep = false
+				end
+				if keep and nameFilter and not string.find(string.lower(child.Name), nameFilter, 1, true) then
+					keep = false
+				end
+				if keep then
+					table.insert(matched, child)
+				end
+				if level < depth then
+					table.insert(nextFrontier, child)
+				end
+			end
+		end
+		frontier = nextFrontier
+		if #frontier == 0 or visits > MAX_VISITS then
+			break
+		end
+	end
+
+	local items: { { [string]: any } } = {}
+	local memo: Paths.NameIndex = {}
+	for index = offset + 1, math.min(offset + limit, #matched) do
+		table.insert(items, summarise(matched[index] :: Instance, memo))
+	end
+
+	return {
+		root = Paths.of(root, memo),
+		items = items,
+		total = #matched,
+		offset = offset,
+		hiddenServices = hidden,
+	}
+end
+
+--[[
+	Detailed read of specific instances. `properties` is chosen server-side from
+	the live API dump, so this handler never needs its own class table.
+]]
+function Discover.inspect(params: { [string]: any }): { [string]: any }
+	local paths = params.paths
+	if typeof(paths) ~= "table" or #paths == 0 then
+		Dispatch.fail(
+			"BAD_PARAMS",
+			"inspect requires a non-empty `paths` array.",
+			'Pass paths like ["Workspace.Model.Part"]. Use `find` or `tree` to discover them.'
+		)
+	end
+
+	local requested: { string }? = params.properties
+	local includeChildren = params.includeChildren ~= false
+	local childLimit = tonumber(params.childLimit) or 25
+
+	local results: { { [string]: any } } = {}
+	local failures: { string } = {}
+	local memo: Paths.NameIndex = {}
+
+	for _, path in paths do
+		local ok, instance = pcall(Paths.resolve, path)
+		if not ok then
+			local err = instance :: any
+			-- The hint carries the sibling listing ("It does have: ..."), which is
+			-- what lets the agent correct the path without another round trip.
+			local reason = if typeof(err) == "table"
+				then (if err.hint then err.message .. " " .. err.hint else err.message)
+				else tostring(err)
+			table.insert(failures, string.format("%s: %s", path, reason))
+			continue
+		end
+
+		local target = instance :: Instance
+		local properties: { [string]: any } = {}
+		if requested then
+			for _, name in requested do
+				local readOk, value = Serialize.readProperty(target, name)
+				if readOk then
+					properties[name] = value
+				end
+			end
+		end
+
+		local entry: { [string]: any } = {
+			path = Paths.of(target, memo),
+			-- Echoed back so a caller can correlate the answer with what it asked
+			-- for. `path` is the canonical form and often differs: ask about
+			-- "Workspace.Wall" and the answer comes back as "Workspace.Wall[1]".
+			requested = path,
+			className = target.ClassName,
+			properties = properties,
+			childCount = #target:GetChildren(),
+		}
+
+		-- Empty attribute and tag sets are omitted rather than sent as empty
+		-- containers: most instances have neither, and Luau encodes an empty
+		-- table as [] which reads as a list and confuses the shape.
+		local attributes: { [string]: any } = {}
+		local hasAttributes = false
+		for name, value in target:GetAttributes() do
+			attributes[name] = Serialize.value(value)
+			hasAttributes = true
+		end
+		if hasAttributes then
+			entry.attributes = attributes
+		end
+
+		local tags = CollectionService:GetTags(target)
+		if #tags > 0 then
+			entry.tags = tags
+		end
+
+		if includeChildren then
+			local children: { { [string]: any } } = {}
+			for index, child in target:GetChildren() do
+				if index > childLimit then
+					break
+				end
+				table.insert(children, { name = child.Name, className = child.ClassName })
+			end
+			entry.children = children
+		end
+
+		table.insert(results, entry)
+	end
+
+	return { items = results, failures = failures }
+end
+
+--[[
+	One search over name, class, property value and tag.
+
+	Every filter supplied must match (AND), which is what lets a single tool
+	answer "every anchored Part under Workspace whose name contains 'door'"
+	without the agent chaining three calls and intersecting the results itself.
+]]
+function Discover.find(params: { [string]: any }): { [string]: any }
+	local root = if params.path then Paths.resolve(params.path) else game
+	local limit = tonumber(params.limit) or 100
+	local offset = tonumber(params.offset) or 0
+
+	local nameFilter = if params.nameContains then string.lower(params.nameContains) else nil
+	local classFilter = params.className
+	local propertyName = params.propertyName
+	local propertyValue = params.propertyValue
+	local tagFilter = params.tag
+
+	-- A tag query is answered from CollectionService's index rather than by
+	-- walking the tree, which is orders of magnitude cheaper on a big place.
+	local candidates: { Instance }
+	if tagFilter then
+		candidates = CollectionService:GetTagged(tagFilter)
+	else
+		candidates = root:GetDescendants()
+	end
+
+	if #candidates > MAX_VISITS then
+		Dispatch.fail(
+			"TOO_BROAD",
+			string.format(
+				"That search would visit %d instances, over the %d limit.",
+				#candidates,
+				MAX_VISITS
+			),
+			"Narrow it with `path` to search one service or model instead of the whole place."
+		)
+	end
+
+	local matched: { Instance } = {}
+	for _, instance in candidates do
+		if tagFilter and root ~= game and not instance:IsDescendantOf(root) then
+			continue
+		end
+		if isNoisy(instance) then
+			continue
+		end
+		if classFilter and not instance:IsA(classFilter) then
+			continue
+		end
+		if nameFilter and not string.find(string.lower(instance.Name), nameFilter, 1, true) then
+			continue
+		end
+		if propertyName then
+			local readOk, value = Serialize.readProperty(instance, propertyName)
+			if not readOk then
+				continue
+			end
+			if propertyValue ~= nil and tostring(value) ~= tostring(propertyValue) then
+				continue
+			end
+		end
+		table.insert(matched, instance)
+	end
+
+	local items: { { [string]: any } } = {}
+	local memo: Paths.NameIndex = {}
+	for index = offset + 1, math.min(offset + limit, #matched) do
+		table.insert(items, summarise(matched[index] :: Instance, memo))
+	end
+
+	return {
+		items = items,
+		total = #matched,
+		offset = offset,
+		searched = #candidates,
+	}
+end
+
+function Discover.register()
+	Dispatch.registerAll("discover", {
+		tree = Discover.tree,
+		inspect = Discover.inspect,
+		find = Discover.find,
+	})
+end
+
+return Discover

package/plugin/src/handlers/Exec.luau

@@ -0,0 +1,270 @@
+--!strict
+--[[
+	Arbitrary Luau, run in the plugin's context.
+
+	This is the escape hatch, not the default. Every dedicated tool validates its
+	input, types values from the API dump, and wraps writes in an undo recording;
+	code run here does none of that. It exists for the cases nothing else covers.
+
+	`LogService:ExecuteScript` -- the API the command bar uses -- is
+	RobloxScriptSecurity, so this compiles with `loadstring` instead. Output is
+	captured while the chunk runs, because "what did it print" is almost always
+	the reason for running it at all.
+]]
+
+local LogService = game:GetService("LogService")
+
+local Dispatch = require(script.Parent.Parent.Dispatch)
+local Serialize = require(script.Parent.Parent.Serialize)
+
+-- A chunk that prints in a loop would otherwise return a response no context
+-- window can hold.
+local MAX_OUTPUT_LINES = 200
+local MAX_RETURN_VALUES = 10
+
+-- Returned tables are walked rather than counted, but not without limit: a
+-- chunk that returns a whole config tree, or one with a cycle in it, must not be
+-- able to produce a response nothing can read.
+local MAX_TABLE_ENTRIES = 50
+local MAX_TABLE_DEPTH = 4
+
+local CHUNK_NAME = "StudioMCP.execute_luau"
+
+local Exec = {}
+
+--[[
+	Describes a returned value.
+
+	Tables used to come back as "<table with 5 entries>", which threw away the
+	answer whenever the answer was a table -- and returning a table is the natural
+	way to report several things at once, so this hit constantly. They are walked
+	now, bounded by breadth and depth. Everything else goes through the same
+	serializer the rest of the server uses, so a Vector3 reads the way it does
+	everywhere else.
+]]
+local function describe(value: any, depth: number?): any
+	local level = depth or 0
+	local kind = typeof(value)
+
+	if kind == "function" or kind == "thread" then
+		return string.format("<%s>", kind)
+	end
+	if kind ~= "table" then
+		return Serialize.value(value)
+	end
+
+	local source = value :: { [any]: any }
+	-- Also the cycle guard: a self-referencing table stops here rather than
+	-- recursing until the stack gives out.
+	if level >= MAX_TABLE_DEPTH then
+		return "<nested table>"
+	end
+
+	local count = 0
+	for _ in source do
+		count += 1
+	end
+
+	-- Arrays keep their shape so they read as lists on the other side; anything
+	-- with non-sequential keys becomes a map with stringified keys.
+	if count == #source then
+		local list: { any } = {}
+		for index, item in ipairs(source) do
+			if index > MAX_TABLE_ENTRIES then
+				table.insert(list, string.format("<%d more>", count - MAX_TABLE_ENTRIES))
+				break
+			end
+			table.insert(list, describe(item, level + 1))
+		end
+		return list
+	end
+
+	local map: { [string]: any } = {}
+	local shown = 0
+	for key, item in source do
+		shown += 1
+		if shown > MAX_TABLE_ENTRIES then
+			map["..."] = string.format("<%d more>", count - MAX_TABLE_ENTRIES)
+			break
+		end
+		map[tostring(key)] = describe(item, level + 1)
+	end
+	return map
+end
+
+--[[
+	Compiles the chunk by whichever route this session actually allows.
+
+	`loadstring` is the direct one and the only one that keeps plugin identity,
+	but the global exists and *throws* unless `ServerScriptService.LoadStringEnabled`
+	is set -- which it is not by default. So every call against a running playtest
+	server failed with "loadstring() is not available" while the identical code ran
+	fine in the editor session, which is the worst shape a limitation can take.
+
+	The fallback compiles through a ModuleScript: a plugin may set `.Source`, and
+	requiring a fresh, unparented instance runs it without touching the place. The
+	cost is real and gets reported back rather than hidden -- a required module
+	runs at script identity, so plugin-only APIs are out of reach on that path.
+
+	Returns the callable, a compile error, which route was taken, and any module
+	to clean up once the chunk has finished with it.
+]]
+local function compile(
+	source: string
+): (((...any) -> ...any)?, string?, string, ModuleScript?)
+	local ok, chunk, syntaxError = pcall(loadstring :: any, source, CHUNK_NAME)
+	if ok then
+		if typeof(chunk) == "function" then
+			return chunk, nil, "loadstring", nil
+		end
+		return nil, tostring(syntaxError), "loadstring", nil
+	end
+
+	-- `chunk` carries the pcall failure when `ok` is false.
+	local refusal = tostring(chunk)
+
+	local module = Instance.new("ModuleScript")
+	-- The wrapper opens on the same line the source starts on, so a syntax error
+	-- still reports the line the caller wrote.
+	local settable = pcall(function()
+		module.Source = "return function(...) " .. source .. "\nend"
+	end)
+	if not settable then
+		module:Destroy()
+		return nil,
+			string.format(
+				"no route to compile is open in this session: loadstring refused (%s) "
+					.. "and setting a script's source is not permitted either",
+				refusal
+			),
+			"none",
+			nil
+	end
+
+	local required, result = pcall(require, module)
+	if not required then
+		module:Destroy()
+		return nil, tostring(result), "module", nil
+	end
+	if typeof(result) ~= "function" then
+		module:Destroy()
+		return nil, "the chunk compiled but produced nothing callable", "module", nil
+	end
+	return result :: any, nil, "module", module
+end
+
+function Exec.run(params: { [string]: any }): { [string]: any }
+	local source = params.source
+	if typeof(source) ~= "string" or source == "" then
+		Dispatch.fail(
+			"BAD_PARAMS",
+			"execute_luau requires `source`.",
+			"Pass the Luau to run as a string."
+		)
+	end
+
+	local chunk, compileError, route, module = compile(source)
+	if chunk == nil then
+		if route == "none" then
+			Dispatch.fail(
+				"NO_COMPILER",
+				string.format("Cannot run code in this session: %s", tostring(compileError)),
+				"Use the dedicated tools instead: create, modify, script_edit and find "
+					.. "cover most of what execute_luau is reached for."
+			)
+		end
+		Dispatch.fail(
+			"COMPILE_ERROR",
+			string.format("The code did not compile: %s", tostring(compileError)),
+			"Fix the syntax and try again. The chunk is compiled as a whole, so a "
+				.. "stray end or missing then reports here rather than at a line."
+		)
+	end
+
+	-- Captured rather than inferred: a chunk's prints are usually the point, and
+	-- reading them back from the log afterwards would also pick up whatever else
+	-- the place logged in the meantime.
+	local output: { { [string]: any } } = {}
+	local connection = LogService.MessageOut:Connect(function(message, messageType)
+		if #output < MAX_OUTPUT_LINES then
+			table.insert(output, {
+				message = message,
+				level = if messageType == Enum.MessageType.MessageError
+					then "error"
+					elseif messageType == Enum.MessageType.MessageWarning then "warning"
+					else "print",
+			})
+		end
+	end)
+
+	local started = os.clock()
+	local results = table.pack(pcall(chunk :: () -> ...any))
+	local elapsed = os.clock() - started
+
+	--[[
+		MessageOut is deferred: `print` returns before the event fires, so
+		disconnecting straight after the chunk finished captured nothing at all.
+		A short settle picks the lines up.
+
+		It is bounded and stops as soon as the flow stops, rather than waiting a
+		fixed period, so a chunk that logged nothing costs almost no time and one
+		that logged plenty is not truncated.
+	]]
+	local settleDeadline = os.clock() + 0.5
+	local seen = #output
+	local quietFrames = 0
+	while os.clock() < settleDeadline and quietFrames < 3 do
+		task.wait()
+		if #output == seen then
+			quietFrames += 1
+		else
+			seen = #output
+			quietFrames = 0
+		end
+	end
+
+	connection:Disconnect()
+
+	if module then
+		module:Destroy()
+	end
+
+	-- Only mentioned when it constrains what the code could do. On the direct
+	-- route there is nothing to say.
+	local identity = if route == "module"
+		then "Ran through a ModuleScript because loadstring is disabled in this "
+			.. "session, so the code held script identity rather than plugin "
+			.. "identity -- plugin-only APIs would have been unavailable to it."
+		else nil
+
+	if not results[1] then
+		return {
+			ok = false,
+			error = tostring(results[2]),
+			output = output,
+			note = identity,
+			milliseconds = math.floor(elapsed * 1000 + 0.5),
+		}
+	end
+
+	local returned: { any } = {}
+	for index = 2, math.min(results.n, MAX_RETURN_VALUES + 1) do
+		table.insert(returned, describe(results[index]))
+	end
+
+	return {
+		ok = true,
+		returned = returned,
+		output = output,
+		note = identity,
+		milliseconds = math.floor(elapsed * 1000 + 0.5),
+	}
+end
+
+function Exec.register()
+	Dispatch.registerAll("exec", {
+		run = Exec.run,
+	})
+end
+
+return Exec