@el4cteo/rbx-studio-mcp 0.1.0

package/plugin/src/Dispatch.luau

@@ -0,0 +1,90 @@
+--!strict
+--[[
+	Handler registry and the single error boundary around every command.
+
+	Handlers raise failures with `Dispatch.fail(code, message, hint)`. The hint is
+	forwarded verbatim to the agent, so it should say what to do next ("call find
+	first to get a valid path"), not just what went wrong.
+]]
+
+local Dispatch = {}
+
+export type Error = {
+	code: string,
+	message: string,
+	hint: string?,
+}
+
+export type Handler = (params: { [string]: any }) -> any
+
+local handlers: { [string]: Handler } = {}
+
+function Dispatch.register(op: string, handler: Handler)
+	handlers[op] = handler
+end
+
+--[[
+	Registers every entry of `map` under the prefix, e.g. `registerAll("script",
+	{ read = fn })` exposes "script.read".
+]]
+function Dispatch.registerAll(prefix: string, map: { [string]: Handler })
+	for name, handler in map do
+		handlers[prefix .. "." .. name] = handler
+	end
+end
+
+--[[
+	Raises a structured failure. Always call this rather than `error("...")` so
+	the agent receives a code it can branch on and a hint it can act on.
+]]
+function Dispatch.fail(code: string, message: string, hint: string?): never
+	error({ code = code, message = message, hint = hint }, 0)
+end
+
+export type Result = {
+	id: string,
+	ok: boolean,
+	data: any?,
+	error: Error?,
+}
+
+--[[
+	Runs one command and returns the frame to POST back. Never throws: an
+	unhandled error inside a handler becomes a HANDLER_ERROR result, because a
+	crashed dispatch would leave the server's promise hanging until it times out.
+]]
+function Dispatch.invoke(id: string, op: string, params: { [string]: any }?): Result
+	local handler = handlers[op]
+	if not handler then
+		return {
+			id = id,
+			ok = false,
+			error = {
+				code = "UNKNOWN_OP",
+				message = string.format('This Studio plugin has no handler for "%s".', op),
+				hint = "The plugin is older than the MCP server. Update the Studio MCP "
+					.. "plugin to the version matching your server.",
+			},
+		}
+	end
+
+	local ok, result = pcall(handler, params or {})
+	if ok then
+		return { id = id, ok = true, data = result }
+	end
+
+	if typeof(result) == "table" and (result :: any).code then
+		return { id = id, ok = false, error = result :: Error }
+	end
+
+	return {
+		id = id,
+		ok = false,
+		error = {
+			code = "HANDLER_ERROR",
+			message = string.format('"%s" failed: %s', op, tostring(result)),
+		},
+	}
+end
+
+return Dispatch

package/plugin/src/Editor.luau

@@ -0,0 +1,142 @@
+--!strict
+--[[
+	What the user is currently looking at in the script editor.
+
+	`ScriptEditorService` is normally used only to read and write source. The
+	document layer underneath it -- open tabs, cursor position, selected text,
+	which lines are on screen -- is left untouched by every other Studio MCP
+	server, and it answers the question an agent most often has to guess at: when
+	the user says "fix this function", which one do they mean.
+
+	Everything here is read-only and defensive. A ScriptDocument can close between
+	being listed and being read, and the accessors throw rather than return nil
+	when that happens, so each one is wrapped.
+]]
+
+local ScriptEditorService = game:GetService("ScriptEditorService")
+
+local Paths = require(script.Parent.Paths)
+
+-- Selected text is included so the agent can act on it without a second call,
+-- but a user can select an entire file. Past this it is summarised instead.
+local MAX_SELECTED_TEXT = 400
+
+local Editor = {}
+
+export type Document = { [string]: any }
+
+--[[
+	Reads an accessor, yielding nil rather than raising when the document closed
+	underneath us. Values come back boxed in a table so a multi-value accessor
+	survives the pcall boundary intact.
+]]
+local function safe(accessor: () -> any): any
+	local ok, value = pcall(accessor)
+	if ok then
+		return value
+	end
+	return nil
+end
+
+local function describe(document: ScriptDocument): Document?
+	-- The command bar is a ScriptDocument too, and it is always open. Reporting
+	-- it would put a line of noise in every studio_status -- the call agents make
+	-- most -- for something that has no backing script and cannot be edited.
+	local isCommandBar = safe(function()
+		return document:IsCommandBar()
+	end)
+	if isCommandBar ~= false then
+		return nil
+	end
+
+	local found = safe(function()
+		return document:GetScript()
+	end)
+	if typeof(found) ~= "Instance" then
+		return nil
+	end
+
+	local target = found :: Instance
+	local entry: Document = {
+		path = Paths.of(target),
+		className = target.ClassName,
+	}
+
+	entry.lineCount = safe(function()
+		return document:GetLineCount()
+	end)
+
+	-- GetSelection returns cursor line/character followed by the anchor: the
+	-- cursor is where the caret is, the anchor where the selection started, and
+	-- they are equal when nothing is selected.
+	local raw = safe(function()
+		local line, character, anchorLine, anchorCharacter = document:GetSelection()
+		return { line, character, anchorLine, anchorCharacter }
+	end)
+	if typeof(raw) == "table" then
+		local selection = raw :: { number }
+		entry.cursorLine = selection[1]
+		entry.cursorColumn = selection[2]
+
+		local hasSelection = selection[1] ~= selection[3] or selection[2] ~= selection[4]
+		if hasSelection then
+			-- Normalised, because a selection dragged upwards reports its anchor
+			-- below its cursor and a raw start/end pair would read as inverted.
+			local startLine = math.min(selection[1], selection[3])
+			local endLine = math.max(selection[1], selection[3])
+			entry.selectedLines = if startLine == endLine
+				then tostring(startLine)
+				else string.format("%d-%d", startLine, endLine)
+
+			local selected = safe(function()
+				return document:GetSelectedText()
+			end)
+			if typeof(selected) == "string" then
+				entry.selectedText = if #selected > MAX_SELECTED_TEXT
+					then string.sub(selected, 1, MAX_SELECTED_TEXT) .. "..."
+					else selected
+			end
+		end
+	end
+
+	local viewport = safe(function()
+		local first, last = document:GetViewport()
+		return { first, last }
+	end)
+	if typeof(viewport) == "table" then
+		local bounds = viewport :: { number }
+		if bounds[1] and bounds[2] then
+			entry.visibleLines = string.format("%d-%d", bounds[1], bounds[2])
+		end
+	end
+
+	return entry
+end
+
+--[[
+	Every script the user has open, most recently interesting first. Studio gives
+	no "focused document" API, so the caller is told what is open rather than
+	which tab has focus -- claiming focus we cannot observe would be worse than
+	saying nothing.
+]]
+function Editor.documents(): { Document }
+	local ok, documents = pcall(function()
+		return ScriptEditorService:GetScriptDocuments()
+	end)
+	if not ok or typeof(documents) ~= "table" then
+		return {}
+	end
+
+	local entries: { Document } = {}
+	for _, document in documents :: { Instance } do
+		if document:IsA("ScriptDocument") then
+			local entry = describe(document)
+			if entry then
+				table.insert(entries, entry)
+			end
+		end
+	end
+	return entries
+end
+
+return Editor

package/plugin/src/Emulation.luau

@@ -0,0 +1,151 @@
+--!strict
+--[[
+	What device, if any, Studio's viewport is currently pretending to be.
+
+	Three places need this and none of them can afford to disagree: the `device`
+	tool reports it, `screenshot` captions it, and `studio_status` mentions it so
+	an agent that never set a device still learns why the viewport is a strange
+	shape. Emulation persists until it is switched off, which is exactly the kind
+	of state that goes wrong quietly.
+
+	`StudioDeviceSimulatorService` is undocumented on its return shapes, so what
+	is here was read off a live session. Two things are worth knowing:
+
+	* Every read THROWS while no device is active -- "no device is active, call
+	  SetDeviceAsync() first" -- rather than returning a default, so each one is
+	  guarded separately and costs only its own field.
+	* `GetResolutionAsync` reports the panel's native size, which does not turn
+	  when the device does. An iPhone 16 emulated in portrait still answers
+	  852x393. See `orientedSize`.
+]]
+
+local StudioDeviceSimulatorService = game:GetService("StudioDeviceSimulatorService")
+
+local Emulation = {}
+
+--[[
+	The resolution as it actually appears, rather than as the panel is specified.
+
+	Reporting 852x393 for a screen that is 393 wide and 852 tall is worse than
+	reporting nothing: getting the shape of the screen right is the entire reason
+	device emulation exists, and a caller sizing a menu against those numbers
+	would place it off the bottom of the display it was told it fits.
+
+	Only swapped when the orientation names a direction. "Sensor" means the
+	device decides, and guessing on its behalf would trade a knowable error for
+	an unknowable one.
+]]
+local function orientedSize(size: Vector2, orientation: string?): (number, number)
+	local width = math.floor(size.X)
+	local height = math.floor(size.Y)
+
+	local wantsPortrait: boolean? = nil
+	if orientation ~= nil then
+		if string.find(orientation, "Portrait") ~= nil then
+			wantsPortrait = true
+		elseif string.find(orientation, "Landscape") ~= nil then
+			wantsPortrait = false
+		end
+	end
+
+	-- `width > height` is the shape we have; `wantsPortrait` is the shape we
+	-- want. Equal means they disagree, because portrait is the narrow one.
+	if wantsPortrait ~= nil and wantsPortrait == (width > height) then
+		return height, width
+	end
+	return width, height
+end
+
+--[[
+	The active device id, or nil when the viewport is the ordinary editor.
+
+	"default" is the simulator's own word for not emulating; it is turned into
+	nil here so callers test one thing rather than two.
+]]
+function Emulation.deviceId(): string?
+	local ok, id = pcall(function()
+		return (StudioDeviceSimulatorService :: any):GetDeviceAsync()
+	end)
+	if not ok or id == nil or tostring(id) == "default" then
+		return nil
+	end
+	return tostring(id)
+end
+
+--[[
+	Orientation with the enum prefix removed: "Portrait", "LandscapeRight".
+]]
+function Emulation.orientation(): string?
+	local ok, orientation = pcall(function()
+		return (StudioDeviceSimulatorService :: any):GetOrientationAsync()
+	end)
+	if not ok then
+		return nil
+	end
+	local name = tostring(orientation):gsub("Enum%.ScreenOrientation%.", "")
+	return name
+end
+
+--[[
+	"393x852", turned the way the screen is actually turned.
+]]
+function Emulation.resolution(orientation: string?): string?
+	local ok, size = pcall(function()
+		return (StudioDeviceSimulatorService :: any):GetResolutionAsync()
+	end)
+	if not ok or typeof(size) ~= "Vector2" then
+		return nil
+	end
+	local width, height = orientedSize(size :: Vector2, orientation)
+	return string.format("%dx%d", width, height)
+end
+
+--[[
+	Everything the simulator will say, for the `device` tool.
+]]
+function Emulation.state(): { [string]: any }
+	local id = Emulation.deviceId()
+	local orientation = Emulation.orientation()
+
+	local state: { [string]: any } = {
+		device = id or "default",
+		emulating = id ~= nil,
+	}
+	state.resolution = Emulation.resolution(orientation)
+	state.orientation = orientation
+
+	local okDensity, density = pcall(function()
+		return (StudioDeviceSimulatorService :: any):GetPixelDensityAsync()
+	end)
+	if okDensity then
+		state.pixelDensity = math.round((tonumber(density) :: number) * 100) / 100
+	end
+
+	local okScaling, scaling = pcall(function()
+		return (StudioDeviceSimulatorService :: any):GetScalingModeAsync()
+	end)
+	if okScaling then
+		state.scalingMode = tostring(scaling)
+	end
+
+	return state
+end
+
+--[[
+	The short form carried by `studio_status`, or nil when nothing is emulated.
+]]
+function Emulation.summary(): { [string]: any }?
+	local id = Emulation.deviceId()
+	if id == nil then
+		return nil
+	end
+	local orientation = Emulation.orientation()
+	return {
+		id = id,
+		resolution = Emulation.resolution(orientation),
+		orientation = orientation,
+		note = 'The viewport is emulating this device. `device op="stop"` returns it to normal.',
+	}
+end
+
+return Emulation

package/plugin/src/LogBuffer.luau

@@ -0,0 +1,277 @@
+--!strict
+--[[
+	The output log, kept ourselves.
+
+	`LogService:GetLogHistory()` looks like the right API and cannot be relied on.
+	Measured: in an editor session it returns a handful of lines from around
+	startup and then stops growing -- prints made later never appear -- and in a
+	playtest server's DataModel it succeeds and returns nothing at all, even
+	immediately after something printed there. The call reports no error either
+	way, so the tool built on it answered "the log is empty" for a place that was
+	logging steadily, which is worse than answering nothing.
+
+	`LogService.MessageOut` does fire reliably in both. So the buffer is filled
+	from the event, seeded once from whatever history the API does offer, and kept
+	from growing without bound.
+
+	This has to be connected at plugin load rather than when a read arrives:
+	anything logged before the first subscription is gone for good.
+]]
+
+local LogService = game:GetService("LogService")
+local ScriptContext = game:GetService("ScriptContext")
+
+-- Roughly what the Output window keeps. Big enough that a playtest's worth of
+-- logging survives, small enough to stay cheap to hold and to scan.
+local CAPACITY = 2000
+
+-- Trimming in batches rather than one entry per insert: a chunk that logs in a
+-- loop would otherwise shift the whole array on every single line.
+local SLACK = 500
+
+-- How far back an arriving stack trace will look for the error line it belongs
+-- to. The two events fire within moments of each other, so anything beyond a
+-- handful of entries is a mismatch rather than a late delivery.
+local CORRELATION_WINDOW = 20
+
+export type Entry = {
+	level: string,
+	message: string,
+	timestamp: number,
+	-- Present on errors once the matching stack trace has been correlated.
+	stack: string?,
+	source: string?,
+}
+
+local LEVELS: { [number]: string } = {
+	[Enum.MessageType.MessageOutput.Value] = "print",
+	[Enum.MessageType.MessageInfo.Value] = "info",
+	[Enum.MessageType.MessageWarning.Value] = "warning",
+	[Enum.MessageType.MessageError.Value] = "error",
+}
+
+local LogBuffer = {}
+
+local entries: { Entry } = {}
+local dropped = 0
+local started = false
+local startedAt = 0
+
+--[[
+	Stack traces that arrived before the error line they describe.
+
+	`ScriptContext.Error` and `LogService.MessageOut` are independent events for
+	the same failure and there is no guaranteed order between them, so the trace
+	is held here until its line shows up rather than being dropped for arriving
+	first.
+]]
+local orphanedStacks: { [string]: { stack: string, source: string? } } = {}
+local orphanCount = 0
+
+--[[
+	The engine also writes each trace to the log as plain lines -- "Stack Begin",
+	one "Script 'X', Line N" per frame, then "Stack End" -- which is how the
+	Output window renders it. Having attached the trace to its error already,
+	echoing those lines as ordinary entries is duplication that reads like
+	unrelated output sitting under the failure.
+
+	They are collected instead of stored, and serve as the fallback source of a
+	trace when ScriptContext.Error is unavailable.
+]]
+local STACK_OPEN = "Stack Begin"
+local STACK_CLOSE = "Stack End"
+
+-- If a close never arrives -- a place that prints "Stack Begin" itself -- the
+-- collected lines are released rather than swallowed indefinitely.
+local MAX_STACK_LINES = 60
+
+local collecting: { string }? = nil
+
+local function pushEntry(entry: Entry)
+	table.insert(entries, entry)
+
+	if #entries > CAPACITY + SLACK then
+		local excess = #entries - CAPACITY
+		entries = table.move(entries, excess + 1, #entries, 1, {})
+		dropped += excess
+	end
+end
+
+local function push(message: string, messageType: Enum.MessageType, timestamp: number?)
+	local level = LEVELS[messageType.Value] or "print"
+	local entry: Entry = {
+		level = level,
+		message = message,
+		timestamp = timestamp or os.time(),
+	}
+
+	-- Claim a trace that beat its own error line here.
+	if level == "error" then
+		local waiting = orphanedStacks[message]
+		if waiting then
+			entry.stack = waiting.stack
+			entry.source = waiting.source
+			orphanedStacks[message] = nil
+			orphanCount -= 1
+		end
+	end
+
+	pushEntry(entry)
+end
+
+--[[
+	Attaches a stack trace to the error it belongs to.
+
+	Correlated by message text because the engine offers nothing better: the two
+	events carry no shared identifier. Matching the most recent unattached error
+	with the same text is right in every case that matters, and the worst outcome
+	if two identical errors interleave is that a trace lands on the wrong one of
+	two identical lines.
+]]
+local function attachStack(message: string, stack: string, source: string?)
+	local first = math.max(1, #entries - CORRELATION_WINDOW + 1)
+	for index = #entries, first, -1 do
+		local entry = entries[index]
+		if entry.level == "error" and entry.message == message and entry.stack == nil then
+			entry.stack = stack
+			entry.source = source
+			return
+		end
+	end
+
+	-- Not logged yet. Held for the line to claim, with a cap so a flood of
+	-- errors that never surface cannot grow this without bound.
+	if orphanCount < CAPACITY then
+		if orphanedStacks[message] == nil then
+			orphanCount += 1
+		end
+		orphanedStacks[message] = { stack = stack, source = source }
+	end
+end
+
+--[[
+	Begins recording. Safe to call more than once; only the first call connects,
+	so a reload cannot end up with two subscriptions writing every line twice.
+]]
+function LogBuffer.start()
+	if started then
+		return
+	end
+	started = true
+	startedAt = os.time()
+
+	-- Seeded before subscribing so the backlog stays in order ahead of live
+	-- lines. MessageOut only fires for messages after the connection, so nothing
+	-- is counted twice.
+	local ok, history = pcall(function()
+		return LogService:GetLogHistory()
+	end)
+	if ok and typeof(history) == "table" then
+		for _, item in history :: { { [string]: any } } do
+			local kind = item.messageType
+			if item.message ~= nil and typeof(kind) == "EnumItem" then
+				push(tostring(item.message), kind :: Enum.MessageType, item.timestamp)
+			end
+		end
+	end
+
+	LogService.MessageOut:Connect(function(message: string, messageType: Enum.MessageType)
+		local buffered = collecting
+
+		if buffered then
+			if message == STACK_CLOSE then
+				collecting = nil
+				--[[
+					ScriptContext.Error is preferred -- it names the originating
+					instance too -- but not blindly. Measured on a nested failure
+					the two agree exactly, one frame each, so folding loses
+					nothing today. They are still compared by frame count rather
+					than trusted to stay equal, because the cost of being wrong
+					is a silently shallower trace and the check is one compare.
+				]]
+				if #buffered > 0 then
+					local recent = entries[#entries]
+					if recent and recent.level == "error" then
+						local existing = recent.stack
+						local existingFrames = if existing then #string.split(existing, "\n") else 0
+						if existing == nil or #buffered > existingFrames then
+							recent.stack = table.concat(buffered, "\n")
+						end
+					end
+				end
+				return
+			end
+
+			if #buffered < MAX_STACK_LINES then
+				table.insert(buffered, message)
+				return
+			end
+
+			-- Not a stack after all. Release what was held, in order, and carry
+			-- on treating this as ordinary output.
+			collecting = nil
+			pushEntry({ level = "print", message = STACK_OPEN, timestamp = os.time() })
+			for _, held in buffered do
+				pushEntry({ level = "print", message = held, timestamp = os.time() })
+			end
+		elseif message == STACK_OPEN then
+			collecting = {}
+			return
+		end
+
+		push(message, messageType)
+	end)
+
+	--[[
+		Stack traces, which MessageOut does not carry.
+
+		Without this an error in the log is a message and nothing else, while the
+		trace arrives separately as loose "Stack Begin / Script X, Line N / Stack
+		End" prints that read as unrelated output. Attaching it to the error turns
+		three ambiguous lines into one answer with a script and a line number.
+
+		`ErrorDetailed` would be the richer source and is closed to plugins --
+		it needs the RobloxScript capability. `Error` is reachable and carries
+		message, trace and originating script, which is the part that matters.
+	]]
+	pcall(function()
+		ScriptContext.Error:Connect(function(message: string, stack: string, source: Instance?)
+			local origin: string? = nil
+			if typeof(source) == "Instance" then
+				local named = pcall(function()
+					origin = source:GetFullName()
+				end)
+				if not named then
+					origin = source.Name
+				end
+			end
+			attachStack(message, stack, origin)
+		end)
+	end)
+end
+
+--[[
+	Everything held, oldest first, plus how much fell off the front. Returned as a
+	copy so a caller filtering it cannot disturb the buffer.
+]]
+function LogBuffer.all(): ({ Entry }, number)
+	return table.move(entries, 1, #entries, 1, {}), dropped
+end
+
+--[[
+	How long this buffer has been recording, in seconds.
+
+	An empty log is ambiguous without it. In a playtest the plugin loads at the
+	same moment as the place's own scripts, so a script that logs on startup can
+	beat the subscription -- and "nothing was logged" then looks identical to
+	"recording began after the thing you are asking about". Reporting the window
+	lets the two be told apart instead of guessed at.
+]]
+function LogBuffer.recordingSeconds(): number
+	if not started then
+		return 0
+	end
+	return math.max(0, os.time() - startedAt)
+end
+
+return LogBuffer