@el4cteo/rbx-studio-mcp 0.1.0

package/plugin/src/Scope.luau

@@ -0,0 +1,78 @@
+--!strict
+--[[
+	Which parts of the DataModel a search is allowed to wander into.
+
+	`game:GetChildren()` returns ~122 instances, nearly all of them engine
+	singletons like TraceRouteService and HSRDataContentProvider that no one
+	authors content into. Listing them costs thousands of tokens and buries the
+	handful of containers that matter.
+
+	A "show it if it has children" rule was tried first and let too much through:
+	MemStorageService alone reports 197 children of pure engine state. So the root
+	level is an explicit allowlist of the containers a place is actually authored
+	in. Everything else stays reachable by passing its path directly, and callers
+	report how many were hidden so that is discoverable.
+]]
+
+local Scope = {}
+
+Scope.ROOT_ALWAYS = {
+	Workspace = true,
+	Players = true,
+	Lighting = true,
+	ReplicatedFirst = true,
+	ReplicatedStorage = true,
+	ServerScriptService = true,
+	ServerStorage = true,
+	StarterGui = true,
+	StarterPack = true,
+	StarterPlayer = true,
+	SoundService = true,
+	Teams = true,
+	MaterialService = true,
+	TextChatService = true,
+	Chat = true,
+	LocalizationService = true,
+	TestService = true,
+}
+
+--[[
+	The top-level service an instance sits under, or the instance itself when it
+	is one. Used to hide whole branches (everything inside CoreGui) rather than
+	just the service node.
+]]
+function Scope.topService(instance: Instance): Instance?
+	if instance == game then
+		return nil
+	end
+
+	local current = instance
+	local parent = current.Parent
+	while parent ~= nil and parent ~= game do
+		current = parent
+		parent = current.Parent
+	end
+
+	-- Landing on `game` means `current` is the service. Landing on nil means the
+	-- instance is detached from the DataModel, which is not noise to filter.
+	if parent == game then
+		return current
+	end
+	return nil
+end
+
+function Scope.isVisibleService(service: Instance): boolean
+	return Scope.ROOT_ALWAYS[service.Name] == true
+end
+
+--[[
+	True for instances the caller almost certainly did not mean to see. Only
+	applied when walking from the DataModel root; an explicit `path` into a
+	hidden service is always honoured.
+]]
+function Scope.isNoisy(instance: Instance): boolean
+	local service = Scope.topService(instance)
+	return service ~= nil and not Scope.isVisibleService(service)
+end
+
+return Scope

package/plugin/src/ScriptEdit.luau

@@ -0,0 +1,100 @@
+--!strict
+--[[
+	Editor-safe script reading and writing.
+
+	Every other Roblox Studio MCP server assigns `script.Source` directly. That is
+	wrong in a specific, silent way: when the script is open in the Studio script
+	editor, the editor holds its own buffer, and a direct Source write either gets
+	overwritten by that buffer or discards the user's unsaved edits. Roblox added
+	`ScriptEditorService:UpdateSourceAsync` precisely to close this gap -- it
+	routes the change through the editor so the open document, its undo stack and
+	the saved source all stay in agreement.
+
+	The cost is that it yields, so every write here is async. That is the whole
+	reason handlers are allowed to yield.
+]]
+
+local ScriptEditorService = game:GetService("ScriptEditorService")
+
+local Dispatch = require(script.Parent.Dispatch)
+
+local ScriptEdit = {}
+
+export type SourceContainer = LuaSourceContainer & { Source: string }
+
+--[[
+	Reads current source. `GetEditorSource` is preferred over `.Source` because it
+	returns the editor's live buffer, including edits the user has typed but not
+	saved -- reading `.Source` there would hand the agent stale code and it would
+	then "fix" changes the user just made.
+]]
+function ScriptEdit.read(target: LuaSourceContainer): string
+	local ok, source = pcall(function()
+		return ScriptEditorService:GetEditorSource(target)
+	end)
+	if ok and typeof(source) == "string" then
+		return source
+	end
+	return (target :: SourceContainer).Source
+end
+
+--[[
+	Replaces source through the editor. `transform` receives the current text and
+	returns the replacement; returning the input unchanged is a no-op.
+
+	`transform` is allowed to raise a structured Dispatch failure -- a bad line
+	range is only discoverable once the authoritative source is in hand. Such a
+	failure is stashed rather than thrown from inside the callback: throwing
+	there would surface as an opaque engine error and lose the code and hint the
+	agent needs. The callback instead returns the text untouched, making that one
+	script a no-op, and the original failure is re-raised afterwards.
+
+	Raises SCRIPT_LOCKED when the write is refused, which normally means the
+	script is a package member or is owned by another Team Create session.
+]]
+function ScriptEdit.write(target: LuaSourceContainer, transform: (string) -> string)
+	local pending: any = nil
+
+	local ok, err = pcall(function()
+		ScriptEditorService:UpdateSourceAsync(target, function(source)
+			local applied, result = pcall(transform, source)
+			if applied then
+				return result
+			end
+			pending = result
+			return source
+		end)
+	end)
+
+	if pending ~= nil then
+		error(pending, 0)
+	end
+	if ok then
+		return
+	end
+
+	local message = tostring(err)
+	if string.find(string.lower(message), "lock") or string.find(string.lower(message), "permission") then
+		Dispatch.fail(
+			"SCRIPT_LOCKED",
+			string.format("Studio refused to edit %s: %s", target:GetFullName(), message),
+			"The script is usually locked because it belongs to a package or is "
+				.. "checked out by another Team Create user. Ask the user to unlock it, "
+				.. "or edit a different script."
+		)
+	end
+	Dispatch.fail(
+		"EDIT_FAILED",
+		string.format("Could not edit %s: %s", target:GetFullName(), message)
+	)
+end
+
+--[[
+	True for instances that hold Luau source. Used to keep script tools from
+	being pointed at ordinary instances with a confusing property error.
+]]
+function ScriptEdit.isScript(instance: Instance): boolean
+	return instance:IsA("LuaSourceContainer")
+end
+
+return ScriptEdit

package/plugin/src/Serialize.luau

@@ -0,0 +1,287 @@
+--!strict
+--[[
+	Converts Roblox values into JSON-safe, token-cheap representations.
+
+	Format mirrors what the Studio Properties panel shows -- Vector3 as
+	"12, 0, 5", Enums as "Enum.Material.Plastic", instance references as their
+	path. Two reasons: a Roblox developer reading the transcript sees what they
+	would see in Studio, and a model has seen far more of that notation in
+	training than any bespoke JSON envelope. It is also markedly cheaper than
+	{"__type":"Vector3","x":12,"y":0,"z":5} on every property of every instance.
+
+	`Serialize.parse` is the exact inverse, so a value read here can be written
+	straight back without the agent reformatting it.
+]]
+
+local Serialize = {}
+
+-- Floats are rounded before display: Studio reports positions like
+-- 12.000000476837158, which costs tokens and means nothing to the caller.
+local PRECISION = 4
+
+-- API-dump type names that accept a plain Luau number.
+local NUMERIC_TYPES: { [string]: boolean } = {
+	int = true,
+	int64 = true,
+	float = true,
+	double = true,
+	number = true,
+}
+
+local function num(value: number): string
+	local rounded = math.round(value * 10 ^ PRECISION) / 10 ^ PRECISION
+	if rounded == math.floor(rounded) and math.abs(rounded) < 1e15 then
+		return string.format("%d", rounded)
+	end
+	return tostring(rounded)
+end
+
+--[[
+	Serializes one value. Unknown userdata falls back to `tostring`, which is
+	always better than dropping the property silently.
+]]
+function Serialize.value(value: any): any
+	local kind = typeof(value)
+
+	if kind == "string" or kind == "boolean" or kind == "nil" then
+		return value
+	end
+	if kind == "number" then
+		-- Kept numeric so the agent can do arithmetic without parsing.
+		return math.round(value * 10 ^ PRECISION) / 10 ^ PRECISION
+	end
+	if kind == "Vector3" then
+		return string.format("%s, %s, %s", num(value.X), num(value.Y), num(value.Z))
+	end
+	if kind == "Vector2" then
+		return string.format("%s, %s", num(value.X), num(value.Y))
+	end
+	if kind == "CFrame" then
+		local position = value.Position
+		local rx, ry, rz = value:ToOrientation()
+		return string.format(
+			"pos %s, %s, %s | rot %s, %s, %s",
+			num(position.X),
+			num(position.Y),
+			num(position.Z),
+			num(math.deg(rx)),
+			num(math.deg(ry)),
+			num(math.deg(rz))
+		)
+	end
+	if kind == "Color3" then
+		return string.format("%s, %s, %s", num(value.R), num(value.G), num(value.B))
+	end
+	if kind == "BrickColor" then
+		return value.Name
+	end
+	if kind == "UDim2" then
+		return string.format(
+			"{%s, %s}, {%s, %s}",
+			num(value.X.Scale),
+			num(value.X.Offset),
+			num(value.Y.Scale),
+			num(value.Y.Offset)
+		)
+	end
+	if kind == "UDim" then
+		return string.format("{%s, %s}", num(value.Scale), num(value.Offset))
+	end
+	if kind == "EnumItem" then
+		return string.format("Enum.%s.%s", tostring(value.EnumType), value.Name)
+	end
+	if kind == "Instance" then
+		return value:GetFullName()
+	end
+	if kind == "NumberRange" then
+		return string.format("%s..%s", num(value.Min), num(value.Max))
+	end
+	if kind == "Rect" then
+		return string.format(
+			"%s, %s, %s, %s",
+			num(value.Min.X),
+			num(value.Min.Y),
+			num(value.Max.X),
+			num(value.Max.Y)
+		)
+	end
+	if kind == "ColorSequence" then
+		local parts: { string } = {}
+		for _, keypoint in value.Keypoints do
+			table.insert(
+				parts,
+				string.format("%s=%s", num(keypoint.Time), Serialize.value(keypoint.Value))
+			)
+		end
+		return table.concat(parts, " ")
+	end
+	if kind == "NumberSequence" then
+		local parts: { string } = {}
+		for _, keypoint in value.Keypoints do
+			table.insert(parts, string.format("%s=%s", num(keypoint.Time), num(keypoint.Value)))
+		end
+		return table.concat(parts, " ")
+	end
+	if kind == "table" then
+		local copy: { [any]: any } = {}
+		for key, item in value :: { [any]: any } do
+			copy[key] = Serialize.value(item)
+		end
+		return copy
+	end
+
+	return tostring(value)
+end
+
+--[[
+	Reads a property without throwing.
+
+	Property access on an instance can error even when the API dump says the
+	property exists -- some are context-gated (only readable during a playtest,
+	or only on a loaded asset). Returning nil for those keeps one awkward
+	property from failing an inspect of 50 instances.
+]]
+function Serialize.readProperty(instance: Instance, name: string): (boolean, any)
+	local ok, value = pcall(function()
+		return (instance :: any)[name]
+	end)
+	if not ok then
+		return false, nil
+	end
+	return true, Serialize.value(value)
+end
+
+--[[
+	Parses a serialized string back into a Roblox value, given the target type
+	from the API dump. Returns ok=false with a reason the agent can act on
+	rather than raising, so batch writes can report per-property failures.
+]]
+function Serialize.parse(text: any, valueType: string): (boolean, any, string?)
+	local kind = typeof(text)
+
+	-- Values already of the right primitive shape pass straight through. The
+	-- number case is matched against the target type rather than excluded from
+	-- one: a bare 5 is a valid `float`, but not a valid Vector3, Enum or Color3.
+	if kind == "boolean" then
+		return true, text, nil
+	end
+	if kind == "number" and NUMERIC_TYPES[valueType] then
+		return true, text, nil
+	end
+
+	if valueType == "string" or valueType == "Content" or valueType == "ProtectedString" then
+		return true, tostring(text), nil
+	end
+	if valueType == "bool" then
+		if kind == "boolean" then
+			return true, text, nil
+		end
+		return true, text == "true", nil
+	end
+	if NUMERIC_TYPES[valueType] then
+		local parsed = tonumber(text)
+		if not parsed then
+			return false, nil, string.format('expected a number, got "%s"', tostring(text))
+		end
+		return true, parsed, nil
+	end
+
+	local numbers: { number } = {}
+	if kind == "string" then
+		for match in string.gmatch(text, "-?%d+%.?%d*") do
+			table.insert(numbers, tonumber(match) :: number)
+		end
+	elseif kind == "table" then
+		for _, item in text :: { any } do
+			local parsed = tonumber(item)
+			if parsed then
+				table.insert(numbers, parsed)
+			end
+		end
+	end
+
+	if valueType == "Vector3" then
+		if #numbers < 3 then
+			return false, nil, 'expected three numbers, e.g. "12, 0, 5"'
+		end
+		return true, Vector3.new(numbers[1], numbers[2], numbers[3]), nil
+	end
+	if valueType == "Vector2" then
+		if #numbers < 2 then
+			return false, nil, 'expected two numbers, e.g. "12, 5"'
+		end
+		return true, Vector2.new(numbers[1], numbers[2]), nil
+	end
+	if valueType == "Color3" then
+		if #numbers < 3 then
+			return false, nil, 'expected three 0-1 components, e.g. "1, 0.5, 0"'
+		end
+		-- 0-255 is a common mistake and unambiguous to detect, so accept it.
+		local scale = if numbers[1] > 1 or numbers[2] > 1 or numbers[3] > 1 then 255 else 1
+		return true, Color3.new(numbers[1] / scale, numbers[2] / scale, numbers[3] / scale), nil
+	end
+	if valueType == "BrickColor" then
+		-- Cast because the API definitions type this overload as a literal union
+		-- of every BrickColor name. At runtime it takes any string and throws on
+		-- an unknown one, which is exactly what the pcall is here to catch.
+		local ok, color = pcall(function()
+			return BrickColor.new(tostring(text) :: any)
+		end)
+		if not ok then
+			return false, nil, string.format('"%s" is not a BrickColor name', tostring(text))
+		end
+		return true, color, nil
+	end
+	if valueType == "UDim2" then
+		if #numbers < 4 then
+			return false, nil, 'expected four numbers, e.g. "{0.5, 10}, {0.5, 20}"'
+		end
+		return true, UDim2.new(numbers[1], numbers[2], numbers[3], numbers[4]), nil
+	end
+	if valueType == "UDim" then
+		if #numbers < 2 then
+			return false, nil, 'expected two numbers, e.g. "{0.5, 10}"'
+		end
+		return true, UDim.new(numbers[1], numbers[2]), nil
+	end
+	if valueType == "CFrame" then
+		if #numbers >= 6 then
+			return true,
+				CFrame.new(numbers[1], numbers[2], numbers[3])
+					* CFrame.fromOrientation(
+						math.rad(numbers[4]),
+						math.rad(numbers[5]),
+						math.rad(numbers[6])
+					),
+				nil
+		end
+		if #numbers >= 3 then
+			return true, CFrame.new(numbers[1], numbers[2], numbers[3]), nil
+		end
+		return false, nil, 'expected "pos x, y, z" or "pos x, y, z | rot rx, ry, rz"'
+	end
+	if valueType == "NumberRange" then
+		if #numbers < 2 then
+			return false, nil, 'expected "min..max"'
+		end
+		return true, NumberRange.new(numbers[1], numbers[2]), nil
+	end
+
+	-- Enum values arrive as "Enum.Material.Plastic" or bare "Plastic".
+	local enumType = (Enum :: any)[valueType]
+	if enumType then
+		local name = tostring(text):match("([^%.]+)$") or tostring(text)
+		for _, item in enumType:GetEnumItems() do
+			if item.Name == name then
+				return true, item, nil
+			end
+		end
+		return false,
+			nil,
+			string.format('"%s" is not a member of Enum.%s', tostring(text), valueType)
+	end
+
+	return false, nil, string.format('no conversion known for type "%s"', valueType)
+end
+
+return Serialize