@playwright/mcp 0.0.28 → 0.0.30

package/README.md

@@ -10,7 +10,7 @@ A Model Context Protocol (MCP) server that provides browser automation capabilit
 
 ### Requirements
 - Node.js 18 or newer
-- VS Code, Cursor, Windsurf, Claude Desktop or any other MCP client
+- VS Code, Cursor, Windsurf, Claude Desktop, Goose or any other MCP client
 
 <!--
 // Generate using:
@@ -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
@@ -71,7 +77,7 @@ Go to `Cursor Settings` -> `MCP` -> `Add new MCP Server`. Name to your liking, u
 <details>
 <summary><b>Install in Windsurf</b></summary>
 
-Follow Windsuff MCP [documentation](https://docs.windsurf.com/windsurf/cascade/mcp). Use following configuration:
+Follow Windsurf MCP [documentation](https://docs.windsurf.com/windsurf/cascade/mcp). Use following configuration:
 
 ```js
 {
@@ -106,6 +112,68 @@ Follow the MCP install [guide](https://modelcontextprotocol.io/quickstart/user),
 ```
 </details>
 
+<details>
+<summary><b>Install in Claude Code</b></summary>
+
+Use the Claude Code CLI to add the Playwright MCP server:
+
+```bash
+claude mcp add playwright npx @playwright/mcp@latest
+```
+</details>
+
+<details>
+<summary><b>Install in Goose</b></summary>
+
+#### Click the button to install:
+
+[![Install in Goose](https://block.github.io/goose/img/extension-install-dark.svg)](https://block.github.io/goose/extension?cmd=npx&arg=%40playwright%2Fmcp%40latest&id=playwright&name=Playwright&description=Interact%20with%20web%20pages%20through%20structured%20accessibility%20snapshots%20using%20Playwright)
+
+#### Or install manually:
+
+Go to `Advanced settings` -> `Extensions` -> `Add custom extension`. Name to your liking, use type `STDIO`, and set the `command` to `npx @playwright/mcp`. Click "Add Extension".
+</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>
+
+<details>
+<summary><b>Install in Gemini CLI</b></summary>
+
+Follow the MCP install [guide](https://github.com/google-gemini/gemini-cli/blob/main/docs/tools/mcp-server.md#configure-the-mcp-server-in-settingsjson), use following configuration:
+
+```js
+{
+  "mcpServers": {
+    "playwright": {
+      "command": "npx",
+      "args": [
+        "@playwright/mcp@latest"
+      ]
+    }
+  }
+}
+```
+</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 +192,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.
@@ -288,9 +357,10 @@ npx @playwright/mcp@latest --config path/to/config.json
   };
  
   /**
-   * Do not send image responses to the client.
+   * Whether to send image responses to the client. Can be "allow", "omit", or "auto". 
+   * Defaults to "auto", images are omitted for Cursor clients and sent for all other clients.
    */
-  noImageResponses?: boolean;
+  imageResponses?: 'allow' | 'omit' | 'auto';
 }
 ```
 </details>
@@ -354,7 +424,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);
 
   // ...
 });
@@ -408,6 +478,7 @@ X Y coordinate space, based on the provided screenshot.
   - Parameters:
     - `element` (string): Human-readable element description used to obtain permission to interact with the element
     - `ref` (string): Exact target element reference from the page snapshot
+    - `doubleClick` (boolean, optional): Whether to perform a double click instead of a single click
   - Read-only: **false**
 
 <!-- NOTE: This has been generated via update-readme.js -->

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,13 +16,11 @@
  */
 
 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>;
 };
 

package/lib/browserContextFactory.js

@@ -14,10 +14,12 @@
  * limitations under the License.
  */
 import fs from 'node:fs';
-import os from 'node:os';
+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)
@@ -26,6 +28,8 @@ export function contextFactory(browserConfig) {
         return new CdpContextFactory(browserConfig);
     if (browserConfig.isolated)
         return new IsolatedContextFactory(browserConfig);
+    if (browserConfig.browserAgent)
+        return new BrowserServerContextFactory(browserConfig);
     return new PersistentContextFactory(browserConfig);
 }
 class BaseContextFactory {
@@ -78,6 +82,7 @@ class IsolatedContextFactory extends BaseContextFactory {
         super('isolated', browserConfig);
     }
     async _doObtainBrowser() {
+        await injectCdpPort(this.browserConfig);
         const browserType = playwright[this.browserConfig.browserName];
         return browserType.launch({
             ...this.browserConfig.launchOptions,
@@ -126,6 +131,7 @@ class PersistentContextFactory {
         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);
@@ -177,3 +183,45 @@ class PersistentContextFactory {
         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';
@@ -48,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) {
@@ -91,6 +88,8 @@ export async function configFromCLIOptions(cliOptions) {
         if (cliOptions.proxyBypass)
             launchOptions.proxy.bypass = cliOptions.proxyBypass;
     }
+    if (cliOptions.device && cliOptions.cdpEndpoint)
+        throw new Error('Device emulation is not supported with cdpEndpoint.');
     // Context options
     const contextOptions = cliOptions.device ? devices[cliOptions.device] : {};
     if (cliOptions.storageState)
@@ -114,6 +113,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,
@@ -137,16 +137,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 {};
@@ -167,6 +157,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: {
@@ -178,9 +170,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;

package/lib/context.js

@@ -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() {

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/program.js

@@ -16,7 +16,7 @@
 import { program } from 'commander';
 // @ts-ignore
 import { startTraceViewerServer } from 'playwright-core/lib/server';
-import { startHttpTransport, startStdioTransport } from './transport.js';
+import { startHttpServer, startHttpTransport, startStdioTransport } from './transport.js';
 import { resolveCLIConfig } from './config.js';
 import { Server } from './server.js';
 import { packageJSON } from './package.js';
@@ -27,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.')
@@ -50,10 +51,11 @@ program
     .option('--vision', 'Run server that uses screenshots (Aria snapshots are used by default)')
     .action(async (options) => {
     const config = await resolveCLIConfig(options);
+    const httpServer = config.server.port !== undefined ? await startHttpServer(config.server) : undefined;
     const server = new Server(config);
     server.setupExitWatchdog();
-    if (config.server.port !== undefined)
-        startHttpTransport(server);
+    if (httpServer)
+        startHttpTransport(httpServer, server);
     else
         await startStdioTransport(server);
     if (config.saveTrace) {

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/tools/snapshot.js

@@ -39,25 +39,33 @@ const elementSchema = z.object({
     element: z.string().describe('Human-readable element description used to obtain permission to interact with the element'),
     ref: z.string().describe('Exact target element reference from the page snapshot'),
 });
+const clickSchema = elementSchema.extend({
+    doubleClick: z.boolean().optional().describe('Whether to perform a double click instead of a single click'),
+});
 const click = defineTool({
     capability: 'core',
     schema: {
         name: 'browser_click',
         title: 'Click',
         description: 'Perform click on a web page',
-        inputSchema: elementSchema,
+        inputSchema: clickSchema,
         type: 'destructive',
     },
     handle: async (context, params) => {
         const tab = context.currentTabOrDie();
         const locator = tab.snapshotOrDie().refLocator(params);
-        const code = [
-            `// Click ${params.element}`,
-            `await page.${await generateLocator(locator)}.click();`
-        ];
+        const code = [];
+        if (params.doubleClick) {
+            code.push(`// Double click ${params.element}`);
+            code.push(`await page.${await generateLocator(locator)}.dblclick();`);
+        }
+        else {
+            code.push(`// Click ${params.element}`);
+            code.push(`await page.${await generateLocator(locator)}.click();`);
+        }
         return {
             code,
-            action: () => locator.click(),
+            action: () => params.doubleClick ? locator.dblclick() : locator.click(),
             captureSnapshot: true,
             waitForNetwork: true,
         };

package/lib/tools/utils.js

@@ -66,7 +66,14 @@ export function sanitizeForFilePath(s) {
     return sanitize(s.substring(0, separator)) + '.' + sanitize(s.substring(separator + 1));
 }
 export async function generateLocator(locator) {
-    return locator._generateLocatorString();
+    try {
+        return await locator._generateLocatorString();
+    }
+    catch (e) {
+        if (e instanceof Error && /locator._generateLocatorString: No element matching locator/.test(e.message))
+            throw new Error('Ref not found, likely because element was removed. Use browser_snapshot to see what elements are currently on the page.');
+        throw e;
+    }
 }
 export async function callOnPageNoTrace(page, callback) {
     return await page._wrapApiCall(() => callback(page), { internal: true });

package/lib/transport.js

@@ -83,44 +83,51 @@ async function handleStreamable(server, req, res, sessions) {
     res.statusCode = 400;
     res.end('Invalid request');
 }
-export function startHttpTransport(server) {
+export async function startHttpServer(config) {
+    const { host, port } = config;
+    const httpServer = http.createServer();
+    await new Promise((resolve, reject) => {
+        httpServer.on('error', reject);
+        httpServer.listen(port, host, () => {
+            resolve();
+            httpServer.removeListener('error', reject);
+        });
+    });
+    return httpServer;
+}
+export function startHttpTransport(httpServer, mcpServer) {
     const sseSessions = new Map();
     const streamableSessions = new Map();
-    const httpServer = http.createServer(async (req, res) => {
+    httpServer.on('request', async (req, res) => {
         const url = new URL(`http://localhost${req.url}`);
         if (url.pathname.startsWith('/mcp'))
-            await handleStreamable(server, req, res, streamableSessions);
+            await handleStreamable(mcpServer, req, res, streamableSessions);
         else
-            await handleSSE(server, req, res, url, sseSessions);
+            await handleSSE(mcpServer, req, res, url, sseSessions);
     });
-    const { host, port } = server.config.server;
-    httpServer.listen(port, host, () => {
-        const address = httpServer.address();
-        assert(address, 'Could not bind server socket');
-        let url;
-        if (typeof address === 'string') {
-            url = address;
-        }
-        else {
-            const resolvedPort = address.port;
-            let resolvedHost = address.family === 'IPv4' ? address.address : `[${address.address}]`;
-            if (resolvedHost === '0.0.0.0' || resolvedHost === '[::]')
-                resolvedHost = 'localhost';
-            url = `http://${resolvedHost}:${resolvedPort}`;
-        }
-        const message = [
-            `Listening on ${url}`,
-            'Put this in your client config:',
-            JSON.stringify({
-                'mcpServers': {
-                    'playwright': {
-                        'url': `${url}/sse`
-                    }
+    const url = httpAddressToString(httpServer.address());
+    const message = [
+        `Listening on ${url}`,
+        'Put this in your client config:',
+        JSON.stringify({
+            'mcpServers': {
+                'playwright': {
+                    'url': `${url}/sse`
                 }
-            }, undefined, 2),
-            'If your client supports streamable HTTP, you can use the /mcp endpoint instead.',
-        ].join('\n');
-        // eslint-disable-next-line no-console
-        console.error(message);
-    });
+            }
+        }, undefined, 2),
+        'If your client supports streamable HTTP, you can use the /mcp endpoint instead.',
+    ].join('\n');
+    // eslint-disable-next-line no-console
+    console.error(message);
+}
+export function httpAddressToString(address) {
+    assert(address, 'Could not bind server socket');
+    if (typeof address === 'string')
+        return address;
+    const resolvedPort = address.port;
+    let resolvedHost = address.family === 'IPv4' ? address.address : `[${address.address}]`;
+    if (resolvedHost === '0.0.0.0' || resolvedHost === '[::]')
+        resolvedHost = 'localhost';
+    return `http://${resolvedHost}:${resolvedPort}`;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@playwright/mcp",
-  "version": "0.0.28",
+  "version": "0.0.30",
   "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"
   },
@@ -38,16 +39,20 @@
     "@modelcontextprotocol/sdk": "^1.11.0",
     "commander": "^13.1.0",
     "debug": "^4.4.1",
-    "playwright": "1.53.0-alpha-2025-05-27",
+    "mime": "^4.0.7",
+    "playwright": "1.54.1",
+    "ws": "^8.18.1",
     "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.54.1",
     "@stylistic/eslint-plugin": "^3.0.1",
+    "@types/chrome": "^0.0.315",
     "@types/debug": "^4.1.12",
     "@types/node": "^22.13.10",
+    "@types/ws": "^8.18.1",
     "@typescript-eslint/eslint-plugin": "^8.26.1",
     "@typescript-eslint/parser": "^8.26.1",
     "@typescript-eslint/utils": "^8.26.1",

package/lib/resources/resource.js

@@ -1,16 +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.
- */
-export {};