@playwright/mcp 0.0.33 → 0.0.34

package/README.md

@@ -100,6 +100,29 @@ Go to `Advanced settings` -> `Extensions` -> `Add custom extension`. Name to you
 Go to `Program` in the right sidebar -> `Install` -> `Edit mcp.json`. Use the standard config above.
 </details>
 
+<details>
+<summary>opencode</summary>
+
+Follow the MCP Servers [documentation](https://opencode.ai/docs/mcp-servers/). For example in `~/.config/opencode/opencode.json`:
+
+```json
+{
+  "$schema": "https://opencode.ai/config.json",
+  "mcp": {
+    "playwright": {
+      "type": "local",
+      "command": [
+        "npx",
+        "@playwright/mcp@latest"
+      ],
+      "enabled": true
+    }
+  }
+}
+
+```
+</details>
+
 <details>
 <summary>Qodo Gen</summary>
 
@@ -158,6 +181,9 @@ Playwright MCP server supports following arguments. They can be provided in the
   --config <path>              path to the configuration file.
   --device <device>            device to emulate, for example: "iPhone 15"
   --executable-path <path>     path to the browser executable.
+  --extension                  Connect to a running browser instance
+                               (Edge/Chrome only). Requires the "Playwright MCP
+                               Bridge" browser extension to be installed.
   --headless                   run browser in headless mode, headed by default
   --host <host>                host to bind server to. Default is localhost. Use
                                0.0.0.0 to bind to all interfaces.
@@ -191,7 +217,7 @@ Playwright MCP server supports following arguments. They can be provided in the
 
 ### User profile
 
-You can run Playwright MCP with persistent profile like a regular browser (default), or in the isolated contexts for the testing sessions.
+You can run Playwright MCP with persistent profile like a regular browser (default), in isolated contexts for testing sessions, or connect to your existing browser using the browser extension.
 
 **Persistent profile**
 
@@ -231,6 +257,10 @@ state [here](https://playwright.dev/docs/auth).
 }
 ```
 
+**Browser Extension**
+
+The Playwright MCP Chrome Extension allows you to connect to existing browser tabs and leverage your logged-in sessions and browser state. See [extension/README.md](extension/README.md) for installation and setup instructions.
+
 ### Configuration file
 
 The Playwright MCP server can be configured using a JSON configuration file. You can specify the configuration file

package/lib/browserContextFactory.js

@@ -19,8 +19,10 @@ import path from 'path';
 import * as playwright from 'playwright';
 // @ts-ignore
 import { registryDirectory } from 'playwright-core/lib/server/registry/index';
-import { logUnhandledError, testDebug } from './log.js';
-import { createHash } from './utils.js';
+// @ts-ignore
+import { startTraceViewerServer } from 'playwright-core/lib/server';
+import { logUnhandledError, testDebug } from './utils/log.js';
+import { createHash } from './utils/guid.js';
 import { outputFile } from './config.js';
 export function contextFactory(config) {
     if (config.browser.remoteEndpoint)
@@ -36,17 +38,16 @@ class BaseContextFactory {
     description;
     config;
     _browserPromise;
-    _tracesDir;
     constructor(name, description, config) {
         this.name = name;
         this.description = description;
         this.config = config;
     }
-    async _obtainBrowser() {
+    async _obtainBrowser(clientInfo) {
         if (this._browserPromise)
             return this._browserPromise;
         testDebug(`obtain browser (${this.name})`);
-        this._browserPromise = this._doObtainBrowser();
+        this._browserPromise = this._doObtainBrowser(clientInfo);
         void this._browserPromise.then(browser => {
             browser.on('disconnected', () => {
                 this._browserPromise = undefined;
@@ -56,14 +57,12 @@ class BaseContextFactory {
         });
         return this._browserPromise;
     }
-    async _doObtainBrowser() {
+    async _doObtainBrowser(clientInfo) {
         throw new Error('Not implemented');
     }
     async createContext(clientInfo) {
-        if (this.config.saveTrace)
-            this._tracesDir = await outputFile(this.config, clientInfo.rootPath, `traces-${Date.now()}`);
         testDebug(`create browser context (${this.name})`);
-        const browser = await this._obtainBrowser();
+        const browser = await this._obtainBrowser(clientInfo);
         const browserContext = await this._doCreateContext(browser);
         return { browserContext, close: () => this._closeBrowserContext(browserContext, browser) };
     }
@@ -85,11 +84,11 @@ class IsolatedContextFactory extends BaseContextFactory {
     constructor(config) {
         super('isolated', 'Create a new isolated browser context', config);
     }
-    async _doObtainBrowser() {
+    async _doObtainBrowser(clientInfo) {
         await injectCdpPort(this.config.browser);
         const browserType = playwright[this.config.browser.browserName];
         return browserType.launch({
-            tracesDir: this._tracesDir,
+            tracesDir: await startTraceServer(this.config, clientInfo.rootPath),
             ...this.config.browser.launchOptions,
             handleSIGINT: false,
             handleSIGTERM: false,
@@ -141,9 +140,7 @@ class PersistentContextFactory {
         await injectCdpPort(this.config.browser);
         testDebug('create browser context (persistent)');
         const userDataDir = this.config.browser.userDataDir ?? await this._createUserDataDir(clientInfo.rootPath);
-        let tracesDir;
-        if (this.config.saveTrace)
-            tracesDir = await outputFile(this.config, clientInfo.rootPath, `traces-${Date.now()}`);
+        const tracesDir = await startTraceServer(this.config, clientInfo.rootPath);
         this._userDataDirs.add(userDataDir);
         testDebug('lock user data dir', userDataDir);
         const browserType = playwright[this.config.browser.browserName];
@@ -203,3 +200,14 @@ async function findFreePort() {
         server.on('error', reject);
     });
 }
+async function startTraceServer(config, rootPath) {
+    if (!config.saveTrace)
+        return undefined;
+    const tracesDir = await outputFile(config, rootPath, `traces-${Date.now()}`);
+    const server = await startTraceViewerServer();
+    const urlPrefix = server.urlPrefix('human-readable');
+    const url = urlPrefix + '/trace/index.html?trace=' + tracesDir + '/trace.json';
+    // eslint-disable-next-line no-console
+    console.error('\nTrace viewer listening on ' + url);
+    return tracesDir;
+}

package/lib/browserServerBackend.js

@@ -14,14 +14,13 @@
  * limitations under the License.
  */
 import { fileURLToPath } from 'url';
-import { z } from 'zod';
 import { Context } from './context.js';
-import { logUnhandledError } from './log.js';
+import { logUnhandledError } from './utils/log.js';
 import { Response } from './response.js';
 import { SessionLog } from './sessionLog.js';
 import { filteredTools } from './tools.js';
-import { packageJSON } from './package.js';
-import { defineTool } from './tools/tool.js';
+import { packageJSON } from './utils/package.js';
+import { toMcpTool } from './mcp/tool.js';
 export class BrowserServerBackend {
     name = 'Playwright';
     version = packageJSON.version;
@@ -30,19 +29,14 @@ export class BrowserServerBackend {
     _sessionLog;
     _config;
     _browserContextFactory;
-    constructor(config, factories) {
+    constructor(config, factory) {
         this._config = config;
-        this._browserContextFactory = factories[0];
+        this._browserContextFactory = factory;
         this._tools = filteredTools(config);
-        if (factories.length > 1)
-            this._tools.push(this._defineContextSwitchTool(factories));
     }
-    async initialize(server) {
-        const capabilities = server.getClientCapabilities();
+    async initialize(clientVersion, roots) {
         let rootPath;
-        if (capabilities.roots && (server.getClientVersion()?.name === 'Visual Studio Code' ||
-            server.getClientVersion()?.name === 'Visual Studio Code - Insiders')) {
-            const { roots } = await server.listRoots();
+        if (roots.length > 0) {
             const firstRootUri = roots[0]?.uri;
             const url = firstRootUri ? new URL(firstRootUri) : undefined;
             rootPath = url ? fileURLToPath(url) : undefined;
@@ -53,16 +47,19 @@ export class BrowserServerBackend {
             config: this._config,
             browserContextFactory: this._browserContextFactory,
             sessionLog: this._sessionLog,
-            clientInfo: { ...server.getClientVersion(), rootPath },
+            clientInfo: { ...clientVersion, rootPath },
         });
     }
-    tools() {
-        return this._tools.map(tool => tool.schema);
+    async listTools() {
+        return this._tools.map(tool => toMcpTool(tool.schema));
     }
-    async callTool(schema, parsedArguments) {
+    async callTool(name, rawArguments) {
+        const tool = this._tools.find(tool => tool.schema.name === name);
+        if (!tool)
+            throw new Error(`Tool "${name}" not found`);
+        const parsedArguments = tool.schema.inputSchema.parse(rawArguments || {});
         const context = this._context;
-        const response = new Response(context, schema.name, parsedArguments);
-        const tool = this._tools.find(tool => tool.schema.name === schema.name);
+        const response = new Response(context, name, parsedArguments);
         context.setRunningTool(true);
         try {
             await tool.handle(context, parsedArguments, response);
@@ -78,44 +75,6 @@ export class BrowserServerBackend {
         return response.serialize();
     }
     serverClosed() {
-        void this._context.dispose().catch(logUnhandledError);
-    }
-    _defineContextSwitchTool(factories) {
-        const self = this;
-        return defineTool({
-            capability: 'core',
-            schema: {
-                name: 'browser_connect',
-                title: 'Connect to a browser context',
-                description: [
-                    'Connect to a browser using one of the available methods:',
-                    ...factories.map(factory => `- "${factory.name}": ${factory.description}`),
-                ].join('\n'),
-                inputSchema: z.object({
-                    method: z.enum(factories.map(factory => factory.name)).default(factories[0].name).describe('The method to use to connect to the browser'),
-                }),
-                type: 'readOnly',
-            },
-            async handle(context, params, response) {
-                const factory = factories.find(factory => factory.name === params.method);
-                if (!factory) {
-                    response.addError('Unknown connection method: ' + params.method);
-                    return;
-                }
-                await self._setContextFactory(factory);
-                response.addResult('Successfully changed connection method.');
-            }
-        });
-    }
-    async _setContextFactory(newFactory) {
-        if (this._context) {
-            const options = {
-                ...this._context.options,
-                browserContextFactory: newFactory,
-            };
-            await this._context.dispose();
-            this._context = new Context(options);
-        }
-        this._browserContextFactory = newFactory;
+        void this._context?.dispose().catch(logUnhandledError);
     }
 }

package/lib/config.js

@@ -17,7 +17,7 @@ import fs from 'fs';
 import os from 'os';
 import path from 'path';
 import { devices } from 'playwright';
-import { sanitizeForFilePath } from './utils.js';
+import { sanitizeForFilePath } from './utils/fileUtils.js';
 const defaultConfig = {
     browser: {
         browserName: 'chromium',

package/lib/context.js

@@ -14,7 +14,7 @@
  * limitations under the License.
  */
 import debug from 'debug';
-import { logUnhandledError } from './log.js';
+import { logUnhandledError } from './utils/log.js';
 import { Tab } from './tab.js';
 import { outputFile } from './config.js';
 const testDebug = debug('pw:mcp:test');

package/lib/extension/cdpRelay.js

@@ -23,9 +23,9 @@
 import { spawn } from 'child_process';
 import debug from 'debug';
 import { WebSocket, WebSocketServer } from 'ws';
-import { httpAddressToString } from '../httpServer.js';
-import { logUnhandledError } from '../log.js';
-import { ManualPromise } from '../manualPromise.js';
+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');
 const debugLogger = debug('pw:mcp:relay');
@@ -66,6 +66,9 @@ export class CDPRelayServer {
         debugLogger('Waiting for incoming extension connection');
         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');

package/lib/extension/extensionContextFactory.js

@@ -15,7 +15,7 @@
  */
 import debug from 'debug';
 import * as playwright from 'playwright';
-import { startHttpServer } from '../httpServer.js';
+import { startHttpServer } from '../utils/httpServer.js';
 import { CDPRelayServer } from './cdpRelay.js';
 const debugLogger = debug('pw:mcp:relay');
 export class ExtensionContextFactory {

package/lib/index.js

@@ -20,7 +20,7 @@ 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);
-    return mcpServer.createServer(new BrowserServerBackend(config, [factory]), false);
+    return mcpServer.createServer(new BrowserServerBackend(config, factory), false);
 }
 class SimpleBrowserContextFactory {
     name = 'custom';

package/lib/loopTools/context.js

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

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,11 +13,12 @@
  * 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 '../manualPromise.js';
-import { logUnhandledError } from '../log.js';
+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();
     const server = createServer(backend, runHeartbeat);
@@ -30,43 +31,45 @@ export function createServer(backend, runHeartbeat) {
             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: '### Result\n' + messages.join('\n') }],
-            isError: true,
-        });
-        const tool = tools.find(tool => tool.name === request.params.name);
-        if (!tool)
-            return errorResult(`Error: 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', () => {
-        backend.initialize?.(server).then(() => initializedPromise.resolve()).catch(logUnhandledError);
+    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, '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 { createExtensionContextFactory, 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,7 +54,6 @@ 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())
@@ -65,7 +66,9 @@ program
     }
     const config = await resolveCLIConfig(options);
     if (options.extension) {
-        await runWithExtension(config);
+        const contextFactory = createExtensionContextFactory(config);
+        const serverBackendFactory = () => new BrowserServerBackend(config, contextFactory);
+        await mcpTransport.start(serverBackendFactory, config.server);
         return;
     }
     if (options.loopTools) {
@@ -73,18 +76,10 @@ program
         return;
     }
     const browserContextFactory = contextFactory(config);
-    const factories = [browserContextFactory];
+    const providers = [mcpProviderForBrowserContextFactory(config, browserContextFactory)];
     if (options.connectTool)
-        factories.push(createExtensionContextFactory(config));
-    const serverBackendFactory = () => new BrowserServerBackend(config, factories);
-    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);
-    }
+        providers.push(mcpProviderForBrowserContextFactory(config, createExtensionContextFactory(config)));
+    await mcpTransport.start(() => new ProxyBackend(providers), config.server);
 });
 function setupExitWatchdog() {
     let isExiting = false;
@@ -100,4 +95,17 @@ function setupExitWatchdog() {
     process.on('SIGINT', handleExit);
     process.on('SIGTERM', handleExit);
 }
+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);

package/lib/sessionLog.js

@@ -15,7 +15,7 @@
  */
 import fs from 'fs';
 import path from 'path';
-import { logUnhandledError } from './log.js';
+import { logUnhandledError } from './utils/log.js';
 import { outputFile } from './config.js';
 export class SessionLog {
     _folder;

package/lib/tab.js

@@ -15,8 +15,8 @@
  */
 import { EventEmitter } from 'events';
 import { callOnPageNoTrace, waitForCompletion } from './tools/utils.js';
-import { logUnhandledError } from './log.js';
-import { ManualPromise } from './manualPromise.js';
+import { logUnhandledError } from './utils/log.js';
+import { ManualPromise } from './utils/manualPromise.js';
 export const TabEvents = {
     modalState: 'modalState'
 };

package/lib/tools/evaluate.js

@@ -15,7 +15,7 @@
  */
 import { z } from 'zod';
 import { defineTabTool } from './tool.js';
-import * as javascript from '../javascript.js';
+import * as javascript from '../utils/codegen.js';
 import { generateLocator } from './utils.js';
 const evaluateSchema = z.object({
     function: z.string().describe('() => { /* code */ } or (element) => { /* code */ } when element is provided'),

package/lib/tools/keyboard.js

@@ -17,7 +17,7 @@ import { z } from 'zod';
 import { defineTabTool } from './tool.js';
 import { elementSchema } from './snapshot.js';
 import { generateLocator } from './utils.js';
-import * as javascript from '../javascript.js';
+import * as javascript from '../utils/codegen.js';
 const pressKey = defineTabTool({
     capability: 'core',
     schema: {

package/lib/tools/pdf.js

@@ -15,7 +15,7 @@
  */
 import { z } from 'zod';
 import { defineTabTool } from './tool.js';
-import * as javascript from '../javascript.js';
+import * as javascript from '../utils/codegen.js';
 const pdfSchema = z.object({
     filename: z.string().optional().describe('File name to save the pdf to. Defaults to `page-{timestamp}.pdf` if not specified.'),
 });

package/lib/tools/screenshot.js

@@ -15,7 +15,7 @@
  */
 import { z } from 'zod';
 import { defineTabTool } from './tool.js';
-import * as javascript from '../javascript.js';
+import * as javascript from '../utils/codegen.js';
 import { generateLocator } from './utils.js';
 const screenshotSchema = z.object({
     type: z.enum(['png', 'jpeg']).default('png').describe('Image format for the screenshot. Default is png.'),

package/lib/tools/snapshot.js

@@ -15,7 +15,7 @@
  */
 import { z } from 'zod';
 import { defineTabTool, defineTool } from './tool.js';
-import * as javascript from '../javascript.js';
+import * as javascript from '../utils/codegen.js';
 import { generateLocator } from './utils.js';
 const snapshot = defineTool({
     capability: 'core',

package/lib/tools/wait.js

@@ -31,20 +31,19 @@ const wait = defineTool({
     handle: async (context, params, response) => {
         if (!params.text && !params.textGone && !params.time)
             throw new Error('Either time, text or textGone must be provided');
-        const code = [];
         if (params.time) {
-            code.push(`await new Promise(f => setTimeout(f, ${params.time} * 1000));`);
+            response.addCode(`await new Promise(f => setTimeout(f, ${params.time} * 1000));`);
             await new Promise(f => setTimeout(f, Math.min(30000, params.time * 1000)));
         }
         const tab = context.currentTabOrDie();
         const locator = params.text ? tab.page.getByText(params.text).first() : undefined;
         const goneLocator = params.textGone ? tab.page.getByText(params.textGone).first() : undefined;
         if (goneLocator) {
-            code.push(`await page.getByText(${JSON.stringify(params.textGone)}).first().waitFor({ state: 'hidden' });`);
+            response.addCode(`await page.getByText(${JSON.stringify(params.textGone)}).first().waitFor({ state: 'hidden' });`);
             await goneLocator.waitFor({ state: 'hidden' });
         }
         if (locator) {
-            code.push(`await page.getByText(${JSON.stringify(params.text)}).first().waitFor({ state: 'visible' });`);
+            response.addCode(`await page.getByText(${JSON.stringify(params.text)}).first().waitFor({ state: 'visible' });`);
             await locator.waitFor({ state: 'visible' });
         }
         response.addResult(`Waited for ${params.text || params.textGone || params.time}`);

package/lib/{javascript.js → utils/codegen.js}

@@ -25,7 +25,7 @@ export function escapeWithQuotes(text, char = '\'') {
     if (char === '"')
         return char + escapedText.replace(/["]/g, '\\"') + char;
     if (char === '`')
-        return char + escapedText.replace(/[`]/g, '`') + char;
+        return char + escapedText.replace(/[`]/g, '\\`') + char;
     throw new Error('Invalid escape char');
 }
 export function quote(text) {

package/lib/{fileUtils.js → utils/fileUtils.js}

@@ -27,6 +27,10 @@ export function cacheDir() {
         throw new Error('Unsupported platform: ' + process.platform);
     return path.join(cacheDirectory, 'ms-playwright');
 }
-export async function userDataDir(browserConfig) {
-    return path.join(cacheDir(), 'ms-playwright', `mcp-${browserConfig.launchOptions?.channel ?? browserConfig?.browserName}-profile`);
+export function sanitizeForFilePath(s) {
+    const sanitize = (s) => s.replace(/[\x00-\x2C\x2E-\x2F\x3A-\x40\x5B-\x60\x7B-\x7F]+/g, '-');
+    const separator = s.lastIndexOf('.');
+    if (separator === -1)
+        return sanitize(s);
+    return sanitize(s.substring(0, separator)) + '.' + sanitize(s.substring(separator + 1));
 }

package/lib/{utils.js → utils/guid.js}

@@ -14,13 +14,9 @@
  * limitations under the License.
  */
 import crypto from 'crypto';
+export function createGuid() {
+    return crypto.randomBytes(16).toString('hex');
+}
 export function createHash(data) {
     return crypto.createHash('sha256').update(data).digest('hex').slice(0, 7);
 }
-export function sanitizeForFilePath(s) {
-    const sanitize = (s) => s.replace(/[\x00-\x2C\x2E-\x2F\x3A-\x40\x5B-\x60\x7B-\x7F]+/g, '-');
-    const separator = s.lastIndexOf('.');
-    if (separator === -1)
-        return sanitize(s);
-    return sanitize(s.substring(0, separator)) + '.' + sanitize(s.substring(separator + 1));
-}

package/lib/{package.js → utils/package.js}

@@ -17,4 +17,4 @@ import fs from 'fs';
 import path from 'path';
 import url from 'url';
 const __filename = url.fileURLToPath(import.meta.url);
-export const packageJSON = JSON.parse(fs.readFileSync(path.join(path.dirname(__filename), '..', 'package.json'), 'utf8'));
+export const packageJSON = JSON.parse(fs.readFileSync(path.join(path.dirname(__filename), '..', '..', 'package.json'), 'utf8'));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@playwright/mcp",
-  "version": "0.0.33",
+  "version": "0.0.34",
   "description": "Playwright Tools for MCP",
   "type": "module",
   "repository": {
@@ -17,8 +17,9 @@
   "license": "Apache-2.0",
   "scripts": {
     "build": "tsc",
-    "lint": "npm run update-readme && eslint . && tsc --noEmit",
+    "lint": "npm run update-readme && npm run check-deps && eslint . && tsc --noEmit",
     "lint-fix": "eslint . --fix",
+    "check-deps": "node utils/check-deps.js",
     "update-readme": "node utils/update-readme.js",
     "watch": "tsc --watch",
     "test": "playwright test",
@@ -42,8 +43,8 @@
     "debug": "^4.4.1",
     "dotenv": "^17.2.0",
     "mime": "^4.0.7",
-    "playwright": "1.55.0-alpha-2025-08-07",
-    "playwright-core": "1.55.0-alpha-2025-08-07",
+    "playwright": "1.55.0-alpha-2025-08-12",
+    "playwright-core": "1.55.0-alpha-2025-08-12",
     "ws": "^8.18.1",
     "zod": "^3.24.1",
     "zod-to-json-schema": "^3.24.4"
@@ -52,7 +53,7 @@
     "@anthropic-ai/sdk": "^0.57.0",
     "@eslint/eslintrc": "^3.2.0",
     "@eslint/js": "^9.19.0",
-    "@playwright/test": "1.55.0-alpha-2025-08-07",
+    "@playwright/test": "1.55.0-alpha-2025-08-12",
     "@stylistic/eslint-plugin": "^3.0.1",
     "@types/debug": "^4.1.12",
     "@types/node": "^22.13.10",

package/lib/extension/main.js

@@ -1,26 +0,0 @@
-/**
- * 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 { ExtensionContextFactory } from './extensionContextFactory.js';
-import { BrowserServerBackend } from '../browserServerBackend.js';
-import * as mcpTransport from '../mcp/transport.js';
-export async function runWithExtension(config) {
-    const contextFactory = new ExtensionContextFactory(config.browser.launchOptions.channel || 'chrome', config.browser.userDataDir);
-    const serverBackendFactory = () => new BrowserServerBackend(config, [contextFactory]);
-    await mcpTransport.start(serverBackendFactory, config.server);
-}
-export function createExtensionContextFactory(config) {
-    return new ExtensionContextFactory(config.browser.launchOptions.channel || 'chrome', config.browser.userDataDir);
-}