@el4cteo/rbx-studio-mcp 0.7.2 → 0.7.6

package/package.json

@@ -1,75 +1,75 @@
-{
-  "name": "@el4cteo/rbx-studio-mcp",
-  "version": "0.7.2",
-  "description": "MCP server for Roblox Studio. 35 tools, push-based SSE bridge, editor-safe script edits, one-step undo.",
-  "type": "module",
-  "license": "MIT",
-  "bin": {
-    "rbx-studio-mcp": "dist/index.js"
-  },
-  "files": [
-    "dist",
-    "plugin",
-    "scripts",
-    "config/dsh.cordis.yml",
-    "README.md",
-    "LICENSE"
-  ],
-  "dsh": {
-    "bundle": {
-      "patch": "./config/dsh.cordis.yml"
-    }
-  },
-  "engines": {
-    "node": ">=22.15"
-  },
-  "scripts": {
-    "build": "tsc",
-    "watch": "tsc --watch",
-    "typecheck": "tsc --noEmit",
-    "start": "node dist/index.js",
-    "build:plugin": "node scripts/check-plugin.mjs && node scripts/build-plugin.mjs",
-    "sourcemap": "node scripts/sourcemap.mjs",
-    "test:live": "node scripts/test-live.mjs",
-    "test": "node scripts/test-plugin.mjs && node scripts/test-transport.mjs && node scripts/test-server.mjs && node scripts/test-bridge.mjs && node scripts/test-console.mjs && node scripts/test-failover.mjs && node scripts/test-tools.mjs",
-    "build:all": "npm run build && npm run build:plugin",
-    "install:plugin": "node scripts/install-plugin.mjs",
-    "check:plugin": "node scripts/check-plugin.mjs",
-    "doctor": "node dist/index.js doctor",
-    "prepack": "npm run build"
-  },
-  "keywords": [
-    "mcp",
-    "mcp-server",
-    "model-context-protocol",
-    "roblox",
-    "roblox-studio",
-    "roblox-development",
-    "luau",
-    "claude",
-    "claude-code",
-    "cursor",
-    "ai",
-    "ai-agent"
-  ],
-  "dependencies": {
-    "@modelcontextprotocol/sdk": "^1.30.0",
-    "zod": "^4.6.5"
-  },
-  "devDependencies": {
-    "@types/node": "^26.6.2",
-    "typescript": "^7.0.2"
-  },
-  "author": "EL4CTEO",
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/EL4CTEO/rbx-studio-mcp.git"
-  },
-  "homepage": "https://github.com/EL4CTEO/rbx-studio-mcp#readme",
-  "bugs": {
-    "url": "https://github.com/EL4CTEO/rbx-studio-mcp/issues"
-  },
-  "publishConfig": {
-    "access": "public"
-  }
-}
+{
+  "name": "@el4cteo/rbx-studio-mcp",
+  "version": "0.7.6",
+  "description": "MCP server for Roblox Studio. 35 tools, push-based SSE bridge, editor-safe script edits, one-step undo.",
+  "type": "module",
+  "license": "MIT",
+  "bin": {
+    "rbx-studio-mcp": "dist/index.js"
+  },
+  "files": [
+    "dist",
+    "plugin",
+    "scripts",
+    "config/dsh.cordis.yml",
+    "README.md",
+    "LICENSE"
+  ],
+  "dsh": {
+    "bundle": {
+      "patch": "./config/dsh.cordis.yml"
+    }
+  },
+  "engines": {
+    "node": ">=22.15"
+  },
+  "scripts": {
+    "build": "tsc",
+    "watch": "tsc --watch",
+    "typecheck": "tsc --noEmit",
+    "start": "node dist/index.js",
+    "build:plugin": "node scripts/check-plugin.mjs && node scripts/build-plugin.mjs",
+    "sourcemap": "node scripts/sourcemap.mjs",
+    "test:live": "node scripts/test-live.mjs",
+    "test": "node scripts/test-plugin.mjs && node scripts/test-transport.mjs && node scripts/test-server.mjs && node scripts/test-bridge.mjs && node scripts/test-console.mjs && node scripts/test-failover.mjs && node scripts/test-tools.mjs",
+    "build:all": "npm run build && npm run build:plugin",
+    "install:plugin": "node scripts/install-plugin.mjs",
+    "check:plugin": "node scripts/check-plugin.mjs",
+    "doctor": "node dist/index.js doctor",
+    "prepack": "npm run build"
+  },
+  "keywords": [
+    "mcp",
+    "mcp-server",
+    "model-context-protocol",
+    "roblox",
+    "roblox-studio",
+    "roblox-development",
+    "luau",
+    "claude",
+    "claude-code",
+    "cursor",
+    "ai",
+    "ai-agent"
+  ],
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.30.0",
+    "zod": "^4.6.5"
+  },
+  "devDependencies": {
+    "@types/node": "^26.6.2",
+    "typescript": "^7.0.2"
+  },
+  "author": "EL4CTEO",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/EL4CTEO/rbx-studio-mcp.git"
+  },
+  "homepage": "https://github.com/EL4CTEO/rbx-studio-mcp#readme",
+  "bugs": {
+    "url": "https://github.com/EL4CTEO/rbx-studio-mcp/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

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

@@ -1,65 +1,65 @@
---!strict
---[[
-	Connection settings for the Studio MCP plugin.
-
-	The port must match the one the Node server was started with (`--port`, or
-	the ROBLOX_STUDIO_MCP_PORT environment variable). It is stored as a plugin
-	setting so a user running on a non-default port only has to set it once.
-]]
-
-local Config = {}
-
-Config.PLUGIN_VERSION = "0.7.2"
-
--- 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
--- plugin left running from an older build is reported rather than silently
--- answering with stale handlers. Stays "dev" when the tree is loaded unbuilt.
-Config.BUILD_ID = "dev"
-Config.PROTOCOL_VERSION = 1
-Config.DEFAULT_PORT = 44755
-
--- Header the bridge requires on every request. A web page cannot set it
--- cross-origin without a preflight the bridge never answers, which is what
--- keeps a malicious site from driving Studio through the loopback port.
-Config.CLIENT_HEADER = "x-roblox-studio-mcp"
-
--- How long to wait before retrying after the stream drops. Studio closes SSE
--- connections at the 30 minute mark, so reconnects are routine, not exceptional.
-Config.RECONNECT_DELAY = 1
-Config.MAX_RECONNECT_DELAY = 30
-
--- How long a connection has to last before it counts as having worked, rather
--- than as one more failure to back off from. Comfortably longer than a failed
--- handshake against a dead port, which resolves in milliseconds, and far shorter
--- than any connection that carried a single command.
-Config.HEALTHY_CONNECTION = 10
-
--- How long a healthy long-poll session runs before standing aside so streaming
--- can be tried again. Long enough that a Studio which genuinely cannot stream
--- is not reconnecting constantly, short enough that a session downgraded by one
--- unlucky attempt does not spend the rest of its life slower than it should be.
-Config.RESTREAM_INTERVAL = 60
-
-local port: number? = nil
-
-function Config.setPort(value: number)
-	port = value
-end
-
-function Config.getPort(): number
-	return port or Config.DEFAULT_PORT
-end
-
-function Config.baseUrl(): string
-	return string.format("http://127.0.0.1:%d", Config.getPort())
-end
-
-function Config.headers(): { [string]: string }
-	return {
-		[Config.CLIENT_HEADER] = tostring(Config.PROTOCOL_VERSION),
-		["Content-Type"] = "application/json",
-	}
-end
-
-return Config
+--!strict
+--[[
+	Connection settings for the Studio MCP plugin.
+
+	The port must match the one the Node server was started with (`--port`, or
+	the ROBLOX_STUDIO_MCP_PORT environment variable). It is stored as a plugin
+	setting so a user running on a non-default port only has to set it once.
+]]
+
+local Config = {}
+
+Config.PLUGIN_VERSION = "0.7.6"
+
+-- 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
+-- plugin left running from an older build is reported rather than silently
+-- answering with stale handlers. Stays "dev" when the tree is loaded unbuilt.
+Config.BUILD_ID = "dev"
+Config.PROTOCOL_VERSION = 1
+Config.DEFAULT_PORT = 44755
+
+-- Header the bridge requires on every request. A web page cannot set it
+-- cross-origin without a preflight the bridge never answers, which is what
+-- keeps a malicious site from driving Studio through the loopback port.
+Config.CLIENT_HEADER = "x-roblox-studio-mcp"
+
+-- How long to wait before retrying after the stream drops. Studio closes SSE
+-- connections at the 30 minute mark, so reconnects are routine, not exceptional.
+Config.RECONNECT_DELAY = 1
+Config.MAX_RECONNECT_DELAY = 30
+
+-- How long a connection has to last before it counts as having worked, rather
+-- than as one more failure to back off from. Comfortably longer than a failed
+-- handshake against a dead port, which resolves in milliseconds, and far shorter
+-- than any connection that carried a single command.
+Config.HEALTHY_CONNECTION = 10
+
+-- How long a healthy long-poll session runs before standing aside so streaming
+-- can be tried again. Long enough that a Studio which genuinely cannot stream
+-- is not reconnecting constantly, short enough that a session downgraded by one
+-- unlucky attempt does not spend the rest of its life slower than it should be.
+Config.RESTREAM_INTERVAL = 60
+
+local port: number? = nil
+
+function Config.setPort(value: number)
+	port = value
+end
+
+function Config.getPort(): number
+	return port or Config.DEFAULT_PORT
+end
+
+function Config.baseUrl(): string
+	return string.format("http://127.0.0.1:%d", Config.getPort())
+end
+
+function Config.headers(): { [string]: string }
+	return {
+		[Config.CLIENT_HEADER] = tostring(Config.PROTOCOL_VERSION),
+		["Content-Type"] = "application/json",
+	}
+end
+
+return Config

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,