@wp-playground/mcp 3.1.5

package/package.json

@@ -0,0 +1,46 @@
+{
+	"name": "@wp-playground/mcp",
+	"version": "3.1.5",
+	"description": "MCP server for WordPress Playground - enables AI agents to interact with the WordPress Playground website.",
+	"repository": {
+		"type": "git",
+		"url": "https://github.com/WordPress/wordpress-playground"
+	},
+	"homepage": "https://developer.wordpress.org/playground",
+	"author": "The WordPress contributors",
+	"license": "GPL-2.0-or-later",
+	"type": "module",
+	"bin": {
+		"wp-playground-mcp": "./index.js"
+	},
+	"exports": {
+		".": {
+			"import": "./src/index.ts",
+			"require": "./index.cjs"
+		},
+		"./client": {
+			"import": "./src/client.ts",
+			"require": "./client.cjs"
+		},
+		"./package.json": "./package.json"
+	},
+	"publishConfig": {
+		"access": "public",
+		"directory": "../../../dist/packages/playground/mcp"
+	},
+	"main": "./index.cjs",
+	"module": "./index.js",
+	"types": "index.d.ts",
+	"engines": {
+		"node": ">=20.10.0",
+		"npm": ">=10.2.3"
+	},
+	"dependencies": {
+		"@modelcontextprotocol/sdk": "^1.27.0",
+		"ws": "^8.18.0",
+		"zod": "^4.3"
+	},
+	"devDependencies": {
+		"@types/ws": "^8.18.0"
+	}
+}

package/playwright.config.ts

@@ -0,0 +1,35 @@
+import { defineConfig, devices } from '@playwright/test';
+
+export default defineConfig({
+	testDir: './e2e',
+	fullyParallel: false,
+	forbidOnly: !!process.env.CI,
+	retries: process.env.CI ? 2 : 0,
+	// Must be 1: the MCP server supports only one browser connection at a time.
+	workers: 1,
+	reporter: [['list', { printSteps: true }]],
+	use: {
+		baseURL: 'http://127.0.0.1:5400/website-server/',
+		trace: 'on-first-retry',
+		actionTimeout: 120_000,
+		navigationTimeout: 120_000,
+	},
+	timeout: 300_000,
+	expect: { timeout: 60_000 },
+	projects: [
+		{
+			name: 'chromium',
+			use: {
+				...devices['Desktop Chrome'],
+				launchOptions: {
+					args: ['--js-flags=--enable-experimental-webassembly-jspi'],
+				},
+			},
+		},
+	],
+	webServer: {
+		command: 'npx nx run playground-website:dev',
+		url: 'http://127.0.0.1:5400/website-server/',
+		reuseExistingServer: !process.env.CI,
+	},
+});

package/project.json

@@ -0,0 +1,64 @@
+{
+	"name": "playground-mcp",
+	"$schema": "../../../node_modules/nx/schemas/project-schema.json",
+	"sourceRoot": "packages/playground/mcp/src",
+	"projectType": "library",
+	"tags": [],
+	"targets": {
+		"build": {
+			"executor": "nx:noop",
+			"dependsOn": ["build:package-json"]
+		},
+		"build:package-json": {
+			"executor": "@wp-playground/nx-extensions:package-json",
+			"options": {
+				"tsConfig": "packages/playground/mcp/tsconfig.lib.json",
+				"outputPath": "dist/packages/playground/mcp",
+				"buildTarget": "playground-mcp:build:bundle:production"
+			}
+		},
+		"build:bundle": {
+			"executor": "@nx/vite:build",
+			"outputs": ["{options.outputPath}"],
+			"options": {
+				"emptyOutDir": false,
+				"outputPath": "dist/packages/playground/mcp"
+			},
+			"defaultConfiguration": "production",
+			"configurations": {
+				"development": {
+					"minify": false
+				},
+				"production": {
+					"minify": true
+				}
+			}
+		},
+		"test:mcp": {
+			"executor": "nx:run-commands",
+			"options": {
+				"commands": [
+					{
+						"command": "node -e \"if (parseInt(process.versions.node) < 22) { console.error('Node.js version 22 or greater is required'); process.exit(1); }\"",
+						"forwardAllArgs": false
+					},
+					"npx playwright test --config=packages/playground/mcp/playwright.config.ts"
+				],
+				"parallel": false
+			}
+		},
+		"package-for-self-hosting": {
+			"executor": "@wp-playground/nx-extensions:package-for-self-hosting",
+			"dependsOn": ["build"]
+		},
+		"lint": {
+			"executor": "@nx/eslint:lint",
+			"outputs": ["{options.outputFile}"],
+			"options": {
+				"useFlatConfig": false,
+				"lintFilePatterns": ["packages/playground/mcp/**/*.ts"],
+				"maxWarnings": 0
+			}
+		}
+	}
+}

package/src/bridge-client.ts

@@ -0,0 +1,196 @@
+import type { PlaygroundClient } from '@wp-playground/remote';
+import { createToolClient } from './tools/tool-executors';
+import type { ToolClient } from './tools/tool-executors';
+
+/**
+ * Shared configuration for the MCP bridge client and WebMCP.
+ *
+ * Both transports need the same callbacks to interact with
+ * the Playground site list and active client.
+ */
+export interface PlaygroundConfig {
+	getSites: () => Array<{
+		slug: string;
+		name: string;
+		storage: string;
+		isActive: boolean;
+	}>;
+	getPlaygroundClient: (siteSlug: string) => PlaygroundClient | undefined;
+	renameSite?: (siteSlug: string, newName: string) => Promise<void>;
+	saveSite?: (siteSlug: string) => Promise<{ slug: string; storage: string }>;
+	onConnect?: () => void;
+}
+
+export interface McpBridgeHandle {
+	notifySitesChanged: () => void;
+	stop: () => void;
+}
+
+const RECONNECT_INTERVAL_MS = 5000;
+
+export function startMcpBridge(
+	config: PlaygroundConfig,
+	port: number
+): McpBridgeHandle {
+	const tabId = crypto.randomUUID();
+	let ws: WebSocket | null = null;
+	let previousSitesSerialized = '';
+	let reconnectTimer: ReturnType<typeof setTimeout> | null = null;
+	let stopped = false;
+
+	function sendSitesRegistration(socket: WebSocket) {
+		const sites = config.getSites();
+		const serialized = JSON.stringify(sites);
+		if (serialized === previousSitesSerialized) {
+			return;
+		}
+		previousSitesSerialized = serialized;
+		socket.send(JSON.stringify({ type: 'register', tabId, sites }));
+	}
+
+	async function connect() {
+		try {
+			const response = await fetch(
+				`http://127.0.0.1:${port}/bridge-token`
+			);
+			if (!response.ok) {
+				scheduleReconnect();
+				return;
+			}
+			const { token } = await response.json();
+			ws = new WebSocket(`ws://127.0.0.1:${port}?token=${token}`);
+		} catch {
+			scheduleReconnect();
+			return;
+		}
+
+		ws.addEventListener('open', () => {
+			previousSitesSerialized = '';
+			sendSitesRegistration(ws!);
+			config.onConnect?.();
+		});
+
+		ws.addEventListener('message', async (event) => {
+			let message;
+			try {
+				message = JSON.parse(event.data as string);
+			} catch {
+				return;
+			}
+			if (message.type !== 'command') {
+				return;
+			}
+
+			const { id, method, args, siteSlug } = message;
+			try {
+				const value = await handleCommand(
+					config,
+					method,
+					args || [],
+					siteSlug
+				);
+				if (ws?.readyState === WebSocket.OPEN) {
+					ws.send(JSON.stringify({ id, type: 'response', value }));
+				}
+			} catch (error) {
+				const errorMsg =
+					error instanceof Error ? error.message : String(error);
+				if (ws?.readyState === WebSocket.OPEN) {
+					ws.send(
+						JSON.stringify({
+							id,
+							type: 'response',
+							error: errorMsg,
+						})
+					);
+				}
+			}
+		});
+
+		ws.addEventListener('close', () => {
+			ws = null;
+			scheduleReconnect();
+		});
+
+		ws.addEventListener('error', () => {
+			// Error will be followed by close event,
+			// which handles reconnect
+		});
+	}
+
+	function scheduleReconnect() {
+		if (stopped) {
+			return;
+		}
+		reconnectTimer = setTimeout(connect, RECONNECT_INTERVAL_MS);
+	}
+
+	connect();
+
+	return {
+		notifySitesChanged: () => {
+			if (ws?.readyState === WebSocket.OPEN) {
+				sendSitesRegistration(ws);
+			}
+		},
+		stop: () => {
+			stopped = true;
+			if (reconnectTimer !== null) {
+				clearTimeout(reconnectTimer);
+				reconnectTimer = null;
+			}
+			if (ws) {
+				ws.close();
+				ws = null;
+			}
+		},
+	};
+}
+
+async function handleCommand(
+	config: PlaygroundConfig,
+	method: string,
+	args: unknown[],
+	siteSlug: string
+): Promise<unknown> {
+	if (method === '__open_site') {
+		const url = new URL(window.location.href);
+		url.searchParams.set('site-slug', siteSlug);
+		const newWindow = window.open(url.toString(), '_blank');
+		if (!newWindow) {
+			throw new Error(
+				'Pop-up blocked by browser. The user ' +
+					'must allow pop-ups for this site.'
+			);
+		}
+		return true;
+	}
+
+	if (method === '__rename_site') {
+		if (!config.renameSite) {
+			throw new Error('renameSite not configured');
+		}
+		const [newName] = args as [string];
+		await config.renameSite(siteSlug, newName);
+		return true;
+	}
+
+	if (method === '__save_site') {
+		if (!config.saveSite) {
+			throw new Error('saveSite not configured');
+		}
+		return await config.saveSite(siteSlug);
+	}
+
+	const playgroundClient = config.getPlaygroundClient(siteSlug);
+	if (!playgroundClient) {
+		throw new Error(`No active client for site: ${siteSlug}`);
+	}
+
+	const client = createToolClient(playgroundClient);
+	const fn = client[method as keyof ToolClient];
+	if (typeof fn !== 'function') {
+		throw new Error(`Unknown method: ${method}`);
+	}
+	return await (fn as (...a: unknown[]) => Promise<unknown>)(...args);
+}

package/src/bridge-server.spec.ts

@@ -0,0 +1,228 @@
+import { describe, it, expect, afterEach } from 'vitest';
+import WebSocket from 'ws';
+import { PlaygroundBridge } from './bridge-server';
+
+// Use high random port to avoid conflicts
+const getPort = () => 19000 + Math.floor(Math.random() * 1000);
+
+describe('PlaygroundBridge token endpoint', () => {
+	let bridge: PlaygroundBridge;
+
+	afterEach(async () => {
+		await bridge?.close();
+	});
+
+	it('returns a session token for allowed origins', async () => {
+		const port = getPort();
+		bridge = new PlaygroundBridge();
+		await bridge.startWebSocketServer(port);
+
+		const response = await fetch(`http://127.0.0.1:${port}/bridge-token`, {
+			headers: { Origin: 'http://localhost:5400' },
+		});
+
+		expect(response.status).toBe(200);
+		const body = await response.json();
+		expect(body.token).toMatch(
+			/^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/
+		);
+	});
+
+	it('returns the same token on repeated requests', async () => {
+		const port = getPort();
+		bridge = new PlaygroundBridge();
+		await bridge.startWebSocketServer(port);
+
+		const headers = { Origin: 'http://localhost:5400' };
+		const r1 = await fetch(`http://127.0.0.1:${port}/bridge-token`, {
+			headers,
+		});
+		const r2 = await fetch(`http://127.0.0.1:${port}/bridge-token`, {
+			headers,
+		});
+
+		const t1 = (await r1.json()).token;
+		const t2 = (await r2.json()).token;
+		expect(t1).toBe(t2);
+	});
+
+	it('rejects token requests from disallowed origins', async () => {
+		const port = getPort();
+		bridge = new PlaygroundBridge();
+		await bridge.startWebSocketServer(port);
+
+		const response = await fetch(`http://127.0.0.1:${port}/bridge-token`, {
+			headers: { Origin: 'https://evil.com' },
+		});
+
+		expect(response.status).toBe(403);
+	});
+
+	it('returns CORS headers matching the request origin', async () => {
+		const port = getPort();
+		bridge = new PlaygroundBridge();
+		await bridge.startWebSocketServer(port);
+
+		const response = await fetch(`http://127.0.0.1:${port}/bridge-token`, {
+			headers: { Origin: 'http://127.0.0.1:5400' },
+		});
+
+		expect(response.headers.get('access-control-allow-origin')).toBe(
+			'http://127.0.0.1:5400'
+		);
+	});
+
+	it('handles CORS preflight OPTIONS request for disallowed origins', async () => {
+		const port = getPort();
+		bridge = new PlaygroundBridge();
+		await bridge.startWebSocketServer(port);
+
+		const response = await fetch(`http://127.0.0.1:${port}/bridge-token`, {
+			method: 'OPTIONS',
+			headers: {
+				Origin: 'https://evil.com',
+				'Access-Control-Request-Method': 'GET',
+			},
+		});
+
+		expect(response.status).toBe(403);
+	});
+
+	it('handles CORS preflight OPTIONS request', async () => {
+		const port = getPort();
+		bridge = new PlaygroundBridge();
+		await bridge.startWebSocketServer(port);
+
+		const response = await fetch(`http://127.0.0.1:${port}/bridge-token`, {
+			method: 'OPTIONS',
+			headers: {
+				Origin: 'http://localhost:5400',
+				'Access-Control-Request-Method': 'GET',
+			},
+		});
+
+		expect(response.status).toBe(204);
+		expect(response.headers.get('access-control-allow-origin')).toBe(
+			'http://localhost:5400'
+		);
+		expect(response.headers.get('access-control-allow-methods')).toBe(
+			'GET'
+		);
+	});
+});
+
+function waitForWebSocket(
+	ws: WebSocket,
+	state: typeof WebSocket.OPEN | typeof WebSocket.CLOSED
+): Promise<void> {
+	return new Promise((resolve, reject) => {
+		const timeout = setTimeout(() => reject(new Error('Timeout')), 5000);
+		if (ws.readyState === state) {
+			clearTimeout(timeout);
+			resolve();
+			return;
+		}
+		ws.on('open', () => {
+			if (state === WebSocket.OPEN) {
+				clearTimeout(timeout);
+				resolve();
+			}
+		});
+		ws.on('close', () => {
+			clearTimeout(timeout);
+			if (state === WebSocket.CLOSED) {
+				resolve();
+			} else {
+				reject(new Error('WebSocket closed unexpectedly'));
+			}
+		});
+		ws.on('error', () => {
+			// close event follows
+		});
+	});
+}
+
+describe('PlaygroundBridge token validation', () => {
+	let bridge: PlaygroundBridge;
+
+	afterEach(async () => {
+		await bridge?.close();
+	});
+
+	it('accepts WebSocket connections with a valid token', async () => {
+		const port = getPort();
+		bridge = new PlaygroundBridge();
+		await bridge.startWebSocketServer(port);
+
+		const res = await fetch(`http://127.0.0.1:${port}/bridge-token`, {
+			headers: { Origin: 'http://localhost:5400' },
+		});
+		const { token } = await res.json();
+
+		const ws = new WebSocket(`ws://127.0.0.1:${port}?token=${token}`);
+		await waitForWebSocket(ws, WebSocket.OPEN);
+		expect(ws.readyState).toBe(WebSocket.OPEN);
+		ws.close();
+	});
+
+	it('rejects WebSocket connections without a token', async () => {
+		const port = getPort();
+		bridge = new PlaygroundBridge();
+		await bridge.startWebSocketServer(port);
+
+		const ws = new WebSocket(`ws://127.0.0.1:${port}`);
+		await waitForWebSocket(ws, WebSocket.CLOSED);
+		expect(ws.readyState).toBe(WebSocket.CLOSED);
+	});
+
+	it('rejects WebSocket connections with an invalid token', async () => {
+		const port = getPort();
+		bridge = new PlaygroundBridge();
+		await bridge.startWebSocketServer(port);
+
+		const ws = new WebSocket(`ws://127.0.0.1:${port}?token=wrong-token`);
+		await waitForWebSocket(ws, WebSocket.CLOSED);
+		expect(ws.readyState).toBe(WebSocket.CLOSED);
+	});
+});
+
+describe('Origin allowlist', () => {
+	let bridge: PlaygroundBridge;
+
+	afterEach(async () => {
+		await bridge?.close();
+	});
+
+	it('allows playground.wordpress.net', async () => {
+		const port = getPort();
+		bridge = new PlaygroundBridge();
+		await bridge.startWebSocketServer(port);
+
+		const response = await fetch(`http://127.0.0.1:${port}/bridge-token`, {
+			headers: {
+				Origin: 'https://playground.wordpress.net',
+			},
+		});
+		expect(response.status).toBe(200);
+	});
+
+	it('rejects non-localhost origins', async () => {
+		const port = getPort();
+		bridge = new PlaygroundBridge();
+		await bridge.startWebSocketServer(port);
+
+		const response = await fetch(`http://127.0.0.1:${port}/bridge-token`, {
+			headers: { Origin: 'https://example.com' },
+		});
+		expect(response.status).toBe(403);
+	});
+
+	it('rejects requests without an Origin header', async () => {
+		const port = getPort();
+		bridge = new PlaygroundBridge();
+		await bridge.startWebSocketServer(port);
+
+		const response = await fetch(`http://127.0.0.1:${port}/bridge-token`);
+		expect(response.status).toBe(403);
+	});
+});