@chrrxs/robloxstudio-mcp 3.0.4 → 3.1.0

package/studio-plugin/MCPPlugin.rbxmx

@@ -16,6 +16,7 @@ local cleanupEditBridgeArtifacts = _EvalBridges.cleanupEditBridgeArtifacts
 local ensureRuntimeBridgeInstalled = _EvalBridges.ensureRuntimeBridgeInstalled
 local RuntimeLogBuffer = TS.import(script, script, "modules", "RuntimeLogBuffer")
 local StopPlayMonitor = TS.import(script, script, "modules", "StopPlayMonitor")
+local StudioEventStream = TS.import(script, script, "modules", "StudioEventStream")
 local BreakpointHandlers = TS.import(script, script, "modules", "handlers", "BreakpointHandlers")
 local RenderMonitor = TS.import(script, script, "modules", "RenderMonitor")
 -- Track render-loop liveness so input/screenshot tools can report "window
@@ -32,8 +33,9 @@ RuntimeLogBuffer.install()
 StopPlayMonitor.init(plugin)
 BreakpointHandlers.init(plugin)
 ServerUrlSettings.init(plugin)
+local startupRole = ClientBroker.forkRole()
 local function applyRememberedServerUrl()
-	if ClientBroker.forkRole() == "client" then
+	if startupRole == "client" then
 		return nil
 	end
 	local rememberedServerUrl = ServerUrlSettings.readServerUrl()
@@ -49,6 +51,15 @@ local function applyRememberedServerUrl()
 	ClientBroker.setServerUrl(rememberedServerUrl)
 end
 applyRememberedServerUrl()
+-- Play DataModels do not reliably fire Plugin.Unloading before Studio tears
+-- down their VM. Close the persistent WebStreamClient while BindToClose still
+-- gives this server peer a live execution context; otherwise each play cycle
+-- can retain one native event stream until Studio itself is restarted. The
+-- transport releases that native stream before yielding to unregister the
+-- logical server peer.
+if startupRole == "server" then
+	game:BindToClose(StudioEventStream.suspendForShutdown)
+end
 UI.init(plugin)
 local elements = UI.getElements()
 local ICON_DISCONNECTED = "rbxassetid://75876056391496"
@@ -86,12 +97,12 @@ end)
 UI.updateUIState()
 Communication.checkForUpdates()
 task.delay(TOOLBAR_REGISTRATION_DELAY_SECONDS, registerToolbarButton)
--- Auto-activate per peer. The boshyxd plugin only registers with MCP when the
--- user clicks Connect in its UI, but that UI is invisible in play DMs - so
--- play peers' plugin instances load without ever registering. Run after a
--- short delay so the UI/State have a chance to initialize first.
-task.delay(2, function()
-	local role = ClientBroker.forkRole()
+-- Auto-activate per Peer. Runtime plugin VMs can load before their first
+-- Heartbeat; task.delay() would then wait behind the very multiplayer startup
+-- that needs this Peer to register. Start runtime initialization immediately,
+-- while retaining the short UI settling delay for the edit Peer.
+local function autoActivatePeer()
+	local role = startupRole
 	if role == "edit" then
 		cleanupEditBridgeArtifacts()
 	else
@@ -101,7 +112,7 @@ task.delay(2, function()
 		end
 	end
 	if role == "edit" or role == "server" then
-		pcall(function()
+		local activationOk, activationError = pcall(function()
 			local conn = State.getActiveConnection()
 			if not conn.isActive then
 				if role == "server" then
@@ -127,17 +138,28 @@ task.delay(2, function()
 				Communication.activatePlugin()
 			end
 		end)
+		if not activationOk then
+			warn(`[robloxstudio-mcp] Automatic {role} Peer activation failed: {activationError}`)
+		end
 	end
 	if role == "server" then
 		ClientBroker.setupServerBroker()
 		-- The play-server DM is the only one where StudioTestService:EndTest is
 		-- legal, so the stop-play monitor lives here. It consumes tokenized
 		-- stop requests from plugin settings and acknowledges EndTest results.
-		StopPlayMonitor.startMonitor()
+		StopPlayMonitor.startMonitor({
+			beforeEndTest = StudioEventStream.suspendForShutdown,
+			afterEndTestFailure = StudioEventStream.resumeAfterShutdownFailure,
+		})
 	elseif role == "client" then
 		ClientBroker.setupClientBroker()
 	end
-end)
+end
+if startupRole == "edit" then
+	task.delay(2, autoActivatePeer)
+else
+	autoActivatePeer()
+end
 ]]></string>
     </Properties>
     <Item class="Folder" referent="1">
@@ -278,17 +300,18 @@ local MicroProfilerHandlers = TS.import(script, script.Parent, "handlers", "Micr
 local LuauExec = TS.import(script, script.Parent, "LuauExec")
 local HttpDiagnostics = TS.import(script, script.Parent, "HttpDiagnostics")
 local PluginSession = TS.import(script, script.Parent, "PluginSession")
+local TopologyId = TS.import(script, script.Parent, "TopologyId")
+local PeerRole = TS.import(script, script.Parent, "PeerRole")
 local StudioTestService = game:GetService("StudioTestService")
--- The client peer cannot reach the MCP HTTP server - Roblox forbids
--- HttpService:RequestAsync from the client DM even under PluginSecurity, and
--- HttpEnabled reads as false there regardless of identity. So the server peer
--- brokers client-targeted requests through a RemoteFunction it places
--- in ReplicatedStorage; each player gets a logical proxy registration on the
--- MCP side, multiplexed over the play-server peer's physical event stream.
+-- Client Peers cannot reach the MCP HTTP server, so the server transport
+-- forwards requests over this RemoteFunction. The client supplies only its
+-- VM Peer identity; the server broker assigns trusted process/group topology
+-- from its own playtest context before publishing that Peer to MCP.
 local DEFAULT_MCP_URL = "http://localhost:58741"
 local mcpUrl = DEFAULT_MCP_URL
 local BROKER_NAME = "__MCPClientBroker"
 local BROKER_OWNER_ATTRIBUTE = "__MCPBrokerOwner"
+local CLIENT_IDENTITY_KIND = "identity"
 -- 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.
@@ -309,13 +332,7 @@ local CLIENT_BROKER_ALLOWED_ENDPOINTS = {
 	["/api/focus-viewport"] = true,
 }
 local function forkRole()
-	if not RunService:IsRunning() then
-		return "edit"
-	end
-	if RunService:IsServer() then
-		return "server"
-	end
-	return "client"
+	return PeerRole.detect()
 end
 local function postJson(endpoint, body)
 	return pcall(function()
@@ -356,13 +373,11 @@ local function handleGetRuntimeLogs(data)
 	local since = d.since
 	local tail = d.tail
 	local filter = d.filter
-	-- "client" is the generic capture tag; MCP-side aggregation overrides it
-	-- with the specific role (e.g. "client-1") for capturedBy.
 	return RuntimeLogBuffer.query({
 		since = since,
 		tail = tail,
 		filter = filter,
-	}, "client")
+	})
 end
 local function handleMultiplayerTestState()
 	local argsOk, args = pcall(function()
@@ -435,10 +450,44 @@ local function handleMultiplayerTestLeaveClient()
 		localPlayer = localPlayer,
 	}
 end
-local function setupClientBroker()
+local proxyRetryDelay
+local function sendClientIdentity(rf, attempt)
+	if PeerRole.detect() ~= "client" or rf.Parent == nil then
+		return nil
+	end
+	local identity = {
+		kind = "identity",
+		peerId = PluginSession.peerId,
+	}
+	local ok, response = pcall(function()
+		return rf:InvokeServer(identity)
+	end)
+	if ok and type(response) == "table" then
+		local acknowledgement = response
+		if acknowledgement.success == true then
+			return nil
+		end
+	end
+	if attempt == 0 then
+		warn(`[robloxstudio-mcp] client identity handshake failed; retrying`)
+	end
+	task.delay(proxyRetryDelay(attempt + 1), sendClientIdentity, rf, attempt + 1)
+end
+local function setupClientBroker(attempt)
+	if attempt == nil then
+		attempt = 0
+	end
+	if PeerRole.detect() ~= "client" then
+		return nil
+	end
 	local rf = ReplicatedStorage:WaitForChild(BROKER_NAME, 10)
 	if not rf or not rf:IsA("RemoteFunction") then
-		warn(`[robloxstudio-mcp] client: {BROKER_NAME} not found`)
+		if attempt == 0 then
+			warn(`[robloxstudio-mcp] client: {BROKER_NAME} not found; retrying`)
+		end
+		if RunService:IsRunning() then
+			task.delay(proxyRetryDelay(attempt + 1), setupClientBroker, attempt + 1)
+		end
 		return nil
 	end
 	rf.OnClientInvoke = function(payload)
@@ -498,11 +547,12 @@ local function setupClientBroker()
 			error = `Unsupported client broker endpoint: {payload.endpoint}`,
 		}
 	end
+	task.spawn(sendClientIdentity, rf, 0)
 end
 local INITIAL_PROXY_RETRY_DELAY_SECONDS = 0.5
 local MAX_PROXY_RETRY_DELAY_SECONDS = 5
 local proxyByPlayer = {}
-local proxyBySessionId = {}
+local proxyByPeerId = {}
 local proxyRegisterFailuresByPlayer = {}
 local pendingProxyDisconnects = {}
 local serverBrokerStarted = false
@@ -520,50 +570,50 @@ local function unregisterProxy(player, entry)
 	proxy.generation += 1
 	local _player = player
 	proxyByPlayer[_player] = nil
-	local _pluginSessionId = proxy.pluginSessionId
-	proxyBySessionId[_pluginSessionId] = nil
+	local _peerId = proxy.peerId
+	proxyByPeerId[_peerId] = nil
 	local _player_1 = player
 	proxyRegisterFailuresByPlayer[_player_1] = nil
-	queueProxyDisconnect(proxy.pluginSessionId)
+	queueProxyDisconnect(proxy.peerId)
 end
 local function disconnectAllProxies()
 	for player, entry in proxyByPlayer do
 		unregisterProxy(player, entry)
 	end
 	table.clear(proxyByPlayer)
-	table.clear(proxyBySessionId)
+	table.clear(proxyByPeerId)
 	table.clear(proxyRegisterFailuresByPlayer)
 end
-local function proxyRetryDelay(attempt)
+function proxyRetryDelay(attempt)
 	return math.min(INITIAL_PROXY_RETRY_DELAY_SECONDS * math.pow(2, math.max(attempt - 1, 0)), MAX_PROXY_RETRY_DELAY_SECONDS)
 end
-local function deliverProxyDisconnect(pluginSessionId, attempt)
-	local _pluginSessionId = pluginSessionId
-	if not (pendingProxyDisconnects[_pluginSessionId] ~= nil) then
+local function deliverProxyDisconnect(peerId, attempt)
+	local _peerId = peerId
+	if not (pendingProxyDisconnects[_peerId] ~= nil) then
 		return nil
 	end
 	local ok, response = postJson("/disconnect", {
-		pluginSessionId = pluginSessionId,
+		peerId = peerId,
 	})
 	if ok and response and response.Success then
-		local _pluginSessionId_1 = pluginSessionId
-		pendingProxyDisconnects[_pluginSessionId_1] = nil
+		local _peerId_1 = peerId
+		pendingProxyDisconnects[_peerId_1] = nil
 		return nil
 	end
 	task.delay(proxyRetryDelay(attempt + 1), function()
-		deliverProxyDisconnect(pluginSessionId, attempt + 1)
+		deliverProxyDisconnect(peerId, attempt + 1)
 	end)
 end
-function queueProxyDisconnect(pluginSessionId)
-	local _pluginSessionId = pluginSessionId
-	if pendingProxyDisconnects[_pluginSessionId] ~= nil then
+function queueProxyDisconnect(peerId)
+	local _peerId = peerId
+	if pendingProxyDisconnects[_peerId] ~= nil then
 		return nil
 	end
-	local _pluginSessionId_1 = pluginSessionId
-	pendingProxyDisconnects[_pluginSessionId_1] = true
-	task.spawn(deliverProxyDisconnect, pluginSessionId, 0)
+	local _peerId_1 = peerId
+	pendingProxyDisconnects[_peerId_1] = true
+	task.spawn(deliverProxyDisconnect, peerId, 0)
 end
-local function parseAssignedRole(body)
+local function parseAssignedRole(body, entry)
 	local decodeOk, decoded = pcall(function()
 		return HttpService:JSONDecode(body)
 	end)
@@ -571,7 +621,7 @@ local function parseAssignedRole(body)
 		return nil
 	end
 	local ready = decoded
-	if ready.success ~= true then
+	if ready.success ~= true or ready.peerId ~= entry.peerId or ready.instanceId ~= entry.instanceId or ready.multiplayerGroupId ~= entry.multiplayerGroupId then
 		return nil
 	end
 	local _assignedRole = ready.assignedRole
@@ -622,27 +672,18 @@ function registerProxyEntry(entry)
 	entry.registering = true
 	local expectedGeneration = entry.generation
 	local requestedRole = if entry.role == "client" then "client" else entry.role
-	local readyPayload = PluginSession.createReadyPayload(entry.pluginSessionId, requestedRole)
+	local readyPayload = PluginSession.createReadyPayload(entry.peerId, requestedRole, entry.instanceId, entry.multiplayerGroupId)
+	local ok, res = postJson("/ready", readyPayload)
 	local _player = entry.player
 	if proxyByPlayer[_player] ~= entry then
-		return nil
-	end
-	if entry.generation ~= expectedGeneration then
-		if not entry.registering then
-			task.spawn(registerProxyEntry, entry)
-		end
-		return nil
-	end
-	local ok, res = postJson("/ready", readyPayload)
-	local _player_1 = entry.player
-	if proxyByPlayer[_player_1] ~= entry then
 		if ok and res and res.Success then
-			queueProxyDisconnect(entry.pluginSessionId)
+			queueProxyDisconnect(entry.peerId)
 		end
 		return nil
 	end
 	if entry.generation ~= expectedGeneration then
-		if not entry.registering then
+		entry.registering = false
+		if not entry.registered then
 			task.spawn(registerProxyEntry, entry)
 		end
 		return nil
@@ -652,30 +693,91 @@ function registerProxyEntry(entry)
 		failProxyRegistration(entry, formatPostJsonFailure("/ready", ok, res))
 		return nil
 	end
-	local assignedRole = parseAssignedRole(res.Body)
+	local assignedRole = parseAssignedRole(res.Body, entry)
 	if assignedRole == nil then
-		failProxyRegistration(entry, "invalid /ready response: expected success=true and a non-empty assignedRole")
+		failProxyRegistration(entry, "invalid /ready response for client Peer topology")
 		return nil
 	end
 	entry.role = assignedRole
 	entry.registered = true
 	entry.retryAttempt = 0
-	local _player_2 = entry.player
-	if proxyRegisterFailuresByPlayer[_player_2] ~= nil then
-		local _player_3 = entry.player
-		proxyRegisterFailuresByPlayer[_player_3] = nil
+	local _player_1 = entry.player
+	if proxyRegisterFailuresByPlayer[_player_1] ~= nil then
+		local _player_2 = entry.player
+		proxyRegisterFailuresByPlayer[_player_2] = nil
 		print(`[robloxstudio-mcp] proxy registered for {entry.player.Name} as {assignedRole} via {mcpUrl}`)
 	end
 end
-local function registerProxy(player, rf)
-	local _player = player
-	if proxyByPlayer[_player] ~= nil then
+local function parseClientIdentity(payload)
+	local _payload = payload
+	if not (type(_payload) == "table") then
+		return nil
+	end
+	local identity = payload
+	local _condition = identity.kind ~= CLIENT_IDENTITY_KIND
+	if not _condition then
+		local _peerId = identity.peerId
+		_condition = not (type(_peerId) == "string")
+		if not _condition then
+			_condition = identity.peerId == ""
+		end
+	end
+	if _condition then
 		return nil
 	end
+	return {
+		kind = "identity",
+		peerId = identity.peerId,
+	}
+end
+local function registerProxy(player, rf, identity)
+	local _peerId = identity.peerId
+	local peerOwner = proxyByPeerId[_peerId]
+	if peerOwner ~= nil and peerOwner.player ~= player then
+		return false
+	end
+	local _player = player
+	local current = proxyByPlayer[_player]
+	local multiplayerGroupId = PluginSession.getMultiplayerGroupId()
+	-- Managed multiplayer launches one client Player per Studio process. The
+	-- server creates that process identity instead of trusting replicated game
+	-- code to claim an Instance or Multiplayer Group. Solo clients use the
+	-- server's process Instance because their VMs share one Studio process.
+	local retainedMultiplayerInstanceId = if current ~= nil and current.multiplayerGroupId == multiplayerGroupId then current.instanceId else nil
+	local _result
+	if multiplayerGroupId ~= nil then
+		local _condition = retainedMultiplayerInstanceId
+		if _condition == nil then
+			_condition = TopologyId.createInstanceId()
+		end
+		_result = _condition
+	else
+		_result = PluginSession.getInstanceId()
+	end
+	local instanceId = _result
+	if current ~= nil then
+		if current.peerId ~= identity.peerId then
+			unregisterProxy(player, current)
+		else
+			if current.instanceId ~= instanceId or current.multiplayerGroupId ~= multiplayerGroupId then
+				current.generation += 1
+				current.instanceId = instanceId
+				current.multiplayerGroupId = multiplayerGroupId
+				current.role = "client"
+				current.registered = false
+				current.registering = false
+				current.retryAttempt = 0
+				task.spawn(registerProxyEntry, current)
+			end
+			return true
+		end
+	end
 	local entry = {
 		player = player,
 		remote = rf,
-		pluginSessionId = HttpService:GenerateGUID(false),
+		peerId = identity.peerId,
+		instanceId = instanceId,
+		multiplayerGroupId = multiplayerGroupId,
 		role = "client",
 		registered = false,
 		registering = false,
@@ -684,11 +786,12 @@ local function registerProxy(player, rf)
 	}
 	local _player_1 = player
 	proxyByPlayer[_player_1] = entry
-	local _pluginSessionId = entry.pluginSessionId
-	proxyBySessionId[_pluginSessionId] = entry
+	local _peerId_1 = entry.peerId
+	proxyByPeerId[_peerId_1] = entry
 	task.spawn(registerProxyEntry, entry)
+	return true
 end
-local function refreshAllLogicalRegistrations()
+local function refreshAllProxyRegistrations()
 	for _, entry in proxyByPlayer do
 		entry.generation += 1
 		entry.registered = false
@@ -697,9 +800,9 @@ local function refreshAllLogicalRegistrations()
 		task.spawn(registerProxyEntry, entry)
 	end
 end
-local function dispatchClientRequest(logicalSessionId, target, endpoint, data)
-	local _logicalSessionId = logicalSessionId
-	local entry = proxyBySessionId[_logicalSessionId]
+local function dispatchClientRequest(peerId, target, endpoint, data)
+	local _peerId = peerId
+	local entry = proxyByPeerId[_peerId]
 	local _condition = not entry
 	if not _condition then
 		local _player = entry.player
@@ -707,7 +810,7 @@ local function dispatchClientRequest(logicalSessionId, target, endpoint, data)
 	end
 	if _condition then
 		return {
-			error = `Client proxy {target} ({logicalSessionId}) is not registered.`,
+			error = `Client proxy {target} ({peerId}) is not registered.`,
 		}
 	end
 	if entry.role == "client" then
@@ -718,7 +821,7 @@ local function dispatchClientRequest(logicalSessionId, target, endpoint, data)
 	end
 	if entry.role ~= target then
 		return {
-			error = `Client proxy {logicalSessionId} is registered as {entry.role}, not {target}.`,
+			error = `Client proxy {peerId} is registered as {entry.role}, not {target}.`,
 		}
 	end
 	if entry.player.Parent == nil or not RunService:IsRunning() then
@@ -759,26 +862,46 @@ local function setupServerBroker()
 	if serverBrokerStarted then
 		return nil
 	end
-	local rf = ReplicatedStorage:FindFirstChild(BROKER_NAME)
-	if not rf then
+	local existing = ReplicatedStorage:FindFirstChild(BROKER_NAME)
+	local rf
+	if existing ~= nil then
+		if not existing:IsA("RemoteFunction") then
+			warn(`[robloxstudio-mcp] server: {BROKER_NAME} exists but is not a RemoteFunction`)
+			return nil
+		end
+		rf = existing
+	else
 		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)
-	end)
-	for _, p in Players:GetPlayers() do
-		task.spawn(registerProxy, p, broker)
+	rf.Name = BROKER_NAME
+	rf:SetAttribute(BROKER_OWNER_ATTRIBUTE, PluginSession.peerId)
+	rf.OnServerInvoke = function(player, payload)
+		local identity = parseClientIdentity(payload)
+		if identity == nil then
+			return {
+				success = false,
+				error = "Invalid client Peer identity handshake.",
+			}
+		end
+		if not registerProxy(player, rf, identity) then
+			return {
+				success = false,
+				error = "Client Peer identity is already registered by another player.",
+			}
+		end
+		return {
+			success = true,
+		}
 	end
-	Players.PlayerRemoving:Connect(function(p)
-		unregisterProxy(p)
+	if rf.Parent == nil then
+		rf.Parent = ReplicatedStorage
+	end
+	serverBrokerStarted = true
+	Players.PlayerRemoving:Connect(function(player)
+		unregisterProxy(player)
 	end)
 	game:BindToClose(function()
 		disconnectAllProxies()
@@ -788,7 +911,7 @@ return {
 	DEFAULT_MCP_URL = DEFAULT_MCP_URL,
 	setServerUrl = setServerUrl,
 	disconnectAllProxies = disconnectAllProxies,
-	refreshAllLogicalRegistrations = refreshAllLogicalRegistrations,
+	refreshAllProxyRegistrations = refreshAllProxyRegistrations,
 	dispatchClientRequest = dispatchClientRequest,
 	forkRole = forkRole,
 	setupClientBroker = setupClientBroker,
@@ -831,7 +954,7 @@ local ServerUrlSettings = TS.import(script, script.Parent, "ServerUrlSettings")
 local PluginSession = TS.import(script, script.Parent, "PluginSession")
 local StudioEventStream = TS.import(script, script.Parent, "StudioEventStream")
 local assignedRole
-local lastReadyInstanceId
+local lastReadyPlaceKey
 local initialRole = PluginSession.getRole()
 local routeMap = {
 	["/api/file-tree"] = QueryHandlers.getFileTree,
@@ -906,8 +1029,8 @@ local function getConnectionStatus()
 	return "connecting"
 end
 local function dispatchStreamRequest(request, context)
-	if request.logicalSessionId ~= PluginSession.id then
-		return ClientBroker.dispatchClientRequest(request.logicalSessionId, request.target, request.endpoint, request.data)
+	if request.peerId ~= PluginSession.peerId then
+		return ClientBroker.dispatchClientRequest(request.peerId, request.target, request.endpoint, request.data)
 	end
 	local _condition = assignedRole
 	if _condition == nil then
@@ -916,7 +1039,7 @@ local function dispatchStreamRequest(request, context)
 	local localRole = _condition
 	if request.target ~= localRole then
 		return {
-			error = `Physical plugin session is registered as {localRole}, not {request.target}.`,
+			error = `Transport peer is registered as {localRole}, not {request.target}.`,
 		}
 	end
 	return processRequest({
@@ -930,9 +1053,9 @@ local function handleReady(response)
 		return nil
 	end
 	assignedRole = response.assignedRole
-	lastReadyInstanceId = response.instanceId
+	lastReadyPlaceKey = PluginSession.getPlaceKey()
 	ServerUrlSettings.rememberServerUrl(conn.serverUrl)
-	ClientBroker.refreshAllLogicalRegistrations()
+	ClientBroker.refreshAllProxyRegistrations()
 end
 local function handleStatus(status)
 	local conn = State.getActiveConnection()
@@ -1011,7 +1134,7 @@ local function ensureIdentityWatchers()
 		if signalOk and signal then
 			placeIdChangeConn = signal:Connect(function()
 				PluginSession.invalidatePlaceName()
-				lastReadyInstanceId = PluginSession.getInstanceId()
+				lastReadyPlaceKey = PluginSession.getPlaceKey()
 				StudioEventStream.refresh()
 			end)
 		end
@@ -1051,7 +1174,7 @@ local function activatePlugin()
 		conn.port = port
 	end
 	ClientBroker.setServerUrl(conn.serverUrl)
-	lastReadyInstanceId = PluginSession.getInstanceId()
+	lastReadyPlaceKey = PluginSession.getPlaceKey()
 	UI.updateUIState()
 	StudioEventStream.start({
 		serverUrl = conn.serverUrl,
@@ -1068,15 +1191,15 @@ local function activatePlugin()
 				deactivatePlugin()
 				return nil
 			end
-			local currentInstanceId = PluginSession.getInstanceId()
-			if lastReadyInstanceId ~= nil and currentInstanceId ~= lastReadyInstanceId then
-				lastReadyInstanceId = currentInstanceId
+			local currentPlaceKey = PluginSession.getPlaceKey()
+			if lastReadyPlaceKey ~= nil and currentPlaceKey ~= lastReadyPlaceKey then
+				lastReadyPlaceKey = currentPlaceKey
 				PluginSession.invalidatePlaceName()
 				StudioEventStream.refresh()
 			end
 		end)
 	end
-	if not RunService:IsRunning() then
+	if initialRole == "edit" then
 		task.spawn(cleanupEditBridgeArtifacts)
 	end
 	ensureIdentityWatchers()
@@ -1099,7 +1222,7 @@ function deactivatePlugin()
 		conn.heartbeatConnection:Disconnect()
 		conn.heartbeatConnection = nil
 	end
-	lastReadyInstanceId = nil
+	lastReadyPlaceKey = nil
 	assignedRole = nil
 	conn.consecutiveFailures = 0
 	conn.currentRetryDelay = 0.5
@@ -1267,6 +1390,7 @@ local ReplicatedStorage = _services.ReplicatedStorage
 local RunService = _services.RunService
 local ServerScriptService = _services.ServerScriptService
 local StarterPlayer = _services.StarterPlayer
+local PeerRole = TS.import(script, script.Parent, "PeerRole")
 local ScriptEditorService = game:GetService("ScriptEditorService")
 local function getStarterPlayerScripts()
 	return StarterPlayer:FindFirstChild("StarterPlayerScripts")
@@ -1348,9 +1472,9 @@ local function computeBridgeStamp()
 	for i = 1, #combined do
 		h = (h * 33 + (string.byte(combined, i))) % 2147483647
 	end
-	-- "3.0.4" is replaced with the package version at package time
+	-- "3.1.0" is replaced with the package version at package time
 	-- (scripts/build-plugin.mjs injectVersion), so a release bump also restamps.
-	return `{tostring(h)}-3.0.4`
+	return `{tostring(h)}-3.1.0`
 end
 local BRIDGE_STAMP = computeBridgeStamp()
 local function setSource(scriptInst, source)
@@ -1484,10 +1608,10 @@ local function installClientRuntimeBridge()
 	}
 end
 local function ensureRuntimeBridgeInstalled()
-	if not RunService:IsRunning() then
+	if PeerRole.detect() == "edit" then
 		return {
 			installed = false,
-			error = "Eval bridges are installed only in running play DataModels",
+			error = "Eval bridges are installed only in play DataModels",
 		}
 	end
 	if RunService:IsServer() then
@@ -1954,10 +2078,10 @@ return {
             <string name="Source"><![CDATA[-- Compiled with roblox-ts v3.0.0
 local TS = require(script.Parent.Parent.Parent.include.RuntimeLib)
 local Utils = TS.import(script, script.Parent.Parent, "Utils")
+local PeerRole = TS.import(script, script.Parent.Parent, "PeerRole")
 local _binding = Utils
 local getInstanceByPath = _binding.getInstanceByPath
 local HttpService = game:GetService("HttpService")
-local RunService = game:GetService("RunService")
 local ServerStorage = game:GetService("ServerStorage")
 local LOG_PREFIX = "Breakpoint"
 local REGISTRY_KEY_PREFIX = "MCP_BREAKPOINTS_V1_"
@@ -1972,7 +2096,7 @@ end
 local function breakpointKey(scriptPath, line)
 	return `{scriptPath}:{line}`
 end
-local function computeInstanceId()
+local function computePlaceKey()
 	if game.PlaceId ~= 0 then
 		return `place:{tostring(game.PlaceId)}`
 	end
@@ -1987,13 +2111,7 @@ local function computeInstanceId()
 	return `anon:{fresh}`
 end
 local function detectRole()
-	if not RunService:IsRunning() then
-		return "edit"
-	end
-	if RunService:IsServer() then
-		return "server"
-	end
-	return "client"
+	return PeerRole.detect()
 end
 local function requestedRole(requestData)
 	local ___mcp_target_role = requestData.__mcp_target_role
@@ -2004,15 +2122,10 @@ local function requestedRole(requestData)
 	return if _condition then requestData.__mcp_target_role else detectRole()
 end
 local function registryScope(requestData)
-	local ___mcp_instance_id = requestData.__mcp_instance_id
-	local _condition = type(___mcp_instance_id) == "string"
-	if _condition then
-		_condition = requestData.__mcp_instance_id ~= ""
-	end
-	local instanceId = if _condition then requestData.__mcp_instance_id else computeInstanceId()
+	local placeKey = computePlaceKey()
 	local role = requestedRole(requestData)
 	return {
-		key = `{REGISTRY_KEY_PREFIX}{instanceId}:{role}`,
+		key = `{REGISTRY_KEY_PREFIX}{placeKey}:{role}`,
 	}
 end
 local function readSetting(key)
@@ -3279,15 +3392,11 @@ local function getRuntimeLogs(requestData)
 	local since = requestData.since
 	local tail = requestData.tail
 	local filter = requestData.filter
-	-- This is the buffer that captured the LogService event, not necessarily
-	-- the script-origin peer. Ordinary playtests share/reflect logs across
-	-- edit/server/client LogService buffers.
-	local capturedBy = RuntimeLogBuffer.detectPeer()
 	return RuntimeLogBuffer.query({
 		since = since,
 		tail = tail,
 		filter = filter,
-	}, capturedBy)
+	})
 end
 return {
 	getRuntimeLogs = getRuntimeLogs,
@@ -7576,7 +7685,7 @@ return {
             <string name="Name">SerializationHandlers</string>
             <string name="Source"><![CDATA[-- Compiled with roblox-ts v3.0.0
 local TS = require(script.Parent.Parent.Parent.include.RuntimeLib)
-local RunService = TS.import(script, script.Parent.Parent.Parent, "node_modules", "@rbxts", "services").RunService
+local PeerRole = TS.import(script, script.Parent.Parent, "PeerRole")
 local Utils = TS.import(script, script.Parent.Parent, "Utils")
 local Recording = TS.import(script, script.Parent.Parent, "Recording")
 -- SerializationService:SerializeInstancesAsync / DeserializeInstancesAsync were
@@ -7696,7 +7805,7 @@ local function importRbxm(requestData)
 	-- All-or-nothing parenting. Track every instance we've attached and roll back
 	-- (unparent + Destroy) if any later one fails - partial imports leave the DM
 	-- in a worse state than failing cleanly.
-	local isEdit = not RunService:IsRunning()
+	local isEdit = PeerRole.detect() == "edit"
 	local recordingId = if isEdit then beginRecording(`Import rbxm`) else nil
 	local attached = {}
 	local failureMessage
@@ -7767,19 +7876,15 @@ local HttpService = _services.HttpService
 local Players = _services.Players
 local RunService = _services.RunService
 local StopPlayMonitor = TS.import(script, script.Parent.Parent, "StopPlayMonitor")
+local PluginSession = TS.import(script, script.Parent.Parent, "PluginSession")
+local PeerRole = TS.import(script, script.Parent.Parent, "PeerRole")
 local StudioTestService = game:GetService("StudioTestService")
 local testRunning = false
 local multiplayerState = {
 	phase = "idle",
 }
 local function detectPeerRole()
-	if not RunService:IsRunning() then
-		return "edit"
-	end
-	if RunService:IsServer() then
-		return "server"
-	end
-	return "client"
+	return PeerRole.detect()
 end
 local function getPlayersSnapshot()
 	local _exp = Players:GetPlayers()
@@ -7854,6 +7959,7 @@ local function startPlaytest(requestData)
 		}
 	end
 	testRunning = true
+	local topologyMarkerToken = PluginSession.prepareSharedTopology()
 	task.spawn(function()
 		local ok, result = pcall(function()
 			if mode == "play" then
@@ -7861,6 +7967,7 @@ local function startPlaytest(requestData)
 			end
 			return StudioTestService:ExecuteRunModeAsync({})
 		end)
+		PluginSession.clearTopologyMarker(topologyMarkerToken)
 		if not ok then
 			warn(`[robloxstudio-mcp] Playtest ended with error: {result}`)
 		end
@@ -7966,11 +8073,13 @@ local function multiplayerTestStart(requestData)
 		testArgs = testArgs,
 		startedAt = tick(),
 	}
+	local topologyMarkerToken = PluginSession.prepareMultiplayerTopology(testId)
 	task.spawn(function()
 		multiplayerState.phase = "running"
 		local ok, result = pcall(function()
 			return StudioTestService:ExecuteMultiplayerTestAsync(numPlayers, testArgs)
 		end)
+		PluginSession.clearTopologyMarker(topologyMarkerToken)
 		multiplayerState.completedAt = tick()
 		multiplayerState.ok = ok
 		if ok then
@@ -8652,20 +8761,69 @@ return {
         </Properties>
       </Item>
       <Item class="ModuleScript" referent="27">
+        <Properties>
+          <string name="Name">PeerRole</string>
+          <string name="Source"><![CDATA[-- Compiled with roblox-ts v3.0.0
+local TS = require(script.Parent.Parent.include.RuntimeLib)
+local RunService = TS.import(script, script.Parent.Parent, "node_modules", "@rbxts", "services").RunService
+local function detect()
+	if RunService:IsEdit() then
+		return "edit"
+	end
+	if RunService:IsServer() then
+		return "server"
+	end
+	return "client"
+end
+return {
+	detect = detect,
+}
+]]></string>
+        </Properties>
+      </Item>
+      <Item class="ModuleScript" referent="28">
         <Properties>
           <string name="Name">PluginSession</string>
           <string name="Source"><![CDATA[-- Compiled with roblox-ts v3.0.0
 local TS = require(script.Parent.Parent.include.RuntimeLib)
 local _services = TS.import(script, script.Parent.Parent, "node_modules", "@rbxts", "services")
 local HttpService = _services.HttpService
+local ReplicatedStorage = _services.ReplicatedStorage
 local RunService = _services.RunService
 local ServerStorage = _services.ServerStorage
 local State = TS.import(script, script.Parent, "State")
+local PeerRole = TS.import(script, script.Parent, "PeerRole")
+local TopologyId = TS.import(script, script.Parent, "TopologyId")
 local MCP_PLACE_ID_ATTRIBUTE = "__MCPPlaceId"
-local id = HttpService:GenerateGUID(false)
+local TOPOLOGY_MODE_ATTRIBUTE = "__MCPTopologyMode"
+local TOPOLOGY_INSTANCE_ID_ATTRIBUTE = "__MCPTopologyInstanceId"
+local TOPOLOGY_GROUP_ID_ATTRIBUTE = "__MCPTopologyGroupId"
+local TOPOLOGY_TOKEN_ATTRIBUTE = "__MCPTopologyToken"
+local peerId = TopologyId.createPeerId()
+local processInstanceId = TopologyId.currentProcessInstanceId()
 local cachedPlaceName
 local cachedPlaceNamePlaceId
+local function getMarkerMode()
+	local mode = ReplicatedStorage:GetAttribute(TOPOLOGY_MODE_ATTRIBUTE)
+	return if mode == "shared" or mode == "multiplayer" then mode else nil
+end
 local function getInstanceId()
+	if getMarkerMode() == "shared" then
+		local sharedInstanceId = ReplicatedStorage:GetAttribute(TOPOLOGY_INSTANCE_ID_ATTRIBUTE)
+		if type(sharedInstanceId) == "string" and sharedInstanceId ~= "" then
+			return sharedInstanceId
+		end
+	end
+	return processInstanceId
+end
+local function getMultiplayerGroupId()
+	if getMarkerMode() ~= "multiplayer" then
+		return nil
+	end
+	local groupId = ReplicatedStorage:GetAttribute(TOPOLOGY_GROUP_ID_ATTRIBUTE)
+	return if type(groupId) == "string" and groupId ~= "" then groupId else nil
+end
+local function getPlaceKey()
 	if game.PlaceId ~= 0 then
 		return `place:{tostring(game.PlaceId)}`
 	end
@@ -8679,14 +8837,32 @@ local function getInstanceId()
 	end)
 	return `anon:{fresh}`
 end
-local function getRole()
-	if not RunService:IsRunning() then
-		return "edit"
-	end
-	if RunService:IsServer() then
-		return "server"
+local function setTopologyMarker(mode, instanceId, groupId)
+	local token = HttpService:GenerateGUID(false)
+	ReplicatedStorage:SetAttribute(TOPOLOGY_MODE_ATTRIBUTE, nil)
+	ReplicatedStorage:SetAttribute(TOPOLOGY_INSTANCE_ID_ATTRIBUTE, instanceId)
+	ReplicatedStorage:SetAttribute(TOPOLOGY_GROUP_ID_ATTRIBUTE, groupId)
+	ReplicatedStorage:SetAttribute(TOPOLOGY_TOKEN_ATTRIBUTE, token)
+	ReplicatedStorage:SetAttribute(TOPOLOGY_MODE_ATTRIBUTE, mode)
+	return token
+end
+local function prepareSharedTopology()
+	return setTopologyMarker("shared", processInstanceId, nil)
+end
+local function prepareMultiplayerTopology(groupId)
+	return setTopologyMarker("multiplayer", nil, groupId)
+end
+local function clearTopologyMarker(token)
+	if ReplicatedStorage:GetAttribute(TOPOLOGY_TOKEN_ATTRIBUTE) ~= token then
+		return nil
 	end
-	return "client"
+	ReplicatedStorage:SetAttribute(TOPOLOGY_MODE_ATTRIBUTE, nil)
+	ReplicatedStorage:SetAttribute(TOPOLOGY_INSTANCE_ID_ATTRIBUTE, nil)
+	ReplicatedStorage:SetAttribute(TOPOLOGY_GROUP_ID_ATTRIBUTE, nil)
+	ReplicatedStorage:SetAttribute(TOPOLOGY_TOKEN_ATTRIBUTE, nil)
+end
+local function getRole()
+	return PeerRole.detect()
 end
 local function invalidatePlaceName()
 	cachedPlaceName = nil
@@ -8717,14 +8893,22 @@ local function getPlaceName()
 	end
 	return game.Name
 end
-local function createReadyPayload(pluginSessionId, role)
+local function createReadyPayload(readyPeerId, role, instanceId, multiplayerGroupId)
+	if instanceId == nil then
+		instanceId = getInstanceId()
+	end
+	if multiplayerGroupId == nil then
+		multiplayerGroupId = getMultiplayerGroupId()
+	end
 	return {
-		pluginSessionId = pluginSessionId,
-		physicalSessionId = id,
-		instanceId = getInstanceId(),
+		peerId = readyPeerId,
+		transportPeerId = peerId,
+		instanceId = instanceId,
+		multiplayerGroupId = multiplayerGroupId,
 		role = role,
 		placeId = game.PlaceId,
 		placeName = getPlaceName(),
+		placeKey = getPlaceKey(),
 		dataModelName = game.Name,
 		isRunning = RunService:IsRunning(),
 		pluginVersion = State.CURRENT_VERSION,
@@ -8733,17 +8917,22 @@ local function createReadyPayload(pluginSessionId, role)
 	}
 end
 return {
-	id = id,
+	peerId = peerId,
 	getInstanceId = getInstanceId,
+	getMultiplayerGroupId = getMultiplayerGroupId,
+	getPlaceKey = getPlaceKey,
 	getRole = getRole,
 	getPlaceName = getPlaceName,
 	invalidatePlaceName = invalidatePlaceName,
+	prepareSharedTopology = prepareSharedTopology,
+	prepareMultiplayerTopology = prepareMultiplayerTopology,
+	clearTopologyMarker = clearTopologyMarker,
 	createReadyPayload = createReadyPayload,
 }
 ]]></string>
         </Properties>
       </Item>
-      <Item class="ModuleScript" referent="28">
+      <Item class="ModuleScript" referent="29">
         <Properties>
           <string name="Name">Recording</string>
           <string name="Source"><![CDATA[-- Compiled with roblox-ts v3.0.0
@@ -8773,7 +8962,7 @@ return {
 ]]></string>
         </Properties>
       </Item>
-      <Item class="ModuleScript" referent="29">
+      <Item class="ModuleScript" referent="30">
         <Properties>
           <string name="Name">RenderMonitor</string>
           <string name="Source"><![CDATA[-- Compiled with roblox-ts v3.0.0
@@ -8841,30 +9030,22 @@ return {
 ]]></string>
         </Properties>
       </Item>
-      <Item class="ModuleScript" referent="30">
+      <Item class="ModuleScript" referent="31">
         <Properties>
           <string name="Name">RuntimeLogBuffer</string>
           <string name="Source"><![CDATA[-- Compiled with roblox-ts v3.0.0
 local TS = require(script.Parent.Parent.include.RuntimeLib)
--- Per-capture in-memory ring buffer for LogService.MessageOut events.
--- Powers the get_runtime_logs MCP tool. Replaces the out-of-tree LogBuffer
--- primitives + StringValue approach from chrrxs/roblox-mcp-primitives.
---
--- Each peer's plugin attaches a MessageOut listener at plugin load (edit DM,
--- play-server DM, play-client DM all run their own copy of this module).
--- Captured entries live in plugin module-state; nothing is parented to the
--- DataModel. The buffer is bounded by a message-byte budget; oldest entries
--- drop when over budget.
+-- Bounded capture for one Peer VM's LogService callbacks.
+-- Powers get_runtime_logs without parenting state to the DataModel.
 --
--- Capture caveat: returned entries reflect which plugin buffer CAPTURED the
--- entry, NOT which peer's script originated the print. LogService reflects
--- prints across peers in ordinary Studio Play (a server print can appear in
--- server and client LogService:GetLogHistory()). The MCP-side aggregator
--- exposes that as capturedBy, and only promotes it to origin peer in
--- StudioTestService multiplayer sessions where peer attribution is reliable.
+-- A Studio process can host several Peer VMs, and its LogService callbacks are
+-- delivered in those VM contexts. MCP reads every Peer buffer in an Instance
+-- and merges them into that process's log stream. Multiplayer Group Instances
+-- remain isolated and are returned independently.
 local _services = TS.import(script, script.Parent.Parent, "node_modules", "@rbxts", "services")
 local LogService = _services.LogService
 local RunService = _services.RunService
+local PeerRole = TS.import(script, script.Parent, "PeerRole")
 local MAX_BYTES = 64 * 1024
 local HARD_ENTRY_CAP = 50_000
 local entries = {}
@@ -8954,7 +9135,7 @@ local function seedRuntimeHistory()
 	if not ok then
 		return nil
 	end
-	local isEdit = not RunService:IsRunning()
+	local isEdit = PeerRole.detect() == "edit"
 	-- GetLogHistory timestamps and DateTime.now() share Unix time, while
 	-- os.clock() is elapsed time for this Studio process. Their difference is
 	-- therefore the process launch boundary. Edit-mode history is filtered to
@@ -8990,16 +9171,7 @@ local function install()
 		pushEntry(msg, t, nil, context)
 	end)
 end
-local function detectPeer()
-	if not RunService:IsRunning() then
-		return "edit"
-	end
-	if RunService:IsServer() then
-		return "server"
-	end
-	return "client"
-end
-local function query(opts, capturedBy)
+local function query(opts)
 	local _result
 	if opts.since ~= nil then
 		-- ▼ ReadonlyArray.filter ▼
@@ -9070,7 +9242,6 @@ local function query(opts, capturedBy)
 	end
 	local last = if #entries > 0 then entries[#entries] else nil
 	local _object = {
-		capturedBy = capturedBy,
 		entries = result,
 		totalDropped = totalDropped,
 	}
@@ -9090,13 +9261,12 @@ local function query(opts, capturedBy)
 end
 return {
 	install = install,
-	detectPeer = detectPeer,
 	query = query,
 }
 ]]></string>
         </Properties>
       </Item>
-      <Item class="ModuleScript" referent="31">
+      <Item class="ModuleScript" referent="32">
         <Properties>
           <string name="Name">ScriptSearch</string>
           <string name="Source"><![CDATA[-- Compiled with roblox-ts v3.0.0
@@ -9423,7 +9593,7 @@ return {
 ]]></string>
         </Properties>
       </Item>
-      <Item class="ModuleScript" referent="32">
+      <Item class="ModuleScript" referent="33">
         <Properties>
           <string name="Name">ServerUrlSettings</string>
           <string name="Source"><![CDATA[-- Compiled with roblox-ts v3.0.0
@@ -9470,14 +9640,14 @@ local function addUnique(values, value)
 		table.insert(_values_1, _value_1)
 	end
 end
-local function computeInstanceIds(options)
-	local ids = {}
+local function computePlaceKeys(options)
+	local placeKeys = {}
 	if game.PlaceId ~= 0 then
-		addUnique(ids, `place:{tostring(game.PlaceId)}`)
+		addUnique(placeKeys, `place:{tostring(game.PlaceId)}`)
 	end
 	local existing = ServerStorage:GetAttribute("__MCPPlaceId")
 	if type(existing) == "string" and existing ~= "" then
-		addUnique(ids, `anon:{existing}`)
+		addUnique(placeKeys, `anon:{existing}`)
 	else
 		local _condition = game.PlaceId == 0
 		if _condition then
@@ -9492,13 +9662,13 @@ local function computeInstanceIds(options)
 			pcall(function()
 				return ServerStorage:SetAttribute("__MCPPlaceId", fresh)
 			end)
-			addUnique(ids, `anon:{fresh}`)
+			addUnique(placeKeys, `anon:{fresh}`)
 		end
 	end
-	return ids
+	return placeKeys
 end
-local function settingKey(instanceId)
-	return SETTING_KEY_PREFIX .. instanceId
+local function settingKey(placeKey)
+	return SETTING_KEY_PREFIX .. placeKey
 end
 local function readSettingString(key)
 	if not pluginRef then
@@ -9527,21 +9697,21 @@ local function rememberServerUrl(serverUrl)
 		return nil
 	end
 	writeSettingString(GLOBAL_SETTING_KEY, normalized)
-	for _, instanceId in computeInstanceIds({
+	for _, placeKey in computePlaceKeys({
 		createAnonymous = true,
 	}) do
-		writeSettingString(settingKey(instanceId), normalized)
+		writeSettingString(settingKey(placeKey), normalized)
 	end
 end
 local function readServerUrl()
 	if not pluginRef then
 		return nil
 	end
-	-- Reading settings should not mint a place identity. Client play DMs have
-	-- their own ServerStorage; creating an id there makes a misleading anon id
-	-- that never matches the edit/server bridge identity.
-	for _, instanceId in computeInstanceIds() do
-		local remembered = readSettingString(settingKey(instanceId))
+	-- Reading settings should not mint a place key. Client play DataModels have
+	-- their own ServerStorage; creating a key there would not match the
+	-- edit/server place-scoped setting.
+	for _, placeKey in computePlaceKeys() do
+		local remembered = readSettingString(settingKey(placeKey))
 		if remembered ~= nil then
 			return remembered
 		end
@@ -9562,11 +9732,11 @@ return {
 ]]></string>
         </Properties>
       </Item>
-      <Item class="ModuleScript" referent="33">
+      <Item class="ModuleScript" referent="34">
         <Properties>
           <string name="Name">State</string>
           <string name="Source"><![CDATA[-- Compiled with roblox-ts v3.0.0
-local CURRENT_VERSION = "3.0.4"
+local CURRENT_VERSION = "3.1.0"
 local PLUGIN_VARIANT = "main"
 local BASE_PORT = 58741
 local function createConnection(port)
@@ -9596,40 +9766,18 @@ return {
 ]]></string>
         </Properties>
       </Item>
-      <Item class="ModuleScript" referent="34">
+      <Item class="ModuleScript" referent="35">
         <Properties>
           <string name="Name">StopPlayMonitor</string>
           <string name="Source"><![CDATA[-- Compiled with roblox-ts v3.0.0
 local TS = require(script.Parent.Parent.include.RuntimeLib)
--- Cross-DM stop_playtest signaling via plugin:SetSetting, scoped by
--- per-instance setting key so the same Studio process can host playtests
--- for multiple places without one place's stop_playtest yanking another's.
--- During publish-after-connect, both "anon:<uuid>" and "place:<PlaceId>"
--- can refer to the same Studio place, so stop requests are mirrored across
--- both keys while the monitor waits for a matching result on either key.
---
--- `plugin:SetSetting` / `plugin:GetSetting` is a per-plugin persistent store
--- shared across every DataModel the plugin runs in (edit DMs, play-server
--- DMs, play-client DMs). For each connected place we use a dedicated key
--- "MCP_STOP_PLAY_<instanceId>" as a tiny request/result mailbox:
---
---   * The edit DM's handler writes a tokenized stop request into its own key
---     (computed from its placeId / ServerStorage anon UUID).
---   * Each play-server DM's monitor loop polls the key matching its own
---     instanceId at 1Hz. On a fresh token, it calls StudioTestService:EndTest
---     and writes a matching result token. Play-server DMs for other places
---     never touch this key.
---   * The edit DM waits up to ~8s for its result token, confirming a matching
---     play-server actually consumed the request.
---
--- Earlier versions used a single shared boolean flag, which let any
--- play-server DM in the same Studio process consume any place's stop
--- request — silently yanking teammates' playtests. The per-key scoping
--- below is the fix.
+-- Cross-DataModel stop_playtest signaling via plugin settings. Solo edit and
+-- runtime peers share one process instanceId through PluginSession's topology
+-- marker, so only the intended Studio process can consume the request.
 local _services = TS.import(script, script.Parent.Parent, "node_modules", "@rbxts", "services")
 local HttpService = _services.HttpService
 local RunService = _services.RunService
-local ServerStorage = _services.ServerStorage
+local PluginSession = TS.import(script, script.Parent, "PluginSession")
 local StudioTestService = game:GetService("StudioTestService")
 local SETTING_KEY_PREFIX = "MCP_STOP_PLAY_"
 -- Keep this conservative. plugin:GetSetting is backed by Studio's plugin
@@ -9646,55 +9794,12 @@ local WAIT_POLL_SEC = 0.1
 local REQUEST_TTL_SEC = 12.0
 local pluginRef
 local endTestIssued = false
+local transportLifecycle
 local function init(p)
 	pluginRef = p
 end
--- Mirror of PluginSession's place identity rules. Duplicated here because
--- StopPlayMonitor runs in both edit and play-server DMs, and both must
--- agree on the place identifier (published places: placeId; unpublished:
--- UUID on ServerStorage's __MCPPlaceId attribute, travels with the .rbxl
--- into the play DM).
-local function addUnique(values, value)
-	local _values = values
-	local _value = value
-	if not (table.find(_values, _value) ~= nil) then
-		local _values_1 = values
-		local _value_1 = value
-		table.insert(_values_1, _value_1)
-	end
-end
-local function computeInstanceIds()
-	local ids = {}
-	if game.PlaceId ~= 0 then
-		addUnique(ids, `place:{tostring(game.PlaceId)}`)
-	end
-	local existing = ServerStorage:GetAttribute("__MCPPlaceId")
-	if type(existing) == "string" and existing ~= "" then
-		addUnique(ids, `anon:{existing}`)
-	elseif game.PlaceId == 0 then
-		local fresh = HttpService:GenerateGUID(false)
-		pcall(function()
-			return ServerStorage:SetAttribute("__MCPPlaceId", fresh)
-		end)
-		addUnique(ids, `anon:{fresh}`)
-	end
-	return ids
-end
-local function settingKey(instanceId)
-	return SETTING_KEY_PREFIX .. instanceId
-end
-local function settingKeys()
-	local _exp = computeInstanceIds()
-	-- ▼ ReadonlyArray.map ▼
-	local _newValue = table.create(#_exp)
-	local _callback = function(instanceId)
-		return settingKey(instanceId)
-	end
-	for _k, _v in _exp do
-		_newValue[_k] = _callback(_v, _k - 1, _exp)
-	end
-	-- ▲ ReadonlyArray.map ▲
-	return _newValue
+local function settingKey()
+	return SETTING_KEY_PREFIX .. PluginSession.getInstanceId()
 end
 local function readSetting(key)
 	if not pluginRef then
@@ -9789,26 +9894,39 @@ local function handleStopRequest(key, request)
 		return nil
 	end
 	endTestIssued = true
+	local lifecycle = transportLifecycle
+	if lifecycle ~= nil then
+		local closeOk, closeError = pcall(lifecycle.beforeEndTest)
+		if not closeOk then
+			warn(`[robloxstudio-mcp] Failed to close the play-server transport before EndTest: {tostring(closeError)}`)
+		end
+	end
 	local endOk, endErr = pcall(function()
 		return StudioTestService:EndTest("stopped_by_mcp")
 	end)
 	writeResult(key, request, endOk, if endOk then nil else tostring(endErr))
 	if not endOk then
 		endTestIssued = false
+		if lifecycle ~= nil then
+			local restoreOk, restoreError = pcall(lifecycle.afterEndTestFailure)
+			if not restoreOk then
+				warn(`[robloxstudio-mcp] Failed to restore the play-server transport after EndTest failed: {tostring(restoreError)}`)
+			end
+		end
 	end
 end
-local function startMonitor()
+local function startMonitor(lifecycle)
+	transportLifecycle = lifecycle
 	if not pluginRef then
 		warn("[robloxstudio-mcp] StopPlayMonitor.startMonitor called before init; skipping")
 		return nil
 	end
 	task.spawn(function()
 		while true do
-			for _, myKey in settingKeys() do
-				local payload = decodePayload(readSetting(myKey))
-				if payload then
-					handleStopRequest(myKey, payload)
-				end
+			local myKey = settingKey()
+			local payload = decodePayload(readSetting(myKey))
+			if payload then
+				handleStopRequest(myKey, payload)
 			end
 			task.wait(POLL_INTERVAL_SEC)
 		end
@@ -9826,10 +9944,7 @@ local function requestStop()
 		id = requestId,
 		requestedAt = tick(),
 	}
-	local ok = false
-	for _, myKey in settingKeys() do
-		ok = writePayload(myKey, payload) or ok
-	end
+	local ok = writePayload(settingKey(), payload)
 	return {
 		ok = ok,
 		requestId = if ok then requestId else nil,
@@ -9845,15 +9960,13 @@ local function waitForConsumption(requestId)
 	end
 	local start = tick()
 	while tick() - start < WAIT_FOR_CONSUMPTION_TIMEOUT_SEC do
-		for _, myKey in settingKeys() do
-			local payload = decodePayload(readSetting(myKey))
-			if payload and payload.kind == "result" and payload.id == requestId then
-				return {
-					ok = payload.ok == true,
-					consumed = true,
-					error = payload.error,
-				}
-			end
+		local payload = decodePayload(readSetting(settingKey()))
+		if payload and payload.kind == "result" and payload.id == requestId then
+			return {
+				ok = payload.ok == true,
+				consumed = true,
+				error = payload.error,
+			}
 		end
 		task.wait(WAIT_POLL_SEC)
 	end
@@ -9867,15 +9980,14 @@ local function clearPending(requestId)
 	if not pluginRef then
 		return nil
 	end
-	for _, myKey in settingKeys() do
-		if requestId ~= nil then
-			local payload = decodePayload(readSetting(myKey))
-			if payload and payload.id ~= requestId then
-				continue
-			end
+	local myKey = settingKey()
+	if requestId ~= nil then
+		local payload = decodePayload(readSetting(myKey))
+		if payload and payload.id ~= requestId then
+			return nil
 		end
-		writeSetting(myKey, false)
 	end
+	writeSetting(myKey, false)
 end
 return {
 	init = init,
@@ -9887,7 +9999,7 @@ return {
 ]]></string>
         </Properties>
       </Item>
-      <Item class="ModuleScript" referent="35">
+      <Item class="ModuleScript" referent="36">
         <Properties>
           <string name="Name">StudioEventStream</string>
           <string name="Source"><![CDATA[-- Compiled with roblox-ts v3.0.0
@@ -9903,6 +10015,7 @@ local MAX_TERMINAL_RESPONSES = 256
 local STREAM_SILENCE_TIMEOUT_SECONDS = 20
 local options
 local active = false
+local shutdownSuspended = false
 local generation = 0
 local reconnectAttempt = 0
 local streamClient
@@ -9940,8 +10053,8 @@ local function decodeMessage(message)
 		}
 	end
 	if envelope.kind == "status" then
-		local _knownInstance = envelope.knownInstance
-		local _condition = not (type(_knownInstance) == "boolean")
+		local _knownPeer = envelope.knownPeer
+		local _condition = not (type(_knownPeer) == "boolean")
 		if not _condition then
 			local _mcpConnected = envelope.mcpConnected
 			_condition = not (type(_mcpConnected) == "boolean")
@@ -9951,7 +10064,7 @@ local function decodeMessage(message)
 		end
 		local _object = {
 			kind = "status",
-			knownInstance = envelope.knownInstance,
+			knownPeer = envelope.knownPeer,
 			mcpConnected = envelope.mcpConnected,
 		}
 		local _left = "serverVersion"
@@ -9984,8 +10097,8 @@ local function decodeMessage(message)
 		local _requestId = envelope.requestId
 		local _condition = not (type(_requestId) == "string")
 		if not _condition then
-			local _logicalSessionId = envelope.logicalSessionId
-			_condition = not (type(_logicalSessionId) == "string")
+			local _peerId = envelope.peerId
+			_condition = not (type(_peerId) == "string")
 			if not _condition then
 				local _target = envelope.target
 				_condition = not (type(_target) == "string")
@@ -10013,7 +10126,7 @@ local function decodeMessage(message)
 		return {
 			kind = "request",
 			requestId = envelope.requestId,
-			logicalSessionId = envelope.logicalSessionId,
+			peerId = envelope.peerId,
 			target = envelope.target,
 			endpoint = envelope.endpoint,
 			data = data,
@@ -10035,6 +10148,20 @@ local function closeCurrentStream()
 		end)
 	end
 end
+local function disconnectSession(currentOptions)
+	pcall(function()
+		return HttpService:RequestAsync({
+			Url = `{currentOptions.serverUrl}/disconnect`,
+			Method = "POST",
+			Headers = {
+				["Content-Type"] = "application/json",
+			},
+			Body = HttpService:JSONEncode({
+				peerId = PluginSession.peerId,
+			}),
+		})
+	end)
+end
 local function responseRetryDelay(attempt)
 	return math.min(INITIAL_RESPONSE_RETRY_DELAY_SECONDS * math.pow(2, math.max(attempt - 1, 0)), MAX_RESPONSE_RETRY_DELAY_SECONDS)
 end
@@ -10351,15 +10478,23 @@ local function parseReadyResponse(body)
 		if not _condition then
 			_condition = value.assignedRole == ""
 			if not _condition then
-				local _instanceId = value.instanceId
-				_condition = not (type(_instanceId) == "string")
+				local _peerId = value.peerId
+				_condition = not (type(_peerId) == "string")
 				if not _condition then
-					_condition = value.instanceId == ""
+					_condition = value.peerId == ""
 					if not _condition then
-						local _serverVersion = value.serverVersion
-						_condition = not (type(_serverVersion) == "string")
+						local _instanceId = value.instanceId
+						_condition = not (type(_instanceId) == "string")
 						if not _condition then
-							_condition = value.serverVersion == ""
+							_condition = value.instanceId == ""
+							if not _condition then
+								local _condition_1 = value.multiplayerGroupId ~= nil
+								if _condition_1 then
+									local _multiplayerGroupId = value.multiplayerGroupId
+									_condition_1 = not (type(_multiplayerGroupId) == "string")
+								end
+								_condition = _condition_1
+							end
 						end
 					end
 				end
@@ -10372,8 +10507,9 @@ local function parseReadyResponse(body)
 	return {
 		success = true,
 		assignedRole = value.assignedRole,
+		peerId = value.peerId,
 		instanceId = value.instanceId,
-		serverVersion = value.serverVersion,
+		multiplayerGroupId = value.multiplayerGroupId,
 	}
 end
 local refresh
@@ -10389,10 +10525,10 @@ function connect(expectedGeneration)
 	})
 	task.spawn(function()
 		local instanceId = PluginSession.getInstanceId()
+		local multiplayerGroupId = PluginSession.getMultiplayerGroupId()
 		local readyUrl = `{currentOptions.serverUrl}/ready`
-		local physicalRole = PluginSession.getRole()
-		local readyPayload = PluginSession.createReadyPayload(PluginSession.id, physicalRole)
-		readyPayload.pluginReady = true
+		local transportRole = PluginSession.getRole()
+		local readyPayload = PluginSession.createReadyPayload(PluginSession.peerId, transportRole, instanceId, multiplayerGroupId)
 		if not active or generation ~= expectedGeneration or options ~= currentOptions then
 			return nil
 		end
@@ -10409,12 +10545,12 @@ function connect(expectedGeneration)
 		if not active or generation ~= expectedGeneration or options ~= currentOptions then
 			return nil
 		end
-		local readyLogKey = `{currentOptions.serverUrl}|{instanceId}|{physicalRole}`
+		local readyLogKey = `{currentOptions.serverUrl}|{PluginSession.peerId}`
 		if not readyOk then
 			local detail = HttpDiagnostics.formatRequestFailure(readyUrl, false, readyResult)
 			if not (readyFailureLogKeys[readyLogKey] ~= nil) then
 				readyFailureLogKeys[readyLogKey] = true
-				warn(`[robloxstudio-mcp] /ready failed for {instanceId}/{physicalRole}: {detail}`)
+				warn(`[robloxstudio-mcp] /ready failed for {instanceId}/{transportRole}: {detail}`)
 			end
 			scheduleReconnect(expectedGeneration, detail)
 			return nil
@@ -10423,14 +10559,14 @@ function connect(expectedGeneration)
 			local detail = HttpDiagnostics.formatRequestFailure(readyUrl, true, readyResult)
 			if not (readyFailureLogKeys[readyLogKey] ~= nil) then
 				readyFailureLogKeys[readyLogKey] = true
-				warn(`[robloxstudio-mcp] /ready rejected for {instanceId}/{physicalRole}: {detail}`)
+				warn(`[robloxstudio-mcp] /ready rejected for {instanceId}/{transportRole}: {detail}`)
 			end
 			scheduleReconnect(expectedGeneration, detail, readyResult.StatusCode == 409)
 			return nil
 		end
 		local readyData = parseReadyResponse(readyResult.Body)
-		if readyData == nil then
-			scheduleReconnect(expectedGeneration, "Invalid /ready response: expected the bundled server protocol")
+		if readyData == nil or readyData.peerId ~= PluginSession.peerId or readyData.instanceId ~= instanceId or readyData.multiplayerGroupId ~= multiplayerGroupId then
+			scheduleReconnect(expectedGeneration, "Invalid /ready response: expected the registered Peer topology")
 			return nil
 		end
 		if readyFailureLogKeys[readyLogKey] ~= nil then
@@ -10442,7 +10578,7 @@ function connect(expectedGeneration)
 		end)
 		local createOk, createdClient = pcall(function()
 			return HttpService:CreateWebStreamClient(Enum.WebStreamClientType.SSE, {
-				Url = `{currentOptions.serverUrl}/events?pluginSessionId={PluginSession.id}`,
+				Url = `{currentOptions.serverUrl}/events?peerId={PluginSession.peerId}`,
 				Method = "GET",
 				Headers = {
 					Accept = "text/event-stream",
@@ -10502,7 +10638,7 @@ function connect(expectedGeneration)
 			invokeCallback("event stream status", function()
 				return currentOptions.onStatus(event)
 			end)
-			if not event.knownInstance then
+			if not event.knownPeer then
 				refresh()
 			end
 		end), createdClient.Error:Connect(function(statusCode, message)
@@ -10523,11 +10659,12 @@ function connect(expectedGeneration)
 end
 local stop
 local function start(newOptions)
-	if active then
+	if active or shutdownSuspended then
 		stop()
 	end
 	options = newOptions
 	active = true
+	shutdownSuspended = false
 	reconnectAttempt = 0
 	generation += 1
 	connect(generation)
@@ -10541,12 +10678,39 @@ function refresh()
 	reconnectAttempt = 0
 	connect(generation)
 end
+-- EndTest can tear down a play DataModel without giving Plugin.Unloading a
+-- usable execution window. Release the native WebStreamClient before the
+-- yielding unregister request, but retain local request state and connection
+-- options so a failed EndTest can register again and reconnect.
+local function suspendForShutdown()
+	local currentOptions = options
+	if not active or currentOptions == nil then
+		return nil
+	end
+	active = false
+	shutdownSuspended = true
+	generation += 1
+	reconnectAttempt = 0
+	closeCurrentStream()
+	disconnectSession(currentOptions)
+end
+local function resumeAfterShutdownFailure()
+	if not shutdownSuspended or options == nil then
+		return nil
+	end
+	shutdownSuspended = false
+	active = true
+	generation += 1
+	reconnectAttempt = 0
+	connect(generation)
+end
 function stop()
-	if not active then
+	if not active and not shutdownSuspended then
 		return nil
 	end
 	local currentOptions = options
 	active = false
+	shutdownSuspended = false
 	generation += 1
 	for _, inFlight in inFlightRequests do
 		inFlight.cancelled = true
@@ -10558,30 +10722,72 @@ function stop()
 	options = nil
 	reconnectAttempt = 0
 	if currentOptions ~= nil then
-		pcall(function()
-			return HttpService:RequestAsync({
-				Url = `{currentOptions.serverUrl}/disconnect`,
-				Method = "POST",
-				Headers = {
-					["Content-Type"] = "application/json",
-				},
-				Body = HttpService:JSONEncode({
-					pluginSessionId = PluginSession.id,
-					timestamp = tick(),
-				}),
-			})
-		end)
+		disconnectSession(currentOptions)
 	end
 end
 return {
 	start = start,
 	refresh = refresh,
+	suspendForShutdown = suspendForShutdown,
+	resumeAfterShutdownFailure = resumeAfterShutdownFailure,
 	stop = stop,
 }
 ]]></string>
         </Properties>
       </Item>
-      <Item class="ModuleScript" referent="36">
+      <Item class="ModuleScript" referent="37">
+        <Properties>
+          <string name="Name">TopologyId</string>
+          <string name="Source"><![CDATA[-- Compiled with roblox-ts v3.0.0
+local TS = require(script.Parent.Parent.include.RuntimeLib)
+local HttpService = TS.import(script, script.Parent.Parent, "node_modules", "@rbxts", "services").HttpService
+local BASE36_DIGITS = "0123456789abcdefghijklmnopqrstuvwxyz"
+local TOKEN_LENGTH = 6
+local TOKEN_MODULUS = 2_176_782_336
+local function tokenFromNumber(value)
+	local remaining = math.floor(math.abs(value)) % TOKEN_MODULUS
+	local token = ""
+	for index = 0, TOKEN_LENGTH - 1 do
+		local digit = remaining % 36
+		local _arg0 = digit + 1
+		local _arg1 = digit + 1
+		token = string.sub(BASE36_DIGITS, _arg0, _arg1) .. token
+		remaining = math.floor(remaining / 36)
+	end
+	return `{string.sub(token, 1, 3)}-{string.sub(token, 4, 6)}`
+end
+local function formatId(kind, value)
+	return `{kind}:{tokenFromNumber(value)}`
+end
+local function randomValue()
+	local guidPrefix = string.sub(HttpService:GenerateGUID(false), 1, 8)
+	local _condition = tonumber(guidPrefix, 16)
+	if _condition == nil then
+		_condition = 0
+	end
+	return _condition
+end
+local function createPeerId()
+	return formatId("peer", randomValue())
+end
+local function createInstanceId()
+	return formatId("instance", randomValue())
+end
+local function currentProcessInstanceId()
+	-- Roblox exposes process uptime through os.clock(). Quantizing the recovered
+	-- launch wall-clock to 10 ms gives every VM in one Studio process the same ID.
+	local launchTick = math.round((DateTime.now().UnixTimestampMillis - os.clock() * 1000) / 10)
+	return formatId("instance", launchTick)
+end
+return {
+	createPeerId = createPeerId,
+	createInstanceId = createInstanceId,
+	currentProcessInstanceId = currentProcessInstanceId,
+}
+]]></string>
+        </Properties>
+      </Item>
+      <Item class="ModuleScript" referent="38">
         <Properties>
           <string name="Name">UI</string>
           <string name="Source"><![CDATA[-- Compiled with roblox-ts v3.0.0
@@ -11133,7 +11339,7 @@ return {
 ]]></string>
         </Properties>
       </Item>
-      <Item class="ModuleScript" referent="37">
+      <Item class="ModuleScript" referent="39">
         <Properties>
           <string name="Name">Utils</string>
           <string name="Source"><![CDATA[-- Compiled with roblox-ts v3.0.0
@@ -11974,11 +12180,11 @@ return {
         </Properties>
       </Item>
     </Item>
-    <Item class="Folder" referent="42">
+    <Item class="Folder" referent="44">
       <Properties>
         <string name="Name">include</string>
       </Properties>
-      <Item class="ModuleScript" referent="38">
+      <Item class="ModuleScript" referent="40">
         <Properties>
           <string name="Name">LibMP</string>
           <string name="Source"><![CDATA[-- =============================================================================
@@ -168362,7 +168568,7 @@ return LibMP
 ]]></string>
         </Properties>
       </Item>
-      <Item class="ModuleScript" referent="39">
+      <Item class="ModuleScript" referent="41">
         <Properties>
           <string name="Name">Promise</string>
           <string name="Source"><![CDATA[--[[
@@ -170436,7 +170642,7 @@ return Promise
 ]]></string>
         </Properties>
       </Item>
-      <Item class="ModuleScript" referent="40">
+      <Item class="ModuleScript" referent="42">
         <Properties>
           <string name="Name">RuntimeLib</string>
           <string name="Source"><![CDATA[local Promise = require(script.Parent.Promise)
@@ -170703,15 +170909,15 @@ return TS
         </Properties>
       </Item>
     </Item>
-    <Item class="Folder" referent="43">
+    <Item class="Folder" referent="45">
       <Properties>
         <string name="Name">node_modules</string>
       </Properties>
-      <Item class="Folder" referent="44">
+      <Item class="Folder" referent="46">
         <Properties>
           <string name="Name">@rbxts</string>
         </Properties>
-      <Item class="ModuleScript" referent="41">
+      <Item class="ModuleScript" referent="43">
         <Properties>
           <string name="Name">services</string>
           <string name="Source"><![CDATA[return setmetatable({}, {