@playwright/mcp 0.0.35 → 0.0.36

package/README.md

@@ -80,7 +80,7 @@ For more information, see the [Codex MCP documentation](https://github.com/opena
 
 #### 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`.
+Go to `Cursor Settings` -> `MCP` -> `Add new MCP Server`. Name to your liking, use `command` type with the command `npx @playwright/mcp@latest`. You can also verify config or add command like arguments via clicking `Edit`.
 
 </details>
 
@@ -705,5 +705,52 @@ http.createServer(async (req, res) => {
 
 </details>
 
+<details>
+<summary><b>Verify (opt-in via --caps=verify)</b></summary>
+
+<!-- NOTE: This has been generated via update-readme.js -->
+
+- **browser_verify_element_visible**
+  - Title: Verify element visible
+  - Description: Verify element is visible on the page
+  - Parameters:
+    - `role` (string): ROLE of the element. Can be found in the snapshot like this: `- {ROLE} "Accessible Name":`
+    - `accessibleName` (string): ACCESSIBLE_NAME of the element. Can be found in the snapshot like this: `- role "{ACCESSIBLE_NAME}"`
+  - Read-only: **true**
+
+<!-- NOTE: This has been generated via update-readme.js -->
+
+- **browser_verify_list_visible**
+  - Title: Verify list visible
+  - Description: Verify list is visible on the page
+  - Parameters:
+    - `element` (string): Human-readable list description
+    - `ref` (string): Exact target element reference that points to the list
+    - `items` (array): Items to verify
+  - Read-only: **true**
+
+<!-- NOTE: This has been generated via update-readme.js -->
+
+- **browser_verify_text_visible**
+  - Title: Verify text visible
+  - Description: Verify text is visible on the page. Prefer browser_verify_element_visible if possible.
+  - Parameters:
+    - `text` (string): TEXT to verify. Can be found in the snapshot like this: `- role "Accessible Name": {TEXT}` or like this: `- text: {TEXT}`
+  - Read-only: **true**
+
+<!-- NOTE: This has been generated via update-readme.js -->
+
+- **browser_verify_value**
+  - Title: Verify value
+  - Description: Verify element value
+  - Parameters:
+    - `type` (string): Type of the element
+    - `element` (string): Human-readable element description
+    - `ref` (string): Exact target element reference that points to the element
+    - `value` (string): Value to verify. For checkbox, use "true" or "false".
+  - Read-only: **true**
+
+</details>
+
 
 <!--- End of tools generated section -->

package/config.d.ts

@@ -16,7 +16,7 @@
 
 import type * as playwright from 'playwright';
 
-export type ToolCapability = 'core' | 'core-tabs' | 'core-install' | 'vision' | 'pdf';
+export type ToolCapability = 'core' | 'core-tabs' | 'core-install' | 'vision' | 'pdf' | 'verify';
 
 export type Config = {
   /**

package/lib/extension/cdpRelay.js

@@ -26,6 +26,7 @@ import { WebSocket, WebSocketServer } from 'ws';
 import { httpAddressToString } from '../mcp/http.js';
 import { logUnhandledError } from '../utils/log.js';
 import { ManualPromise } from '../mcp/manualPromise.js';
+import * as protocol from './protocol.js';
 // @ts-ignore
 const { registry } = await import('playwright-core/lib/server/registry/index');
 const debugLogger = debug('pw:mcp:relay');
@@ -33,6 +34,7 @@ export class CDPRelayServer {
     _wsHost;
     _browserChannel;
     _userDataDir;
+    _executablePath;
     _cdpPath;
     _extensionPath;
     _wss;
@@ -41,10 +43,11 @@ export class CDPRelayServer {
     _connectedTabInfo;
     _nextSessionId = 1;
     _extensionConnectionPromise;
-    constructor(server, browserChannel, userDataDir) {
+    constructor(server, browserChannel, userDataDir, executablePath) {
         this._wsHost = httpAddressToString(server.address()).replace(/^http/, 'ws');
         this._browserChannel = browserChannel;
         this._userDataDir = userDataDir;
+        this._executablePath = executablePath;
         const uuid = crypto.randomUUID();
         this._cdpPath = `/cdp/${uuid}`;
         this._extensionPath = `/extension/${uuid}`;
@@ -83,15 +86,19 @@ export class CDPRelayServer {
             version: clientInfo.version,
         };
         url.searchParams.set('client', JSON.stringify(client));
+        url.searchParams.set('protocolVersion', process.env.PWMCP_TEST_PROTOCOL_VERSION ?? protocol.VERSION.toString());
         if (toolName)
             url.searchParams.set('newTab', String(toolName === 'browser_navigate'));
         const href = url.toString();
-        const executableInfo = registry.findExecutable(this._browserChannel);
-        if (!executableInfo)
-            throw new Error(`Unsupported channel: "${this._browserChannel}"`);
-        const executablePath = executableInfo.executablePath();
-        if (!executablePath)
-            throw new Error(`"${this._browserChannel}" executable not found. Make sure it is installed at a standard location.`);
+        let executablePath = this._executablePath;
+        if (!executablePath) {
+            const executableInfo = registry.findExecutable(this._browserChannel);
+            if (!executableInfo)
+                throw new Error(`Unsupported channel: "${this._browserChannel}"`);
+            executablePath = executableInfo.executablePath();
+            if (!executablePath)
+                throw new Error(`"${this._browserChannel}" executable not found. Make sure it is installed at a standard location.`);
+        }
         const args = [];
         if (this._userDataDir)
             args.push(`--user-data-dir=${this._userDataDir}`);
@@ -195,10 +202,6 @@ export class CDPRelayServer {
                     params: params.params
                 });
                 break;
-            case 'detachedFromTab':
-                debugLogger('← Debugger detached from tab:', params);
-                this._connectedTabInfo = undefined;
-                break;
         }
     }
     async _handlePlaywrightMessage(message) {
@@ -234,7 +237,7 @@ export class CDPRelayServer {
                 if (sessionId)
                     break;
                 // Simulate auto-attach behavior with real target info
-                const { targetInfo } = await this._extensionConnection.send('attachToTab');
+                const { targetInfo } = await this._extensionConnection.send('attachToTab', {});
                 this._connectedTabInfo = {
                     targetInfo,
                     sessionId: `pw-tab-${this._nextSessionId++}`,
@@ -284,11 +287,11 @@ class ExtensionConnection {
         this._ws.on('close', this._onClose.bind(this));
         this._ws.on('error', this._onError.bind(this));
     }
-    async send(method, params, sessionId) {
+    async send(method, params) {
         if (this._ws.readyState !== WebSocket.OPEN)
             throw new Error(`Unexpected WebSocket state: ${this._ws.readyState}`);
         const id = ++this._lastId;
-        this._ws.send(JSON.stringify({ id, method, params, sessionId }));
+        this._ws.send(JSON.stringify({ id, method, params }));
         const error = new Error(`Protocol error: ${method}`);
         return new Promise((resolve, reject) => {
             this._callbacks.set(id, { resolve, reject, error });

package/lib/extension/extensionContextFactory.js

@@ -21,9 +21,11 @@ const debugLogger = debug('pw:mcp:relay');
 export class ExtensionContextFactory {
     _browserChannel;
     _userDataDir;
-    constructor(browserChannel, userDataDir) {
+    _executablePath;
+    constructor(browserChannel, userDataDir, executablePath) {
         this._browserChannel = browserChannel;
         this._userDataDir = userDataDir;
+        this._executablePath = executablePath;
     }
     async createContext(clientInfo, abortSignal, toolName) {
         const browser = await this._obtainBrowser(clientInfo, abortSignal, toolName);
@@ -46,7 +48,7 @@ export class ExtensionContextFactory {
             httpServer.close();
             throw new Error(abortSignal.reason);
         }
-        const cdpRelayServer = new CDPRelayServer(httpServer, this._browserChannel, this._userDataDir);
+        const cdpRelayServer = new CDPRelayServer(httpServer, this._browserChannel, this._userDataDir, this._executablePath);
         abortSignal.addEventListener('abort', () => cdpRelayServer.stop());
         debugLogger(`CDP relay server started, extension endpoint: ${cdpRelayServer.extensionEndpoint()}.`);
         return cdpRelayServer;

package/lib/extension/protocol.js

@@ -0,0 +1,18 @@
+/**
+ * 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.
+ */
+// Whenever the commands/events change, the version must be updated. The latest
+// extension version should be compatible with the old MCP clients.
+export const VERSION = 1;

package/lib/program.js

@@ -66,7 +66,7 @@ program
     }
     const config = await resolveCLIConfig(options);
     const browserContextFactory = contextFactory(config);
-    const extensionContextFactory = new ExtensionContextFactory(config.browser.launchOptions.channel || 'chrome', config.browser.userDataDir);
+    const extensionContextFactory = new ExtensionContextFactory(config.browser.launchOptions.channel || 'chrome', config.browser.userDataDir, config.browser.launchOptions.executablePath);
     if (options.extension) {
         const serverBackendFactory = {
             name: 'Playwright w/ extension',

package/lib/tools/tabs.js

@@ -45,7 +45,7 @@ const browserTabs = defineTool({
                 return;
             }
             case 'select': {
-                if (!params.index)
+                if (params.index === undefined)
                     throw new Error('Tab index is required');
                 await context.selectTab(params.index);
                 response.setIncludeSnapshot();

package/lib/tools/verify.js

@@ -0,0 +1,137 @@
+/**
+ * Copyright (c) Microsoft Corporation.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+import { z } from 'zod';
+import { defineTabTool } from './tool.js';
+import * as javascript from '../utils/codegen.js';
+import { generateLocator } from './utils.js';
+const verifyElement = defineTabTool({
+    capability: 'verify',
+    schema: {
+        name: 'browser_verify_element_visible',
+        title: 'Verify element visible',
+        description: 'Verify element is visible on the page',
+        inputSchema: z.object({
+            role: z.string().describe('ROLE of the element. Can be found in the snapshot like this: \`- {ROLE} "Accessible Name":\`'),
+            accessibleName: z.string().describe('ACCESSIBLE_NAME of the element. Can be found in the snapshot like this: \`- role "{ACCESSIBLE_NAME}"\`'),
+        }),
+        type: 'readOnly',
+    },
+    handle: async (tab, params, response) => {
+        const locator = tab.page.getByRole(params.role, { name: params.accessibleName });
+        if (await locator.count() === 0) {
+            response.addError(`Element with role "${params.role}" and accessible name "${params.accessibleName}" not found`);
+            return;
+        }
+        response.addCode(`await expect(page.getByRole(${javascript.escapeWithQuotes(params.role)}, { name: ${javascript.escapeWithQuotes(params.accessibleName)} })).toBeVisible();`);
+        response.addResult('Done');
+    },
+});
+const verifyText = defineTabTool({
+    capability: 'verify',
+    schema: {
+        name: 'browser_verify_text_visible',
+        title: 'Verify text visible',
+        description: `Verify text is visible on the page. Prefer ${verifyElement.schema.name} if possible.`,
+        inputSchema: z.object({
+            text: z.string().describe('TEXT to verify. Can be found in the snapshot like this: \`- role "Accessible Name": {TEXT}\` or like this: \`- text: {TEXT}\`'),
+        }),
+        type: 'readOnly',
+    },
+    handle: async (tab, params, response) => {
+        const locator = tab.page.getByText(params.text).filter({ visible: true });
+        if (await locator.count() === 0) {
+            response.addError('Text not found');
+            return;
+        }
+        response.addCode(`await expect(page.getByText(${javascript.escapeWithQuotes(params.text)})).toBeVisible();`);
+        response.addResult('Done');
+    },
+});
+const verifyList = defineTabTool({
+    capability: 'verify',
+    schema: {
+        name: 'browser_verify_list_visible',
+        title: 'Verify list visible',
+        description: 'Verify list is visible on the page',
+        inputSchema: z.object({
+            element: z.string().describe('Human-readable list description'),
+            ref: z.string().describe('Exact target element reference that points to the list'),
+            items: z.array(z.string()).describe('Items to verify'),
+        }),
+        type: 'readOnly',
+    },
+    handle: async (tab, params, response) => {
+        const locator = await tab.refLocator({ ref: params.ref, element: params.element });
+        const itemTexts = [];
+        for (const item of params.items) {
+            const itemLocator = locator.getByText(item);
+            if (await itemLocator.count() === 0) {
+                response.addError(`Item "${item}" not found`);
+                return;
+            }
+            itemTexts.push((await itemLocator.textContent()));
+        }
+        const ariaSnapshot = `\`
+- list:
+${itemTexts.map(t => `  - listitem: ${javascript.escapeWithQuotes(t, '"')}`).join('\n')}
+\``;
+        response.addCode(`await expect(page.locator('body')).toMatchAriaSnapshot(${ariaSnapshot});`);
+        response.addResult('Done');
+    },
+});
+const verifyValue = defineTabTool({
+    capability: 'verify',
+    schema: {
+        name: 'browser_verify_value',
+        title: 'Verify value',
+        description: 'Verify element value',
+        inputSchema: z.object({
+            type: z.enum(['textbox', 'checkbox', 'radio', 'combobox', 'slider']).describe('Type of the element'),
+            element: z.string().describe('Human-readable element description'),
+            ref: z.string().describe('Exact target element reference that points to the element'),
+            value: z.string().describe('Value to verify. For checkbox, use "true" or "false".'),
+        }),
+        type: 'readOnly',
+    },
+    handle: async (tab, params, response) => {
+        const locator = await tab.refLocator({ ref: params.ref, element: params.element });
+        const locatorSource = `page.${await generateLocator(locator)}`;
+        if (params.type === 'textbox' || params.type === 'slider' || params.type === 'combobox') {
+            const value = await locator.inputValue();
+            if (value !== params.value) {
+                response.addError(`Expected value "${params.value}", but got "${value}"`);
+                return;
+            }
+            response.addCode(`await expect(${locatorSource}).toHaveValue(${javascript.quote(params.value)});`);
+        }
+        else if (params.type === 'checkbox' || params.type === 'radio') {
+            const value = await locator.isChecked();
+            if (value !== (params.value === 'true')) {
+                response.addError(`Expected value "${params.value}", but got "${value}"`);
+                return;
+            }
+            const matcher = value ? 'toBeChecked' : 'not.toBeChecked';
+            response.addCode(`await expect(${locatorSource}).${matcher}();`);
+        }
+        response.addResult('Done');
+    },
+});
+export default [
+    verifyElement,
+    verifyText,
+    verifyList,
+    verifyValue,
+];

package/lib/tools.js

@@ -21,6 +21,7 @@ import files from './tools/files.js';
 import form from './tools/form.js';
 import install from './tools/install.js';
 import keyboard from './tools/keyboard.js';
+import mouse from './tools/mouse.js';
 import navigate from './tools/navigate.js';
 import network from './tools/network.js';
 import pdf from './tools/pdf.js';
@@ -28,7 +29,7 @@ import snapshot from './tools/snapshot.js';
 import tabs from './tools/tabs.js';
 import screenshot from './tools/screenshot.js';
 import wait from './tools/wait.js';
-import mouse from './tools/mouse.js';
+import verify from './tools/verify.js';
 export const allTools = [
     ...common,
     ...console,
@@ -46,6 +47,7 @@ export const allTools = [
     ...snapshot,
     ...tabs,
     ...wait,
+    ...verify,
 ];
 export function filteredTools(config) {
     return allTools.filter(tool => tool.capability.startsWith('core') || config.capabilities?.includes(tool.capability));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@playwright/mcp",
-  "version": "0.0.35",
+  "version": "0.0.36",
   "description": "Playwright Tools for MCP",
   "type": "module",
   "repository": {
@@ -43,8 +43,8 @@
     "debug": "^4.4.1",
     "dotenv": "^17.2.0",
     "mime": "^4.0.7",
-    "playwright": "1.55.0-alpha-2025-08-12",
-    "playwright-core": "1.55.0-alpha-2025-08-12",
+    "playwright": "1.56.0-alpha-1756505518000",
+    "playwright-core": "1.56.0-alpha-1756505518000",
     "ws": "^8.18.1",
     "zod": "^3.24.1",
     "zod-to-json-schema": "^3.24.4"
@@ -53,7 +53,7 @@
     "@anthropic-ai/sdk": "^0.57.0",
     "@eslint/eslintrc": "^3.2.0",
     "@eslint/js": "^9.19.0",
-    "@playwright/test": "1.55.0-alpha-2025-08-12",
+    "@playwright/test": "1.56.0-alpha-1756505518000",
     "@stylistic/eslint-plugin": "^3.0.1",
     "@types/debug": "^4.1.12",
     "@types/node": "^22.13.10",