@chrrxs/robloxstudio-mcp 2.13.0 → 2.15.0

package/studio-plugin/src/modules/ClientBroker.ts

@@ -1,10 +1,19 @@
 import { HttpService, Players, ReplicatedStorage, RunService, ServerStorage } from "@rbxts/services";
 import RuntimeLogBuffer from "./RuntimeLogBuffer";
 import MemoryHandlers from "./handlers/MemoryHandlers";
+import SceneAnalysisHandlers from "./handlers/SceneAnalysisHandlers";
 import CaptureHandlers from "./handlers/CaptureHandlers";
 import InputHandlers from "./handlers/InputHandlers";
 import LuauExec from "./LuauExec";
 
+interface StudioTestServiceMultiplayer extends StudioTestService {
+	CanLeaveTest(): boolean;
+	LeaveTest(): void;
+	EditModeActive: boolean;
+}
+
+const StudioTestService = game.GetService("StudioTestService") as StudioTestServiceMultiplayer;
+
 // 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
@@ -55,6 +64,7 @@ function resolvePlaceName(): string {
 
 const MCP_URL = "http://localhost:58741";
 const BROKER_NAME = "__MCPClientBroker";
+const BROKER_OWNER_ATTRIBUTE = "__MCPBrokerOwner";
 
 interface ProxyEntry {
 	pluginSessionId: string;
@@ -78,6 +88,9 @@ const CLIENT_BROKER_ALLOWED_ENDPOINTS = new Set<string>([
 	"/api/execute-luau",
 	"/api/get-runtime-logs",
 	"/api/get-memory-breakdown",
+	"/api/get-scene-analysis",
+	"/api/multiplayer-test-state",
+	"/api/multiplayer-test-leave-client",
 	// Screenshot capture must run in the client peer (CaptureService captures
 	// the play viewport there); the edit DM reads the temp id back separately.
 	"/api/capture-begin",
@@ -164,10 +177,56 @@ function handleGetRuntimeLogs(data: Record<string, unknown> | undefined): unknow
 	return RuntimeLogBuffer.query({ since, tail, filter }, "client");
 }
 
+function handleMultiplayerTestState(): unknown {
+	const [argsOk, args] = pcall(() => StudioTestService.GetTestArgs());
+	const [canLeaveOk, canLeave] = pcall(() => StudioTestService.CanLeaveTest());
+	const players = Players.GetPlayers().map((player) => ({
+		name: player.Name,
+		userId: player.UserId,
+		displayName: player.DisplayName,
+	}));
+	players.sort((a, b) => a.name < b.name);
+	return {
+		success: true,
+		peer: "client",
+		isRunning: RunService.IsRunning(),
+		isRunMode: RunService.IsRunMode(),
+		editModeActive: StudioTestService.EditModeActive,
+		testArgsOk: argsOk,
+		testArgs: argsOk ? args : undefined,
+		testArgsError: argsOk ? undefined : tostring(args),
+		players,
+		playerCount: players.size(),
+		localPlayer: Players.LocalPlayer ? Players.LocalPlayer.Name : undefined,
+		canLeaveOk,
+		canLeave: canLeaveOk ? canLeave : false,
+		canLeaveError: canLeaveOk ? undefined : tostring(canLeave),
+	};
+}
+
+function handleMultiplayerTestLeaveClient(): unknown {
+	const [canLeaveOk, canLeave] = pcall(() => StudioTestService.CanLeaveTest());
+	if (!canLeaveOk) {
+		return { error: tostring(canLeave), canLeaveOk: false };
+	}
+	if (!canLeave) {
+		return { error: "This client cannot leave the current test session.", canLeaveOk: true, canLeave: false };
+	}
+	const localPlayer = Players.LocalPlayer ? Players.LocalPlayer.Name : undefined;
+	task.defer(() => {
+		pcall(() => StudioTestService.LeaveTest());
+	});
+	return {
+		success: true,
+		message: "Client leave requested.",
+		localPlayer,
+	};
+}
+
 function setupClientBroker() {
 	const rf = ReplicatedStorage.WaitForChild(BROKER_NAME, 10);
 	if (!rf || !rf.IsA("RemoteFunction")) {
-		warn(`[MCPFork] client: ${BROKER_NAME} not found`);
+		warn(`[robloxstudio-mcp] client: ${BROKER_NAME} not found`);
 		return;
 	}
 	rf.OnClientInvoke = (payload: BrokerEnvelope | undefined) => {
@@ -183,6 +242,15 @@ function setupClientBroker() {
 		if (payload && payload.endpoint === "/api/get-memory-breakdown") {
 			return MemoryHandlers.getMemoryBreakdown(payload.data ?? {});
 		}
+		if (payload && payload.endpoint === "/api/get-scene-analysis") {
+			return SceneAnalysisHandlers.getSceneAnalysis(payload.data ?? {});
+		}
+		if (payload && payload.endpoint === "/api/multiplayer-test-state") {
+			return handleMultiplayerTestState();
+		}
+		if (payload && payload.endpoint === "/api/multiplayer-test-leave-client") {
+			return handleMultiplayerTestLeaveClient();
+		}
 		if (payload && payload.endpoint === "/api/capture-begin") {
 			return CaptureHandlers.captureBegin();
 		}
@@ -201,6 +269,7 @@ function setupClientBroker() {
 }
 
 const proxyByPlayer = new Map<Player, ProxyEntry>();
+let serverBrokerStarted = false;
 
 function pollProxy(proxyId: string, player: Player, rf: RemoteFunction) {
 	while (player.Parent !== undefined && proxyByPlayer.has(player)) {
@@ -262,7 +331,7 @@ function registerProxy(player: Player, rf: RemoteFunction) {
 		isRunning: RunService.IsRunning(),
 	});
 	if (!ok || !res || !res.Success) {
-		warn(`[MCPFork] proxy register failed for ${player.Name}`);
+		warn(`[robloxstudio-mcp] proxy register failed for ${player.Name}`);
 		return;
 	}
 	const body = HttpService.JSONDecode(res.Body) as ReadyResponseBody;
@@ -277,12 +346,18 @@ function registerProxy(player: Player, rf: RemoteFunction) {
 // which doesn't depend on MCP server state or peer registration at all.)
 
 function setupServerBroker() {
+	if (serverBrokerStarted) return;
 	let rf = ReplicatedStorage.FindFirstChild(BROKER_NAME) as RemoteFunction | undefined;
 	if (!rf) {
 		rf = new Instance("RemoteFunction");
 		rf.Name = BROKER_NAME;
 		rf.Parent = ReplicatedStorage;
 	}
+	if (rf.GetAttribute(BROKER_OWNER_ATTRIBUTE) !== undefined) {
+		return;
+	}
+	rf.SetAttribute(BROKER_OWNER_ATTRIBUTE, HttpService.GenerateGUID(false));
+	serverBrokerStarted = true;
 	const broker = rf;
 	Players.PlayerAdded.Connect((p) => registerProxy(p, broker));
 	for (const p of Players.GetPlayers()) {

package/studio-plugin/src/modules/Communication.ts

@@ -16,6 +16,7 @@ import InputHandlers from "./handlers/InputHandlers";
 import LogHandlers from "./handlers/LogHandlers";
 import SerializationHandlers from "./handlers/SerializationHandlers";
 import MemoryHandlers from "./handlers/MemoryHandlers";
+import SceneAnalysisHandlers from "./handlers/SceneAnalysisHandlers";
 import { Connection, RequestPayload, PollResponse, ReadyResponse } from "../types";
 
 // Per-plugin-load random GUID. Used as the /poll URL param so the server
@@ -133,6 +134,11 @@ const routeMap: Record<string, Handler> = {
 	"/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,
@@ -157,6 +163,7 @@ const routeMap: Record<string, Handler> = {
 	"/api/import-rbxm": SerializationHandlers.importRbxm,
 
 	"/api/get-memory-breakdown": MemoryHandlers.getMemoryBreakdown,
+	"/api/get-scene-analysis": SceneAnalysisHandlers.getSceneAnalysis,
 };
 
 function processRequest(request: RequestPayload): unknown {

package/studio-plugin/src/modules/handlers/SceneAnalysisHandlers.ts

@@ -0,0 +1,216 @@
+interface SceneAnalysisServiceLike extends Instance {
+	GetInstanceCompositionAsync(this: SceneAnalysisServiceLike): unknown;
+	GetScriptMemoryAsync(this: SceneAnalysisServiceLike): unknown;
+	GetUnparentedInstancesAsync(this: SceneAnalysisServiceLike): unknown;
+	GetTriangleCompositionAsync(this: SceneAnalysisServiceLike): unknown;
+	GetAnimationMemoryAsync(this: SceneAnalysisServiceLike): unknown;
+	GetAudioMemoryAsync(this: SceneAnalysisServiceLike): unknown;
+}
+
+interface SceneAnalysisNode {
+	Name?: string;
+	Size?: number;
+	Sizes?: Record<string, number>;
+	Children?: SceneAnalysisNode[];
+	AssetId?: string;
+}
+
+interface ModeConfig {
+	method: string;
+	query: (service: SceneAnalysisServiceLike) => unknown;
+	sortByTriangles?: boolean;
+}
+
+const MODE_CONFIGS: Record<string, ModeConfig> = {
+	instance_composition: {
+		method: "GetInstanceCompositionAsync",
+		query: (service) => service.GetInstanceCompositionAsync(),
+	},
+	script_memory: {
+		method: "GetScriptMemoryAsync",
+		query: (service) => service.GetScriptMemoryAsync(),
+	},
+	unparented_instances: {
+		method: "GetUnparentedInstancesAsync",
+		query: (service) => service.GetUnparentedInstancesAsync(),
+	},
+	triangle_composition: {
+		method: "GetTriangleCompositionAsync",
+		query: (service) => service.GetTriangleCompositionAsync(),
+		sortByTriangles: true,
+	},
+	animation_memory: {
+		method: "GetAnimationMemoryAsync",
+		query: (service) => service.GetAnimationMemoryAsync(),
+	},
+	audio_memory: {
+		method: "GetAudioMemoryAsync",
+		query: (service) => service.GetAudioMemoryAsync(),
+	},
+};
+
+const ALL_MODES = [
+	"instance_composition",
+	"script_memory",
+	"unparented_instances",
+	"triangle_composition",
+	"animation_memory",
+	"audio_memory",
+];
+
+function betaDisabledError(): Record<string, unknown> {
+	return {
+		error: "scene_analysis_not_enabled",
+		message: "SceneAnalysisService is not enabled. Enable Scene Analysis in Studio Beta Features and restart Studio.",
+		betaFeatureRequired: true,
+	};
+}
+
+function isBetaDisabledError(value: unknown): boolean {
+	return typeIs(value, "string") && string.find(value, "SceneAnalysisService is not enabled", 1, true)[0] !== undefined;
+}
+
+function getSceneAnalysisService(): SceneAnalysisServiceLike | Record<string, unknown> {
+	const provider = game as unknown as { GetService(serviceName: string): Instance };
+	const [ok, service] = pcall(() => provider.GetService("SceneAnalysisService") as SceneAnalysisServiceLike);
+	if (!ok || !service) {
+		return {
+			error: "scene_analysis_unavailable",
+			message: `SceneAnalysisService is unavailable: ${tostring(service)}`,
+		};
+	}
+	return service;
+}
+
+function normalizeMode(mode: unknown): string | Record<string, unknown> {
+	if (mode === undefined || mode === "all") return "all";
+	if (!typeIs(mode, "string") || MODE_CONFIGS[mode] === undefined) {
+		return {
+			error: "invalid_mode",
+			message: `mode must be one of: all, ${ALL_MODES.join(", ")}`,
+		};
+	}
+	return mode;
+}
+
+function normalizeTopN(topN: unknown): number {
+	if (!typeIs(topN, "number")) return 10;
+	return math.clamp(math.floor(topN), 1, 100);
+}
+
+function countLeaves(node: SceneAnalysisNode): number {
+	const children = node.Children;
+	if (children && children.size() > 0) {
+		let total = 0;
+		for (const child of children) total += countLeaves(child);
+		return total;
+	}
+	return 1;
+}
+
+function flattenLeaves(node: SceneAnalysisNode, out: SceneAnalysisNode[]): void {
+	const children = node.Children;
+	if (children && children.size() > 0) {
+		for (const child of children) flattenLeaves(child, out);
+		return;
+	}
+	out.push(node);
+}
+
+function compactEntry(node: SceneAnalysisNode): Record<string, unknown> {
+	const entry: Record<string, unknown> = {
+		name: node.Name,
+	};
+	if (node.Size !== undefined) entry.size = node.Size;
+	if (node.Sizes !== undefined) entry.sizes = node.Sizes;
+	if (node.AssetId !== undefined) entry.asset_id = node.AssetId;
+	return entry;
+}
+
+function compactRoot(node: SceneAnalysisNode, leafCount: number): Record<string, unknown> {
+	const children = node.Children;
+	const root: Record<string, unknown> = {
+		name: node.Name,
+		child_count: children ? children.size() : 0,
+		leaf_count: leafCount,
+	};
+	if (node.Size !== undefined) root.size = node.Size;
+	if (node.Sizes !== undefined) root.sizes = node.Sizes;
+	return root;
+}
+
+function metric(node: SceneAnalysisNode, sortByTriangles: boolean): number {
+	if (sortByTriangles) {
+		const sizes = node.Sizes;
+		const triangles = sizes ? sizes.Triangles : undefined;
+		return triangles ?? 0;
+	}
+	return node.Size ?? 0;
+}
+
+function summarizeMode(
+	mode: string,
+	config: ModeConfig,
+	service: SceneAnalysisServiceLike,
+	topN: number,
+	raw: boolean,
+): Record<string, unknown> {
+	const started = os.clock();
+	const [ok, result] = pcall(() => config.query(service) as SceneAnalysisNode);
+	const elapsedMs = math.floor((os.clock() - started) * 1000);
+
+	if (!ok) {
+		if (isBetaDisabledError(result)) return betaDisabledError();
+		return {
+			error: "scene_analysis_query_failed",
+			mode,
+			method: config.method,
+			message: tostring(result),
+		};
+	}
+
+	const tree = result as SceneAnalysisNode;
+	const leaves: SceneAnalysisNode[] = [];
+	flattenLeaves(tree, leaves);
+	leaves.sort((a, b) => metric(a, config.sortByTriangles === true) > metric(b, config.sortByTriangles === true));
+
+	const top: Record<string, unknown>[] = [];
+	for (let i = 0; i < math.min(topN, leaves.size()); i++) {
+		top.push(compactEntry(leaves[i]));
+	}
+
+	const body: Record<string, unknown> = {
+		mode,
+		method: config.method,
+		elapsed_ms: elapsedMs,
+		root: compactRoot(tree, leaves.size()),
+		top,
+	};
+	if (raw) body.tree = tree;
+	return body;
+}
+
+function getSceneAnalysis(requestData: Record<string, unknown>): unknown {
+	const mode = normalizeMode(requestData.mode);
+	if (!typeIs(mode, "string")) return mode;
+
+	const serviceOrError = getSceneAnalysisService();
+	if (!serviceOrError.IsA) return serviceOrError;
+	const service = serviceOrError as SceneAnalysisServiceLike;
+	const topN = normalizeTopN(requestData.topN);
+	const raw = requestData.raw === true;
+
+	if (mode !== "all") {
+		return summarizeMode(mode, MODE_CONFIGS[mode], service, topN, raw);
+	}
+
+	const body: Record<string, unknown> = {};
+	for (const m of ALL_MODES) {
+		const result = summarizeMode(m, MODE_CONFIGS[m], service, topN, raw);
+		if (result.error === "scene_analysis_not_enabled") return result;
+		body[m] = result;
+	}
+	return body;
+}
+
+export = { getSceneAnalysis };

package/studio-plugin/src/modules/handlers/TestHandlers.ts

@@ -1,8 +1,16 @@
-import { HttpService, LogService, RunService } from "@rbxts/services";
+import { HttpService, LogService, Players, RunService } from "@rbxts/services";
 import { installBridges, ensureBridgesInstalled } from "../EvalBridges";
 import StopPlayMonitor from "../StopPlayMonitor";
 
-const StudioTestService = game.GetService("StudioTestService");
+interface StudioTestServiceMultiplayer extends StudioTestService {
+	ExecuteMultiplayerTestAsync(numPlayers: number, testArgs: unknown): unknown;
+	AddPlayers(numPlayers: number): void;
+	CanLeaveTest(): boolean;
+	LeaveTest(): void;
+	EditModeActive: boolean;
+}
+
+const StudioTestService = game.GetService("StudioTestService") as StudioTestServiceMultiplayer;
 const ServerScriptService = game.GetService("ServerScriptService");
 const ScriptEditorService = game.GetService("ScriptEditorService");
 
@@ -27,6 +35,59 @@ let testError: string | undefined;
 let stopListenerScript: Script | undefined;
 let navResultCallback: ((json: string) => void) | undefined;
 
+type MultiplayerPhase = "idle" | "starting" | "running" | "completed" | "failed";
+
+interface MultiplayerSessionState {
+	phase: MultiplayerPhase;
+	testId?: string;
+	numPlayers?: number;
+	testArgs?: unknown;
+	startedAt?: number;
+	completedAt?: number;
+	ok?: boolean;
+	result?: unknown;
+	error?: string;
+}
+
+let multiplayerState: MultiplayerSessionState = { phase: "idle" };
+
+function detectPeerRole(): string {
+	if (!RunService.IsRunning()) return "edit";
+	if (RunService.IsServer()) return "server";
+	return "client";
+}
+
+function getPlayersSnapshot() {
+	const players = Players.GetPlayers().map((player) => ({
+		name: player.Name,
+		userId: player.UserId,
+		displayName: player.DisplayName,
+	}));
+	players.sort((a, b) => a.name < b.name);
+	return players;
+}
+
+function cloneMultiplayerState(): MultiplayerSessionState {
+	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,
+	};
+}
+
+function normalizeNumPlayers(value: unknown): number | undefined {
+	if (!typeIs(value, "number")) return undefined;
+	const n = math.floor(value);
+	if (n !== value || n < 1 || n > 8) return undefined;
+	return n;
+}
+
 function buildCommandListenerSource(): string {
 	return `local LogService = game:GetService("LogService")
 local PathfindingService = game:GetService("PathfindingService")
@@ -124,6 +185,10 @@ function startPlaytest(requestData: Record<string, unknown>) {
 		return { error: 'mode must be "play" or "run"' };
 	}
 
+	if (numPlayers !== undefined) {
+		return { error: "start_playtest is single-player only. Use multiplayer_test_start for multi-client StudioTestService sessions." };
+	}
+
 	// 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).
@@ -180,11 +245,6 @@ function startPlaytest(requestData: Record<string, unknown>) {
 		warn(`[MCP] Eval bridge install failed: ${bridgeInstall.error}`);
 	}
 
-	if (numPlayers !== undefined && mode === "run") {
-		const TestService = game.GetService("TestService") as TestService & { NumberOfPlayers: number };
-		TestService.NumberOfPlayers = math.clamp(numPlayers, 1, 8);
-	}
-
 	task.spawn(() => {
 		const [ok, result] = pcall(() => {
 			if (mode === "play") {
@@ -211,13 +271,9 @@ function startPlaytest(requestData: Record<string, unknown>) {
 		ensureBridgesInstalled();
 	});
 
-	const msg = numPlayers !== undefined
-		? `Playtest started in ${mode} mode with ${numPlayers} player(s).`
-		: `Playtest started in ${mode} mode.`;
-
 	const response: Record<string, unknown> = {
 		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
@@ -294,6 +350,179 @@ function getPlaytestOutput(_requestData: Record<string, unknown>) {
 	};
 }
 
+function multiplayerTestStart(requestData: Record<string, unknown>) {
+	if (RunService.IsRunning()) {
+		return { error: "multiplayer_test_start must be called on the edit DataModel. Route with target=edit." };
+	}
+
+	const numPlayers = normalizeNumPlayers(requestData.numPlayers);
+	if (numPlayers === undefined) {
+		return { error: "numPlayers must be an integer from 1 to 8" };
+	}
+
+	if (multiplayerState.phase === "starting" || multiplayerState.phase === "running") {
+		return {
+			error: "A multiplayer Studio test is already running",
+			state: cloneMultiplayerState(),
+		};
+	}
+
+	const testArgs = requestData.testArgs !== undefined ? requestData.testArgs : {};
+	const testId = HttpService.GenerateGUID(false);
+
+	const bridgeInstall = installBridges();
+	if (!bridgeInstall.installed) {
+		warn(`[MCP] Eval bridge install failed: ${bridgeInstall.error}`);
+	}
+
+	multiplayerState = {
+		phase: "starting",
+		testId,
+		numPlayers,
+		testArgs,
+		startedAt: tick(),
+	};
+
+	task.spawn(() => {
+		multiplayerState.phase = "running";
+		const [ok, result] = pcall(() => {
+			return StudioTestService.ExecuteMultiplayerTestAsync(numPlayers, testArgs);
+		});
+
+		multiplayerState.completedAt = tick();
+		multiplayerState.ok = ok;
+		if (ok) {
+			multiplayerState.phase = "completed";
+			multiplayerState.result = result;
+			multiplayerState.error = undefined;
+		} else {
+			multiplayerState.phase = "failed";
+			multiplayerState.result = undefined;
+			multiplayerState.error = tostring(result);
+		}
+
+		ensureBridgesInstalled();
+	});
+
+	const response: Record<string, unknown> = {
+		success: true,
+		message: `Multiplayer Studio test starting with ${numPlayers} player(s).`,
+		testId,
+		phase: multiplayerState.phase,
+		numPlayers,
+		testArgs,
+	};
+	if (!bridgeInstall.installed) {
+		response.evalBridgesError = bridgeInstall.error;
+	}
+	return response;
+}
+
+function multiplayerTestState(_requestData: Record<string, unknown>) {
+	const peer = detectPeerRole();
+	const response: Record<string, unknown> = {
+		success: true,
+		peer,
+		isRunning: RunService.IsRunning(),
+		isRunMode: RunService.IsRunMode(),
+		editModeActive: StudioTestService.EditModeActive,
+	};
+
+	if (peer === "edit") {
+		response.session = cloneMultiplayerState();
+		return response;
+	}
+
+	const [argsOk, args] = pcall(() => StudioTestService.GetTestArgs());
+	response.testArgsOk = argsOk;
+	response.testArgs = argsOk ? args : undefined;
+	if (!argsOk) response.testArgsError = tostring(args);
+
+	const players = getPlayersSnapshot();
+	response.players = players;
+	response.playerCount = players.size();
+
+	if (peer === "client") {
+		response.localPlayer = Players.LocalPlayer ? Players.LocalPlayer.Name : undefined;
+		const [canLeaveOk, canLeave] = pcall(() => StudioTestService.CanLeaveTest());
+		response.canLeaveOk = canLeaveOk;
+		response.canLeave = canLeaveOk ? canLeave : false;
+		if (!canLeaveOk) response.canLeaveError = tostring(canLeave);
+	}
+
+	return response;
+}
+
+function multiplayerTestAddPlayers(requestData: Record<string, unknown>) {
+	if (!RunService.IsRunning() || !RunService.IsServer()) {
+		return { error: "multiplayer_test_add_players must be called on the running server peer. Route with target=server." };
+	}
+	const numPlayers = normalizeNumPlayers(requestData.numPlayers);
+	if (numPlayers === undefined) {
+		return { error: "numPlayers must be an integer from 1 to 8" };
+	}
+
+	const before = Players.GetPlayers().size();
+	const [ok, result] = pcall(() => StudioTestService.AddPlayers(numPlayers));
+	if (!ok) {
+		return { error: tostring(result) };
+	}
+
+	const deadline = tick() + ((requestData.timeout as number | undefined) ?? 10);
+	while (Players.GetPlayers().size() < before + numPlayers && tick() < deadline) {
+		task.wait(0.1);
+	}
+
+	const players = getPlayersSnapshot();
+	return {
+		success: true,
+		message: `Requested ${numPlayers} additional player(s).`,
+		playerCount: players.size(),
+		players,
+	};
+}
+
+function multiplayerTestLeaveClient(_requestData: Record<string, unknown>) {
+	if (!RunService.IsRunning() || RunService.IsServer()) {
+		return { error: "multiplayer_test_leave_client must be called on a running client peer. Route with target=client-N." };
+	}
+
+	const [canLeaveOk, canLeave] = pcall(() => StudioTestService.CanLeaveTest());
+	if (!canLeaveOk) {
+		return { error: tostring(canLeave), canLeaveOk: false };
+	}
+	if (!canLeave) {
+		return { error: "This client cannot leave the current test session.", canLeaveOk: true, canLeave: false };
+	}
+
+	const localPlayer = Players.LocalPlayer ? Players.LocalPlayer.Name : undefined;
+	task.defer(() => {
+		pcall(() => StudioTestService.LeaveTest());
+	});
+	return {
+		success: true,
+		message: "Client leave requested.",
+		localPlayer,
+	};
+}
+
+function multiplayerTestEnd(requestData: Record<string, unknown>) {
+	if (!RunService.IsRunning() || !RunService.IsServer()) {
+		return { error: "multiplayer_test_end must be called on the running server peer. Route with target=server." };
+	}
+
+	const value = requestData.value !== undefined ? requestData.value : "ended_by_mcp";
+	const [ok, result] = pcall(() => StudioTestService.EndTest(value));
+	if (!ok) {
+		return { error: tostring(result) };
+	}
+	return {
+		success: true,
+		message: "Multiplayer Studio test end requested.",
+		value,
+	};
+}
+
 function characterNavigation(requestData: Record<string, unknown>) {
 	if (!testRunning) {
 		return { error: "Playtest must be running. Start a playtest in 'play' mode first." };
@@ -344,5 +573,10 @@ export = {
 	startPlaytest,
 	stopPlaytest,
 	getPlaytestOutput,
+	multiplayerTestStart,
+	multiplayerTestState,
+	multiplayerTestAddPlayers,
+	multiplayerTestLeaveClient,
+	multiplayerTestEnd,
 	characterNavigation,
 };