@el4cteo/rbx-studio-mcp 0.1.0

package/plugin/src/handlers/Api.luau

@@ -0,0 +1,242 @@
+--!strict
+--[[
+	What a class can do, answered by the engine that is running.
+
+	The server already validates property names against Roblox's published API
+	dump, fetched over HTTP from a community mirror. That works and has two
+	weaknesses: it needs the network, and it describes whatever build the mirror
+	last published rather than the Studio in front of you.
+
+	`ReflectionService` is the same information, locally, from the binary that is
+	actually executing -- 633 classes and 96 properties on Part, measured. It
+	cannot go stale and it cannot fail to download.
+
+	This answers a question an agent asks constantly and currently cannot:
+	"what do I call on this thing?" Without it the only way to learn a class's
+	surface is to find an instance of it and read every property, which needs one
+	to exist and still never lists methods or events.
+]]
+
+local ReflectionService = game:GetService("ReflectionService")
+
+local Dispatch = require(script.Parent.Parent.Dispatch)
+
+local Api = {}
+
+-- A class listing is for orientation, not for reading end to end; 633 classes
+-- would be most of a context window.
+local MAX_CLASSES = 150
+
+local function nameOf(entry: any): string
+	if typeof(entry) == "table" then
+		return tostring((entry :: any).Name)
+	end
+	return tostring(entry)
+end
+
+--[[
+	The script-facing name of a type, which is not always the engine's.
+
+	Entries carry `{ EngineType, ScriptType }` and they differ where it matters:
+	an int64 is a `number` to Luau, and a caller writing code wants the second.
+]]
+local function typeName(spec: any): string
+	if typeof(spec) ~= "table" then
+		return "?"
+	end
+	return tostring((spec :: any).ScriptType or (spec :: any).EngineType or "?")
+end
+
+--[[
+	Renders a member as something that can be typed, not just recognised.
+
+	A bare name says a method exists; a signature says how to call it, which is
+	the actual question. `Humanoid.AddAccessory` is a guess until you know it
+	takes one Instance.
+]]
+local function signature(entry: any): string
+	local name = nameOf(entry)
+	local parameters = (entry :: any).Parameters
+	if typeof(parameters) ~= "table" then
+		-- A property. Its type is the useful half.
+		local kind = (entry :: any).Type
+		return if kind ~= nil then string.format("%s: %s", name, typeName(kind)) else name
+	end
+
+	local rendered: { string } = {}
+	for _, parameter in parameters :: { any } do
+		table.insert(rendered, string.format("%s: %s", tostring(parameter.Name), typeName(parameter.Type)))
+	end
+
+	local returns = (entry :: any).ReturnType
+	local suffix = if returns ~= nil and typeName(returns) ~= "Void"
+		then " -> " .. typeName(returns)
+		else ""
+	return string.format("%s(%s)%s", name, table.concat(rendered, ", "), suffix)
+end
+
+--[[
+	The deprecation notice on a member, if the engine carries one.
+
+	`Display.DeprecationMessage` is how the reflection data marks a member as
+	superseded, and Instance carries eight: `clone`, `remove`, `getChildren` and
+	the rest of the lowercase aliases retired years ago. They are a fifth of
+	everything Instance appears to offer, and they still run -- so an agent that
+	picks one from the list gets working code and a deprecation warning in the
+	user's output, which is exactly the sort of thing this tool exists to stop.
+]]
+local function deprecation(entry: any): string?
+	if typeof(entry) ~= "table" then
+		return nil
+	end
+	local display = (entry :: any).Display
+	if typeof(display) ~= "table" then
+		return nil
+	end
+	local message = (display :: any).DeprecationMessage
+	return if typeof(message) == "string" and message ~= "" then message else nil
+end
+
+--[[
+	Renders the members worth showing, and counts the ones left out.
+
+	Two things are held back. Deprecated members always: nothing should be
+	written against them. Inherited members unless asked for: ProximityPrompt has
+	2 methods of its own and 42 from Instance and Object, so a flat alphabetical
+	list buries `InputHoldBegin` among boilerplate the caller already knows.
+
+	Both are counted rather than silently dropped, because "it has no such
+	method" and "it has it, from Instance" and "it has it, but do not use it" are
+	three different answers and the caller needs to tell them apart.
+
+	Sorted so two calls agree: an agent comparing a class across engine versions
+	should see what changed, not a reshuffle.
+]]
+local function collect(entries: { any }, className: string, wantInherited: boolean): ({ string }, number, number)
+	local kept: { string } = {}
+	local inherited = 0
+	local deprecated = 0
+
+	for _, entry in entries do
+		if deprecation(entry) ~= nil then
+			deprecated += 1
+			continue
+		end
+		local own = typeof(entry) ~= "table" or tostring((entry :: any).Owner) == className
+		if not own then
+			inherited += 1
+		end
+		if own or wantInherited then
+			table.insert(kept, signature(entry))
+		end
+	end
+
+	table.sort(kept)
+	return kept, inherited, deprecated
+end
+
+function Api.describe(params: { [string]: any }): { [string]: any }
+	local className = params.className
+	if typeof(className) ~= "string" or className == "" then
+		Dispatch.fail("BAD_PARAMS", "describe needs a `className`, e.g. \"TweenService\".")
+	end
+
+	local okClass, class = pcall(function()
+		return (ReflectionService :: any):GetClass(className, {})
+	end)
+	if not okClass or class == nil then
+		Dispatch.fail(
+			"NO_SUCH_CLASS",
+			string.format("The engine has no class called %q.", className),
+			"Class names are case-sensitive. Use `api op=\"classes\"` with a `contains` filter to find it."
+		)
+	end
+
+	local result: { [string]: any } = {
+		className = nameOf(class),
+		superclass = if typeof(class) == "table" then tostring((class :: any).Superclass) else nil,
+	}
+
+	local wanted = params.include
+	local include = if typeof(wanted) == "table" then wanted :: { string } else { "properties", "methods", "events" }
+	local function asked(what: string): boolean
+		for _, item in include do
+			if item == what then
+				return true
+			end
+		end
+		return false
+	end
+
+	-- Asked for explicitly, because the filter argument these calls accept is
+	-- ignored: passing Inherited = false, IncludeInherited = false and
+	-- Deprecated = false each returned exactly the same 26 properties as {}.
+	-- The Owner field is the only thing that actually separates them.
+	local exact = tostring(result.className)
+	local wantInherited = params.inherited == true
+
+	local sources = {
+		{ key = "properties", method = "GetPropertiesOfClass" },
+		{ key = "methods", method = "GetMethodsOfClass" },
+		{ key = "events", method = "GetEventsOfClass" },
+	}
+	for _, source in sources do
+		if not asked(source.key) then
+			continue
+		end
+		local ok, entries = pcall(function()
+			return (ReflectionService :: any)[source.method](ReflectionService, className, {})
+		end)
+		if not ok then
+			continue
+		end
+		local members, inherited, deprecated = collect(entries :: { any }, exact, wantInherited)
+		result[source.key] = members
+		if inherited > 0 and not wantInherited then
+			result[source.key .. "Inherited"] = inherited
+		end
+		if deprecated > 0 then
+			result[source.key .. "Deprecated"] = deprecated
+		end
+	end
+
+	return result
+end
+
+function Api.classes(params: { [string]: any }): { [string]: any }
+	local ok, classes = pcall(function()
+		return (ReflectionService :: any):GetClasses({})
+	end)
+	if not ok then
+		Dispatch.fail("REFLECTION_FAILED", string.format("Could not list classes: %s", tostring(classes)))
+	end
+
+	local needle = if typeof(params.contains) == "string" then string.lower(params.contains) else nil
+	local matched: { string } = {}
+	local total = 0
+	for _, entry in classes :: { any } do
+		local name = nameOf(entry)
+		if needle == nil or string.find(string.lower(name), needle, 1, true) ~= nil then
+			total += 1
+			if #matched < MAX_CLASSES then
+				table.insert(matched, name)
+			end
+		end
+	end
+	table.sort(matched)
+
+	return {
+		classes = matched,
+		matched = total,
+		truncated = if total > #matched then total - #matched else nil,
+	}
+end
+
+function Api.register()
+	Dispatch.registerAll("api", {
+		describe = Api.describe,
+		classes = Api.classes,
+	})
+end
+
+return Api

package/plugin/src/handlers/Assets.luau

@@ -0,0 +1,145 @@
+--!strict
+--[[
+	Inserting Creator Store assets into the place.
+
+	The search half of this lives on the server, not here: Node already has
+	internet access and Roblox's toolbox endpoints answer unauthenticated, while
+	a plugin making outbound HTTP needs the user to grant permission per domain.
+	Doing it server-side means search works the moment the server starts, and the
+	plugin only ever talks to the one host it already talks to.
+
+	So this file does the half only Studio can do: turn an asset id into real
+	instances in the data model, under a recording so one insert is one Ctrl+Z.
+]]
+
+local Dispatch = require(script.Parent.Parent.Dispatch)
+local Paths = require(script.Parent.Parent.Paths)
+local Undo = require(script.Parent.Parent.Undo)
+
+local Assets = {}
+
+--[[
+	Counts scripts anywhere inside what was inserted.
+
+	Free models carrying scripts are the oldest hazard on the platform, and the
+	agent inserting one has no other way to know. This is reported on every
+	insert rather than only when asked, because the caller who most needs to see
+	it is the one who did not think to look.
+]]
+local function countScripts(root: Instance): (number, { string })
+	local total = 0
+	local names: { string } = {}
+	for _, descendant in root:GetDescendants() do
+		if descendant:IsA("LuaSourceContainer") then
+			total += 1
+			if #names < 10 then
+				table.insert(names, string.format("%s (%s)", descendant.Name, descendant.ClassName))
+			end
+		end
+	end
+	return total, names
+end
+
+function Assets.insert(params: { [string]: any }): { [string]: any }
+	local assetId = tonumber(params.assetId)
+	if assetId == nil or assetId <= 0 then
+		Dispatch.fail("BAD_PARAMS", "insert needs a numeric `assetId`.")
+	end
+
+	local parent = if typeof(params.parent) == "string" and params.parent ~= ""
+		then Paths.resolve(params.parent)
+		else workspace
+
+	--[[
+		`game:GetObjects`, not `InsertService:LoadAsset`.
+
+		LoadAsset is the documented route and it refuses everything here: every
+		public model tried, from several creators, came back "User is not
+		authorized to access Asset". It enforces ownership, which makes it useful
+		for a game loading its own assets and useless for inserting from the
+		Creator Store -- the entire point of this tool.
+
+		GetObjects is the plugin-security path Studio's own toolbox uses, and it
+		loaded the same ids without complaint. It returns an array of top-level
+		instances rather than a wrapper model, so there is nothing to unwrap.
+	]]
+	local ok, loaded = pcall(function()
+		return game:GetObjects("rbxassetid://" .. assetId)
+	end)
+	if not ok then
+		Dispatch.fail(
+			"INSERT_FAILED",
+			string.format("Could not load asset %d: %s", assetId, tostring(loaded)),
+			"The asset may be private, deleted, or not a model."
+		)
+	end
+
+	local children = loaded :: { Instance }
+	if #children == 0 then
+		Dispatch.fail("EMPTY_ASSET", string.format("Asset %d contained nothing.", assetId))
+	end
+
+	-- Counted across every root, since an asset can arrive as several instances
+	-- and a script hiding in the second one counts exactly as much.
+	local scriptCount = 0
+	local scriptNames: { string } = {}
+	for _, child in children do
+		local count, names = countScripts(child)
+		scriptCount += count
+		for _, name in names do
+			if #scriptNames < 10 then
+				table.insert(scriptNames, name)
+			end
+		end
+		if child:IsA("LuaSourceContainer") then
+			scriptCount += 1
+			if #scriptNames < 10 then
+				table.insert(scriptNames, string.format("%s (%s)", child.Name, child.ClassName))
+			end
+		end
+	end
+
+	local inserted: { string } = {}
+	local _, undoable = Undo.record("MCPInsertAsset", "MCP insert asset", function()
+		for _, child in children do
+			if typeof(params.name) == "string" and params.name ~= "" and #children == 1 then
+				child.Name = params.name
+			end
+			child.Parent = parent
+			table.insert(inserted, Paths.of(child))
+		end
+
+		-- Position after parenting, so PrimaryPart and pivot are settled.
+		if typeof(params.position) == "string" and params.position ~= "" then
+			local x, y, z = string.match(params.position, "^%s*(-?[%d%.]+)%s*,%s*(-?[%d%.]+)%s*,%s*(-?[%d%.]+)%s*$")
+			if x then
+				local target = CFrame.new(tonumber(x) :: number, tonumber(y) :: number, tonumber(z) :: number)
+				for _, child in children do
+					pcall(function()
+						if child:IsA("Model") then
+							(child :: Model):PivotTo(target)
+						elseif child:IsA("BasePart") then
+							(child :: BasePart).CFrame = target
+						end
+					end)
+				end
+			end
+		end
+	end)
+
+	return {
+		inserted = inserted,
+		assetId = assetId,
+		scriptCount = scriptCount,
+		scripts = if scriptCount > 0 then scriptNames else nil,
+		undoable = undoable,
+	}
+end
+
+function Assets.register()
+	Dispatch.registerAll("assets", {
+		insert = Assets.insert,
+	})
+end
+
+return Assets

package/plugin/src/handlers/Capture.luau

@@ -0,0 +1,187 @@
+--!strict
+--[[
+	Screenshots, so an agent can look at the place instead of inferring it.
+
+	Everything else this server exposes reads the data model: names, properties,
+	numbers. None of that answers "does it look right", which for a 3D medium is
+	most of the question. A part can sit at the correct position, anchored, the
+	right size, and still be inside a wall.
+
+	The path is four steps, none of them optional. `CaptureService` hands back a
+	temporary content id rather than pixels; `AssetService` turns that id into an
+	EditableImage; the image gives up raw RGBA; and PNG and base64 are written by
+	hand because the engine has neither. See Png.luau.
+]]
+
+local AssetService = game:GetService("AssetService")
+local CaptureService = game:GetService("CaptureService")
+local EncodingService = game:GetService("EncodingService")
+local RunService = game:GetService("RunService")
+
+local Dispatch = require(script.Parent.Parent.Dispatch)
+local Emulation = require(script.Parent.Parent.Emulation)
+local Png = require(script.Parent.Parent.Png)
+
+-- Wide enough to read a GUI label, small enough that the encode stays quick and
+-- the reply does not dominate the conversation it is part of.
+local DEFAULT_WIDTH = 800
+local MAX_WIDTH = 1600
+local MIN_WIDTH = 160
+
+-- The callback has never taken close to this. It exists so a capture that never
+-- calls back fails with something an agent can act on rather than hanging the
+-- session until the request deadline.
+local CAPTURE_TIMEOUT = 10
+
+-- Zstd level. 3 is its default and already gets most of the win on screen
+-- content; the higher levels cost Studio's main thread for a few percent.
+local COMPRESSION_LEVEL = 3
+
+local Capture = {}
+
+--[[
+	Takes the shot and waits for the id.
+
+	`CaptureService:CaptureScreenshot` answers through a callback rather than
+	yielding, so this bridges the two: the handler is already running on its own
+	task and is free to wait.
+]]
+local function takeScreenshot(): string
+	local contentId: string? = nil
+	local failed: string? = nil
+
+	local ok, err = pcall(function()
+		CaptureService:CaptureScreenshot(function(id: string)
+			contentId = id
+		end)
+	end)
+	if not ok then
+		failed = tostring(err)
+	end
+
+	if failed ~= nil then
+		Dispatch.fail(
+			"CAPTURE_REFUSED",
+			string.format("Studio refused to take a screenshot: %s", failed)
+		)
+	end
+
+	local waited = 0
+	while contentId == nil and waited < CAPTURE_TIMEOUT do
+		task.wait(0.05)
+		waited += 0.05
+	end
+
+	if contentId == nil then
+		Dispatch.fail(
+			"CAPTURE_TIMEOUT",
+			string.format("Studio did not return a screenshot within %ds.", CAPTURE_TIMEOUT),
+			"The viewport may be hidden or Studio may be busy; try again."
+		)
+	end
+
+	return contentId :: any
+end
+
+function Capture.screenshot(params: { [string]: any }): { [string]: any }
+	local width = math.clamp(tonumber(params.width) or DEFAULT_WIDTH, MIN_WIDTH, MAX_WIDTH)
+
+	local contentId = takeScreenshot()
+
+	local okImage, image = pcall(function()
+		return AssetService:CreateEditableImageAsync(Content.fromUri(contentId))
+	end)
+	if not okImage then
+		Dispatch.fail(
+			"CAPTURE_UNREADABLE",
+			string.format("The screenshot could not be opened for reading: %s", tostring(image))
+		)
+	end
+
+	local size = (image :: any).Size
+	local sourceWidth = math.floor(size.X)
+	local sourceHeight = math.floor(size.Y)
+
+	--[[
+		Both arguments are required. Called with none it reports "expects 2
+		arguments" rather than defaulting to the whole image, which is worth
+		stating because every other read on this object takes none.
+	]]
+	local okPixels, pixels = pcall(function()
+		return (image :: any):ReadPixelsBuffer(Vector2.zero, size)
+	end)
+	if not okPixels then
+		Dispatch.fail(
+			"CAPTURE_UNREADABLE",
+			string.format("The screenshot's pixels could not be read: %s", tostring(pixels))
+		)
+	end
+
+	local rgb, outWidth, outHeight = Png.downscaleToRgb(pixels, sourceWidth, sourceHeight, width)
+
+	--[[
+		Raw pixels, compressed by the engine, assembled into a PNG by Node.
+
+		The plugin used to write the whole PNG itself, and could only write a bad
+		one: Studio has no deflate, so `Png.encode` emitted zlib *stored* blocks
+		-- the format's "compression not applied" escape hatch -- and every
+		screenshot travelled and landed at full uncompressed size. It was also
+		base64-ing by hand, a table lookup per byte in Luau.
+
+		`EncodingService` has both, natively. Zstd is the only algorithm the
+		engine exposes and PNG cannot use it, so the split is: the plugin
+		compresses the pixels for the wire, and Node -- which has real zlib --
+		decompresses and writes a properly deflated PNG. The side with the
+		compressor does the compressing.
+
+		Guarded rather than assumed: EncodingService is recent, and a Studio
+		without it should cost a bigger screenshot, not a failed one.
+	]]
+	local okPacked, packed = pcall(function()
+		local compressed = (EncodingService :: any):CompressBuffer(
+			rgb,
+			(Enum :: any).CompressionAlgorithm.Zstd,
+			COMPRESSION_LEVEL
+		)
+		return buffer.tostring((EncodingService :: any):Base64Encode(compressed))
+	end)
+
+	if okPacked then
+		return {
+			encoding = "zstd-rgb",
+			data = packed,
+			width = outWidth,
+			height = outHeight,
+			sourceWidth = sourceWidth,
+			sourceHeight = sourceHeight,
+			rawBytes = buffer.len(rgb),
+			bytes = #(packed :: string),
+			context = if RunService:IsEdit() then "edit" else "playtest",
+			device = Emulation.deviceId(),
+		}
+	end
+
+	local png = Png.encode(rgb, outWidth, outHeight)
+
+	return {
+		encoding = "png",
+		data = Png.base64(png),
+		width = outWidth,
+		height = outHeight,
+		sourceWidth = sourceWidth,
+		sourceHeight = sourceHeight,
+		bytes = buffer.len(png),
+		-- Which window this came from. A screenshot carries no indication of
+		-- whether it shows the editor or a running game, and the two look alike.
+		context = if RunService:IsEdit() then "edit" else "playtest",
+		device = Emulation.deviceId(),
+	}
+end
+
+function Capture.register()
+	Dispatch.registerAll("capture", {
+		screenshot = Capture.screenshot,
+	})
+end
+
+return Capture