@playwright/mcp 0.0.27 → 0.0.29

package/README.md

@@ -52,6 +52,12 @@ After installation, the Playwright MCP server will be available for use with you
 <details>
 <summary><b>Install in Cursor</b></summary>
 
+#### Click the button to install:
+
+[![Install MCP Server](https://cursor.com/deeplink/mcp-install-dark.svg)](https://cursor.com/install-mcp?name=playwright&config=eyJjb21tYW5kIjoibnB4IEBwbGF5d3JpZ2h0L21jcEBsYXRlc3QifQ%3D%3D)
+
+#### Or install manually:
+
 Go to `Cursor Settings` -> `MCP` -> `Add new MCP Server`. Name to your liking, use `command` type with the command `npx @playwright/mcp`. You can also verify config or add command like arguments via clicking `Edit`.
 
 ```js
@@ -106,6 +112,27 @@ Follow the MCP install [guide](https://modelcontextprotocol.io/quickstart/user),
 ```
 </details>
 
+<details>
+<summary><b>Install in Qodo Gen</b></summary>
+
+Open [Qodo Gen](https://docs.qodo.ai/qodo-documentation/qodo-gen) chat panel in VSCode or IntelliJ → Connect more tools → + Add new MCP → Paste the following configuration:
+
+```js
+{
+  "mcpServers": {
+    "playwright": {
+      "command": "npx",
+      "args": [
+        "@playwright/mcp@latest"
+      ]
+    }
+  }
+}
+```
+
+Click <code>Save</code>.
+</details>
+
 ### Configuration
 
 Playwright MCP server supports following arguments. They can be provided in the JSON configuration above, as a part of the `"args"` list:
@@ -124,6 +151,7 @@ Playwright MCP server supports following arguments. They can be provided in the
   --block-service-workers      block service workers
   --browser <browser>          browser or chrome channel to use, possible
                                values: chrome, firefox, webkit, msedge.
+  --browser-agent <endpoint>   Use browser agent (experimental).
   --caps <caps>                comma-separated list of capabilities to enable,
                                possible values: tabs, pdf, history, wait, files,
                                install. Default is all.
@@ -199,7 +227,7 @@ state [here](https://playwright.dev/docs/auth).
       "args": [
         "@playwright/mcp@latest",
         "--isolated",
-        "--storage-state={path/to/storage.json}
+        "--storage-state={path/to/storage.json}"
       ]
     }
   }
@@ -354,7 +382,7 @@ http.createServer(async (req, res) => {
   // Creates a headless Playwright MCP server with SSE transport
   const connection = await createConnection({ browser: { launchOptions: { headless: true } } });
   const transport = new SSEServerTransport('/messages', res);
-  await connection.connect(transport);
+  await connection.sever.connect(transport);
 
   // ...
 });

package/config.d.ts

@@ -23,6 +23,11 @@ export type Config = {
    * The browser to use.
    */
   browser?: {
+    /**
+     * Use browser agent (experimental).
+     */
+    browserAgent?: string;
+
     /**
      * The type of browser to use.
      */

package/index.d.ts

@@ -16,14 +16,13 @@
  */
 
 import type { Server } from '@modelcontextprotocol/sdk/server/index.js';
-import type { Config } from './config';
-import type { Transport } from '@modelcontextprotocol/sdk/shared/transport.js';
+import type { Config } from './config.js';
+import type { BrowserContext } from 'playwright';
 
 export type Connection = {
   server: Server;
-  connect(transport: Transport): Promise<void>;
   close(): Promise<void>;
 };
 
-export declare function createConnection(config?: Config): Promise<Connection>;
+export declare function createConnection(config?: Config, contextGetter?: () => Promise<BrowserContext>): Promise<Connection>;
 export {};

package/lib/browserContextFactory.js

@@ -0,0 +1,227 @@
+/**
+ * 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 fs from 'node:fs';
+import net from 'node:net';
+import path from 'node:path';
+import os from 'node:os';
+import debug from 'debug';
+import * as playwright from 'playwright';
+import { userDataDir } from './fileUtils.js';
+const testDebug = debug('pw:mcp:test');
+export function contextFactory(browserConfig) {
+    if (browserConfig.remoteEndpoint)
+        return new RemoteContextFactory(browserConfig);
+    if (browserConfig.cdpEndpoint)
+        return new CdpContextFactory(browserConfig);
+    if (browserConfig.isolated)
+        return new IsolatedContextFactory(browserConfig);
+    if (browserConfig.browserAgent)
+        return new BrowserServerContextFactory(browserConfig);
+    return new PersistentContextFactory(browserConfig);
+}
+class BaseContextFactory {
+    browserConfig;
+    _browserPromise;
+    name;
+    constructor(name, browserConfig) {
+        this.name = name;
+        this.browserConfig = browserConfig;
+    }
+    async _obtainBrowser() {
+        if (this._browserPromise)
+            return this._browserPromise;
+        testDebug(`obtain browser (${this.name})`);
+        this._browserPromise = this._doObtainBrowser();
+        void this._browserPromise.then(browser => {
+            browser.on('disconnected', () => {
+                this._browserPromise = undefined;
+            });
+        }).catch(() => {
+            this._browserPromise = undefined;
+        });
+        return this._browserPromise;
+    }
+    async _doObtainBrowser() {
+        throw new Error('Not implemented');
+    }
+    async createContext() {
+        testDebug(`create browser context (${this.name})`);
+        const browser = await this._obtainBrowser();
+        const browserContext = await this._doCreateContext(browser);
+        return { browserContext, close: () => this._closeBrowserContext(browserContext, browser) };
+    }
+    async _doCreateContext(browser) {
+        throw new Error('Not implemented');
+    }
+    async _closeBrowserContext(browserContext, browser) {
+        testDebug(`close browser context (${this.name})`);
+        if (browser.contexts().length === 1)
+            this._browserPromise = undefined;
+        await browserContext.close().catch(() => { });
+        if (browser.contexts().length === 0) {
+            testDebug(`close browser (${this.name})`);
+            await browser.close().catch(() => { });
+        }
+    }
+}
+class IsolatedContextFactory extends BaseContextFactory {
+    constructor(browserConfig) {
+        super('isolated', browserConfig);
+    }
+    async _doObtainBrowser() {
+        await injectCdpPort(this.browserConfig);
+        const browserType = playwright[this.browserConfig.browserName];
+        return browserType.launch({
+            ...this.browserConfig.launchOptions,
+            handleSIGINT: false,
+            handleSIGTERM: false,
+        }).catch(error => {
+            if (error.message.includes('Executable doesn\'t exist'))
+                throw new Error(`Browser specified in your config is not installed. Either install it (likely) or change the config.`);
+            throw error;
+        });
+    }
+    async _doCreateContext(browser) {
+        return browser.newContext(this.browserConfig.contextOptions);
+    }
+}
+class CdpContextFactory extends BaseContextFactory {
+    constructor(browserConfig) {
+        super('cdp', browserConfig);
+    }
+    async _doObtainBrowser() {
+        return playwright.chromium.connectOverCDP(this.browserConfig.cdpEndpoint);
+    }
+    async _doCreateContext(browser) {
+        return this.browserConfig.isolated ? await browser.newContext() : browser.contexts()[0];
+    }
+}
+class RemoteContextFactory extends BaseContextFactory {
+    constructor(browserConfig) {
+        super('remote', browserConfig);
+    }
+    async _doObtainBrowser() {
+        const url = new URL(this.browserConfig.remoteEndpoint);
+        url.searchParams.set('browser', this.browserConfig.browserName);
+        if (this.browserConfig.launchOptions)
+            url.searchParams.set('launch-options', JSON.stringify(this.browserConfig.launchOptions));
+        return playwright[this.browserConfig.browserName].connect(String(url));
+    }
+    async _doCreateContext(browser) {
+        return browser.newContext();
+    }
+}
+class PersistentContextFactory {
+    browserConfig;
+    _userDataDirs = new Set();
+    constructor(browserConfig) {
+        this.browserConfig = browserConfig;
+    }
+    async createContext() {
+        await injectCdpPort(this.browserConfig);
+        testDebug('create browser context (persistent)');
+        const userDataDir = this.browserConfig.userDataDir ?? await this._createUserDataDir();
+        this._userDataDirs.add(userDataDir);
+        testDebug('lock user data dir', userDataDir);
+        const browserType = playwright[this.browserConfig.browserName];
+        for (let i = 0; i < 5; i++) {
+            try {
+                const browserContext = await browserType.launchPersistentContext(userDataDir, {
+                    ...this.browserConfig.launchOptions,
+                    ...this.browserConfig.contextOptions,
+                    handleSIGINT: false,
+                    handleSIGTERM: false,
+                });
+                const close = () => this._closeBrowserContext(browserContext, userDataDir);
+                return { browserContext, close };
+            }
+            catch (error) {
+                if (error.message.includes('Executable doesn\'t exist'))
+                    throw new Error(`Browser specified in your config is not installed. Either install it (likely) or change the config.`);
+                if (error.message.includes('ProcessSingleton') || error.message.includes('Invalid URL')) {
+                    // User data directory is already in use, try again.
+                    await new Promise(resolve => setTimeout(resolve, 1000));
+                    continue;
+                }
+                throw error;
+            }
+        }
+        throw new Error(`Browser is already in use for ${userDataDir}, use --isolated to run multiple instances of the same browser`);
+    }
+    async _closeBrowserContext(browserContext, userDataDir) {
+        testDebug('close browser context (persistent)');
+        testDebug('release user data dir', userDataDir);
+        await browserContext.close().catch(() => { });
+        this._userDataDirs.delete(userDataDir);
+        testDebug('close browser context complete (persistent)');
+    }
+    async _createUserDataDir() {
+        let cacheDirectory;
+        if (process.platform === 'linux')
+            cacheDirectory = process.env.XDG_CACHE_HOME || path.join(os.homedir(), '.cache');
+        else if (process.platform === 'darwin')
+            cacheDirectory = path.join(os.homedir(), 'Library', 'Caches');
+        else if (process.platform === 'win32')
+            cacheDirectory = process.env.LOCALAPPDATA || path.join(os.homedir(), 'AppData', 'Local');
+        else
+            throw new Error('Unsupported platform: ' + process.platform);
+        const result = path.join(cacheDirectory, 'ms-playwright', `mcp-${this.browserConfig.launchOptions?.channel ?? this.browserConfig?.browserName}-profile`);
+        await fs.promises.mkdir(result, { recursive: true });
+        return result;
+    }
+}
+export class BrowserServerContextFactory extends BaseContextFactory {
+    constructor(browserConfig) {
+        super('persistent', browserConfig);
+    }
+    async _doObtainBrowser() {
+        const response = await fetch(new URL(`/json/launch`, this.browserConfig.browserAgent), {
+            method: 'POST',
+            body: JSON.stringify({
+                browserType: this.browserConfig.browserName,
+                userDataDir: this.browserConfig.userDataDir ?? await this._createUserDataDir(),
+                launchOptions: this.browserConfig.launchOptions,
+                contextOptions: this.browserConfig.contextOptions,
+            }),
+        });
+        const info = await response.json();
+        if (info.error)
+            throw new Error(info.error);
+        return await playwright.chromium.connectOverCDP(`http://localhost:${info.cdpPort}/`);
+    }
+    async _doCreateContext(browser) {
+        return this.browserConfig.isolated ? await browser.newContext() : browser.contexts()[0];
+    }
+    async _createUserDataDir() {
+        const dir = await userDataDir(this.browserConfig);
+        await fs.promises.mkdir(dir, { recursive: true });
+        return dir;
+    }
+}
+async function injectCdpPort(browserConfig) {
+    if (browserConfig.browserName === 'chromium')
+        browserConfig.launchOptions.cdpPort = await findFreePort();
+}
+async function findFreePort() {
+    return new Promise((resolve, reject) => {
+        const server = net.createServer();
+        server.listen(0, () => {
+            const { port } = server.address();
+            server.close(() => resolve(port));
+        });
+        server.on('error', reject);
+    });
+}

package/lib/browserServer.js

@@ -0,0 +1,151 @@
+/**
+ * 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.
+ */
+/* eslint-disable no-console */
+import net from 'net';
+import { program } from 'commander';
+import playwright from 'playwright';
+import { HttpServer } from './httpServer.js';
+import { packageJSON } from './package.js';
+class BrowserServer {
+    _server = new HttpServer();
+    _entries = [];
+    constructor() {
+        this._setupExitHandler();
+    }
+    async start(port) {
+        await this._server.start({ port });
+        this._server.routePath('/json/list', (req, res) => {
+            this._handleJsonList(res);
+        });
+        this._server.routePath('/json/launch', async (req, res) => {
+            void this._handleLaunchBrowser(req, res).catch(e => console.error(e));
+        });
+        this._setEntries([]);
+    }
+    _handleJsonList(res) {
+        const list = this._entries.map(browser => browser.info);
+        res.end(JSON.stringify(list));
+    }
+    async _handleLaunchBrowser(req, res) {
+        const request = await readBody(req);
+        let info = this._entries.map(entry => entry.info).find(info => info.userDataDir === request.userDataDir);
+        if (!info || info.error)
+            info = await this._newBrowser(request);
+        res.end(JSON.stringify(info));
+    }
+    async _newBrowser(request) {
+        const cdpPort = await findFreePort();
+        request.launchOptions.cdpPort = cdpPort;
+        const info = {
+            browserType: request.browserType,
+            userDataDir: request.userDataDir,
+            cdpPort,
+            launchOptions: request.launchOptions,
+            contextOptions: request.contextOptions,
+        };
+        const browserType = playwright[request.browserType];
+        const { browser, error } = await browserType.launchPersistentContext(request.userDataDir, {
+            ...request.launchOptions,
+            ...request.contextOptions,
+            handleSIGINT: false,
+            handleSIGTERM: false,
+        }).then(context => {
+            return { browser: context.browser(), error: undefined };
+        }).catch(error => {
+            return { browser: undefined, error: error.message };
+        });
+        this._setEntries([...this._entries, {
+                browser,
+                info: {
+                    browserType: request.browserType,
+                    userDataDir: request.userDataDir,
+                    cdpPort,
+                    launchOptions: request.launchOptions,
+                    contextOptions: request.contextOptions,
+                    error,
+                },
+            }]);
+        browser?.on('disconnected', () => {
+            this._setEntries(this._entries.filter(entry => entry.browser !== browser));
+        });
+        return info;
+    }
+    _updateReport() {
+        // Clear the current line and move cursor to top of screen
+        process.stdout.write('\x1b[2J\x1b[H');
+        process.stdout.write(`Playwright Browser Server v${packageJSON.version}\n`);
+        process.stdout.write(`Listening on ${this._server.urlPrefix('human-readable')}\n\n`);
+        if (this._entries.length === 0) {
+            process.stdout.write('No browsers currently running\n');
+            return;
+        }
+        process.stdout.write('Running browsers:\n');
+        for (const entry of this._entries) {
+            const status = entry.browser ? 'running' : 'error';
+            const statusColor = entry.browser ? '\x1b[32m' : '\x1b[31m'; // green for running, red for error
+            process.stdout.write(`${statusColor}${entry.info.browserType}\x1b[0m (${entry.info.userDataDir}) - ${statusColor}${status}\x1b[0m\n`);
+            if (entry.info.error)
+                process.stdout.write(`  Error: ${entry.info.error}\n`);
+        }
+    }
+    _setEntries(entries) {
+        this._entries = entries;
+        this._updateReport();
+    }
+    _setupExitHandler() {
+        let isExiting = false;
+        const handleExit = async () => {
+            if (isExiting)
+                return;
+            isExiting = true;
+            setTimeout(() => process.exit(0), 15000);
+            for (const entry of this._entries)
+                await entry.browser?.close().catch(() => { });
+            process.exit(0);
+        };
+        process.stdin.on('close', handleExit);
+        process.on('SIGINT', handleExit);
+        process.on('SIGTERM', handleExit);
+    }
+}
+program
+    .name('browser-agent')
+    .option('-p, --port <port>', 'Port to listen on', '9224')
+    .action(async (options) => {
+    await main(options);
+});
+void program.parseAsync(process.argv);
+async function main(options) {
+    const server = new BrowserServer();
+    await server.start(+options.port);
+}
+function readBody(req) {
+    return new Promise((resolve, reject) => {
+        const chunks = [];
+        req.on('data', (chunk) => chunks.push(chunk));
+        req.on('end', () => resolve(JSON.parse(Buffer.concat(chunks).toString())));
+    });
+}
+async function findFreePort() {
+    return new Promise((resolve, reject) => {
+        const server = net.createServer();
+        server.listen(0, () => {
+            const { port } = server.address();
+            server.close(() => resolve(port));
+        });
+        server.on('error', reject);
+    });
+}

package/lib/config.js

@@ -14,7 +14,6 @@
  * limitations under the License.
  */
 import fs from 'fs';
-import net from 'net';
 import os from 'os';
 import path from 'path';
 import { devices } from 'playwright';
@@ -35,6 +34,7 @@ const defaultConfig = {
         allowedOrigins: undefined,
         blockedOrigins: undefined,
     },
+    server: {},
     outputDir: path.join(os.tmpdir(), 'playwright-mcp-output', sanitizeForFilePath(new Date().toISOString())),
 };
 export async function resolveConfig(config) {
@@ -47,8 +47,6 @@ export async function resolveCLIConfig(cliOptions) {
     // Derive artifact output directory from config.outputDir
     if (result.saveTrace)
         result.browser.launchOptions.tracesDir = path.join(result.outputDir, 'traces');
-    if (result.browser.browserName === 'chromium')
-        result.browser.launchOptions.cdpPort = await findFreePort();
     return result;
 }
 export async function configFromCLIOptions(cliOptions) {
@@ -113,6 +111,7 @@ export async function configFromCLIOptions(cliOptions) {
         contextOptions.serviceWorkers = 'block';
     const result = {
         browser: {
+            browserAgent: cliOptions.browserAgent ?? process.env.PW_BROWSER_AGENT,
             browserName,
             isolated: cliOptions.isolated,
             userDataDir: cliOptions.userDataDir,
@@ -136,16 +135,6 @@ export async function configFromCLIOptions(cliOptions) {
     };
     return result;
 }
-async function findFreePort() {
-    return new Promise((resolve, reject) => {
-        const server = net.createServer();
-        server.listen(0, () => {
-            const { port } = server.address();
-            server.close(() => resolve(port));
-        });
-        server.on('error', reject);
-    });
-}
 async function loadConfig(configFile) {
     if (!configFile)
         return {};
@@ -166,6 +155,8 @@ function pickDefined(obj) {
 }
 function mergeConfig(base, overrides) {
     const browser = {
+        ...pickDefined(base.browser),
+        ...pickDefined(overrides.browser),
         browserName: overrides.browser?.browserName ?? base.browser?.browserName ?? 'chromium',
         isolated: overrides.browser?.isolated ?? base.browser?.isolated ?? false,
         launchOptions: {
@@ -177,9 +168,6 @@ function mergeConfig(base, overrides) {
             ...pickDefined(base.browser?.contextOptions),
             ...pickDefined(overrides.browser?.contextOptions),
         },
-        userDataDir: overrides.browser?.userDataDir ?? base.browser?.userDataDir,
-        cdpEndpoint: overrides.browser?.cdpEndpoint ?? base.browser?.cdpEndpoint,
-        remoteEndpoint: overrides.browser?.remoteEndpoint ?? base.browser?.remoteEndpoint,
     };
     if (browser.browserName !== 'chromium' && browser.launchOptions)
         delete browser.launchOptions.channel;
@@ -190,6 +178,10 @@ function mergeConfig(base, overrides) {
         network: {
             ...pickDefined(base.network),
             ...pickDefined(overrides.network),
-        }
+        },
+        server: {
+            ...pickDefined(base.server),
+            ...pickDefined(overrides.server),
+        },
     };
 }

package/lib/connection.js

@@ -13,16 +13,17 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
-import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { Server as McpServer } from '@modelcontextprotocol/sdk/server/index.js';
 import { CallToolRequestSchema, ListToolsRequestSchema } from '@modelcontextprotocol/sdk/types.js';
 import { zodToJsonSchema } from 'zod-to-json-schema';
-import { Context, packageJSON } from './context.js';
+import { Context } from './context.js';
 import { snapshotTools, visionTools } from './tools.js';
-export async function createConnection(config) {
+import { packageJSON } from './package.js';
+export function createConnection(config, browserContextFactory) {
     const allTools = config.vision ? visionTools : snapshotTools;
     const tools = allTools.filter(tool => !config.capabilities || tool.capability === 'core' || config.capabilities.includes(tool.capability));
-    const context = new Context(tools, config);
-    const server = new Server({ name: 'Playwright', version: packageJSON.version }, {
+    const context = new Context(tools, config, browserContextFactory);
+    const server = new McpServer({ name: 'Playwright', version: packageJSON.version }, {
         capabilities: {
             tools: {},
         }
@@ -62,8 +63,7 @@ export async function createConnection(config) {
             return errorResult(String(error));
         }
     });
-    const connection = new Connection(server, context);
-    return connection;
+    return new Connection(server, context);
 }
 export class Connection {
     server;
@@ -71,13 +71,9 @@ export class Connection {
     constructor(server, context) {
         this.server = server;
         this.context = context;
-    }
-    async connect(transport) {
-        await this.server.connect(transport);
-        await new Promise(resolve => {
-            this.server.oninitialized = () => resolve();
-        });
-        this.context.clientVersion = this.server.getClientVersion();
+        this.server.oninitialized = () => {
+            this.context.clientVersion = this.server.getClientVersion();
+        };
     }
     async close() {
         await this.server.close();

package/lib/context.js

@@ -13,28 +13,28 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
-import fs from 'node:fs';
-import url from 'node:url';
-import os from 'node:os';
-import path from 'node:path';
-import * as playwright from 'playwright';
+import debug from 'debug';
 import { callOnPageNoTrace, waitForCompletion } from './tools/utils.js';
 import { ManualPromise } from './manualPromise.js';
 import { Tab } from './tab.js';
 import { outputFile } from './config.js';
+const testDebug = debug('pw:mcp:test');
 export class Context {
     tools;
     config;
     _browserContextPromise;
+    _browserContextFactory;
     _tabs = [];
     _currentTab;
     _modalStates = [];
     _pendingAction;
     _downloads = [];
     clientVersion;
-    constructor(tools, config) {
+    constructor(tools, config, browserContextFactory) {
         this.tools = tools;
         this.config = config;
+        this._browserContextFactory = browserContextFactory;
+        testDebug('create context');
     }
     clientSupportsImages() {
         if (this.config.imageResponses === 'allow')
@@ -67,7 +67,7 @@ export class Context {
     }
     currentTabOrDie() {
         if (!this._currentTab)
-            throw new Error('No current snapshot available. Capture a snapshot of navigate to a new location first.');
+            throw new Error('No current snapshot available. Capture a snapshot or navigate to a new location first.');
         return this._currentTab;
     }
     async newTab() {
@@ -241,14 +241,13 @@ ${code.join('\n')}
     async close() {
         if (!this._browserContextPromise)
             return;
+        testDebug('close context');
         const promise = this._browserContextPromise;
         this._browserContextPromise = undefined;
-        await promise.then(async ({ browserContext, browser }) => {
+        await promise.then(async ({ browserContext, close }) => {
             if (this.config.saveTrace)
                 await browserContext.tracing.stop();
-            await browserContext.close().then(async () => {
-                await browser?.close();
-            }).catch(() => { });
+            await close();
         });
     }
     async _setupRequestInterception(context) {
@@ -272,7 +271,9 @@ ${code.join('\n')}
         return this._browserContextPromise;
     }
     async _setupBrowserContext() {
-        const { browser, browserContext } = await this._createBrowserContext();
+        // TODO: move to the browser context factory to make it based on isolation mode.
+        const result = await this._browserContextFactory.createContext();
+        const { browserContext } = result;
         await this._setupRequestInterception(browserContext);
         for (const page of browserContext.pages())
             this._onPageCreated(page);
@@ -285,70 +286,6 @@ ${code.join('\n')}
                 sources: false,
             });
         }
-        return { browser, browserContext };
-    }
-    async _createBrowserContext() {
-        if (this.config.browser?.remoteEndpoint) {
-            const url = new URL(this.config.browser?.remoteEndpoint);
-            if (this.config.browser.browserName)
-                url.searchParams.set('browser', this.config.browser.browserName);
-            if (this.config.browser.launchOptions)
-                url.searchParams.set('launch-options', JSON.stringify(this.config.browser.launchOptions));
-            const browser = await playwright[this.config.browser?.browserName ?? 'chromium'].connect(String(url));
-            const browserContext = await browser.newContext();
-            return { browser, browserContext };
-        }
-        if (this.config.browser?.cdpEndpoint) {
-            const browser = await playwright.chromium.connectOverCDP(this.config.browser.cdpEndpoint);
-            const browserContext = this.config.browser.isolated ? await browser.newContext() : browser.contexts()[0];
-            return { browser, browserContext };
-        }
-        return this.config.browser?.isolated ?
-            await createIsolatedContext(this.config.browser) :
-            await launchPersistentContext(this.config.browser);
-    }
-}
-async function createIsolatedContext(browserConfig) {
-    try {
-        const browserName = browserConfig?.browserName ?? 'chromium';
-        const browserType = playwright[browserName];
-        const browser = await browserType.launch(browserConfig.launchOptions);
-        const browserContext = await browser.newContext(browserConfig.contextOptions);
-        return { browser, browserContext };
-    }
-    catch (error) {
-        if (error.message.includes('Executable doesn\'t exist'))
-            throw new Error(`Browser specified in your config is not installed. Either install it (likely) or change the config.`);
-        throw error;
-    }
-}
-async function launchPersistentContext(browserConfig) {
-    try {
-        const browserName = browserConfig.browserName ?? 'chromium';
-        const userDataDir = browserConfig.userDataDir ?? await createUserDataDir({ ...browserConfig, browserName });
-        const browserType = playwright[browserName];
-        const browserContext = await browserType.launchPersistentContext(userDataDir, { ...browserConfig.launchOptions, ...browserConfig.contextOptions });
-        return { browserContext };
-    }
-    catch (error) {
-        if (error.message.includes('Executable doesn\'t exist'))
-            throw new Error(`Browser specified in your config is not installed. Either install it (likely) or change the config.`);
-        throw error;
+        return result;
     }
 }
-async function createUserDataDir(browserConfig) {
-    let cacheDirectory;
-    if (process.platform === 'linux')
-        cacheDirectory = process.env.XDG_CACHE_HOME || path.join(os.homedir(), '.cache');
-    else if (process.platform === 'darwin')
-        cacheDirectory = path.join(os.homedir(), 'Library', 'Caches');
-    else if (process.platform === 'win32')
-        cacheDirectory = process.env.LOCALAPPDATA || path.join(os.homedir(), 'AppData', 'Local');
-    else
-        throw new Error('Unsupported platform: ' + process.platform);
-    const result = path.join(cacheDirectory, 'ms-playwright', `mcp-${browserConfig.launchOptions?.channel ?? browserConfig?.browserName}-profile`);
-    await fs.promises.mkdir(result, { recursive: true });
-    return result;
-}
-const __filename = url.fileURLToPath(import.meta.url);
-export const packageJSON = JSON.parse(fs.readFileSync(path.join(path.dirname(__filename), '..', 'package.json'), 'utf8'));

package/lib/fileUtils.js

@@ -0,0 +1,32 @@
+/**
+ * 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 os from 'node:os';
+import path from 'node:path';
+export function cacheDir() {
+    let cacheDirectory;
+    if (process.platform === 'linux')
+        cacheDirectory = process.env.XDG_CACHE_HOME || path.join(os.homedir(), '.cache');
+    else if (process.platform === 'darwin')
+        cacheDirectory = path.join(os.homedir(), 'Library', 'Caches');
+    else if (process.platform === 'win32')
+        cacheDirectory = process.env.LOCALAPPDATA || path.join(os.homedir(), 'AppData', 'Local');
+    else
+        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`);
+}

package/lib/httpServer.js

@@ -0,0 +1,201 @@
+/**
+ * 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 fs from 'fs';
+import path from 'path';
+import http from 'http';
+import mime from 'mime';
+import { ManualPromise } from './manualPromise.js';
+export class HttpServer {
+    _server;
+    _urlPrefixPrecise = '';
+    _urlPrefixHumanReadable = '';
+    _port = 0;
+    _routes = [];
+    constructor() {
+        this._server = http.createServer(this._onRequest.bind(this));
+        decorateServer(this._server);
+    }
+    server() {
+        return this._server;
+    }
+    routePrefix(prefix, handler) {
+        this._routes.push({ prefix, handler });
+    }
+    routePath(path, handler) {
+        this._routes.push({ exact: path, handler });
+    }
+    port() {
+        return this._port;
+    }
+    async _tryStart(port, host) {
+        const errorPromise = new ManualPromise();
+        const errorListener = (error) => errorPromise.reject(error);
+        this._server.on('error', errorListener);
+        try {
+            this._server.listen(port, host);
+            await Promise.race([
+                new Promise(cb => this._server.once('listening', cb)),
+                errorPromise,
+            ]);
+        }
+        finally {
+            this._server.removeListener('error', errorListener);
+        }
+    }
+    async start(options = {}) {
+        const host = options.host || 'localhost';
+        if (options.preferredPort) {
+            try {
+                await this._tryStart(options.preferredPort, host);
+            }
+            catch (e) {
+                if (!e || !e.message || !e.message.includes('EADDRINUSE'))
+                    throw e;
+                await this._tryStart(undefined, host);
+            }
+        }
+        else {
+            await this._tryStart(options.port, host);
+        }
+        const address = this._server.address();
+        if (typeof address === 'string') {
+            this._urlPrefixPrecise = address;
+            this._urlPrefixHumanReadable = address;
+        }
+        else {
+            this._port = address.port;
+            const resolvedHost = address.family === 'IPv4' ? address.address : `[${address.address}]`;
+            this._urlPrefixPrecise = `http://${resolvedHost}:${address.port}`;
+            this._urlPrefixHumanReadable = `http://${host}:${address.port}`;
+        }
+    }
+    async stop() {
+        await new Promise(cb => this._server.close(cb));
+    }
+    urlPrefix(purpose) {
+        return purpose === 'human-readable' ? this._urlPrefixHumanReadable : this._urlPrefixPrecise;
+    }
+    serveFile(request, response, absoluteFilePath, headers) {
+        try {
+            for (const [name, value] of Object.entries(headers || {}))
+                response.setHeader(name, value);
+            if (request.headers.range)
+                this._serveRangeFile(request, response, absoluteFilePath);
+            else
+                this._serveFile(response, absoluteFilePath);
+            return true;
+        }
+        catch (e) {
+            return false;
+        }
+    }
+    _serveFile(response, absoluteFilePath) {
+        const content = fs.readFileSync(absoluteFilePath);
+        response.statusCode = 200;
+        const contentType = mime.getType(path.extname(absoluteFilePath)) || 'application/octet-stream';
+        response.setHeader('Content-Type', contentType);
+        response.setHeader('Content-Length', content.byteLength);
+        response.end(content);
+    }
+    _serveRangeFile(request, response, absoluteFilePath) {
+        const range = request.headers.range;
+        if (!range || !range.startsWith('bytes=') || range.includes(', ') || [...range].filter(char => char === '-').length !== 1) {
+            response.statusCode = 400;
+            return response.end('Bad request');
+        }
+        // Parse the range header: https://datatracker.ietf.org/doc/html/rfc7233#section-2.1
+        const [startStr, endStr] = range.replace(/bytes=/, '').split('-');
+        // Both start and end (when passing to fs.createReadStream) and the range header are inclusive and start counting at 0.
+        let start;
+        let end;
+        const size = fs.statSync(absoluteFilePath).size;
+        if (startStr !== '' && endStr === '') {
+            // No end specified: use the whole file
+            start = +startStr;
+            end = size - 1;
+        }
+        else if (startStr === '' && endStr !== '') {
+            // No start specified: calculate start manually
+            start = size - +endStr;
+            end = size - 1;
+        }
+        else {
+            start = +startStr;
+            end = +endStr;
+        }
+        // Handle unavailable range request
+        if (Number.isNaN(start) || Number.isNaN(end) || start >= size || end >= size || start > end) {
+            // Return the 416 Range Not Satisfiable: https://datatracker.ietf.org/doc/html/rfc7233#section-4.4
+            response.writeHead(416, {
+                'Content-Range': `bytes */${size}`
+            });
+            return response.end();
+        }
+        // Sending Partial Content: https://datatracker.ietf.org/doc/html/rfc7233#section-4.1
+        response.writeHead(206, {
+            'Content-Range': `bytes ${start}-${end}/${size}`,
+            'Accept-Ranges': 'bytes',
+            'Content-Length': end - start + 1,
+            'Content-Type': mime.getType(path.extname(absoluteFilePath)),
+        });
+        const readable = fs.createReadStream(absoluteFilePath, { start, end });
+        readable.pipe(response);
+    }
+    _onRequest(request, response) {
+        if (request.method === 'OPTIONS') {
+            response.writeHead(200);
+            response.end();
+            return;
+        }
+        request.on('error', () => response.end());
+        try {
+            if (!request.url) {
+                response.end();
+                return;
+            }
+            const url = new URL('http://localhost' + request.url);
+            for (const route of this._routes) {
+                if (route.exact && url.pathname === route.exact) {
+                    route.handler(request, response);
+                    return;
+                }
+                if (route.prefix && url.pathname.startsWith(route.prefix)) {
+                    route.handler(request, response);
+                    return;
+                }
+            }
+            response.statusCode = 404;
+            response.end();
+        }
+        catch (e) {
+            response.end();
+        }
+    }
+}
+function decorateServer(server) {
+    const sockets = new Set();
+    server.on('connection', socket => {
+        sockets.add(socket);
+        socket.once('close', () => sockets.delete(socket));
+    });
+    const close = server.close;
+    server.close = (callback) => {
+        for (const socket of sockets)
+            socket.destroy();
+        sockets.clear();
+        return close.call(server, callback);
+    };
+}

package/lib/index.js

@@ -15,7 +15,22 @@
  */
 import { createConnection as createConnectionImpl } from './connection.js';
 import { resolveConfig } from './config.js';
-export async function createConnection(userConfig = {}) {
+import { contextFactory } from './browserContextFactory.js';
+export async function createConnection(userConfig = {}, contextGetter) {
     const config = await resolveConfig(userConfig);
-    return createConnectionImpl(config);
+    const factory = contextGetter ? new SimpleBrowserContextFactory(contextGetter) : contextFactory(config.browser);
+    return createConnectionImpl(config, factory);
+}
+class SimpleBrowserContextFactory {
+    _contextGetter;
+    constructor(contextGetter) {
+        this._contextGetter = contextGetter;
+    }
+    async createContext() {
+        const browserContext = await this._contextGetter();
+        return {
+            browserContext,
+            close: () => browserContext.close()
+        };
+    }
 }

package/lib/package.js

@@ -0,0 +1,20 @@
+/**
+ * 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 fs from 'node:fs';
+import url from 'node:url';
+import path from 'node:path';
+const __filename = url.fileURLToPath(import.meta.url);
+export const packageJSON = JSON.parse(fs.readFileSync(path.join(path.dirname(__filename), '..', 'package.json'), 'utf8'));

package/lib/program.js

@@ -14,11 +14,12 @@
  * limitations under the License.
  */
 import { program } from 'commander';
-import { startHttpTransport, startStdioTransport } from './transport.js';
-import { resolveCLIConfig } from './config.js';
 // @ts-ignore
 import { startTraceViewerServer } from 'playwright-core/lib/server';
-import { packageJSON } from './context.js';
+import { startHttpTransport, startStdioTransport } from './transport.js';
+import { resolveCLIConfig } from './config.js';
+import { Server } from './server.js';
+import { packageJSON } from './package.js';
 program
     .version('Version ' + packageJSON.version)
     .name(packageJSON.name)
@@ -26,6 +27,7 @@ program
     .option('--blocked-origins <origins>', 'semicolon-separated list of origins to block the browser from requesting. Blocklist is evaluated before allowlist. If used without the allowlist, requests not matching the blocklist are still allowed.', semicolonSeparatedList)
     .option('--block-service-workers', 'block service workers')
     .option('--browser <browser>', 'browser or chrome channel to use, possible values: chrome, firefox, webkit, msedge.')
+    .option('--browser-agent <endpoint>', 'Use browser agent (experimental).')
     .option('--caps <caps>', 'comma-separated list of capabilities to enable, possible values: tabs, pdf, history, wait, files, install. Default is all.')
     .option('--cdp-endpoint <endpoint>', 'CDP endpoint to connect to.')
     .option('--config <path>', 'path to the configuration file.')
@@ -49,12 +51,12 @@ program
     .option('--vision', 'Run server that uses screenshots (Aria snapshots are used by default)')
     .action(async (options) => {
     const config = await resolveCLIConfig(options);
-    const connectionList = [];
-    setupExitWatchdog(connectionList);
-    if (options.port)
-        startHttpTransport(config, +options.port, options.host, connectionList);
+    const server = new Server(config);
+    server.setupExitWatchdog();
+    if (config.server.port !== undefined)
+        startHttpTransport(server);
     else
-        await startStdioTransport(config, connectionList);
+        await startStdioTransport(server);
     if (config.saveTrace) {
         const server = await startTraceViewerServer();
         const urlPrefix = server.urlPrefix('human-readable');
@@ -63,18 +65,7 @@ program
         console.error('\nTrace viewer listening on ' + url);
     }
 });
-function setupExitWatchdog(connectionList) {
-    const handleExit = async () => {
-        setTimeout(() => process.exit(0), 15000);
-        for (const connection of connectionList)
-            await connection.close();
-        process.exit(0);
-    };
-    process.stdin.on('close', handleExit);
-    process.on('SIGINT', handleExit);
-    process.on('SIGTERM', handleExit);
-}
 function semicolonSeparatedList(value) {
     return value.split(';').map(v => v.trim());
 }
-program.parse(process.argv);
+void program.parseAsync(process.argv);

package/lib/server.js

@@ -0,0 +1,48 @@
+/**
+ * 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 { createConnection } from './connection.js';
+import { contextFactory } from './browserContextFactory.js';
+export class Server {
+    config;
+    _connectionList = [];
+    _browserConfig;
+    _contextFactory;
+    constructor(config) {
+        this.config = config;
+        this._browserConfig = config.browser;
+        this._contextFactory = contextFactory(this._browserConfig);
+    }
+    async createConnection(transport) {
+        const connection = createConnection(this.config, this._contextFactory);
+        this._connectionList.push(connection);
+        await connection.server.connect(transport);
+        return connection;
+    }
+    setupExitWatchdog() {
+        let isExiting = false;
+        const handleExit = async () => {
+            if (isExiting)
+                return;
+            isExiting = true;
+            setTimeout(() => process.exit(0), 15000);
+            await Promise.all(this._connectionList.map(connection => connection.close()));
+            process.exit(0);
+        };
+        process.stdin.on('close', handleExit);
+        process.on('SIGINT', handleExit);
+        process.on('SIGTERM', handleExit);
+    }
+}

package/lib/tab.js

@@ -73,7 +73,7 @@ export class Tab {
             // on chromium, the download event is fired *after* page.goto rejects, so we wait a lil bit
             const download = await Promise.race([
                 downloadEvent,
-                new Promise(resolve => setTimeout(resolve, 500)),
+                new Promise(resolve => setTimeout(resolve, 1000)),
             ]);
             if (!download)
                 throw e;

package/lib/transport.js

@@ -16,16 +16,15 @@
 import http from 'node:http';
 import assert from 'node:assert';
 import crypto from 'node:crypto';
+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 { createConnection } from './connection.js';
-export async function startStdioTransport(config, connectionList) {
-    const connection = await createConnection(config);
-    await connection.connect(new StdioServerTransport());
-    connectionList.push(connection);
+export async function startStdioTransport(server) {
+    await server.createConnection(new StdioServerTransport());
 }
-async function handleSSE(config, req, res, url, sessions, connectionList) {
+const testDebug = debug('pw:mcp:test');
+async function handleSSE(server, req, res, url, sessions) {
     if (req.method === 'POST') {
         const sessionId = url.searchParams.get('sessionId');
         if (!sessionId) {
@@ -42,22 +41,20 @@ async function handleSSE(config, req, res, url, sessions, connectionList) {
     else if (req.method === 'GET') {
         const transport = new SSEServerTransport('/sse', res);
         sessions.set(transport.sessionId, transport);
-        const connection = await createConnection(config);
-        await connection.connect(transport);
-        connectionList.push(connection);
+        testDebug(`create SSE session: ${transport.sessionId}`);
+        const connection = await server.createConnection(transport);
         res.on('close', () => {
+            testDebug(`delete SSE session: ${transport.sessionId}`);
             sessions.delete(transport.sessionId);
-            connection.close().catch(e => {
-                // eslint-disable-next-line no-console
-                console.error(e);
-            });
+            // eslint-disable-next-line no-console
+            void connection.close().catch(e => console.error(e));
         });
         return;
     }
     res.statusCode = 405;
     res.end('Method not allowed');
 }
-async function handleStreamable(config, req, res, sessions, connectionList) {
+async function handleStreamable(server, req, res, sessions) {
     const sessionId = req.headers['mcp-session-id'];
     if (sessionId) {
         const transport = sessions.get(sessionId);
@@ -79,28 +76,25 @@ async function handleStreamable(config, req, res, sessions, connectionList) {
             if (transport.sessionId)
                 sessions.delete(transport.sessionId);
         };
-        const connection = await createConnection(config);
-        connectionList.push(connection);
-        await Promise.all([
-            connection.connect(transport),
-            transport.handleRequest(req, res),
-        ]);
+        await server.createConnection(transport);
+        await transport.handleRequest(req, res);
         return;
     }
     res.statusCode = 400;
     res.end('Invalid request');
 }
-export function startHttpTransport(config, port, hostname, connectionList) {
+export function startHttpTransport(server) {
     const sseSessions = new Map();
     const streamableSessions = new Map();
     const httpServer = http.createServer(async (req, res) => {
         const url = new URL(`http://localhost${req.url}`);
         if (url.pathname.startsWith('/mcp'))
-            await handleStreamable(config, req, res, streamableSessions, connectionList);
+            await handleStreamable(server, req, res, streamableSessions);
         else
-            await handleSSE(config, req, res, url, sseSessions, connectionList);
+            await handleSSE(server, req, res, url, sseSessions);
     });
-    httpServer.listen(port, hostname, () => {
+    const { host, port } = server.config.server;
+    httpServer.listen(port, host, () => {
         const address = httpServer.address();
         assert(address, 'Could not bind server socket');
         let url;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@playwright/mcp",
-  "version": "0.0.27",
+  "version": "0.0.29",
   "description": "Playwright Tools for MCP",
   "type": "module",
   "repository": {
@@ -24,6 +24,7 @@
     "ctest": "playwright test --project=chrome",
     "ftest": "playwright test --project=firefox",
     "wtest": "playwright test --project=webkit",
+    "run-server": "node lib/browserServer.js",
     "clean": "rm -rf lib",
     "npm-publish": "npm run clean && npm run build && npm run test && npm publish"
   },
@@ -37,14 +38,17 @@
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.11.0",
     "commander": "^13.1.0",
-    "playwright": "1.53.0-alpha-2025-05-27",
+    "debug": "^4.4.1",
+    "mime": "^4.0.7",
+    "playwright": "1.53.0",
     "zod-to-json-schema": "^3.24.4"
   },
   "devDependencies": {
     "@eslint/eslintrc": "^3.2.0",
     "@eslint/js": "^9.19.0",
-    "@playwright/test": "1.53.0-alpha-2025-05-27",
+    "@playwright/test": "1.53.0",
     "@stylistic/eslint-plugin": "^3.0.1",
+    "@types/debug": "^4.1.12",
     "@types/node": "^22.13.10",
     "@typescript-eslint/eslint-plugin": "^8.26.1",
     "@typescript-eslint/parser": "^8.26.1",