@el4cteo/rbx-studio-mcp 0.3.0 → 0.3.5

package/plugin/src/handlers/Discover.luau

@@ -39,6 +39,72 @@ local function summarise(instance: Instance, memo: Paths.NameIndex): { [string]:
 	}
 end
 
+--[[
+	Puts a result list into an order that does not change between calls.
+
+	`GetChildren` and `GetDescendants` do NOT return a stable order. Measured on
+	twelve parts named P01..P12 with nothing mutating between the two calls, the
+	engine returned them in ascending order once and as P08, P06, P04, P03, P11,
+	P02, P01, P12, P10, P07, P05, P09 the next time.
+
+	Unsorted, that made paging incoherent rather than merely untidy: `offset` is
+	a position in this list, so page two came from a different ordering than page
+	one, which silently skips some instances and repeats others. Nothing about
+	the response would have said so -- the counts stay right and every row is a
+	real instance.
+
+	Sorted by name, with the engine's per-instance debug id breaking ties so
+	same-named siblings hold a fixed order too. Name first because it is also
+	the order a reader expects: P01 before P02.
+]]
+local function stableOrder(list: { Instance })
+	local ids: { [Instance]: string } = {}
+	for _, instance in list do
+		-- Cached: `GetDebugId` is a call per comparison otherwise, and a sort
+		-- makes O(n log n) of them.
+		local ok, id = pcall(function()
+			return instance:GetDebugId()
+		end)
+		ids[instance] = if ok then id else tostring(instance)
+	end
+	table.sort(list, function(a: Instance, b: Instance): boolean
+		if a.Name ~= b.Name then
+			return a.Name < b.Name
+		end
+		return (ids[a] or "") < (ids[b] or "")
+	end)
+end
+
+--[[
+	Compares a property against the text a caller asked for.
+
+	This was an exact `tostring` match, which made `find` disagree with `modify`
+	about its own notation: `modify` documents an enum as either "Neon" or
+	"Enum.Material.Neon", but only the qualified form matched here, and "False"
+	matched nothing at all. Both came back as a confident zero rather than an
+	error, which is the hardest kind of wrong answer to notice.
+
+	The bare-name shortcut is allowed only for enums, so a part named
+	"Map.Backup" is not matched by a search for "Backup".
+]]
+local function valueMatches(actual: any, wanted: string): boolean
+	local text = tostring(actual)
+	if text == wanted then
+		return true
+	end
+
+	local lowered = string.lower(text)
+	local target = string.lower(wanted)
+	if lowered == target then
+		return true
+	end
+
+	if string.sub(lowered, 1, 5) == "enum." then
+		return string.match(lowered, "([^%.]+)$") == target
+	end
+	return false
+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.
@@ -86,12 +152,18 @@ function Discover.tree(params: { [string]: any }): { [string]: any }
 				end
 			end
 		end
+		-- Sorted per level rather than at the end, so the breadth-first shape is
+		-- kept -- shallow instances still come before deep ones -- while the
+		-- siblings inside each level stop reshuffling between calls.
+		stableOrder(nextFrontier)
 		frontier = nextFrontier
 		if #frontier == 0 or visits > MAX_VISITS then
 			break
 		end
 	end
 
+	stableOrder(matched)
+
 	local items: { { [string]: any } } = {}
 	local memo: Paths.NameIndex = {}
 	for index = offset + 1, math.min(offset + limit, #matched) do
@@ -257,13 +329,15 @@ function Discover.find(params: { [string]: any }): { [string]: any }
 			if not readOk then
 				continue
 			end
-			if propertyValue ~= nil and tostring(value) ~= tostring(propertyValue) then
+			if propertyValue ~= nil and not valueMatches(value, tostring(propertyValue)) then
 				continue
 			end
 		end
 		table.insert(matched, instance)
 	end
 
+	stableOrder(matched)
+
 	local items: { { [string]: any } } = {}
 	local memo: Paths.NameIndex = {}
 	for index = offset + 1, math.min(offset + limit, #matched) do

package/plugin/src/handlers/Exec.luau

@@ -43,8 +43,9 @@ local Exec = {}
 	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 function describe(value: any, depth: number?, seen: { [any]: boolean }?): any
 	local level = depth or 0
+	local visited = seen or {}
 	local kind = typeof(value)
 
 	if kind == "function" or kind == "thread" then
@@ -55,11 +56,18 @@ local function describe(value: any, depth: number?): any
 	end
 
 	local source = value :: { [any]: any }
-	-- Also the cycle guard: a self-referencing table stops here rather than
-	-- recursing until the stack gives out.
+	-- Named separately from the depth cap, because they mean opposite things to
+	-- a reader. The depth cap says "there is more below this"; a cycle says
+	-- "this is the table you are already inside". Reporting the second as the
+	-- first printed `t.self.self.self` as three distinct nested tables, which
+	-- reads as real structure that does not exist.
+	if visited[source] then
+		return "<circular reference>"
+	end
 	if level >= MAX_TABLE_DEPTH then
 		return "<nested table>"
 	end
+	visited[source] = true
 
 	local count = 0
 	for _ in source do
@@ -75,8 +83,11 @@ local function describe(value: any, depth: number?): any
 				table.insert(list, string.format("<%d more>", count - MAX_TABLE_ENTRIES))
 				break
 			end
-			table.insert(list, describe(item, level + 1))
+			table.insert(list, describe(item, level + 1, visited))
 		end
+		-- Cleared on the way out so the same table appearing twice side by side
+		-- still renders twice; only a table containing itself is a cycle.
+		visited[source] = nil
 		return list
 	end
 
@@ -88,8 +99,9 @@ local function describe(value: any, depth: number?): any
 			map["..."] = string.format("<%d more>", count - MAX_TABLE_ENTRIES)
 			break
 		end
-		map[tostring(key)] = describe(item, level + 1)
+		map[tostring(key)] = describe(item, level + 1, visited)
 	end
+	visited[source] = nil
 	return map
 end
 

package/plugin/src/handlers/Instances.luau

@@ -53,13 +53,45 @@ local function applyProperty(target: Instance, name: string, spec: PropertySpec)
 	return nil
 end
 
+--[[
+	Sets attributes, honouring an explicit type where one is given.
+
+	A bare value is written as it arrives, so a string stays a string. That is
+	the safe default and it is also a trap: attributes hold Vector3, Color3,
+	UDim2 and the rest, and `"0, 5, 0"` -- the exact text that sets a Vector3
+	property -- was landing on an attribute as five characters. The write looked
+	like it worked and the game read a string. So a value may instead arrive as
+	{ type = "Vector3", value = "0, 5, 0" }, which goes through the same parser
+	properties use.
+]]
 local function applyAttributes(target: Instance, attributes: { [string]: any }): { string }
 	local failures: { string } = {}
 	for name, value in attributes do
-		-- A JSON null means "remove this attribute", which SetAttribute spells
-		-- as nil. There is no other way to express removal in the payload.
+		local resolved: any = value
+		local typed = typeof(value) == "table" and (value :: any).type ~= nil
+		if typed then
+			local spec = value :: { type: string, value: any }
+			local parsedOk, parsed, reason = Serialize.parse(spec.value, spec.type)
+			if not parsedOk then
+				table.insert(
+					failures,
+					string.format(
+						"attribute %s: %s",
+						name,
+						reason or string.format("could not be read as a %s", tostring(spec.type))
+					)
+				)
+				continue
+			end
+			resolved = parsed
+		end
+
+		-- An empty string means "remove this attribute", which SetAttribute spells
+		-- as nil. There is no other way to express removal in the payload -- and
+		-- the typed form is how to set an attribute to a genuinely empty string,
+		-- since only the bare form is read as removal.
 		local ok, err = pcall(function()
-			target:SetAttribute(name, if value == "" then nil else value)
+			target:SetAttribute(name, if not typed and value == "" then nil else resolved)
 		end)
 		if not ok then
 			table.insert(failures, string.format("attribute %s: %s", name, tostring(err)))

package/plugin/src/handlers/Scripts.luau

@@ -324,6 +324,33 @@ end
 	open in the editor and there is no buffer to conflict with. Every later edit
 	goes through the editor path.
 ]]
+--[[
+	Names the starter container a script was just parented into, or nil.
+
+	These four are copied into the player rather than run where they sit, so a
+	`Script` with a non-Legacy RunContext inside one runs BOTH in the original
+	and in every copy. Roblox does warn about it -- "will cause it to run
+	multiple times" -- but that warning is emitted by Studio itself and never
+	reaches `console`, so an agent following the "prefer Script with runContext
+	Client over LocalScript" advice writes a double-running script and is given
+	no way to find out.
+]]
+local STARTER_CONTAINERS = {
+	"StarterGui",
+	"StarterPack",
+	"StarterPlayerScripts",
+	"StarterCharacterScripts",
+}
+
+local function starterContainer(instance: Instance): string?
+	for _, className in STARTER_CONTAINERS do
+		if instance:FindFirstAncestorOfClass(className :: any) then
+			return className
+		end
+	end
+	return nil
+end
+
 function Scripts.create(params: { [string]: any }): { [string]: any }
 	local requests = params.scripts
 	if typeof(requests) ~= "table" or #requests == 0 then
@@ -343,13 +370,18 @@ function Scripts.create(params: { [string]: any }): { [string]: any }
 				"BAD_PARAMS",
 				string.format('scripts[%d] has className "%s".', position, tostring(request.className)),
 				"Use Script, LocalScript or ModuleScript. Prefer a Script with "
-					.. "runContext Client over LocalScript in new work."
+					.. "runContext Client over LocalScript in new work -- except inside "
+					.. "StarterGui, StarterPack, StarterPlayerScripts or "
+					.. "StarterCharacterScripts, where LocalScript is still the right "
+					.. "class."
 			)
 		end
 	end
 
 	-- No shared path memo here: each creation changes its parent's children, so a
 	-- cached sibling grouping would go stale mid-batch and mis-number the paths.
+	local warnings: { string } = {}
+
 	local created, recorded = Undo.record("StudioMCP.ScriptCreate", "MCP create script", function()
 		local created: { { [string]: any } } = {}
 
@@ -381,6 +413,26 @@ function Scripts.create(params: { [string]: any }): { [string]: any }
 
 			instance.Parent = parent
 
+			if instance:IsA("Script") and instance.RunContext ~= Enum.RunContext.Legacy then
+				local container = starterContainer(instance)
+				if container then
+					table.insert(
+						warnings,
+						string.format(
+							'%s is a Script with RunContext %s inside %s. That container is '
+								.. "COPIED into each player, so the script runs once where it "
+								.. "sits and again in every copy. Make it a LocalScript "
+								.. "instead -- a Legacy Script there would not run at all. "
+								.. "Studio warns about this in its own Output, which `console` "
+								.. "cannot read.",
+							instance.Name,
+							instance.RunContext.Name,
+							container
+						)
+					)
+				end
+			end
+
 			table.insert(created, {
 				path = Paths.of(instance),
 				className = instance.ClassName,
@@ -390,7 +442,11 @@ function Scripts.create(params: { [string]: any }): { [string]: any }
 		return created
 	end)
 
-	return { items = created, undoStep = if recorded then "MCP create script" else nil }
+	return {
+		items = created,
+		undoStep = if recorded then "MCP create script" else nil,
+		warnings = if #warnings > 0 then warnings else nil,
+	}
 end
 
 function Scripts.register()