@el4cteo/rbx-studio-mcp 0.7.2 → 0.7.5

package/plugin/src/ClientRelay.luau

@@ -0,0 +1,88 @@
+--!strict
+-- One temporary client relay lifecycle for input and execution.
+local Players = game:GetService("Players")
+local RunService = game:GetService("RunService")
+local Dispatch = require(script.Parent.Dispatch)
+local ClientRelay = {}
+function ClientRelay.playerFor(name: string?): Player
+	if not RunService:IsRunning() then
+		Dispatch.fail("NOT_RUNNING", "Client access needs a running playtest; this is an edit session.")
+	end
+	if not RunService:IsServer() then
+		Dispatch.fail("WRONG_CONTEXT", "Address the playtest server's studioId for client access.")
+	end
+	local players = Players:GetPlayers()
+	if #players == 0 then
+		Dispatch.fail(
+			"NO_PLAYER",
+			"No player is in this session.",
+			"Client access needs a running playtest. Use `playtest op=\"play\"`, "
+				.. "then address this at the playtest's studioId."
+		)
+	end
+	if name == nil or name == "" then
+		if #players > 1 then
+			Dispatch.fail(
+				"AMBIGUOUS_PLAYER",
+				string.format("%d players are in this session.", #players),
+				"Name one with `player`."
+			)
+		end
+		return players[1]
+	end
+	for _, player in players do
+		if player.Name == name then
+			return player
+		end
+	end
+	Dispatch.fail("NO_PLAYER", string.format("No player named %q is in this session.", name))
+	return players[1]
+end
+
+
+function ClientRelay.run(player: Player, name: string, source: string, attributes: { [string]: any }, timeout: number, prepare: ((LocalScript) -> ())?, ready: (() -> ())?): { [string]: any }
+	local gui = player:FindFirstChildOfClass("PlayerGui")
+	if not gui then Dispatch.fail("NO_PLAYER", player.Name .. " has no PlayerGui yet.") end
+	local relay = Instance.new("LocalScript")
+	local connection: RBXScriptConnection? = nil
+	local answer: any = nil
+	local ok, failure = pcall(function()
+		relay.Name = name
+		relay:SetAttribute("MCPClientRelay", true)
+		relay.Source = source
+		for key, value in attributes do relay:SetAttribute(key, value) end
+		local remote = Instance.new("RemoteEvent")
+		remote.Name = "Report"
+		remote.Parent = relay
+		if prepare then prepare(relay) end
+		local started = false
+		connection = remote.OnServerEvent:Connect(function(from, payload)
+			if from ~= player or answer ~= nil or typeof(payload) ~= "table" then return end
+			-- A capture can wait until its client relay is ready before starting
+			-- the server window. Existing single-response relays are unchanged.
+			if ready and payload.ready == true then
+				if started then return end
+				started = true
+				local prepared, reason = pcall(ready)
+				if not prepared then
+					answer = { ok = false, reason = tostring(reason) }
+					return
+				end
+				remote:FireClient(player, true)
+			else
+				answer = payload
+			end
+		end)
+		relay.Parent = gui
+		local deadline = os.clock() + timeout
+		while answer == nil and os.clock() < deadline and player.Parent == Players do task.wait(0.05) end
+	end)
+	if connection then connection:Disconnect() end
+	relay:Destroy()
+	if not ok then Dispatch.fail("CLIENT_FAILED", tostring(failure)) end
+	if answer == nil then
+		Dispatch.fail("NO_ACK", string.format("The client did not respond within %gs (or disconnected).", timeout), "The temporary relay was removed; code may have made changes before timing out.")
+	end
+	return answer
+end
+return ClientRelay

package/plugin/src/Commands.luau

@@ -22,9 +22,11 @@
 
 local ScriptEditorService = game:GetService("ScriptEditorService")
 local Selection = game:GetService("Selection")
+local RunService = game:GetService("RunService")
 local ServerStorage = game:GetService("ServerStorage")
 
 local Config = require(script.Parent.Config)
+local Playtest = require(script.Parent.handlers.Playtest)
 local Console = require(script.Parent.Console)
 local Net = require(script.Parent.Net)
 local Secret = require(script.Parent.Secret)
@@ -251,6 +253,30 @@ define({
 	end,
 })
 
+define({
+	name = "playtests",
+	usage = "playtests [on|off]",
+	summary = "allow or block MCP playtests; ON permits, OFF enforces",
+	run = function(args)
+		local wanted = args[1]
+		if #args > 1 or (wanted ~= nil and wanted ~= "on" and wanted ~= "off") then
+			Console.log("error", "usage: playtests [on|off]")
+			return
+		end
+		if wanted ~= nil then Playtest.setAllowed(wanted == "on") end
+		Console.log("info", if Playtest.isAllowed() then "Playtests: ON" else "Playtests: OFF")
+		if wanted == "off" then
+			-- Persist the lock BEFORE stopping, because stopping can destroy this VM.
+			-- The bridge sees other connected test sessions; the client view cannot
+			-- make HTTP calls and stops its own session locally instead.
+			if not (RunService:IsClient() and not RunService:IsServer()) then
+				task.spawn(function() remote("playtests", { "off" }, "playtests off") end)
+			end
+			Playtest.stopLocal()
+		end
+	end,
+})
+
 define({
 	name = "autoopen",
 	usage = "autoopen [on|off]",

package/plugin/src/Config.luau

@@ -9,7 +9,7 @@
 
 local Config = {}
 
-Config.PLUGIN_VERSION = "0.7.2"
+Config.PLUGIN_VERSION = "0.7.5"
 
 -- Fingerprint of plugin/src, stamped in by scripts/build-plugin.mjs. The server
 -- computes the same hash from its own copy of the sources and compares, so a

package/plugin/src/ExecRuntime.luau

@@ -0,0 +1,161 @@
+--!strict
+-- Shared bounded execution results in the VM that calls run.
+local LogService = game:GetService("LogService")
+local Serialize = require(script.Parent.Serialize)
+-- A chunk that prints in a loop would otherwise return a response no context
+-- window can hold.
+local MAX_OUTPUT_LINES = 200
+local MAX_RETURN_VALUES = 10
+
+-- Returned tables are walked rather than counted, but not without limit: a
+-- chunk that returns a whole config tree, or one with a cycle in it, must not be
+-- able to produce a response nothing can read.
+local MAX_TABLE_ENTRIES = 50
+local MAX_TABLE_DEPTH = 4
+
+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
+		return string.format("<%s>", kind)
+	end
+	if kind ~= "table" then
+		return Serialize.value(value)
+	end
+
+	local source = value :: { [any]: any }
+	-- 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
+		count += 1
+	end
+
+	-- Arrays keep their shape so they read as lists on the other side; anything
+	-- with non-sequential keys becomes a map with stringified keys.
+	if count == #source then
+		local list: { any } = {}
+		for index, item in ipairs(source) do
+			if index > MAX_TABLE_ENTRIES then
+				table.insert(list, string.format("<%d more>", count - MAX_TABLE_ENTRIES))
+				break
+			end
+			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
+
+	local map: { [string]: any } = {}
+	local shown = 0
+	for key, item in source do
+		shown += 1
+		if shown > MAX_TABLE_ENTRIES then
+			map["..."] = string.format("<%d more>", count - MAX_TABLE_ENTRIES)
+			break
+		end
+		map[tostring(key)] = describe(item, level + 1, visited)
+	end
+	visited[source] = nil
+	return map
+end
+
+local Runtime = {}
+Runtime.describe = describe
+function Runtime.run(chunk: () -> ...any, timeout: number?): { [string]: any }
+	-- Captured rather than inferred: a chunk's prints are usually the point, and
+	-- reading them back from the log afterwards would also pick up whatever else
+	-- the place logged in the meantime.
+	local output: { { [string]: any } } = {}
+	local connection = LogService.MessageOut:Connect(function(message, messageType)
+		if #output < MAX_OUTPUT_LINES then
+			table.insert(output, {
+				message = message,
+				level = if messageType == Enum.MessageType.MessageError
+					then "error"
+					elseif messageType == Enum.MessageType.MessageWarning then "warning"
+					else "print",
+			})
+		end
+	end)
+
+	local started = os.clock()
+	local results: any = nil
+	if timeout then
+		local worker = task.spawn(function() results = table.pack(pcall(chunk :: any)) end)
+		local deadline = started + timeout
+		while results == nil and os.clock() < deadline do task.wait() end
+		if results == nil then
+			task.cancel(worker)
+			results = table.pack(false, "CLIENT_TIMEOUT: execution exceeded " .. tostring(timeout) .. "s")
+		end
+	else
+		results = table.pack(pcall(chunk :: () -> ...any))
+	end
+	local elapsed = os.clock() - started
+
+	--[[
+		MessageOut is deferred: `print` returns before the event fires, so
+		disconnecting straight after the chunk finished captured nothing at all.
+		A short settle picks the lines up.
+
+		It is bounded and stops as soon as the flow stops, rather than waiting a
+		fixed period, so a chunk that logged nothing costs almost no time and one
+		that logged plenty is not truncated.
+	]]
+	local settleDeadline = os.clock() + 0.5
+	local seen = #output
+	local quietFrames = 0
+	while os.clock() < settleDeadline and quietFrames < 3 do
+		task.wait()
+		if #output == seen then
+			quietFrames += 1
+		else
+			seen = #output
+			quietFrames = 0
+		end
+	end
+
+	connection:Disconnect()
+
+	if not results[1] then
+		return {
+			ok = false,
+			error = tostring(results[2]),
+			output = output,
+			milliseconds = math.floor(elapsed * 1000 + 0.5),
+		}
+	end
+
+	local returned: { any } = {}
+	for index = 2, math.min(results.n, MAX_RETURN_VALUES + 1) do
+		-- A nil return is written out rather than dropped. `table.insert` of nil
+		-- does nothing, so `return a, nil, b` came back as two values and every
+		-- one after the nil shifted into the wrong position.
+		local value = results[index]
+		table.insert(returned, if value == nil then "nil" else describe(value))
+	end
+
+	return {
+		ok = true,
+		returned = returned,
+		output = output,
+		milliseconds = math.floor(elapsed * 1000 + 0.5),
+	}
+end
+return Runtime

package/plugin/src/Phrase.luau

@@ -288,6 +288,9 @@ local DESCRIBERS: { [string]: Describer } = {
 		local name = leaf(params.path)
 		return if name ~= nil then "Clear breakpoints in " .. name else "Clear all breakpoints"
 	end,
+	["debug.remotes"] = function()
+		return "Observe playtest RemoteEvent traffic"
+	end,
 	["debug.snapshots"] = function()
 		return "Read what the breakpoints caught"
 	end,

package/plugin/src/RemoteTrace.luau

@@ -0,0 +1,143 @@
+--!strict
+-- Passive, bounded RemoteEvent observations shared by the server and client.
+local Paths = require(script.Parent.Paths)
+local Trace = {}
+local MAX_EVENTS = 1000 -- per direction; disconnect at the cap, never keep raw payloads
+local MAX_REMOTES = 128
+local MAX_ROWS = 20
+local MAX_VISITS = 10000
+
+local function brief(value: string, limit: number): string
+	local clipped = string.sub(value, 1, limit)
+	-- ASCII keeps invalid UTF-8, controls and JSON escaping from expanding output.
+	clipped = string.gsub(clipped, "[^ -~]", "?")
+	return clipped .. (if #value > limit then "..." else "")
+end
+
+local function pathOf(remote: Instance): string
+	local path = Paths.of(remote)
+	if #path <= 256 then return path end
+	-- Keep Unicode instance names valid at the byte boundary.
+	local ok, boundary = pcall(utf8.offset, path, 0, 257)
+	return string.sub(path, 1, if ok and boundary then boundary - 1 else 256) .. "..."
+end
+
+local function shape(value: any, depth: number): string
+	local kind = typeof(value)
+	if kind == "string" then return "string:" .. string.format("%q", brief(value, 32)) end
+	if kind == "number" or kind == "boolean" or kind == "nil" then return kind .. ":" .. tostring(value) end
+	if kind == "Instance" then return "Instance<" .. value.ClassName .. ">" end
+	if kind ~= "table" then return kind end
+	if depth >= 2 then return "table{...}" end
+	local parts = {}
+	local key, item = next(value)
+	for _ = 1, 4 do
+		if key == nil then break end
+		local label = if typeof(key) == "string" then brief(key, 20) else typeof(key)
+		table.insert(parts, label .. "=" .. shape(item, depth + 1))
+		key, item = next(value, key)
+	end
+	if key ~= nil then table.insert(parts, "...") end
+	return brief("table{" .. table.concat(parts, ",") .. "}", 160)
+end
+
+function Trace.arguments(...: any): string
+	local parts = {}
+	local count = select("#", ...)
+	for index = 1, math.min(count, 6) do
+		table.insert(parts, shape(select(index, ...), 0))
+	end
+	if count > 6 then table.insert(parts, "...") end
+	return brief("(" .. table.concat(parts, ", ") .. ")", 192)
+end
+
+-- Returns an idempotent stop function; its deadline also cleans up if the caller fails.
+function Trace.start(root: Instance, player: Player, client: boolean, seconds: number, excluded: Instance?): () -> { [string]: any }
+	local connections: { RBXScriptConnection } = {}
+	local watched: { [Instance]: boolean } = {}
+	local rows: { any } = {}
+	local byRemote: { [Instance]: any } = {}
+	local events, remotes, visits = 0, 0, 0
+	local omitted, scanLimited, eventLimited = false, false, false
+	local skipped = 0
+	local active = true
+	local started = os.clock()
+	local elapsed = 0
+	local timer: thread? = nil
+	local function stop(): { [string]: any }
+		if active then
+			active = false
+			elapsed = math.max(os.clock() - started, 0.001)
+			for _, connection in connections do connection:Disconnect() end
+			if timer then task.cancel(timer); timer = nil end
+			for _, row in rows do row.callsPerSecond = math.round(row.count / elapsed * 100) / 100 end
+		end
+		return { items = rows, events = events, seconds = elapsed, watched = remotes,
+			eventLimitReached = eventLimited, scanLimitReached = scanLimited, rowsOmitted = omitted, skipped = skipped }
+	end
+	local function record(remote: Instance, ...: any)
+		if not active or (remote ~= root and not remote:IsDescendantOf(root)) then return end
+		events += 1
+		local row = byRemote[remote]
+		if row == nil and #rows < MAX_ROWS then
+			row = { path = pathOf(remote), direction = if client then "server -> client" else "client -> server",
+				player = brief(player.Name, 64), count = 0, samples = {} }
+			byRemote[remote] = row
+			table.insert(rows, row)
+		end
+		if row then
+			row.count += 1
+			if #row.samples < 2 then
+				local sample = Trace.arguments(...)
+				if row.samples[1] ~= sample then table.insert(row.samples, sample) end
+			end
+		else omitted = true end
+		if events >= MAX_EVENTS then eventLimited = true; stop() end
+	end
+	local function attach(remote: Instance)
+		if not active or watched[remote] or not remote:IsA("RemoteEvent") then return end
+		if excluded and (remote == excluded or remote:IsDescendantOf(excluded)) then return end
+		-- Ignore all temporary bridge traffic, including overlapping MCP calls.
+		local ancestor: Instance? = remote.Parent
+		while ancestor and ancestor ~= game do
+			if ancestor:GetAttribute("MCPClientRelay") == true then return end
+			ancestor = ancestor.Parent
+		end
+		if remotes >= MAX_REMOTES then scanLimited = true; return end
+		watched[remote] = true
+		remotes += 1
+		if client then
+			table.insert(connections, (remote :: RemoteEvent).OnClientEvent:Connect(function(...) record(remote, ...) end))
+		else
+			table.insert(connections, (remote :: RemoteEvent).OnServerEvent:Connect(function(from, ...)
+				if from == player then record(remote, ...) end
+			end))
+		end
+	end
+	local ok, failure = pcall(function()
+		-- Subscribe first, then scan so remotes created during discovery are not missed.
+		table.insert(connections, root.DescendantAdded:Connect(function(object)
+			if visits >= MAX_VISITS then scanLimited = true; return end
+			visits += 1
+			local attached = pcall(attach, object)
+			if not attached then skipped += 1 end
+		end))
+		local pending = { root }
+		while #pending > 0 and visits < MAX_VISITS do
+			local object = table.remove(pending) :: Instance
+			visits += 1
+			attach(object)
+			local readable, children = pcall(object.GetChildren, object)
+			if not readable then skipped += 1; continue end
+			for _, child in children do
+				if visits + #pending >= MAX_VISITS then scanLimited = true; break end
+				table.insert(pending, child)
+			end
+		end
+		if #pending > 0 then scanLimited = true end
+		timer = task.delay(seconds, function() timer = nil; stop() end)
+	end)
+	if not ok then stop(); error(failure, 0) end
+	return stop
+end
+return Trace