@playwright/mcp 0.0.29 → 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:
@@ -77,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
 {
@@ -112,6 +112,28 @@ 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>
 
@@ -133,6 +155,25 @@ Open [Qodo Gen](https://docs.qodo.ai/qodo-documentation/qodo-gen) chat panel in
 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:
@@ -316,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>
@@ -436,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/lib/config.js

@@ -88,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)

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';
@@ -51,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/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.29",
+  "version": "0.0.30",
   "description": "Playwright Tools for MCP",
   "type": "module",
   "repository": {
@@ -40,16 +40,19 @@
     "commander": "^13.1.0",
     "debug": "^4.4.1",
     "mime": "^4.0.7",
-    "playwright": "1.53.0",
+    "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",
+    "@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 {};