@playwright/mcp 0.0.32 → 0.0.34

package/lib/extension/cdpRelay.js

@@ -13,19 +13,26 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
+/**
+ * WebSocket server that bridges Playwright MCP and Chrome Extension
+ *
+ * Endpoints:
+ * - /cdp/guid - Full CDP interface for Playwright MCP
+ * - /extension/guid - Extension connection for chrome.debugger forwarding
+ */
 import { spawn } from 'child_process';
-import { WebSocket, WebSocketServer } from 'ws';
 import debug from 'debug';
-import * as playwright from 'playwright';
+import { WebSocket, WebSocketServer } from 'ws';
+import { httpAddressToString } from '../utils/httpServer.js';
+import { logUnhandledError } from '../utils/log.js';
+import { ManualPromise } from '../utils/manualPromise.js';
 // @ts-ignore
 const { registry } = await import('playwright-core/lib/server/registry/index');
-import { httpAddressToString, startHttpServer } from '../httpServer.js';
-import { logUnhandledError } from '../log.js';
-import { ManualPromise } from '../manualPromise.js';
 const debugLogger = debug('pw:mcp:relay');
 export class CDPRelayServer {
     _wsHost;
     _browserChannel;
+    _userDataDir;
     _cdpPath;
     _extensionPath;
     _wss;
@@ -34,9 +41,10 @@ export class CDPRelayServer {
     _connectedTabInfo;
     _nextSessionId = 1;
     _extensionConnectionPromise;
-    constructor(server, browserChannel) {
+    constructor(server, browserChannel, userDataDir) {
         this._wsHost = httpAddressToString(server.address()).replace(/^http/, 'ws');
         this._browserChannel = browserChannel;
+        this._userDataDir = userDataDir;
         const uuid = crypto.randomUUID();
         this._cdpPath = `/cdp/${uuid}`;
         this._extensionPath = `/extension/${uuid}`;
@@ -50,16 +58,22 @@ export class CDPRelayServer {
     extensionEndpoint() {
         return `${this._wsHost}${this._extensionPath}`;
     }
-    async ensureExtensionConnectionForMCPContext(clientInfo) {
+    async ensureExtensionConnectionForMCPContext(clientInfo, abortSignal) {
         debugLogger('Ensuring extension connection for MCP context');
         if (this._extensionConnection)
             return;
-        await this._connectBrowser(clientInfo);
+        this._connectBrowser(clientInfo);
         debugLogger('Waiting for incoming extension connection');
-        await this._extensionConnectionPromise;
+        await Promise.race([
+            this._extensionConnectionPromise,
+            new Promise((_, reject) => setTimeout(() => {
+                reject(new Error(`Extension connection timeout. Make sure the "Playwright MCP Bridge" extension is installed. See https://github.com/microsoft/playwright-mcp/blob/main/extension/README.md for installation instructions.`));
+            }, process.env.PWMCP_TEST_CONNECTION_TIMEOUT ? parseInt(process.env.PWMCP_TEST_CONNECTION_TIMEOUT, 10) : 5_000)),
+            new Promise((_, reject) => abortSignal.addEventListener('abort', reject))
+        ]);
         debugLogger('Extension connection established');
     }
-    async _connectBrowser(clientInfo) {
+    _connectBrowser(clientInfo) {
         const mcpRelayEndpoint = `${this._wsHost}${this._extensionPath}`;
         // Need to specify "key" in the manifest.json to make the id stable when loading from file.
         const url = new URL('chrome-extension://jakfalbnbhgkpmoaakfflhflbfpkailf/connect.html');
@@ -72,7 +86,11 @@ export class CDPRelayServer {
         const executablePath = executableInfo.executablePath();
         if (!executablePath)
             throw new Error(`"${this._browserChannel}" executable not found. Make sure it is installed at a standard location.`);
-        spawn(executablePath, [href], {
+        const args = [];
+        if (this._userDataDir)
+            args.push(`--user-data-dir=${this._userDataDir}`);
+        args.push(href);
+        spawn(executablePath, args, {
             windowsHide: true,
             detached: true,
             shell: false,
@@ -248,45 +266,6 @@ export class CDPRelayServer {
         this._playwrightConnection?.send(JSON.stringify(message));
     }
 }
-class ExtensionContextFactory {
-    _relay;
-    _browserPromise;
-    constructor(relay) {
-        this._relay = relay;
-    }
-    async createContext(clientInfo) {
-        // First call will establish the connection to the extension.
-        if (!this._browserPromise)
-            this._browserPromise = this._obtainBrowser(clientInfo);
-        const browser = await this._browserPromise;
-        return {
-            browserContext: browser.contexts()[0],
-            close: async () => {
-                debugLogger('close() called for browser context, ignoring');
-            }
-        };
-    }
-    clientDisconnected() {
-        this._relay.closeConnections('MCP client disconnected');
-        this._browserPromise = undefined;
-    }
-    async _obtainBrowser(clientInfo) {
-        await this._relay.ensureExtensionConnectionForMCPContext(clientInfo);
-        const browser = await playwright.chromium.connectOverCDP(this._relay.cdpEndpoint());
-        browser.on('disconnected', () => {
-            this._browserPromise = undefined;
-            debugLogger('Browser disconnected');
-        });
-        return browser;
-    }
-}
-export async function startCDPRelayServer(browserChannel, abortController) {
-    const httpServer = await startHttpServer({});
-    const cdpRelayServer = new CDPRelayServer(httpServer, browserChannel);
-    abortController.signal.addEventListener('abort', () => cdpRelayServer.stop());
-    debugLogger(`CDP relay server started, extension endpoint: ${cdpRelayServer.extensionEndpoint()}.`);
-    return new ExtensionContextFactory(cdpRelayServer);
-}
 class ExtensionConnection {
     _ws;
     _callbacks = new Map();

package/lib/extension/extensionContextFactory.js

@@ -0,0 +1,56 @@
+/**
+ * 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.
+ */
+import debug from 'debug';
+import * as playwright from 'playwright';
+import { startHttpServer } from '../utils/httpServer.js';
+import { CDPRelayServer } from './cdpRelay.js';
+const debugLogger = debug('pw:mcp:relay');
+export class ExtensionContextFactory {
+    name = 'extension';
+    description = 'Connect to a browser using the Playwright MCP extension';
+    _browserChannel;
+    _userDataDir;
+    constructor(browserChannel, userDataDir) {
+        this._browserChannel = browserChannel;
+        this._userDataDir = userDataDir;
+    }
+    async createContext(clientInfo, abortSignal) {
+        const browser = await this._obtainBrowser(clientInfo, abortSignal);
+        return {
+            browserContext: browser.contexts()[0],
+            close: async () => {
+                debugLogger('close() called for browser context');
+                await browser.close();
+            }
+        };
+    }
+    async _obtainBrowser(clientInfo, abortSignal) {
+        const relay = await this._startRelay(abortSignal);
+        await relay.ensureExtensionConnectionForMCPContext(clientInfo, abortSignal);
+        return await playwright.chromium.connectOverCDP(relay.cdpEndpoint());
+    }
+    async _startRelay(abortSignal) {
+        const httpServer = await startHttpServer({});
+        if (abortSignal.aborted) {
+            httpServer.close();
+            throw new Error(abortSignal.reason);
+        }
+        const cdpRelayServer = new CDPRelayServer(httpServer, this._browserChannel, this._userDataDir);
+        abortSignal.addEventListener('abort', () => cdpRelayServer.stop());
+        debugLogger(`CDP relay server started, extension endpoint: ${cdpRelayServer.extensionEndpoint()}.`);
+        return cdpRelayServer;
+    }
+}

package/lib/index.js

@@ -19,10 +19,12 @@ import { contextFactory } from './browserContextFactory.js';
 import * as mcpServer from './mcp/server.js';
 export async function createConnection(userConfig = {}, contextGetter) {
     const config = await resolveConfig(userConfig);
-    const factory = contextGetter ? new SimpleBrowserContextFactory(contextGetter) : contextFactory(config.browser);
+    const factory = contextGetter ? new SimpleBrowserContextFactory(contextGetter) : contextFactory(config);
     return mcpServer.createServer(new BrowserServerBackend(config, factory), false);
 }
 class SimpleBrowserContextFactory {
+    name = 'custom';
+    description = 'Connect to a browser using a custom context getter';
     _contextGetter;
     constructor(contextGetter) {
         this._contextGetter = contextGetter;

package/lib/loopTools/context.js

@@ -38,7 +38,7 @@ export class Context {
     }
     static async create(config) {
         const client = new Client({ name: 'Playwright Proxy', version: '1.0.0' });
-        const browserContextFactory = contextFactory(config.browser);
+        const browserContextFactory = contextFactory(config);
         const server = mcpServer.createServer(new BrowserServerBackend(config, browserContextFactory), false);
         await client.connect(new InProcessTransport(server));
         await client.ping();

package/lib/loopTools/main.js

@@ -15,10 +15,11 @@
  */
 import dotenv from 'dotenv';
 import * as mcpTransport from '../mcp/transport.js';
-import { packageJSON } from '../package.js';
+import { packageJSON } from '../utils/package.js';
 import { Context } from './context.js';
 import { perform } from './perform.js';
 import { snapshot } from './snapshot.js';
+import { toMcpTool } from '../mcp/tool.js';
 export async function runLoopTools(config) {
     dotenv.config();
     const serverBackendFactory = () => new LoopToolsServerBackend(config);
@@ -36,11 +37,12 @@ class LoopToolsServerBackend {
     async initialize() {
         this._context = await Context.create(this._config);
     }
-    tools() {
-        return this._tools.map(tool => tool.schema);
+    async listTools() {
+        return this._tools.map(tool => toMcpTool(tool.schema));
     }
-    async callTool(schema, parsedArguments) {
-        const tool = this._tools.find(tool => tool.schema.name === schema.name);
+    async callTool(name, args) {
+        const tool = this._tools.find(tool => tool.schema.name === name);
+        const parsedArguments = tool.schema.inputSchema.parse(args || {});
         return await tool.handle(this._context, parsedArguments);
     }
     serverClosed() {

package/lib/mcp/proxyBackend.js

@@ -0,0 +1,106 @@
+/**
+ * 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.
+ */
+import { z } from 'zod';
+import { zodToJsonSchema } from 'zod-to-json-schema';
+import { Client } from '@modelcontextprotocol/sdk/client/index.js';
+import { ListRootsRequestSchema, PingRequestSchema } from '@modelcontextprotocol/sdk/types.js';
+import { logUnhandledError } from '../utils/log.js';
+import { packageJSON } from '../utils/package.js';
+export class ProxyBackend {
+    name = 'Playwright MCP Client Switcher';
+    version = packageJSON.version;
+    _mcpProviders;
+    _currentClient;
+    _contextSwitchTool;
+    _roots = [];
+    constructor(mcpProviders) {
+        this._mcpProviders = mcpProviders;
+        this._contextSwitchTool = this._defineContextSwitchTool();
+    }
+    async initialize(clientVersion, roots) {
+        this._roots = roots;
+        await this._setCurrentClient(this._mcpProviders[0]);
+    }
+    async listTools() {
+        const response = await this._currentClient.listTools();
+        if (this._mcpProviders.length === 1)
+            return response.tools;
+        return [
+            ...response.tools,
+            this._contextSwitchTool,
+        ];
+    }
+    async callTool(name, args) {
+        if (name === this._contextSwitchTool.name)
+            return this._callContextSwitchTool(args);
+        return await this._currentClient.callTool({
+            name,
+            arguments: args,
+        });
+    }
+    serverClosed() {
+        void this._currentClient?.close().catch(logUnhandledError);
+    }
+    async _callContextSwitchTool(params) {
+        try {
+            const factory = this._mcpProviders.find(factory => factory.name === params.name);
+            if (!factory)
+                throw new Error('Unknown connection method: ' + params.name);
+            await this._setCurrentClient(factory);
+            return {
+                content: [{ type: 'text', text: '### Result\nSuccessfully changed connection method.\n' }],
+            };
+        }
+        catch (error) {
+            return {
+                content: [{ type: 'text', text: `### Result\nError: ${error}\n` }],
+                isError: true,
+            };
+        }
+    }
+    _defineContextSwitchTool() {
+        return {
+            name: 'browser_connect',
+            description: [
+                'Connect to a browser using one of the available methods:',
+                ...this._mcpProviders.map(factory => `- "${factory.name}": ${factory.description}`),
+            ].join('\n'),
+            inputSchema: zodToJsonSchema(z.object({
+                name: z.enum(this._mcpProviders.map(factory => factory.name)).default(this._mcpProviders[0].name).describe('The method to use to connect to the browser'),
+            }), { strictUnions: true }),
+            annotations: {
+                title: 'Connect to a browser context',
+                readOnlyHint: true,
+                openWorldHint: false,
+            },
+        };
+    }
+    async _setCurrentClient(factory) {
+        await this._currentClient?.close();
+        this._currentClient = undefined;
+        const client = new Client({ name: 'Playwright MCP Proxy', version: packageJSON.version });
+        client.registerCapabilities({
+            roots: {
+                listRoots: true,
+            },
+        });
+        client.setRequestHandler(ListRootsRequestSchema, () => ({ roots: this._roots }));
+        client.setRequestHandler(PingRequestSchema, () => ({}));
+        const transport = await factory.connect();
+        await client.connect(transport);
+        this._currentClient = client;
+    }
+}

package/lib/mcp/server.js

@@ -13,56 +13,64 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
+import debug from 'debug';
 import { Server } from '@modelcontextprotocol/sdk/server/index.js';
 import { CallToolRequestSchema, ListToolsRequestSchema } from '@modelcontextprotocol/sdk/types.js';
-import { zodToJsonSchema } from 'zod-to-json-schema';
+import { ManualPromise } from '../utils/manualPromise.js';
+import { logUnhandledError } from '../utils/log.js';
+const serverDebug = debug('pw:mcp:server');
 export async function connect(serverBackendFactory, transport, runHeartbeat) {
     const backend = serverBackendFactory();
-    await backend.initialize?.();
     const server = createServer(backend, runHeartbeat);
     await server.connect(transport);
 }
 export function createServer(backend, runHeartbeat) {
+    const initializedPromise = new ManualPromise();
     const server = new Server({ name: backend.name, version: backend.version }, {
         capabilities: {
             tools: {},
         }
     });
-    const tools = backend.tools();
     server.setRequestHandler(ListToolsRequestSchema, async () => {
-        return { tools: tools.map(tool => ({
-                name: tool.name,
-                description: tool.description,
-                inputSchema: zodToJsonSchema(tool.inputSchema),
-                annotations: {
-                    title: tool.title,
-                    readOnlyHint: tool.type === 'readOnly',
-                    destructiveHint: tool.type === 'destructive',
-                    openWorldHint: true,
-                },
-            })) };
+        serverDebug('listTools');
+        await initializedPromise;
+        const tools = await backend.listTools();
+        return { tools };
     });
     let heartbeatRunning = false;
     server.setRequestHandler(CallToolRequestSchema, async (request) => {
+        serverDebug('callTool', request);
+        await initializedPromise;
         if (runHeartbeat && !heartbeatRunning) {
             heartbeatRunning = true;
             startHeartbeat(server);
         }
-        const errorResult = (...messages) => ({
-            content: [{ type: 'text', text: messages.join('\n') }],
-            isError: true,
-        });
-        const tool = tools.find(tool => tool.name === request.params.name);
-        if (!tool)
-            return errorResult(`Tool "${request.params.name}" not found`);
         try {
-            return await backend.callTool(tool, tool.inputSchema.parse(request.params.arguments || {}));
+            return await backend.callTool(request.params.name, request.params.arguments || {});
         }
         catch (error) {
-            return errorResult(String(error));
+            return {
+                content: [{ type: 'text', text: '### Result\n' + String(error) }],
+                isError: true,
+            };
+        }
+    });
+    addServerListener(server, 'initialized', async () => {
+        try {
+            const capabilities = server.getClientCapabilities();
+            let clientRoots = [];
+            if (capabilities?.roots) {
+                const { roots } = await server.listRoots(undefined, { timeout: 2_000 }).catch(() => ({ roots: [] }));
+                clientRoots = roots;
+            }
+            const clientVersion = server.getClientVersion() ?? { name: 'unknown', version: 'unknown' };
+            await backend.initialize?.(clientVersion, clientRoots);
+            initializedPromise.resolve();
+        }
+        catch (e) {
+            logUnhandledError(e);
         }
     });
-    addServerListener(server, 'initialized', () => backend.serverInitialized?.(server.getClientVersion()));
     addServerListener(server, 'close', () => backend.serverClosed?.());
     return server;
 }

package/lib/mcp/tool.js

@@ -0,0 +1,29 @@
+/**
+ * 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.
+ */
+import { zodToJsonSchema } from 'zod-to-json-schema';
+export function toMcpTool(tool) {
+    return {
+        name: tool.name,
+        description: tool.description,
+        inputSchema: zodToJsonSchema(tool.inputSchema, { strictUnions: true }),
+        annotations: {
+            title: tool.title,
+            readOnlyHint: tool.type === 'readOnly',
+            destructiveHint: tool.type === 'destructive',
+            openWorldHint: true,
+        },
+    };
+}

package/lib/mcp/transport.js

@@ -18,7 +18,7 @@ import debug from 'debug';
 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 { httpAddressToString, startHttpServer } from '../httpServer.js';
+import { httpAddressToString, startHttpServer } from '../utils/httpServer.js';
 import * as mcpServer from './server.js';
 export async function start(serverBackendFactory, options) {
     if (options.port !== undefined) {

package/lib/program.js

@@ -14,16 +14,17 @@
  * limitations under the License.
  */
 import { program, Option } from 'commander';
-// @ts-ignore
-import { startTraceViewerServer } from 'playwright-core/lib/server';
+import * as mcpServer from './mcp/server.js';
 import * as mcpTransport from './mcp/transport.js';
 import { commaSeparatedList, resolveCLIConfig, semicolonSeparatedList } from './config.js';
-import { packageJSON } from './package.js';
-import { runWithExtension } from './extension/main.js';
-import { BrowserServerBackend } from './browserServerBackend.js';
+import { packageJSON } from './utils/package.js';
 import { Context } from './context.js';
 import { contextFactory } from './browserContextFactory.js';
 import { runLoopTools } from './loopTools/main.js';
+import { ProxyBackend } from './mcp/proxyBackend.js';
+import { BrowserServerBackend } from './browserServerBackend.js';
+import { ExtensionContextFactory } from './extension/extensionContextFactory.js';
+import { InProcessTransport } from './mcp/inProcessTransport.js';
 program
     .version('Version ' + packageJSON.version)
     .name(packageJSON.name)
@@ -36,6 +37,7 @@ program
     .option('--config <path>', 'path to the configuration file.')
     .option('--device <device>', 'device to emulate, for example: "iPhone 15"')
     .option('--executable-path <path>', 'path to the browser executable.')
+    .option('--extension', 'Connect to a running browser instance (Edge/Chrome only). Requires the "Playwright MCP Bridge" browser extension to be installed.')
     .option('--headless', 'run browser in headless mode, headed by default')
     .option('--host <host>', 'host to bind server to. Default is localhost. Use 0.0.0.0 to bind to all interfaces.')
     .option('--ignore-https-errors', 'ignore https errors')
@@ -52,11 +54,11 @@ program
     .option('--user-agent <ua string>', 'specify user agent string')
     .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"')
-    .addOption(new Option('--extension', 'Connect to a running browser instance (Edge/Chrome only). Requires the "Playwright MCP Bridge" browser extension to be installed.').hideHelp())
+    .addOption(new Option('--connect-tool', 'Allow to switch between different browser connection methods.').hideHelp())
     .addOption(new Option('--loop-tools', 'Run loop tools').hideHelp())
     .addOption(new Option('--vision', 'Legacy option, use --caps=vision instead').hideHelp())
     .action(async (options) => {
-    const abortController = setupExitWatchdog();
+    setupExitWatchdog();
     if (options.vision) {
         // eslint-disable-next-line no-console
         console.error('The --vision option is deprecated, use --caps=vision instead');
@@ -64,39 +66,46 @@ program
     }
     const config = await resolveCLIConfig(options);
     if (options.extension) {
-        await runWithExtension(config, abortController);
+        const contextFactory = createExtensionContextFactory(config);
+        const serverBackendFactory = () => new BrowserServerBackend(config, contextFactory);
+        await mcpTransport.start(serverBackendFactory, config.server);
         return;
     }
     if (options.loopTools) {
         await runLoopTools(config);
         return;
     }
-    const browserContextFactory = contextFactory(config.browser);
-    const serverBackendFactory = () => new BrowserServerBackend(config, browserContextFactory);
-    await mcpTransport.start(serverBackendFactory, config.server);
-    if (config.saveTrace) {
-        const server = await startTraceViewerServer();
-        const urlPrefix = server.urlPrefix('human-readable');
-        const url = urlPrefix + '/trace/index.html?trace=' + config.browser.launchOptions.tracesDir + '/trace.json';
-        // eslint-disable-next-line no-console
-        console.error('\nTrace viewer listening on ' + url);
-    }
+    const browserContextFactory = contextFactory(config);
+    const providers = [mcpProviderForBrowserContextFactory(config, browserContextFactory)];
+    if (options.connectTool)
+        providers.push(mcpProviderForBrowserContextFactory(config, createExtensionContextFactory(config)));
+    await mcpTransport.start(() => new ProxyBackend(providers), config.server);
 });
 function setupExitWatchdog() {
-    const abortController = new AbortController();
     let isExiting = false;
     const handleExit = async () => {
         if (isExiting)
             return;
         isExiting = true;
         setTimeout(() => process.exit(0), 15000);
-        abortController.abort('Process exiting');
         await Context.disposeAll();
         process.exit(0);
     };
     process.stdin.on('close', handleExit);
     process.on('SIGINT', handleExit);
     process.on('SIGTERM', handleExit);
-    return abortController;
+}
+function createExtensionContextFactory(config) {
+    return new ExtensionContextFactory(config.browser.launchOptions.channel || 'chrome', config.browser.userDataDir);
+}
+function mcpProviderForBrowserContextFactory(config, browserContextFactory) {
+    return {
+        name: browserContextFactory.name,
+        description: browserContextFactory.description,
+        connect: async () => {
+            const server = mcpServer.createServer(new BrowserServerBackend(config, browserContextFactory), false);
+            return new InProcessTransport(server);
+        },
+    };
 }
 void program.parseAsync(process.argv);