feat: add MCP Chrome extension (#325)

Instructions: 1. `git clone https://github.com/mxschmitt/playwright-mcp && git checkout extension-drafft` 2. `npm ci && npm run build` 3. `chrome://extensions` in your normal Chrome, "load unpacked" and select the extension folder. 4. `node cli.js --port=4242 --extension` - The URL it prints at the end you can put into the extension popup. 5. Put either this into Claude Desktop (it does not support SSE yet hence wrapping it or just put the URL into Cursor/VSCode) ```json { "mcpServers": { "playwright": { "command": "bash", "args": [ "-c", "source $HOME/.nvm/nvm.sh && nvm use --silent 22 && npx supergateway --streamableHttp http://127.0.0.1:4242/mcp" ] } } } ``` Things like `Take a snapshot of my browser.` should now work in your Prompt Chat. ---- - SSE only for now, since we already have a http server with a port there - Upstream "page tests" can be executed over this CDP relay via https://github.com/microsoft/playwright/pull/36286 - Limitations for now are everything what happens outside of the tab its session is shared with -> `window.open` / `target=_blank`. --------- Co-authored-by: Yury Semikhatsky <yurys@chromium.org>
2025-06-13 22:15:17 +02:00
parent 0df6d7a441
commit 6c3f3b6576
28 changed files with 1430 additions and 56 deletions
--- a/src/browserContextFactory.ts
+++ b/src/browserContextFactory.ts
@@ -28,10 +28,10 @@ import type { BrowserInfo, LaunchBrowserRequest } from './browserServer.js';

 const testDebug = debug('pw:mcp:test');

-export function contextFactory(browserConfig: FullConfig['browser']): BrowserContextFactory {
+export function contextFactory(browserConfig: FullConfig['browser'], { forceCdp }: { forceCdp?: boolean } = {}): BrowserContextFactory {
  if (browserConfig.remoteEndpoint)
    return new RemoteContextFactory(browserConfig);
-  if (browserConfig.cdpEndpoint)
+  if (browserConfig.cdpEndpoint || forceCdp)
    return new CdpContextFactory(browserConfig);
  if (browserConfig.isolated)
    return new IsolatedContextFactory(browserConfig);
--- a/src/cdp-relay.ts
+++ b/src/cdp-relay.ts
@@ -0,0 +1,306 @@
+/**
+ * Copyright (c) Microsoft Corporation.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+/**
+ * Bridge Server - Standalone WebSocket server that bridges Playwright MCP and Chrome Extension
+ *
+ * Endpoints:
+ * - /cdp - Full CDP interface for Playwright MCP
+ * - /extension - Extension connection for chrome.debugger forwarding
+ */
+
+/* eslint-disable no-console */
+
+import { WebSocket, WebSocketServer } from 'ws';
+import http from 'node:http';
+import { EventEmitter } from 'node:events';
+import debug from 'debug';
+
+const debugLogger = debug('pw-mcp:cdp-relay');
+
+export class CDPBridgeServer extends EventEmitter {
+  private _wss: WebSocketServer;
+  private _playwrightSocket: WebSocket | null = null;
+  private _extensionSocket: WebSocket | null = null;
+  private _connectionInfo: {
+    targetInfo: any;
+    sessionId: string;
+  } | undefined;
+
+  public static readonly CDP_PATH = '/cdp';
+  public static readonly EXTENSION_PATH = '/extension';
+
+  constructor(server: http.Server) {
+    super();
+    this._wss = new WebSocketServer({ server });
+    this._wss.on('connection', this._onConnection.bind(this));
+  }
+
+  stop(): void {
+    this._playwrightSocket?.close();
+    this._extensionSocket?.close();
+  }
+
+  private _onConnection(ws: WebSocket, request: http.IncomingMessage): void {
+    const url = new URL(`http://localhost${request.url}`);
+
+    debugLogger(`New connection to ${url.pathname}`);
+
+    if (url.pathname === CDPBridgeServer.CDP_PATH) {
+      this._handlePlaywrightConnection(ws);
+    } else if (url.pathname === CDPBridgeServer.EXTENSION_PATH) {
+      this._handleExtensionConnection(ws);
+    } else {
+      debugLogger(`Invalid path: ${url.pathname}`);
+      ws.close(4004, 'Invalid path');
+    }
+  }
+
+  /**
+   * Handle Playwright MCP connection - provides full CDP interface
+   */
+  private _handlePlaywrightConnection(ws: WebSocket): void {
+    if (this._playwrightSocket?.readyState === WebSocket.OPEN) {
+      debugLogger('Closing previous Playwright connection');
+      this._playwrightSocket.close(1000, 'New connection established');
+    }
+
+    this._playwrightSocket = ws;
+    debugLogger('Playwright MCP connected');
+
+    ws.on('message', data => {
+      try {
+        const message = JSON.parse(data.toString());
+        this._handlePlaywrightMessage(message);
+      } catch (error) {
+        debugLogger('Error parsing Playwright message:', error);
+      }
+    });
+
+    ws.on('close', () => {
+      if (this._playwrightSocket === ws)
+        this._playwrightSocket = null;
+
+      debugLogger('Playwright MCP disconnected');
+    });
+
+    ws.on('error', error => {
+      debugLogger('Playwright WebSocket error:', error);
+    });
+  }
+
+  /**
+   * Handle Extension connection - forwards to chrome.debugger
+   */
+  private _handleExtensionConnection(ws: WebSocket): void {
+    if (this._extensionSocket?.readyState === WebSocket.OPEN) {
+      debugLogger('Closing previous extension connection');
+      this._extensionSocket.close(1000, 'New connection established');
+    }
+
+    this._extensionSocket = ws;
+    debugLogger('Extension connected');
+
+    ws.on('message', data => {
+      try {
+        const message = JSON.parse(data.toString());
+        this._handleExtensionMessage(message);
+      } catch (error) {
+        debugLogger('Error parsing extension message:', error);
+      }
+    });
+
+    ws.on('close', () => {
+      if (this._extensionSocket === ws)
+        this._extensionSocket = null;
+
+      debugLogger('Extension disconnected');
+    });
+
+    ws.on('error', error => {
+      debugLogger('Extension WebSocket error:', error);
+    });
+  }
+
+  /**
+   * Handle messages from Playwright MCP
+   */
+  private _handlePlaywrightMessage(message: any): void {
+    debugLogger('← Playwright:', message.method || `response(${message.id})`);
+
+    // Handle Browser domain methods locally
+    if (message.method?.startsWith('Browser.')) {
+      this._handleBrowserDomainMethod(message);
+      return;
+    }
+
+    // Handle Target domain methods
+    if (message.method?.startsWith('Target.')) {
+      this._handleTargetDomainMethod(message);
+      return;
+    }
+
+    // Forward other commands to extension
+    if (message.method)
+      this._forwardToExtension(message);
+
+  }
+
+  /**
+   * Handle messages from Extension
+   */
+  private _handleExtensionMessage(message: any): void {
+    // Handle connection info from extension
+    if (message.type === 'connection_info') {
+      debugLogger('← Extension connected to tab:', message);
+      this._connectionInfo = {
+        targetInfo: message.targetInfo,
+        // Page sessionId that should be used by this connection.
+        sessionId: message.sessionId
+      };
+      return;
+    }
+
+    // CDP event from extension
+    debugLogger(`← Extension message: ${message.method ?? (message.id && `response(id=${message.id})`) ?? 'unknown'}`);
+    this._sendToPlaywright(message);
+  }
+
+  /**
+   * Handle Browser domain methods locally
+   */
+  private _handleBrowserDomainMethod(message: any): void {
+    switch (message.method) {
+      case 'Browser.getVersion':
+        this._sendToPlaywright({
+          id: message.id,
+          result: {
+            protocolVersion: '1.3',
+            product: 'Chrome/Extension-Bridge',
+            userAgent: 'CDP-Bridge-Server/1.0.0',
+          }
+        });
+        break;
+
+      case 'Browser.setDownloadBehavior':
+        this._sendToPlaywright({
+          id: message.id,
+          result: {}
+        });
+        break;
+
+      default:
+        // Forward unknown Browser methods to extension
+        this._forwardToExtension(message);
+    }
+  }
+
+  /**
+   * Handle Target domain methods
+   */
+  private _handleTargetDomainMethod(message: any): void {
+    switch (message.method) {
+      case 'Target.setAutoAttach':
+        // Simulate auto-attach behavior with real target info
+        if (this._connectionInfo && !message.sessionId) {
+          debugLogger('Simulating auto-attach for target:', JSON.stringify(message));
+          this._sendToPlaywright({
+            method: 'Target.attachedToTarget',
+            params: {
+              sessionId: this._connectionInfo.sessionId,
+              targetInfo: {
+                ...this._connectionInfo.targetInfo,
+                attached: true,
+              },
+              waitingForDebugger: false
+            }
+          });
+          this._sendToPlaywright({
+            id: message.id,
+            result: {}
+          });
+        } else {
+          this._forwardToExtension(message);
+        }
+        break;
+
+      case 'Target.getTargets':
+        const targetInfos = [];
+
+        if (this._connectionInfo) {
+          targetInfos.push({
+            ...this._connectionInfo.targetInfo,
+            attached: true,
+          });
+        }
+
+        this._sendToPlaywright({
+          id: message.id,
+          result: { targetInfos }
+        });
+        break;
+
+      default:
+        this._forwardToExtension(message);
+    }
+  }
+
+  /**
+   * Forward message to extension
+   */
+  private _forwardToExtension(message: any): void {
+    if (this._extensionSocket?.readyState === WebSocket.OPEN) {
+      debugLogger('→ Extension:', message.method || `command(${message.id})`);
+      this._extensionSocket.send(JSON.stringify(message));
+    } else {
+      debugLogger('Extension not connected, cannot forward message');
+      if (message.id) {
+        this._sendToPlaywright({
+          id: message.id,
+          error: { message: 'Extension not connected' }
+        });
+      }
+    }
+  }
+
+  /**
+   * Forward message to Playwright
+   */
+  private _sendToPlaywright(message: any): void {
+    if (this._playwrightSocket?.readyState === WebSocket.OPEN) {
+      debugLogger('→ Playwright:', JSON.stringify(message));
+      this._playwrightSocket.send(JSON.stringify(message));
+    }
+  }
+}
+
+// CLI usage
+if (import.meta.url === `file://${process.argv[1]}`) {
+  const port = parseInt(process.argv[2], 10) || 9223;
+  const httpServer = http.createServer();
+  await new Promise<void>(resolve => httpServer.listen(port, resolve));
+  const server = new CDPBridgeServer(httpServer);
+
+  console.error(`CDP Bridge Server listening on ws://localhost:${port}`);
+  console.error(`- Playwright MCP: ws://localhost:${port}${CDPBridgeServer.CDP_PATH}`);
+  console.error(`- Extension: ws://localhost:${port}${CDPBridgeServer.EXTENSION_PATH}`);
+
+  process.on('SIGINT', () => {
+    debugLogger('\nShutting down bridge server...');
+    server.stop();
+    process.exit(0);
+  });
+}
--- a/src/config.ts
+++ b/src/config.ts
@@ -19,10 +19,18 @@ import os from 'os';
 import path from 'path';
 import { devices } from 'playwright';

-import type { Config, ToolCapability } from '../config.js';
+import type { Config as PublicConfig, ToolCapability } from '../config.js';
 import type { BrowserContextOptions, LaunchOptions } from 'playwright';
 import { sanitizeForFilePath } from './tools/utils.js';

+type Config = PublicConfig & {
+  /**
+   * TODO: Move to PublicConfig once we are ready to release this feature.
+   * Run server that is able to connect to the 'Playwright MCP' Chrome extension.
+   */
+  extension?: boolean;
+};
+
 export type CLIOptions = {
  allowedOrigins?: string[];
  blockedOrigins?: string[];
@@ -50,6 +58,7 @@ export type CLIOptions = {
  userDataDir?: string;
  viewportSize?: string;
  vision?: boolean;
+  extension?: boolean;
 };

 const defaultConfig: FullConfig = {
@@ -99,6 +108,13 @@ export async function resolveCLIConfig(cliOptions: CLIOptions): Promise<FullConf
  return result;
 }

+export function validateConfig(config: Config) {
+  if (config.extension) {
+    if (config.browser?.browserName !== 'chromium')
+      throw new Error('Extension mode is only supported for Chromium browsers.');
+  }
+}
+
 export async function configFromCLIOptions(cliOptions: CLIOptions): Promise<Config> {
  let browserName: 'chromium' | 'firefox' | 'webkit' | undefined;
  let channel: string | undefined;
@@ -142,6 +158,11 @@ export async function configFromCLIOptions(cliOptions: CLIOptions): Promise<Conf
      launchOptions.proxy.bypass = cliOptions.proxyBypass;
  }

+  if (cliOptions.device && cliOptions.cdpEndpoint)
+    throw new Error('Device emulation is not supported with cdpEndpoint.');
+  if (cliOptions.device && cliOptions.extension)
+    throw new Error('Device emulation is not supported with extension mode.');
+
  // Context options
  const contextOptions: BrowserContextOptions = cliOptions.device ? devices[cliOptions.device] : {};
  if (cliOptions.storageState)
@@ -183,6 +204,7 @@ export async function configFromCLIOptions(cliOptions: CLIOptions): Promise<Conf
    },
    capabilities: cliOptions.caps?.split(',').map((c: string) => c.trim() as ToolCapability),
    vision: !!cliOptions.vision,
+    extension: !!cliOptions.extension,
    network: {
      allowedOrigins: cliOptions.allowedOrigins,
      blockedOrigins: cliOptions.blockedOrigins,
--- a/src/connection.ts
+++ b/src/connection.ts
@@ -22,14 +22,14 @@ import { Context } from './context.js';
 import { snapshotTools, visionTools } from './tools.js';
 import { packageJSON } from './package.js';

-import { FullConfig } from './config.js';
+import { FullConfig, validateConfig } from './config.js';

 import type { BrowserContextFactory } from './browserContextFactory.js';

 export function createConnection(config: FullConfig, browserContextFactory: BrowserContextFactory): Connection {
  const allTools = config.vision ? visionTools : snapshotTools;
  const tools = allTools.filter(tool => !config.capabilities || tool.capability === 'core' || config.capabilities.includes(tool.capability));
-
+  validateConfig(config);
  const context = new Context(tools, config, browserContextFactory);
  const server = new McpServer({ name: 'Playwright', version: packageJSON.version }, {
    capabilities: {
--- a/src/program.ts
+++ b/src/program.ts
@@ -14,14 +14,16 @@
 * limitations under the License.
 */

-import { program } from 'commander';
+import type http from 'http';
+import { Option, program } from 'commander';
 // @ts-ignore
 import { startTraceViewerServer } from 'playwright-core/lib/server';

-import { startHttpTransport, startStdioTransport } from './transport.js';
+import { httpAddressToString, startHttpTransport, startStdioTransport } from './transport.js';
 import { resolveCLIConfig } from './config.js';
 import { Server } from './server.js';
 import { packageJSON } from './package.js';
+import { CDPBridgeServer } from './cdp-relay.js';

 program
    .version('Version ' + packageJSON.version)
@@ -52,13 +54,15 @@ program
    .option('--user-data-dir <path>', 'path to the user data directory. If not specified, a temporary directory will be created.')
    .option('--viewport-size <size>', 'specify browser viewport size in pixels, for example "1280, 720"')
    .option('--vision', 'Run server that uses screenshots (Aria snapshots are used by default)')
+    .addOption(new Option('--extension', 'Allow connecting to a running browser instance (Edge/Chrome only). Requires the \'Playwright MCP\' browser extension to be installed.').hideHelp())
    .action(async options => {
      const config = await resolveCLIConfig(options);
-      const server = new Server(config);
+      const server = new Server(config, { forceCdp: !!config.extension });
      server.setupExitWatchdog();

+      let httpServer: http.Server | undefined = undefined;
      if (config.server.port !== undefined)
-        startHttpTransport(server);
+        httpServer = await startHttpTransport(server);
      else
        await startStdioTransport(server);

@@ -69,6 +73,14 @@ program
        // eslint-disable-next-line no-console
        console.error('\nTrace viewer listening on ' + url);
      }
+      if (config.extension && httpServer) {
+        const wsAddress = httpAddressToString(httpServer.address()).replace(/^http/, 'ws');
+        config.browser.cdpEndpoint = `${wsAddress}${CDPBridgeServer.CDP_PATH}`;
+        const cdpRelayServer = new CDPBridgeServer(httpServer);
+        process.on('exit', () => cdpRelayServer.stop());
+        // eslint-disable-next-line no-console
+        console.error(`CDP relay server started on ${wsAddress}${CDPBridgeServer.EXTENSION_PATH} - Connect to it using the browser extension.`);
+      }
    });

 function semicolonSeparatedList(value: string): string[] {
--- a/src/server.ts
+++ b/src/server.ts
@@ -28,10 +28,10 @@ export class Server {
  private _browserConfig: FullConfig['browser'];
  private _contextFactory: BrowserContextFactory;

-  constructor(config: FullConfig) {
+  constructor(config: FullConfig, { forceCdp }: { forceCdp: boolean }) {
    this.config = config;
    this._browserConfig = config.browser;
-    this._contextFactory = contextFactory(this._browserConfig);
+    this._contextFactory = contextFactory(this._browserConfig, { forceCdp });
  }

  async createConnection(transport: Transport): Promise<Connection> {
--- a/src/transport.ts
+++ b/src/transport.ts
@@ -23,6 +23,7 @@ import { SSEServerTransport } from '@modelcontextprotocol/sdk/server/sse.js';
 import { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/streamableHttp.js';
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';

+import type { AddressInfo } from 'node:net';
 import type { Server } from './server.js';

 export async function startStdioTransport(server: Server) {
@@ -96,7 +97,7 @@ async function handleStreamable(server: Server, req: http.IncomingMessage, res:
  res.end('Invalid request');
 }

-export function startHttpTransport(server: Server) {
+export async function startHttpTransport(server: Server): Promise<http.Server> {
  const sseSessions = new Map<string, SSEServerTransport>();
  const streamableSessions = new Map<string, StreamableHTTPServerTransport>();
  const httpServer = http.createServer(async (req, res) => {
@@ -107,32 +108,32 @@ export function startHttpTransport(server: Server) {
      await handleSSE(server, req, res, url, sseSessions);
  });
  const { host, port } = server.config.server;
-  httpServer.listen(port, host, () => {
-    const address = httpServer.address();
-    assert(address, 'Could not bind server socket');
-    let url: string;
-    if (typeof address === 'string') {
-      url = address;
-    } else {
-      const resolvedPort = address.port;
-      let resolvedHost = address.family === 'IPv4' ? address.address : `[${address.address}]`;
-      if (resolvedHost === '0.0.0.0' || resolvedHost === '[::]')
-        resolvedHost = 'localhost';
-      url = `http://${resolvedHost}:${resolvedPort}`;
-    }
-    const message = [
-      `Listening on ${url}`,
-      'Put this in your client config:',
-      JSON.stringify({
-        'mcpServers': {
-          'playwright': {
-            'url': `${url}/sse`
-          }
+  await new Promise<void>(resolve => httpServer.listen(port, host, resolve));
+  const url = httpAddressToString(httpServer.address());
+  const message = [
+    `Listening on ${url}`,
+    'Put this in your client config:',
+    JSON.stringify({
+      'mcpServers': {
+        'playwright': {
+          'url': `${url}/sse`
        }
-      }, undefined, 2),
-      'If your client supports streamable HTTP, you can use the /mcp endpoint instead.',
-    ].join('\n');
+      }
+    }, undefined, 2),
+    'If your client supports streamable HTTP, you can use the /mcp endpoint instead.',
+  ].join('\n');
    // eslint-disable-next-line no-console
-    console.error(message);
-  });
+  console.error(message);
+  return httpServer;
+}
+
+export function httpAddressToString(address: string | AddressInfo | null): string {
+  assert(address, 'Could not bind server socket');
+  if (typeof address === 'string')
+    return address;
+  const resolvedPort = address.port;
+  let resolvedHost = address.family === 'IPv4' ? address.address : `[${address.address}]`;
+  if (resolvedHost === '0.0.0.0' || resolvedHost === '[::]')
+    resolvedHost = 'localhost';
+  return `http://${resolvedHost}:${resolvedPort}`;
 }