@chrrxs/robloxstudio-mcp 2.12.0 → 2.14.0

package/studio-plugin/MCPPlugin.rbxmx

@@ -12,6 +12,11 @@ local Communication = TS.import(script, script, "modules", "Communication")
 local ClientBroker = TS.import(script, script, "modules", "ClientBroker")
 local RuntimeLogBuffer = TS.import(script, script, "modules", "RuntimeLogBuffer")
 local StopPlayMonitor = TS.import(script, script, "modules", "StopPlayMonitor")
+local RenderMonitor = TS.import(script, script, "modules", "RenderMonitor")
+-- Track render-loop liveness so input/screenshot tools can report "window
+-- minimized / not rendering" instead of silently no-op'ing. No-op in the
+-- server DM (RenderStepped can't connect there).
+RenderMonitor.start()
 -- Attach the per-peer LogService.MessageOut listener as early as possible so
 -- boot-time prints from the user's place scripts are captured. Powers the
 -- get_runtime_logs MCP tool. Idempotent; safe to call before UI.init().
@@ -97,7 +102,10 @@ local RunService = _services.RunService
 local ServerStorage = _services.ServerStorage
 local RuntimeLogBuffer = TS.import(script, script.Parent, "RuntimeLogBuffer")
 local MemoryHandlers = TS.import(script, script.Parent, "handlers", "MemoryHandlers")
+local CaptureHandlers = TS.import(script, script.Parent, "handlers", "CaptureHandlers")
+local InputHandlers = TS.import(script, script.Parent, "handlers", "InputHandlers")
 local LuauExec = TS.import(script, script.Parent, "LuauExec")
+local StudioTestService = game:GetService("StudioTestService")
 -- Mirror of Communication.computeInstanceId() — duplicated here because the
 -- client broker runs in the play-server DM where it can't easily import from
 -- the edit-side module, and the place identifier must match what the edit-DM
@@ -151,6 +159,7 @@ end
 -- signaling, which works regardless of MCP server state.)
 local MCP_URL = "http://localhost:58741"
 local BROKER_NAME = "__MCPClientBroker"
+local BROKER_OWNER_ATTRIBUTE = "__MCPBrokerOwner"
 -- Endpoints the server-peer broker is allowed to forward to the client peer.
 -- Each requires the client peer's plugin VM (because the buffer / require
 -- cache / etc. lives there) so the server peer alone can't satisfy them.
@@ -158,6 +167,11 @@ local CLIENT_BROKER_ALLOWED_ENDPOINTS = {
 	["/api/execute-luau"] = true,
 	["/api/get-runtime-logs"] = true,
 	["/api/get-memory-breakdown"] = true,
+	["/api/multiplayer-test-state"] = true,
+	["/api/multiplayer-test-leave-client"] = true,
+	["/api/capture-begin"] = true,
+	["/api/simulate-mouse-input"] = true,
+	["/api/simulate-keyboard-input"] = true,
 }
 -- Throttle re-ready calls per proxyId so a brief window of unknownInstance
 -- polls doesn't cause a re-register stampede.
@@ -236,6 +250,77 @@ local function handleGetRuntimeLogs(data)
 		filter = filter,
 	}, "client")
 end
+local function handleMultiplayerTestState()
+	local argsOk, args = pcall(function()
+		return StudioTestService:GetTestArgs()
+	end)
+	local canLeaveOk, canLeave = pcall(function()
+		return StudioTestService:CanLeaveTest()
+	end)
+	local _exp = Players:GetPlayers()
+	-- ▼ ReadonlyArray.map ▼
+	local _newValue = table.create(#_exp)
+	local _callback = function(player)
+		return {
+			name = player.Name,
+			userId = player.UserId,
+			displayName = player.DisplayName,
+		}
+	end
+	for _k, _v in _exp do
+		_newValue[_k] = _callback(_v, _k - 1, _exp)
+	end
+	-- ▲ ReadonlyArray.map ▲
+	local players = _newValue
+	table.sort(players, function(a, b)
+		return a.name < b.name
+	end)
+	return {
+		success = true,
+		peer = "client",
+		isRunning = RunService:IsRunning(),
+		isRunMode = RunService:IsRunMode(),
+		editModeActive = StudioTestService.EditModeActive,
+		testArgsOk = argsOk,
+		testArgs = if argsOk then args else nil,
+		testArgsError = if argsOk then nil else tostring(args),
+		players = players,
+		playerCount = #players,
+		localPlayer = if Players.LocalPlayer then Players.LocalPlayer.Name else nil,
+		canLeaveOk = canLeaveOk,
+		canLeave = if canLeaveOk then canLeave else false,
+		canLeaveError = if canLeaveOk then nil else tostring(canLeave),
+	}
+end
+local function handleMultiplayerTestLeaveClient()
+	local canLeaveOk, canLeave = pcall(function()
+		return StudioTestService:CanLeaveTest()
+	end)
+	if not canLeaveOk then
+		return {
+			error = tostring(canLeave),
+			canLeaveOk = false,
+		}
+	end
+	if not canLeave then
+		return {
+			error = "This client cannot leave the current test session.",
+			canLeaveOk = true,
+			canLeave = false,
+		}
+	end
+	local localPlayer = if Players.LocalPlayer then Players.LocalPlayer.Name else nil
+	task.defer(function()
+		pcall(function()
+			return StudioTestService:LeaveTest()
+		end)
+	end)
+	return {
+		success = true,
+		message = "Client leave requested.",
+		localPlayer = localPlayer,
+	}
+end
 local function setupClientBroker()
 	local rf = ReplicatedStorage:WaitForChild(BROKER_NAME, 10)
 	if not rf or not rf:IsA("RemoteFunction") then
@@ -255,6 +340,21 @@ local function setupClientBroker()
 		if payload and payload.endpoint == "/api/get-memory-breakdown" then
 			return MemoryHandlers.getMemoryBreakdown(payload.data or {})
 		end
+		if payload and payload.endpoint == "/api/multiplayer-test-state" then
+			return handleMultiplayerTestState()
+		end
+		if payload and payload.endpoint == "/api/multiplayer-test-leave-client" then
+			return handleMultiplayerTestLeaveClient()
+		end
+		if payload and payload.endpoint == "/api/capture-begin" then
+			return CaptureHandlers.captureBegin()
+		end
+		if payload and payload.endpoint == "/api/simulate-mouse-input" then
+			return InputHandlers.simulateMouseInput(payload.data or {})
+		end
+		if payload and payload.endpoint == "/api/simulate-keyboard-input" then
+			return InputHandlers.simulateKeyboardInput(payload.data or {})
+		end
 		if payload and payload.endpoint == "/api/execute-luau" then
 			return handleExecuteLuau(payload.data)
 		end
@@ -263,6 +363,7 @@ local function setupClientBroker()
 	end
 end
 local proxyByPlayer = {}
+local serverBrokerStarted = false
 local function pollProxy(proxyId, player, rf)
 	while true do
 		local _condition = player.Parent ~= nil
@@ -318,8 +419,12 @@ local function pollProxy(proxyId, player, rf)
 							}
 						end
 					else
+						local allowed = {}
+						for ep in CLIENT_BROKER_ALLOWED_ENDPOINTS do
+							table.insert(allowed, ep)
+						end
 						response = {
-							error = `Client-proxy does not forward {tostring(request.endpoint)}. ` .. `Allowed: /api/execute-luau, /api/get-runtime-logs.`,
+							error = `Client-proxy does not forward {tostring(request.endpoint)}. ` .. `Allowed: {table.concat(allowed, ", ")}.`,
 						}
 					end
 					postJson("/response", {
@@ -370,12 +475,20 @@ end
 -- plugin:SetSetting flag consumed by StopPlayMonitor in the play-server DM,
 -- which doesn't depend on MCP server state or peer registration at all.)
 local function setupServerBroker()
+	if serverBrokerStarted then
+		return nil
+	end
 	local rf = ReplicatedStorage:FindFirstChild(BROKER_NAME)
 	if not rf then
 		rf = Instance.new("RemoteFunction")
 		rf.Name = BROKER_NAME
 		rf.Parent = ReplicatedStorage
 	end
+	if rf:GetAttribute(BROKER_OWNER_ATTRIBUTE) ~= nil then
+		return nil
+	end
+	rf:SetAttribute(BROKER_OWNER_ATTRIBUTE, HttpService:GenerateGUID(false))
+	serverBrokerStarted = true
 	local broker = rf
 	Players.PlayerAdded:Connect(function(p)
 		return registerProxy(p, broker)
@@ -424,6 +537,7 @@ local ServerStorage = _services.ServerStorage
 local State = TS.import(script, script.Parent, "State")
 local Utils = TS.import(script, script.Parent, "Utils")
 local UI = TS.import(script, script.Parent, "UI")
+local ensureBridgesInstalled = TS.import(script, script.Parent, "EvalBridges").ensureBridgesInstalled
 local QueryHandlers = TS.import(script, script.Parent, "handlers", "QueryHandlers")
 local PropertyHandlers = TS.import(script, script.Parent, "handlers", "PropertyHandlers")
 local InstanceHandlers = TS.import(script, script.Parent, "handlers", "InstanceHandlers")
@@ -547,6 +661,11 @@ local routeMap = {
 	["/api/start-playtest"] = TestHandlers.startPlaytest,
 	["/api/stop-playtest"] = TestHandlers.stopPlaytest,
 	["/api/get-playtest-output"] = TestHandlers.getPlaytestOutput,
+	["/api/multiplayer-test-start"] = TestHandlers.multiplayerTestStart,
+	["/api/multiplayer-test-state"] = TestHandlers.multiplayerTestState,
+	["/api/multiplayer-test-add-players"] = TestHandlers.multiplayerTestAddPlayers,
+	["/api/multiplayer-test-leave-client"] = TestHandlers.multiplayerTestLeaveClient,
+	["/api/multiplayer-test-end"] = TestHandlers.multiplayerTestEnd,
 	["/api/character-navigation"] = TestHandlers.characterNavigation,
 	["/api/export-build"] = BuildHandlers.exportBuild,
 	["/api/import-build"] = BuildHandlers.importBuild,
@@ -555,6 +674,8 @@ local routeMap = {
 	["/api/insert-asset"] = AssetHandlers.insertAsset,
 	["/api/preview-asset"] = AssetHandlers.previewAsset,
 	["/api/capture-screenshot"] = CaptureHandlers.captureScreenshot,
+	["/api/capture-begin"] = CaptureHandlers.captureBegin,
+	["/api/capture-read"] = CaptureHandlers.captureRead,
 	["/api/simulate-mouse-input"] = InputHandlers.simulateMouseInput,
 	["/api/simulate-keyboard-input"] = InputHandlers.simulateKeyboardInput,
 	["/api/find-and-replace-in-scripts"] = ScriptHandlers.findAndReplaceInScripts,
@@ -895,6 +1016,19 @@ local function activatePlugin(connIndex)
 	-- Initial /ready; pollForRequests will also re-fire ready if the server
 	-- later reports knownInstance=false (process restart, etc).
 	sendReady(conn)
+	-- Keep the eval bridges present in the edit DM so that ANY playtest —
+	-- including one the dev starts manually via the Studio Play button —
+	-- clones them into the play DMs and eval_*_runtime works with no setup
+	-- roundtrip. Only the edit DM installs; play DMs already have the cloned
+	-- copies. Idempotent, so reconnects don't re-dirty the place.
+	if not RunService:IsRunning() then
+		task.spawn(function()
+			local result = ensureBridgesInstalled()
+			if not result.installed then
+				warn(`[MCPPlugin] Eval bridge install failed: {result.error}`)
+			end
+		end)
+	end
 	-- Watch for game.Name updates so a stale "Place1" captured at first
 	-- /ready gets refreshed once Studio settles on the real DM name.
 	ensureNameChangeWatcher(conn)
@@ -1016,11 +1150,16 @@ local TS = require(script.Parent.Parent.include.RuntimeLib)
 -- ServerScriptService.LoadStringEnabled, so eval_server_runtime works even
 -- when LoadStringEnabled=false (the default in fresh places).
 --
--- Lifecycle: TestHandlers.startPlaytest inserts both scripts into the EDIT
--- DM right before ExecutePlayModeAsync. ExecutePlayModeAsync clones the
--- DataModel into the play DMs, so the scripts come along and run there.
--- TestHandlers cleans them up from the edit DM when ExecutePlayModeAsync
--- returns (test ended for any reason: stop_playtest, manual close, EndTest).
+-- Lifecycle: the bridges live PERMANENTLY in the edit DM. Communication
+-- installs them (ensureBridgesInstalled) when the plugin connects in edit,
+-- and TestHandlers.startPlaytest force-refreshes them right before
+-- ExecutePlayModeAsync. ExecutePlayModeAsync clones the DataModel into the
+-- play DMs, so the scripts come along and run there. We keep them in the edit
+-- DM after a playtest ends (rather than cleaning up) so that a playtest the
+-- dev starts MANUALLY via the Studio Play button — not the MCP start_playtest
+-- tool — also gets the bridges cloned in. This is intentionally a little
+-- intrusive (two helper scripts visible in Explorer) in exchange for a
+-- zero-roundtrip eval_*_runtime experience for devs working 1:1 with an agent.
 --
 -- Archivable handling: ExecutePlayModeAsync's deep-clone SKIPS instances
 -- with Archivable=false (verified empirically in v2.9.0 testing - bridges
@@ -1052,9 +1191,9 @@ local BRIDGE_NAMES = {
 -- Embedded Luau. The double `${...}` references our exported names so a
 -- rename here propagates to both the script source and the tool wrappers.
 local SERVER_BRIDGE_SOURCE = `\
--- Auto-installed by @chrrxs/robloxstudio-mcp at start_playtest, removed at\
--- stop_playtest. Provides shared-require-cache eval on the server peer for\
--- the eval_server_runtime MCP tool.\
+-- Installed by @chrrxs/robloxstudio-mcp to power the eval_server_runtime MCP\
+-- tool (shared-require-cache eval on the server during playtests). Inert\
+-- outside Studio (no-ops in live games); safe to leave in place.\
 \
 local ServerScriptService = game:GetService("ServerScriptService")\
 local RunService = game:GetService("RunService")\
@@ -1078,9 +1217,9 @@ bf.OnInvoke = function(payload)\
 end\
 `
 local CLIENT_BRIDGE_SOURCE = `\
--- Auto-installed by @chrrxs/robloxstudio-mcp at start_playtest, removed at\
--- stop_playtest. Provides shared-require-cache eval on the client peer for\
--- the eval_client_runtime MCP tool.\
+-- Installed by @chrrxs/robloxstudio-mcp to power the eval_client_runtime MCP\
+-- tool (shared-require-cache eval on the client during playtests). Inert\
+-- outside Studio (no-ops in live games); safe to leave in place.\
 \
 local ReplicatedStorage = game:GetService("ReplicatedStorage")\
 local RunService = game:GetService("RunService")\
@@ -1103,6 +1242,25 @@ bf.OnInvoke = function(payload)\
 	return pcall(require, payload)\
 end\
 `
+-- Stamp written onto each installed bridge Script so we can tell whether the
+-- bridge currently in the DM was produced by THIS plugin build. It's a djb2
+-- hash of the actual bridge source plus the plugin version, so ANY change to
+-- the source (or a version bump) yields a new stamp — which makes
+-- ensureBridgesInstalled() force a refresh on the next plugin load instead of
+-- keeping a stale bridge that happens to still be present (e.g. one saved into
+-- the .rbxl from an older build).
+local STAMP_ATTR = "__MCPBridgeStamp"
+local function computeBridgeStamp()
+	local combined = `{SERVER_BRIDGE_SOURCE}|{CLIENT_BRIDGE_SOURCE}`
+	local h = 5381
+	for i = 1, #combined do
+		h = (h * 33 + (string.byte(combined, i))) % 2147483647
+	end
+	-- "2.14.0" is replaced with the package version at package time
+	-- (scripts/build-plugin.mjs injectVersion), so a release bump also restamps.
+	return `{tostring(h)}-2.14.0`
+end
+local BRIDGE_STAMP = computeBridgeStamp()
 local function setSource(scriptInst, source)
 	-- ScriptEditorService is the cleaner API and integrates with Studio's
 	-- edit history; fall back to direct Source mutation (allowed in plugin
@@ -1138,7 +1296,31 @@ local function cleanupBridges()
 		end)
 	end
 end
-local function installBridges()
+-- Idempotent variant: install only if the bridge scripts aren't already
+-- present in the edit DM. Used to keep the bridges always available (so a
+-- playtest the dev starts manually — not via the MCP start_playtest tool —
+-- still clones them into the play DMs). Cheap no-op when already installed,
+-- which avoids re-dirtying the place on every plugin reconnect.
+local installBridges
+local function ensureBridgesInstalled()
+	local _binding = findBridges()
+	local server = _binding.server
+	local client = _binding.client
+	if server and client then
+		-- Both present — but only skip the reinstall if they were produced by
+		-- THIS build. A mismatched/absent stamp means a stale bridge (older
+		-- plugin, or one persisted in the saved place), so force a refresh.
+		local sStamp = server:GetAttribute(STAMP_ATTR)
+		local cStamp = client:GetAttribute(STAMP_ATTR)
+		if sStamp == BRIDGE_STAMP and cStamp == BRIDGE_STAMP then
+			return {
+				installed = true,
+			}
+		end
+	end
+	return installBridges()
+end
+function installBridges()
 	-- Defensive: clear any stale bridges from a prior unclean exit before
 	-- inserting fresh. The injected script also self-cleans its
 	-- ReplicatedStorage/ServerScriptService children at startup, but the
@@ -1151,6 +1333,7 @@ local function installBridges()
 		-- script. cleanupBridges() removes it from the edit DM when the
 		-- playtest ends.
 		setSource(serverScript, SERVER_BRIDGE_SOURCE)
+		serverScript:SetAttribute(STAMP_ATTR, BRIDGE_STAMP)
 		serverScript.Parent = ServerScriptService
 		local sps = getStarterPlayerScripts()
 		if not sps then
@@ -1159,6 +1342,7 @@ local function installBridges()
 		local clientScript = Instance.new("LocalScript")
 		clientScript.Name = CLIENT_SCRIPT_NAME
 		setSource(clientScript, CLIENT_BRIDGE_SOURCE)
+		clientScript:SetAttribute(STAMP_ATTR, BRIDGE_STAMP)
 		clientScript.Parent = sps
 	end)
 	if not ok then
@@ -1173,6 +1357,7 @@ local function installBridges()
 end
 return {
 	cleanupBridges = cleanupBridges,
+	ensureBridgesInstalled = ensureBridgesInstalled,
 	installBridges = installBridges,
 	BRIDGE_NAMES = BRIDGE_NAMES,
 }
@@ -2038,6 +2223,8 @@ return {
           <Properties>
             <string name="Name">CaptureHandlers</string>
             <string name="Source"><![CDATA[-- Compiled with roblox-ts v3.0.0
+local TS = require(script.Parent.Parent.Parent.include.RuntimeLib)
+local RenderMonitor = TS.import(script, script.Parent.Parent, "RenderMonitor")
 local CaptureService = game:GetService("CaptureService")
 local AssetService = game:GetService("AssetService")
 local MAX_TILE_SIZE = 1024
@@ -2147,7 +2334,20 @@ local function readPixelsTiled(img, w, h)
 	end
 	return fullBuf
 end
-local function captureScreenshotData()
+-- Triggers CaptureService:CaptureScreenshot and waits for the temporary
+-- content id. Works in any DM, including the play CLIENT (where reading the
+-- pixels back is blocked, but capturing is not). The returned rbxtemp:// id is
+-- a process-scoped handle: it can be dereferenced from a DIFFERENT, more
+-- privileged DM (the edit DM) — see captureRead.
+local function doCaptureScreenshot()
+	-- Fast-fail with a clear reason if the window isn't rendering — otherwise
+	-- CaptureScreenshot's callback never fires and we'd block for the full 10s.
+	local notRendering = RenderMonitor.notRenderingReason()
+	if notRendering ~= nil then
+		return {
+			error = notRendering,
+		}
+	end
 	local contentId
 	CaptureService:CaptureScreenshot(function(id)
 		contentId = id
@@ -2156,11 +2356,21 @@ local function captureScreenshotData()
 	while contentId == nil do
 		if tick() - startTime > 10 then
 			return {
-				error = "Screenshot capture timed out. Ensure the Studio viewport is visible and you are in Edit mode (not Play mode). Known Roblox bug: capture may fail if viewport renders a solid color.",
+				error = "Screenshot capture timed out (CaptureScreenshot callback never fired). The Studio window is likely minimized or occluded — restore it so the viewport renders. (Known Roblox bug: capture can also fail if the viewport renders a solid color.)",
 			}
 		end
 		task.wait(0.1)
 	end
+	return {
+		contentId = contentId,
+	}
+end
+-- Promotes a CaptureScreenshot content id into an EditableImage and reads its
+-- RGBA pixels. MUST run in the edit/plugin context: the running game VM lacks
+-- the privilege to create an EditableImage from a temporary texture id (errors
+-- "cannot currently create editable image from temporary texture id"), while
+-- the edit DM can — even for an id captured in the play client DM.
+local function readContentToBase64(contentId)
 	local editableOk, editableResult = pcall(function()
 		return AssetService:CreateEditableImageAsync(Content.fromUri(contentId))
 	end)
@@ -2190,12 +2400,36 @@ local function captureScreenshotData()
 		data = base64Data,
 	}
 end
+-- Edit-mode single shot: capture and read back in the same (edit) context.
+local function captureScreenshotData()
+	local cap = doCaptureScreenshot()
+	if cap.error ~= nil then
+		return cap
+	end
+	return readContentToBase64(cap.contentId)
+end
 local function captureScreenshot()
 	return captureScreenshotData()
 end
+-- Play-mode step 1 (run on the CLIENT): capture only, return the temp id.
+local function captureBegin()
+	return doCaptureScreenshot()
+end
+-- Play-mode step 2 (run on EDIT): read pixels from a temp id captured elsewhere.
+local function captureRead(requestData)
+	local contentId = requestData.contentId
+	if not (contentId ~= "" and contentId) then
+		return {
+			error = "contentId is required",
+		}
+	end
+	return readContentToBase64(contentId)
+end
 return {
 	captureScreenshotData = captureScreenshotData,
 	captureScreenshot = captureScreenshot,
+	captureBegin = captureBegin,
+	captureRead = captureRead,
 }
 ]]></string>
           </Properties>
@@ -2204,19 +2438,56 @@ return {
           <Properties>
             <string name="Name">InputHandlers</string>
             <string name="Source"><![CDATA[-- Compiled with roblox-ts v3.0.0
-local function getVIM()
-	local ok, result = pcall(function()
-		return game:GetService("VirtualInputManager")
+local TS = require(script.Parent.Parent.Parent.include.RuntimeLib)
+-- Virtual input via UserInputService:CreateVirtualInput().
+--
+-- We deliberately do NOT use VirtualInputManager:Send*Event — those methods
+-- are gated behind RobloxScriptSecurity ("lacking capability RobloxScript")
+-- in every context a plugin can reach (edit DM, play server/client DMs), so
+-- they silently never worked. CreateVirtualInput() is callable without that
+-- capability and drives the REAL input pipeline: SendKey feeds
+-- UserInputService.InputBegan/Ended and the control modules (so WASD walks the
+-- character at full WalkSpeed with controls intact, no Humanoid hijack),
+-- SendMouseButton feeds UIS and activates GUI buttons (and hit-tests against
+-- CoreGui), and SendTextInput types into the focused TextBox.
+--
+-- Method set on the VirtualInput object (verified live):
+--   SendKey(isDown: boolean, keyCode: Enum.KeyCode)
+--   SendMouseButton(position: Vector2, inputType: Enum.UserInputType, isDown: boolean)
+--   SendTextInput(text: string)
+-- There is NO SendMouseMove / SendMouseWheel / SendKeyEvent — so "move" and
+-- "scroll" mouse actions are not supported.
+--
+-- Coordinate space: SendMouseButton coordinates are viewport pixels matching
+-- what capture_screenshot returns (window space, origin at the top-left of the
+-- rendered viewport). Pass screenshot pixel coordinates straight through. Note
+-- that UserInputService reports input positions in GUI space, which is offset
+-- from this by GuiService:GetGuiInset() (~58px on the Y axis) — irrelevant for
+-- callers who pick coordinates off a screenshot, which is why we do not
+-- translate here.
+local RenderMonitor = TS.import(script, script.Parent.Parent, "RenderMonitor")
+local UserInputService = game:GetService("UserInputService")
+-- One VirtualInput per plugin VM, reused across calls so that a key held down
+-- in one call (action="press") and released in a later call (action="release")
+-- share the same input source.
+local cachedVI
+local function getVI()
+	if cachedVI then
+		return cachedVI
+	end
+	local ok, vi = pcall(function()
+		return UserInputService:CreateVirtualInput()
 	end)
-	if ok and result then
-		return result
+	if ok and vi ~= nil then
+		cachedVI = vi
+		return cachedVI
 	end
 	return nil
 end
-local BUTTON_MAP = {
-	Left = 0,
-	Right = 1,
-	Middle = 2,
+local MOUSE_TYPE_MAP = {
+	Left = Enum.UserInputType.MouseButton1,
+	Right = Enum.UserInputType.MouseButton2,
+	Middle = Enum.UserInputType.MouseButton3,
 }
 local function simulateMouseInput(requestData)
 	local action = requestData.action
@@ -2227,56 +2498,43 @@ local function simulateMouseInput(requestData)
 		_condition = "Left"
 	end
 	local button = _condition
-	local scrollDirection = requestData.scrollDirection
 	if not (action ~= "" and action) then
 		return {
 			error = "action is required",
 		}
 	end
-	local vim = getVIM()
-	if not vim then
+	if x == nil or y == nil then
 		return {
-			error = "VirtualInputManager is not available in this context",
+			error = "x and y are required",
 		}
 	end
-	local _condition_1 = BUTTON_MAP[button]
-	if _condition_1 == nil then
-		_condition_1 = 0
+	-- Input is silently dropped by the engine when the window isn't rendering
+	-- (e.g. minimized). Surface that instead of returning a false success.
+	local notRendering = RenderMonitor.notRenderingReason()
+	if notRendering ~= nil then
+		return {
+			error = notRendering,
+		}
+	end
+	local vi = getVI()
+	if not vi then
+		return {
+			error = "UserInputService:CreateVirtualInput() is not available in this context",
+		}
 	end
-	local buttonNum = _condition_1
+	local inputType = MOUSE_TYPE_MAP[button] or Enum.UserInputType.MouseButton1
+	local pos = Vector2.new(x, y)
 	local success, err = pcall(function()
 		if action == "click" then
-			if x == nil or y == nil then
-				error("x and y are required for click")
-			end
-			vim:SendMouseButtonEvent(x, y, buttonNum, true)
+			vi:SendMouseButton(pos, inputType, true)
 			task.wait(0.05)
-			vim:SendMouseButtonEvent(x, y, buttonNum, false)
+			vi:SendMouseButton(pos, inputType, false)
 		elseif action == "mouseDown" then
-			if x == nil or y == nil then
-				error("x and y are required for mouseDown")
-			end
-			vim:SendMouseButtonEvent(x, y, buttonNum, true)
+			vi:SendMouseButton(pos, inputType, true)
 		elseif action == "mouseUp" then
-			if x == nil or y == nil then
-				error("x and y are required for mouseUp")
-			end
-			vim:SendMouseButtonEvent(x, y, buttonNum, false)
-		elseif action == "move" then
-			if x == nil or y == nil then
-				error("x and y are required for move")
-			end
-			vim:SendMouseMoveEvent(x, y)
-		elseif action == "scroll" then
-			if x == nil or y == nil then
-				error("x and y are required for scroll")
-			end
-			if not (scrollDirection ~= "" and scrollDirection) then
-				error("scrollDirection is required for scroll")
-			end
-			vim:SendMouseWheelEvent(x, y, scrollDirection == "up")
+			vi:SendMouseButton(pos, inputType, false)
 		else
-			error(`Unknown action: {action}`)
+			error(`Unsupported action "{action}". CreateVirtualInput supports click, mouseDown, mouseUp ` .. `(no move/scroll — those methods don't exist on VirtualInput).`)
 		end
 	end)
 	if success then
@@ -2293,7 +2551,40 @@ local function simulateMouseInput(requestData)
 	}
 end
 local function simulateKeyboardInput(requestData)
+	local notRendering = RenderMonitor.notRenderingReason()
+	if notRendering ~= nil then
+		return {
+			error = notRendering,
+		}
+	end
+	local vi = getVI()
+	if not vi then
+		return {
+			error = "UserInputService:CreateVirtualInput() is not available in this context",
+		}
+	end
+	-- Text mode: type a string into the focused TextBox.
+	local text = requestData.text
+	if text ~= nil then
+		local ok, err = pcall(function()
+			return vi:SendTextInput(text)
+		end)
+		if ok then
+			return {
+				success = true,
+				text = text,
+			}
+		end
+		return {
+			error = `Failed to send text input: {err}`,
+		}
+	end
 	local keyCodeName = requestData.keyCode
+	if not (keyCodeName ~= "" and keyCodeName) then
+		return {
+			error = "keyCode (or text) is required",
+		}
+	end
 	local _condition = (requestData.action)
 	if _condition == nil then
 		_condition = "tap"
@@ -2304,17 +2595,6 @@ local function simulateKeyboardInput(requestData)
 		_condition_1 = 0.1
 	end
 	local duration = _condition_1
-	if not (keyCodeName ~= "" and keyCodeName) then
-		return {
-			error = "keyCode is required",
-		}
-	end
-	local vim = getVIM()
-	if not vim then
-		return {
-			error = "VirtualInputManager is not available in this context",
-		}
-	end
 	local enumOk, keyCode = pcall(function()
 		return (Enum.KeyCode)[keyCodeName]
 	end)
@@ -2325,13 +2605,13 @@ local function simulateKeyboardInput(requestData)
 	end
 	local success, err = pcall(function()
 		if action == "press" then
-			vim:SendKeyEvent(true, keyCode, false)
+			vi:SendKey(true, keyCode)
 		elseif action == "release" then
-			vim:SendKeyEvent(false, keyCode, false)
+			vi:SendKey(false, keyCode)
 		elseif action == "tap" then
-			vim:SendKeyEvent(true, keyCode, false)
+			vi:SendKey(true, keyCode)
 			task.wait(duration)
-			vim:SendKeyEvent(false, keyCode, false)
+			vi:SendKey(false, keyCode)
 		else
 			error(`Unknown action: {action}`)
 		end
@@ -5679,10 +5959,11 @@ local TS = require(script.Parent.Parent.Parent.include.RuntimeLib)
 local _services = TS.import(script, script.Parent.Parent.Parent, "node_modules", "@rbxts", "services")
 local HttpService = _services.HttpService
 local LogService = _services.LogService
+local Players = _services.Players
 local RunService = _services.RunService
 local _EvalBridges = TS.import(script, script.Parent.Parent, "EvalBridges")
 local installBridges = _EvalBridges.installBridges
-local cleanupBridges = _EvalBridges.cleanupBridges
+local ensureBridgesInstalled = _EvalBridges.ensureBridgesInstalled
 local StopPlayMonitor = TS.import(script, script.Parent.Parent, "StopPlayMonitor")
 local StudioTestService = game:GetService("StudioTestService")
 local ServerScriptService = game:GetService("ServerScriptService")
@@ -5700,6 +5981,63 @@ local testResult
 local testError
 local stopListenerScript
 local navResultCallback
+local multiplayerState = {
+	phase = "idle",
+}
+local function detectPeerRole()
+	if not RunService:IsRunning() then
+		return "edit"
+	end
+	if RunService:IsServer() then
+		return "server"
+	end
+	return "client"
+end
+local function getPlayersSnapshot()
+	local _exp = Players:GetPlayers()
+	-- ▼ ReadonlyArray.map ▼
+	local _newValue = table.create(#_exp)
+	local _callback = function(player)
+		return {
+			name = player.Name,
+			userId = player.UserId,
+			displayName = player.DisplayName,
+		}
+	end
+	for _k, _v in _exp do
+		_newValue[_k] = _callback(_v, _k - 1, _exp)
+	end
+	-- ▲ ReadonlyArray.map ▲
+	local players = _newValue
+	table.sort(players, function(a, b)
+		return a.name < b.name
+	end)
+	return players
+end
+local function cloneMultiplayerState()
+	return {
+		phase = multiplayerState.phase,
+		testId = multiplayerState.testId,
+		numPlayers = multiplayerState.numPlayers,
+		testArgs = multiplayerState.testArgs,
+		startedAt = multiplayerState.startedAt,
+		completedAt = multiplayerState.completedAt,
+		ok = multiplayerState.ok,
+		result = multiplayerState.result,
+		error = multiplayerState.error,
+	}
+end
+local function normalizeNumPlayers(value)
+	local _value = value
+	if not (type(_value) == "number") then
+		return nil
+	end
+	local n = math.floor(value)
+	if n ~= value or n < 1 or n > 8 then
+		return nil
+	end
+	return n
+end
 local function buildCommandListenerSource()
 	return `local LogService = game:GetService("LogService")\
 local PathfindingService = game:GetService("PathfindingService")\
@@ -5796,6 +6134,11 @@ local function startPlaytest(requestData)
 			error = 'mode must be "play" or "run"',
 		}
 	end
+	if numPlayers ~= nil then
+		return {
+			error = "start_playtest is single-player only. Use multiplayer_test_start for multi-client StudioTestService sessions.",
+		}
+	end
 	-- Self-heal: if testRunning is stuck true but Studio reports no active
 	-- playtest, the previous start_playtest's task.spawn was orphaned
 	-- (plugin reload mid-test, Studio entered some inconsistent state, etc).
@@ -5807,7 +6150,9 @@ local function startPlaytest(requestData)
 			logConnection = nil
 		end
 		cleanupStopListener()
-		cleanupBridges()
+		-- Note: eval bridges are intentionally NOT cleaned up — they live
+		-- permanently in the edit DM so manual playtests also get them. See
+		-- EvalBridges.ts lifecycle comment.
 	end
 	if testRunning then
 		return {
@@ -5850,17 +6195,14 @@ local function startPlaytest(requestData)
 	if not injected then
 		warn(`[MCP] Failed to inject stop listener: {injErr}`)
 	end
-	-- Auto-install the game-VM eval bridges (ServerEvalBridge + ClientEvalBridge)
-	-- so eval_server_runtime / eval_client_runtime work without manual setup.
-	-- Bridges are cleaned up from the edit DM after the play DMs tear down.
+	-- Force-refresh the game-VM eval bridges (ServerEvalBridge + ClientEvalBridge)
+	-- right before cloning so the play DMs get the current source. They also
+	-- live permanently in the edit DM (installed on connect) so manually-started
+	-- playtests get them too; here we just ensure they're fresh.
 	local bridgeInstall = installBridges()
 	if not bridgeInstall.installed then
 		warn(`[MCP] Eval bridge install failed: {bridgeInstall.error}`)
 	end
-	if numPlayers ~= nil and mode == "run" then
-		local TestService = game:GetService("TestService")
-		TestService.NumberOfPlayers = math.clamp(numPlayers, 1, 8)
-	end
 	task.spawn(function()
 		local ok, result = pcall(function()
 			if mode == "play" then
@@ -5879,12 +6221,13 @@ local function startPlaytest(requestData)
 		end
 		testRunning = false
 		cleanupStopListener()
-		cleanupBridges()
+		-- Eval bridges persist in the edit DM (see EvalBridges.ts) — do not
+		-- clean up here, so the next manual playtest still gets them.
+		ensureBridgesInstalled()
 	end)
-	local msg = if numPlayers ~= nil then `Playtest started in {mode} mode with {numPlayers} player(s).` else `Playtest started in {mode} mode.`
 	local response = {
 		success = true,
-		message = msg,
+		message = `Playtest started in {mode} mode.`,
 	}
 	-- Only mention eval bridges when they failed — when they're fine, the
 	-- detail is noise. eval_server_runtime / eval_client_runtime will surface
@@ -5967,6 +6310,198 @@ local function getPlaytestOutput(_requestData)
 	_object.testError = testError
 	return _object
 end
+local function multiplayerTestStart(requestData)
+	if RunService:IsRunning() then
+		return {
+			error = "multiplayer_test_start must be called on the edit DataModel. Route with target=edit.",
+		}
+	end
+	local numPlayers = normalizeNumPlayers(requestData.numPlayers)
+	if numPlayers == nil then
+		return {
+			error = "numPlayers must be an integer from 1 to 8",
+		}
+	end
+	if multiplayerState.phase == "starting" or multiplayerState.phase == "running" then
+		return {
+			error = "A multiplayer Studio test is already running",
+			state = cloneMultiplayerState(),
+		}
+	end
+	local testArgs = if requestData.testArgs ~= nil then requestData.testArgs else {}
+	local testId = HttpService:GenerateGUID(false)
+	local bridgeInstall = installBridges()
+	if not bridgeInstall.installed then
+		warn(`[MCP] Eval bridge install failed: {bridgeInstall.error}`)
+	end
+	multiplayerState = {
+		phase = "starting",
+		testId = testId,
+		numPlayers = numPlayers,
+		testArgs = testArgs,
+		startedAt = tick(),
+	}
+	task.spawn(function()
+		multiplayerState.phase = "running"
+		local ok, result = pcall(function()
+			return StudioTestService:ExecuteMultiplayerTestAsync(numPlayers, testArgs)
+		end)
+		multiplayerState.completedAt = tick()
+		multiplayerState.ok = ok
+		if ok then
+			multiplayerState.phase = "completed"
+			multiplayerState.result = result
+			multiplayerState.error = nil
+		else
+			multiplayerState.phase = "failed"
+			multiplayerState.result = nil
+			multiplayerState.error = tostring(result)
+		end
+		ensureBridgesInstalled()
+	end)
+	local response = {
+		success = true,
+		message = `Multiplayer Studio test starting with {numPlayers} player(s).`,
+		testId = testId,
+		phase = multiplayerState.phase,
+		numPlayers = numPlayers,
+		testArgs = testArgs,
+	}
+	if not bridgeInstall.installed then
+		response.evalBridgesError = bridgeInstall.error
+	end
+	return response
+end
+local function multiplayerTestState(_requestData)
+	local peer = detectPeerRole()
+	local response = {
+		success = true,
+		peer = peer,
+		isRunning = RunService:IsRunning(),
+		isRunMode = RunService:IsRunMode(),
+		editModeActive = StudioTestService.EditModeActive,
+	}
+	if peer == "edit" then
+		response.session = cloneMultiplayerState()
+		return response
+	end
+	local argsOk, args = pcall(function()
+		return StudioTestService:GetTestArgs()
+	end)
+	response.testArgsOk = argsOk
+	response.testArgs = if argsOk then args else nil
+	if not argsOk then
+		response.testArgsError = tostring(args)
+	end
+	local players = getPlayersSnapshot()
+	response.players = players
+	response.playerCount = #players
+	if peer == "client" then
+		response.localPlayer = if Players.LocalPlayer then Players.LocalPlayer.Name else nil
+		local canLeaveOk, canLeave = pcall(function()
+			return StudioTestService:CanLeaveTest()
+		end)
+		response.canLeaveOk = canLeaveOk
+		response.canLeave = if canLeaveOk then canLeave else false
+		if not canLeaveOk then
+			response.canLeaveError = tostring(canLeave)
+		end
+	end
+	return response
+end
+local function multiplayerTestAddPlayers(requestData)
+	if not RunService:IsRunning() or not RunService:IsServer() then
+		return {
+			error = "multiplayer_test_add_players must be called on the running server peer. Route with target=server.",
+		}
+	end
+	local numPlayers = normalizeNumPlayers(requestData.numPlayers)
+	if numPlayers == nil then
+		return {
+			error = "numPlayers must be an integer from 1 to 8",
+		}
+	end
+	local before = #Players:GetPlayers()
+	local ok, result = pcall(function()
+		return StudioTestService:AddPlayers(numPlayers)
+	end)
+	if not ok then
+		return {
+			error = tostring(result),
+		}
+	end
+	local _exp = tick()
+	local _condition = (requestData.timeout)
+	if _condition == nil then
+		_condition = 10
+	end
+	local deadline = _exp + _condition
+	while #Players:GetPlayers() < before + numPlayers and tick() < deadline do
+		task.wait(0.1)
+	end
+	local players = getPlayersSnapshot()
+	return {
+		success = true,
+		message = `Requested {numPlayers} additional player(s).`,
+		playerCount = #players,
+		players = players,
+	}
+end
+local function multiplayerTestLeaveClient(_requestData)
+	if not RunService:IsRunning() or RunService:IsServer() then
+		return {
+			error = "multiplayer_test_leave_client must be called on a running client peer. Route with target=client-N.",
+		}
+	end
+	local canLeaveOk, canLeave = pcall(function()
+		return StudioTestService:CanLeaveTest()
+	end)
+	if not canLeaveOk then
+		return {
+			error = tostring(canLeave),
+			canLeaveOk = false,
+		}
+	end
+	if not canLeave then
+		return {
+			error = "This client cannot leave the current test session.",
+			canLeaveOk = true,
+			canLeave = false,
+		}
+	end
+	local localPlayer = if Players.LocalPlayer then Players.LocalPlayer.Name else nil
+	task.defer(function()
+		pcall(function()
+			return StudioTestService:LeaveTest()
+		end)
+	end)
+	return {
+		success = true,
+		message = "Client leave requested.",
+		localPlayer = localPlayer,
+	}
+end
+local function multiplayerTestEnd(requestData)
+	if not RunService:IsRunning() or not RunService:IsServer() then
+		return {
+			error = "multiplayer_test_end must be called on the running server peer. Route with target=server.",
+		}
+	end
+	local value = if requestData.value ~= nil then requestData.value else "ended_by_mcp"
+	local ok, result = pcall(function()
+		return StudioTestService:EndTest(value)
+	end)
+	if not ok then
+		return {
+			error = tostring(result),
+		}
+	end
+	return {
+		success = true,
+		message = "Multiplayer Studio test end requested.",
+		value = value,
+	}
+end
 local function characterNavigation(requestData)
 	if not testRunning then
 		return {
@@ -6038,6 +6573,11 @@ return {
 	startPlaytest = startPlaytest,
 	stopPlaytest = stopPlaytest,
 	getPlaytestOutput = getPlaytestOutput,
+	multiplayerTestStart = multiplayerTestStart,
+	multiplayerTestState = multiplayerTestState,
+	multiplayerTestAddPlayers = multiplayerTestAddPlayers,
+	multiplayerTestLeaveClient = multiplayerTestLeaveClient,
+	multiplayerTestEnd = multiplayerTestEnd,
 	characterNavigation = characterNavigation,
 }
 ]]></string>
@@ -6393,6 +6933,74 @@ return {
         </Properties>
       </Item>
       <Item class="ModuleScript" referent="21">
+        <Properties>
+          <string name="Name">RenderMonitor</string>
+          <string name="Source"><![CDATA[-- Compiled with roblox-ts v3.0.0
+local TS = require(script.Parent.Parent.include.RuntimeLib)
+-- Detects whether the Studio window is actually rendering, so virtual input
+-- and screenshot tools can surface a clear reason instead of silently failing.
+--
+-- When a Studio window is MINIMIZED, the engine suspends the render loop AND
+-- input processing, but keeps running scripts (Heartbeat keeps firing). That's
+-- why simulate_*_input would return success while having zero effect, and
+-- CaptureService:CaptureScreenshot would time out. Validated live: during a 3s
+-- minimize, RenderStepped's max inter-frame gap was 5.08s while Heartbeat's was
+-- 0.10s. So RenderStepped freshness is the reliable "is this window rendering?"
+-- signal; Heartbeat is not.
+local RunService = TS.import(script, script.Parent.Parent, "node_modules", "@rbxts", "services").RunService
+local lastFrame = 0
+local connected = false
+-- Above this many seconds since the last rendered frame, we treat the window
+-- as not rendering. RenderStepped normally fires every ~16ms; a multi-second
+-- gap only happens when minimized/suspended, so 1s cleanly avoids false
+-- positives from ordinary frame hitches while still catching the real case.
+local STALE_THRESHOLD = 1.0
+local function start()
+	if connected then
+		return nil
+	end
+	-- RenderStepped can only be connected from a client/edit render loop; it
+	-- throws in the play-server DM. pcall so a server-DM call is a safe no-op
+	-- (connected stays false → notRenderingReason() returns undefined there).
+	local ok = pcall(function()
+		RunService.RenderStepped:Connect(function()
+			lastFrame = tick()
+		end)
+	end)
+	if ok then
+		connected = true
+		lastFrame = tick()
+	end
+end
+local function secondsSinceFrame()
+	if not connected then
+		return 0
+	end
+	return tick() - lastFrame
+end
+-- Returns a human-readable reason if the window appears minimized / not
+-- rendering (so input + screenshots won't work), else undefined. Fail-open:
+-- when the monitor isn't active in this DM (server peer, or connect failed) it
+-- returns undefined so we never block on a false signal.
+local function notRenderingReason()
+	if not connected then
+		return nil
+	end
+	local gap = secondsSinceFrame()
+	if gap > STALE_THRESHOLD then
+		return string.format("Studio window appears minimized or not rendering (no frame in %.1fs). " .. "Virtual input and screenshots only work while the window is visible — " .. "restore/un-minimize the Studio window and retry.", gap)
+	end
+	return nil
+end
+return {
+	start = start,
+	secondsSinceFrame = secondsSinceFrame,
+	notRenderingReason = notRenderingReason,
+}
+]]></string>
+        </Properties>
+      </Item>
+      <Item class="ModuleScript" referent="22">
         <Properties>
           <string name="Name">RuntimeLogBuffer</string>
           <string name="Source"><![CDATA[-- Compiled with roblox-ts v3.0.0
@@ -6573,11 +7181,11 @@ return {
 ]]></string>
         </Properties>
       </Item>
-      <Item class="ModuleScript" referent="22">
+      <Item class="ModuleScript" referent="23">
         <Properties>
           <string name="Name">State</string>
           <string name="Source"><![CDATA[-- Compiled with roblox-ts v3.0.0
-local CURRENT_VERSION = "2.12.0"
+local CURRENT_VERSION = "2.14.0"
 local MAX_CONNECTIONS = 5
 local BASE_PORT = 58741
 local activeTabIndex = 0
@@ -6669,7 +7277,7 @@ return {
 ]]></string>
         </Properties>
       </Item>
-      <Item class="ModuleScript" referent="23">
+      <Item class="ModuleScript" referent="24">
         <Properties>
           <string name="Name">StopPlayMonitor</string>
           <string name="Source"><![CDATA[-- Compiled with roblox-ts v3.0.0
@@ -6814,7 +7422,7 @@ return {
 ]]></string>
         </Properties>
       </Item>
-      <Item class="ModuleScript" referent="24">
+      <Item class="ModuleScript" referent="25">
         <Properties>
           <string name="Name">UI</string>
           <string name="Source"><![CDATA[-- Compiled with roblox-ts v3.0.0
@@ -7565,7 +8173,7 @@ return {
 ]]></string>
         </Properties>
       </Item>
-      <Item class="ModuleScript" referent="25">
+      <Item class="ModuleScript" referent="26">
         <Properties>
           <string name="Name">Utils</string>
           <string name="Source"><![CDATA[-- Compiled with roblox-ts v3.0.0
@@ -8095,11 +8703,11 @@ return {
         </Properties>
       </Item>
     </Item>
-    <Item class="Folder" referent="29">
+    <Item class="Folder" referent="30">
       <Properties>
         <string name="Name">include</string>
       </Properties>
-      <Item class="ModuleScript" referent="26">
+      <Item class="ModuleScript" referent="27">
         <Properties>
           <string name="Name">Promise</string>
           <string name="Source"><![CDATA[--[[
@@ -10173,7 +10781,7 @@ return Promise
 ]]></string>
         </Properties>
       </Item>
-      <Item class="ModuleScript" referent="27">
+      <Item class="ModuleScript" referent="28">
         <Properties>
           <string name="Name">RuntimeLib</string>
           <string name="Source"><![CDATA[local Promise = require(script.Parent.Promise)
@@ -10440,15 +11048,15 @@ return TS
         </Properties>
       </Item>
     </Item>
-    <Item class="Folder" referent="30">
+    <Item class="Folder" referent="31">
       <Properties>
         <string name="Name">node_modules</string>
       </Properties>
-      <Item class="Folder" referent="31">
+      <Item class="Folder" referent="32">
         <Properties>
           <string name="Name">@rbxts</string>
         </Properties>
-      <Item class="ModuleScript" referent="28">
+      <Item class="ModuleScript" referent="29">
         <Properties>
           <string name="Name">services</string>
           <string name="Source"><![CDATA[return setmetatable({}, {