@el4cteo/rbx-studio-mcp 0.1.0

package/plugin/src/handlers/Session.luau

@@ -0,0 +1,168 @@
+--!strict
+--[[
+	Session and connectivity handlers. `studio.status` is the cheapest call in the
+	system and doubles as the liveness probe, so it must never touch anything
+	expensive -- notably it counts descendants lazily and caps the selection.
+]]
+
+local MarketplaceService = game:GetService("MarketplaceService")
+local RunService = game:GetService("RunService")
+local Selection = game:GetService("Selection")
+
+local Dispatch = require(script.Parent.Parent.Dispatch)
+local Context = require(script.Parent.Parent.Context)
+local Editor = require(script.Parent.Parent.Editor)
+local Emulation = require(script.Parent.Parent.Emulation)
+local Paths = require(script.Parent.Parent.Paths)
+
+-- `version()` is marked deprecated but remains the only way to read the Studio
+-- build, and the agent needs it to know which engine APIs actually exist in this
+-- session. Bound indirectly so the deprecation lint stays enabled file-wide.
+local studioVersion: () -> string = (version :: any)
+
+-- Selection can be tens of thousands of instances after a rubber-band drag.
+-- Anything past this is noise for an agent and would blow the response budget.
+local MAX_SELECTION = 50
+
+-- Counting descendants of a large place is O(n) over the whole DataModel, so it
+-- is cached briefly; status is polled often enough for this to matter.
+local COUNT_CACHE_SECONDS = 5
+
+local cachedCounts: { descendants: number, scripts: number }? = nil
+local cachedAt = 0
+
+--[[
+	Which device Studio is pretending to be, or nil for none.
+
+	Reported here because nothing else says it. Device emulation resizes the
+	viewport and stays on until it is switched off, so every screenshot after it
+	comes back the wrong shape with no indication why -- and a caller who did not
+	set it, or who set it twenty calls ago, has no way to find out. `status` is
+	the call agents are told to make first, which makes it the right place for a
+	piece of session state that silently changes what everything else returns.
+]]
+local function counts(): { descendants: number, scripts: number }
+	local now = os.clock()
+	local cache = cachedCounts
+	if cache and now - cachedAt < COUNT_CACHE_SECONDS then
+		return cache
+	end
+
+	local descendants = 0
+	local scripts = 0
+	for _, instance in game:GetDescendants() do
+		descendants += 1
+		if instance:IsA("LuaSourceContainer") then
+			scripts += 1
+		end
+	end
+
+	local fresh = { descendants = descendants, scripts = scripts }
+	cachedCounts = fresh
+	cachedAt = now
+	return fresh
+end
+
+--[[
+	The name the user would recognise.
+
+	`game.Name` is the data model's name -- "Place1", "Place5" -- and has nothing
+	to do with what the place is called on the Studio tab or the Creator
+	Dashboard. Nothing local holds the real name: it lives on Roblox's servers, so
+	it takes a lookup. Without it, a user saying "the other place, the published
+	one" cannot be matched to any window, which is the whole point of being able
+	to drive several Studios at once.
+
+	Cached, including the failure, because an unpublished place would otherwise
+	make a doomed web request on every status call.
+]]
+local NAME_RETRY_SECONDS = 60
+
+local resolvedName: string? = nil
+local resolvedFor = -1
+local resolvedAt = 0
+
+local function publishedPlaceName(): string?
+	local placeId = game.PlaceId
+	-- A place that has never been saved to Roblox has no id and no remote name.
+	if placeId == 0 then
+		return nil
+	end
+
+	local fresh = resolvedFor == placeId
+		and (resolvedName ~= nil or os.clock() - resolvedAt < NAME_RETRY_SECONDS)
+	if fresh then
+		return resolvedName
+	end
+
+	resolvedFor = placeId
+	resolvedAt = os.clock()
+
+	local ok, info = pcall(function()
+		return MarketplaceService:GetProductInfo(placeId, Enum.InfoType.Asset)
+	end)
+	local name = if ok and typeof(info) == "table" then (info :: any).Name else nil
+	resolvedName = if typeof(name) == "string" and name ~= "" then name else nil
+	return resolvedName
+end
+
+local Session = {}
+
+function Session.status(): { [string]: any }
+	local selected: { { path: string, className: string } } = {}
+	for index, instance in Selection:Get() do
+		if index > MAX_SELECTION then
+			break
+		end
+		table.insert(selected, { path = Paths.of(instance), className = instance.ClassName })
+	end
+
+	local totals = counts()
+	-- Open tabs ride along with status rather than getting their own tool: this
+	-- is the call agents are told to make first, and "which script is the user
+	-- looking at" is orientation, not a separate question.
+	local openScripts = Editor.documents()
+
+	local published = publishedPlaceName()
+
+	return {
+		openScripts = if #openScripts > 0 then openScripts else nil,
+		placeName = published or (if game.Name ~= "" then game.Name else "Untitled place"),
+		-- Kept separate when the two differ, so a path rooted at the data model
+		-- name stays explicable next to a place called something else entirely.
+		dataModelName = if published and published ~= game.Name then game.Name else nil,
+		placeId = game.PlaceId,
+		context = Context.of(),
+		-- RunService:IsRunning() is true for both Play and Run; IsEdit()
+		-- distinguishes the authoring session from a live one.
+		isRunning = RunService:IsRunning(),
+		isEdit = RunService:IsEdit(),
+		isRunMode = RunService:IsRunning() and not RunService:IsClient(),
+		isServerView = RunService:IsServer(),
+		selection = selected,
+		selectionCount = #Selection:Get(),
+		descendantCount = totals.descendants,
+		scriptCount = totals.scripts,
+		studioVersion = studioVersion(),
+		emulatedDevice = Emulation.summary(),
+	}
+end
+
+--[[
+	Round-trip probe used by the smoke test and by `studio_status` when the agent
+	only needs to know the channel is alive.
+]]
+function Session.ping(params: { [string]: any }): { [string]: any }
+	return { pong = true, echo = params.echo }
+end
+
+function Session.register()
+	Dispatch.registerAll("studio", {
+		status = function()
+			return Session.status()
+		end,
+		ping = Session.ping,
+	})
+end
+
+return Session

package/plugin/src/handlers/Viewport.luau

@@ -0,0 +1,302 @@
+--!strict
+--[[
+	The viewport and the selection -- what the user is pointing at, and what they
+	have highlighted.
+
+	Selection is the counterpart to `studio_status`, which reports it: this sets
+	it. Selecting what a tool just built is the cheapest way to show someone the
+	result of a change, and it puts the instance in reach of Studio's own move
+	and scale handles.
+
+	Raycasting answers "what is under this point in the 3D view", which is
+	otherwise unanswerable: an agent can enumerate the data model but has no way
+	to know what occupies a piece of space.
+]]
+
+local RunService = game:GetService("RunService")
+local Selection = game:GetService("Selection")
+local Workspace = game:GetService("Workspace")
+
+local Dispatch = require(script.Parent.Parent.Dispatch)
+local Paths = require(script.Parent.Parent.Paths)
+local Serialize = require(script.Parent.Parent.Serialize)
+
+local MAX_SELECTION = 200
+local DEFAULT_RAY_LENGTH = 1000
+
+local Viewport = {}
+
+--[[
+	Whether moving the camera in this session would change what anyone sees.
+
+	A playtest server has a `CurrentCamera` and accepts every write to it, and
+	renders nothing -- the picture on screen comes from the playtest's client. So
+	framing a subject here succeeds, reports a plausible camera position, and
+	moves no camera the user has. Measured: `focus` against a playtest server
+	returned a full result for a shot nobody could ever see.
+]]
+local function rendersToScreen(): boolean
+	return not (RunService:IsRunning() and RunService:IsServer())
+end
+
+
+local function toVector(value: any, label: string): Vector3
+	local ok, parsed = Serialize.parse(value, "Vector3")
+	if not ok or typeof(parsed) ~= "Vector3" then
+		Dispatch.fail(
+			"BAD_PARAMS",
+			string.format('%s must be three numbers, e.g. "0, 50, 0".', label)
+		)
+	end
+	return parsed :: Vector3
+end
+
+--[[
+	Casts a ray through the world and reports the first thing it hits.
+
+	`Workspace:Raycast`, not `StudioService:GizmoRaycast`. The latter reads like
+	the Studio-aware choice and is not: measured against a place with parts under
+	the ray, it returns nil every time. It picks Studio's own gizmos and
+	adornments, not world geometry.
+]]
+function Viewport.raycast(params: { [string]: any }): { [string]: any }
+	local origin = toVector(params.origin, "origin")
+	local direction = toVector(params.direction, "direction")
+	local length = tonumber(params.maxDistance) or DEFAULT_RAY_LENGTH
+
+	local filter: { Instance } = {}
+	for _, path in (params.ignore or {}) :: { string } do
+		table.insert(filter, Paths.resolve(path))
+	end
+
+	local config = RaycastParams.new()
+	config.FilterType = Enum.RaycastFilterType.Exclude
+	config.FilterDescendantsInstances = filter
+
+	local ok, result = pcall(function()
+		return Workspace:Raycast(origin, direction.Unit * length, config)
+	end)
+
+	if not ok or result == nil then
+		return { hit = false, origin = Serialize.value(origin), direction = Serialize.value(direction.Unit) }
+	end
+
+	local cast = result :: RaycastResult
+	return {
+		hit = true,
+		path = if cast.Instance then Paths.of(cast.Instance) else nil,
+		className = if cast.Instance then cast.Instance.ClassName else nil,
+		position = Serialize.value(cast.Position),
+		normal = Serialize.value(cast.Normal),
+		distance = math.floor(cast.Distance * 1000 + 0.5) / 1000,
+		material = Serialize.value(cast.Material),
+	}
+end
+
+--[[
+	Sets, extends or shrinks the Studio selection.
+]]
+function Viewport.select(params: { [string]: any }): { [string]: any }
+	local paths = params.paths
+	if typeof(paths) ~= "table" then
+		Dispatch.fail("BAD_PARAMS", "select requires a `paths` array.")
+	end
+	if #paths > MAX_SELECTION then
+		Dispatch.fail(
+			"TOO_MANY",
+			string.format("%d paths, over the %d selection limit.", #paths, MAX_SELECTION)
+		)
+	end
+
+	local instances: { Instance } = {}
+	for _, path in paths :: { string } do
+		table.insert(instances, Paths.resolve(path))
+	end
+
+	local mode = params.mode or "set"
+	if mode == "add" then
+		Selection:Add(instances)
+	elseif mode == "remove" then
+		Selection:Remove(instances)
+	else
+		Selection:Set(instances)
+	end
+
+	local current: { { [string]: any } } = {}
+	local memo: Paths.NameIndex = {}
+	for index, instance in Selection:Get() do
+		if index > MAX_SELECTION then
+			break
+		end
+		table.insert(current, { path = Paths.of(instance, memo), className = instance.ClassName })
+	end
+
+	return { items = current, count = #Selection:Get() }
+end
+
+--[[
+	The world-space box an instance occupies.
+
+	A Model knows its own extents; a lone part has to be measured from its size
+	and orientation. Anything else -- a Folder, a Script -- has no position at
+	all, and saying so is better than framing the origin and returning a picture
+	of empty ground.
+]]
+local function extentsOf(instance: Instance): (Vector3, Vector3)
+	if instance:IsA("Model") then
+		local cframe, size = (instance :: Model):GetBoundingBox()
+		return cframe.Position, size
+	end
+	if instance:IsA("BasePart") then
+		local part = instance :: BasePart
+		return part.Position, part.Size
+	end
+
+	-- A container is worth framing if anything inside it has a position.
+	local minimum: Vector3? = nil
+	local maximum: Vector3? = nil
+	for _, descendant in instance:GetDescendants() do
+		if descendant:IsA("BasePart") then
+			local part = descendant :: BasePart
+			local half = part.Size / 2
+			minimum = if minimum == nil then part.Position - half else (minimum :: Vector3):Min(part.Position - half)
+			maximum = if maximum == nil then part.Position + half else (maximum :: Vector3):Max(part.Position + half)
+		end
+	end
+	if minimum == nil or maximum == nil then
+		Dispatch.fail(
+			"NOT_POSITIONED",
+			string.format("%s is a %s and occupies no space in the world.", instance:GetFullName(), instance.ClassName),
+			"Frame something with geometry -- a part, a model, or a folder containing them."
+		)
+	end
+	local low, high = minimum :: Vector3, maximum :: Vector3
+	return (low + high) / 2, high - low
+end
+
+--[[
+	Points the Studio camera at something, framed so all of it is on screen.
+
+	This is what makes `screenshot` worth having. A picture of wherever the user
+	last left their camera answers nothing; a picture of the thing just built
+	answers "does it look right", which the data model cannot.
+
+	The distance is computed from the subject's size and the camera's own field
+	of view rather than guessed, so a doorway and a whole map both arrive filling
+	a similar share of the frame.
+]]
+function Viewport.focus(params: { [string]: any }): { [string]: any }
+	if not rendersToScreen() then
+		Dispatch.fail(
+			"NOT_RENDERED",
+			"This is the playtest's server session, which draws nothing -- moving its "
+				.. "camera would change no picture anybody sees.",
+			"Address the editor session (see `list_studios`), or stop the playtest first."
+		)
+	end
+	local camera = Workspace.CurrentCamera
+	if camera == nil then
+		Dispatch.fail("NO_CAMERA", "This session has no camera.")
+	end
+
+	local centre: Vector3
+	local size: Vector3
+	if typeof(params.path) == "string" and params.path ~= "" then
+		centre, size = extentsOf(Paths.resolve(params.path))
+	else
+		centre = toVector(params.at, "`at`")
+		size = Vector3.new(10, 10, 10)
+	end
+
+	--[[
+		Half the diagonal, not half the width: a wall seen from an angle presents
+		its diagonal, and framing to the width alone crops the corners off
+		exactly the shapes most worth looking at.
+	]]
+	local radius = math.max(size.Magnitude / 2, 1)
+	local fov = math.rad((camera :: Camera).FieldOfView)
+	local distance = (radius / math.tan(fov / 2)) * (tonumber(params.padding) or 1.5)
+
+	-- Down the -Z axis and slightly above by default, which is how a person
+	-- would stand to look at something: face on, a little raised, never level
+	-- with a flat surface where it would vanish to a line.
+	local direction: Vector3
+	if typeof(params.from) == "string" and params.from ~= "" then
+		direction = toVector(params.from, "`from`").Unit
+	else
+		direction = Vector3.new(0.45, 0.35, 1).Unit
+	end
+
+	local eye = centre + direction * distance
+	;(camera :: Camera).CFrame = CFrame.lookAt(eye, centre)
+	--[[
+		`Focus` is not optional here, and leaving it out is a silent failure.
+
+		Studio's edit camera orbits around Focus and re-derives its heading from
+		it every frame. Setting CFrame alone applies -- and is then thrown away
+		about a fifth of a second later, keeping the new position and restoring
+		the old rotation. Measured: the look vector read back correct
+		immediately, and had reverted to the previous heading by the next check,
+		so the camera moved to the right place and pointed the wrong way, and a
+		screenshot came back showing empty ground.
+	]]
+	;(camera :: Camera).Focus = CFrame.new(centre)
+
+	return {
+		focused = if typeof(params.path) == "string" then params.path else tostring(centre),
+		cameraPosition = tostring(eye),
+		lookingAt = tostring(centre),
+		distance = math.floor(distance * 10 + 0.5) / 10,
+		subjectSize = tostring(size),
+	}
+end
+
+--[[
+	Reads or sets the camera directly, for the cases framing cannot express --
+	standing inside a room, or matching a specific shot.
+]]
+function Viewport.camera(params: { [string]: any }): { [string]: any }
+	if not rendersToScreen() then
+		Dispatch.fail(
+			"NOT_RENDERED",
+			"This is the playtest's server session, which draws nothing -- moving its "
+				.. "camera would change no picture anybody sees.",
+			"Address the editor session (see `list_studios`), or stop the playtest first."
+		)
+	end
+	local camera = Workspace.CurrentCamera
+	if camera == nil then
+		Dispatch.fail("NO_CAMERA", "This session has no camera.")
+	end
+	local view = camera :: Camera
+
+	if params.position ~= nil then
+		local eye = toVector(params.position, "`position`")
+		local target = if params.lookAt ~= nil
+			then toVector(params.lookAt, "`lookAt`")
+			else eye + view.CFrame.LookVector
+		view.CFrame = CFrame.lookAt(eye, target)
+		-- Same reason as focus: without this the rotation survives a frame.
+		view.Focus = CFrame.new(target)
+	end
+	if tonumber(params.fieldOfView) ~= nil then
+		view.FieldOfView = math.clamp(tonumber(params.fieldOfView) :: number, 1, 120)
+	end
+
+	return {
+		position = tostring(view.CFrame.Position),
+		lookVector = tostring(view.CFrame.LookVector),
+		fieldOfView = view.FieldOfView,
+	}
+end
+
+function Viewport.register()
+	Dispatch.registerAll("viewport", {
+		raycast = Viewport.raycast,
+		select = Viewport.select,
+		focus = Viewport.focus,
+		camera = Viewport.camera,
+	})
+end
+
+return Viewport

package/plugin/src/handlers/World.luau

@@ -0,0 +1,176 @@
+--!strict
+--[[
+	Undo/redo, and collision groups.
+
+	Two small things that share a file because neither is big enough to deserve
+	its own and both are about the state of the place rather than its contents.
+
+	Undo matters more than it looks. Every write this server makes is already
+	wrapped in a ChangeHistoryService recording, so the user can revert any of it
+	by hand -- but the agent that made the mess could not clean it up, which made
+	"undo that" a request only a human could carry out. Now it can.
+
+	Collision groups are the engine's answer to "these parts should pass through
+	each other". Without them the alternative is toggling CanCollide, which turns
+	collision off against everything rather than against one class of thing.
+]]
+
+local ChangeHistoryService = game:GetService("ChangeHistoryService")
+local PhysicsService = game:GetService("PhysicsService")
+
+local Dispatch = require(script.Parent.Parent.Dispatch)
+local Paths = require(script.Parent.Parent.Paths)
+local Undo = require(script.Parent.Parent.Undo)
+
+local World = {}
+
+--[[
+	Steps the undo stack.
+
+	Reports what the stack looks like afterwards, because "undo" that quietly did
+	nothing -- an empty stack, or history disabled -- is indistinguishable from
+	one that worked unless the caller is told.
+]]
+function World.history(params: { [string]: any }): { [string]: any }
+	local action = tostring(params.action or "status")
+	local steps = math.clamp(tonumber(params.steps) or 1, 1, 25)
+
+	if action == "status" then
+		return {
+			canUndo = ChangeHistoryService:GetCanUndo(),
+			canRedo = ChangeHistoryService:GetCanRedo(),
+		}
+	end
+
+	if action ~= "undo" and action ~= "redo" then
+		Dispatch.fail("BAD_PARAMS", string.format("unknown history action %q", action))
+	end
+
+	local applied = 0
+	for _ = 1, steps do
+		local can = if action == "undo"
+			then ChangeHistoryService:GetCanUndo()
+			else ChangeHistoryService:GetCanRedo()
+		if not can then
+			break
+		end
+		local ok = pcall(function()
+			if action == "undo" then
+				ChangeHistoryService:Undo()
+			else
+				ChangeHistoryService:Redo()
+			end
+		end)
+		if not ok then
+			break
+		end
+		applied += 1
+	end
+
+	return {
+		action = action,
+		requested = steps,
+		applied = applied,
+		canUndo = ChangeHistoryService:GetCanUndo(),
+		canRedo = ChangeHistoryService:GetCanRedo(),
+		-- Said plainly rather than left to be inferred from applied == 0, which
+		-- is the case someone is most likely to misread as success.
+		note = if applied == 0
+			then string.format("Nothing to %s -- the history stack is empty in that direction.", action)
+			elseif applied < steps then string.format("Only %d of %d steps were available.", applied, steps)
+			else nil,
+	}
+end
+
+--[[
+	Collision groups: create them, set which collide with which, assign parts.
+
+	One call does all three, because they are never useful separately -- a group
+	nothing is assigned to has no effect, and an assignment to a group that does
+	not exist is an error.
+]]
+function World.collision(params: { [string]: any }): { [string]: any }
+	local action = tostring(params.action or "list")
+
+	if action == "list" then
+		local groups: { { [string]: any } } = {}
+		local ok, registered = pcall(function()
+			return PhysicsService:GetRegisteredCollisionGroups()
+		end)
+		if ok and typeof(registered) == "table" then
+			for _, group in registered :: { any } do
+				table.insert(groups, { name = group.name, mask = group.mask })
+			end
+		end
+		return { groups = groups }
+	end
+
+	local name = params.group
+	if typeof(name) ~= "string" or name == "" then
+		Dispatch.fail("BAD_PARAMS", "collision needs a `group` name.")
+	end
+
+	if action == "create" then
+		local ok, err = pcall(function()
+			PhysicsService:RegisterCollisionGroup(name)
+		end)
+		if not ok then
+			-- Already existing is the common case and is not a failure worth
+			-- refusing over: the caller wanted the group to exist, and it does.
+			if not string.find(tostring(err), "already", 1, true) then
+				Dispatch.fail("COLLISION_FAILED", string.format("Could not create %q: %s", name, tostring(err)))
+			end
+		end
+		return { group = name, created = ok, existed = not ok }
+	end
+
+	if action == "assign" then
+		local paths = params.paths
+		if typeof(paths) ~= "table" or #(paths :: { any }) == 0 then
+			Dispatch.fail("BAD_PARAMS", "assign needs a `paths` array.")
+		end
+		local assigned: { string } = {}
+		local _, undoable = Undo.record("MCPCollision", "MCP collision group", function()
+			for _, path in paths :: { string } do
+				local instance = Paths.resolve(path)
+				-- A model is what a caller usually means; assigning its parts is
+				-- what they want, and refusing would just make them enumerate.
+				local targets = if instance:IsA("BasePart") then { instance } else instance:GetDescendants()
+				for _, target in targets do
+					if target:IsA("BasePart") then
+						(target :: BasePart).CollisionGroup = name
+						table.insert(assigned, Paths.of(target))
+					end
+				end
+			end
+		end)
+		return { group = name, assigned = #assigned, parts = assigned, undoable = undoable }
+	end
+
+	if action == "collidable" then
+		local other = params.with
+		if typeof(other) ~= "string" or other == "" then
+			Dispatch.fail("BAD_PARAMS", "collidable needs `with`, the other group's name.")
+		end
+		local collidable = params.collidable ~= false
+		local ok, err = pcall(function()
+			PhysicsService:CollisionGroupSetCollidable(name, other, collidable)
+		end)
+		if not ok then
+			Dispatch.fail("COLLISION_FAILED", string.format("Could not set collidability: %s", tostring(err)))
+		end
+		return { group = name, with = other, collidable = collidable }
+	end
+
+	Dispatch.fail("BAD_PARAMS", string.format("unknown collision action %q", action))
+	return {}
+end
+
+function World.register()
+	Dispatch.registerAll("world", {
+		history = World.history,
+		collision = World.collision,
+	})
+end
+
+return World