chore: mark v0.0.36 (#972)

Fixes https://github.com/microsoft/playwright-mcp/issues/941

.github/workflows/publish-canary.yml

@@ -0,0 +1,48 @@
+name: Publish Canary
+on:
+  schedule:
+    - cron: '0 8 * * *'
+  workflow_dispatch:
+
+jobs:
+  publish-canary:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      id-token: write # Needed for npm provenance
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 18
+          registry-url: https://registry.npmjs.org/
+
+      - name: Get current date
+        id: date
+        run: echo "date=$(date +'%Y-%m-%d')" >> $GITHUB_OUTPUT
+
+      - name: Get current version
+        id: version
+        run: echo "version=$(node -p "require('./package.json').version")" >> $GITHUB_OUTPUT
+
+      - name: Set canary version
+        id: canary-version
+        run: echo "version=${{ steps.version.outputs.version }}-alpha-${{ steps.date.outputs.date }}" >> $GITHUB_OUTPUT
+
+      - name: Update package.json version
+        run: |
+          npm version ${{ steps.canary-version.outputs.version }} --no-git-tag-version
+
+      - run: npm ci
+      - run: npx playwright install --with-deps
+      - run: npm run build
+      - run: npm run lint
+      - run: npm run ctest
+
+      - name: Publish to npm with next tag
+        run: npm publish --tag next --provenance
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
+
+      - name: Reset package.json version
+        run: git checkout -- package.json

README.md

@@ -56,6 +56,21 @@ Follow the MCP install [guide](https://modelcontextprotocol.io/quickstart/user),
 
 </details>
 
+<details>
+<summary>Codex</summary>
+
+Create or edit the configuration file `~/.codex/config.toml` and add:
+
+```toml
+[mcp_servers.playwright]
+command = "npx"
+args = ["@playwright/mcp@latest"]
+```
+
+For more information, see the [Codex MCP documentation](https://github.com/openai/codex/blob/main/codex-rs/config.md#mcp_servers).
+
+</details>
+
 <details>
 <summary>Cursor</summary>
 
@@ -65,7 +80,7 @@ Follow the MCP install [guide](https://modelcontextprotocol.io/quickstart/user),
 
 #### 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>
 
@@ -479,6 +494,15 @@ http.createServer(async (req, res) => {
 
 <!-- NOTE: This has been generated via update-readme.js -->
 
+- **browser_fill_form**
+  - Title: Fill form
+  - Description: Fill multiple form fields
+  - Parameters:
+    - `fields` (array): Fields to fill in
+  - Read-only: **false**
+
+<!-- NOTE: This has been generated via update-readme.js -->
+
 - **browser_handle_dialog**
   - Title: Handle a dialog
   - Description: Handle a dialog
@@ -516,14 +540,6 @@ http.createServer(async (req, res) => {
 
 <!-- NOTE: This has been generated via update-readme.js -->
 
-- **browser_navigate_forward**
-  - Title: Go forward
-  - Description: Go forward to the next page
-  - Parameters: None
-  - Read-only: **true**
-
-<!-- NOTE: This has been generated via update-readme.js -->
-
 - **browser_network_requests**
   - Title: List network requests
   - Description: Returns all network requests since loading the page
@@ -612,39 +628,14 @@ http.createServer(async (req, res) => {
 
 <!-- NOTE: This has been generated via update-readme.js -->
 
-- **browser_tab_close**
-  - Title: Close a tab
-  - Description: Close a tab
+- **browser_tabs**
+  - Title: Manage tabs
+  - Description: List, create, close, or select a browser tab.
   - Parameters:
-    - `index` (number, optional): The index of the tab to close. Closes current tab if not provided.
+    - `action` (string): Operation to perform
+    - `index` (number, optional): Tab index, used for close/select. If omitted for close, current tab is closed.
   - Read-only: **false**
 
-<!-- NOTE: This has been generated via update-readme.js -->
-
-- **browser_tab_list**
-  - Title: List tabs
-  - Description: List browser tabs
-  - Parameters: None
-  - Read-only: **true**
-
-<!-- NOTE: This has been generated via update-readme.js -->
-
-- **browser_tab_new**
-  - Title: Open a new tab
-  - Description: Open a new tab
-  - Parameters:
-    - `url` (string, optional): The URL to navigate to in the new tab. If not provided, the new tab will be blank.
-  - Read-only: **true**
-
-<!-- NOTE: This has been generated via update-readme.js -->
-
-- **browser_tab_select**
-  - Title: Select a tab
-  - Description: Select a tab by index
-  - Parameters:
-    - `index` (number): The index of the tab to select
-  - Read-only: **true**
-
 </details>
 
 <details>
@@ -714,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 -->

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 = {
   /**

extension/manifest.json

@@ -1,26 +1,22 @@
 {
   "manifest_version": 3,
   "name": "Playwright MCP Bridge",
-  "version": "0.0.34",
+  "version": "0.0.36",
   "description": "Share browser tabs with Playwright MCP server",
   "key": "MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEA9nMS2b0WCohjVHPGb8D9qAdkbIngDqoAjTeSccHJijgcONejge+OJxOQOMLu7b0ovt1c9BiEJa5JcpM+EHFVGL1vluBxK71zmBy1m2f9vZF3HG0LSCp7YRkum9rAIEthDwbkxx6XTvpmAY5rjFa/NON6b9Hlbo+8peUSkoOK7HTwYnnI36asZ9eUTiveIf+DMPLojW2UX33vDWG2UKvMVDewzclb4+uLxAYshY7Mx8we/b44xu+Anb/EBLKjOPk9Yh541xJ5Ozc8EiP/5yxOp9c/lRiYUHaRW+4r0HKZyFt0eZ52ti2iM4Nfk7jRXR7an3JPsUIf5deC/1cVM/+1ZQIDAQAB",
-
   "permissions": [
     "debugger",
     "activeTab",
     "tabs",
     "storage"
   ],
-
   "host_permissions": [
     "<all_urls>"
   ],
-
   "background": {
     "service_worker": "lib/background.js",
     "type": "module"
   },
-
   "action": {
     "default_title": "Playwright MCP Bridge",
     "default_icon": {
@@ -30,7 +26,6 @@
       "128": "icons/icon-128.png"
     }
   },
-
   "icons": {
     "16": "icons/icon-16.png",
     "32": "icons/icon-32.png",

extension/package-lock.json

@@ -1,12 +1,12 @@
 {
   "name": "@playwright/mcp-extension",
-  "version": "0.0.34",
+  "version": "0.0.36",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "@playwright/mcp-extension",
-      "version": "0.0.34",
+      "version": "0.0.36",
       "license": "Apache-2.0",
       "devDependencies": {
         "@types/chrome": "^0.0.315",

extension/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@playwright/mcp-extension",
-  "version": "0.0.34",
+  "version": "0.0.36",
   "description": "Playwright MCP Browser Extension",
   "type": "module",
   "private": true,

extension/src/background.ts

@@ -23,8 +23,8 @@ type PageMessage = {
   type: 'getTabs';
 } | {
   type: 'connectToTab';
-  tabId: number;
-  windowId: number;
+  tabId?: number;
+  windowId?: number;
   mcpRelayUrl: string;
 } | {
   type: 'getConnectionStatus';
@@ -49,7 +49,7 @@ class TabShareExtension {
   private _onMessage(message: PageMessage, sender: chrome.runtime.MessageSender, sendResponse: (response: any) => void) {
     switch (message.type) {
       case 'connectToMCPRelay':
-        this._connectToRelay(sender.tab!.id!, message.mcpRelayUrl!).then(
+        this._connectToRelay(sender.tab!.id!, message.mcpRelayUrl).then(
             () => sendResponse({ success: true }),
             (error: any) => sendResponse({ success: false, error: error.message }));
         return true;
@@ -59,7 +59,9 @@ class TabShareExtension {
             (error: any) => sendResponse({ success: false, error: error.message }));
         return true;
       case 'connectToTab':
-        this._connectTab(sender.tab!.id!, message.tabId, message.windowId, message.mcpRelayUrl!).then(
+        const tabId = message.tabId || sender.tab?.id!;
+        const windowId = message.windowId || sender.tab?.windowId!;
+        this._connectTab(sender.tab!.id!, tabId, windowId, message.mcpRelayUrl!).then(
             () => sendResponse({ success: true }),
             (error: any) => sendResponse({ success: false, error: error.message }));
         return true; // Return true to indicate that the response will be sent asynchronously
@@ -96,8 +98,9 @@ class TabShareExtension {
       this._pendingTabSelection.set(selectorTabId, { connection });
       debugLog(`Connected to MCP relay`);
     } catch (error: any) {
-      debugLog(`Failed to connect to MCP relay:`, error.message);
-      throw error;
+      const message = `Failed to connect to MCP relay: ${error.message}`;
+      debugLog(message);
+      throw new Error(message);
     }
   }
 

extension/src/ui/connect.css

@@ -192,4 +192,15 @@ body {
   white-space: nowrap;
   overflow: hidden;
   text-overflow: ellipsis;
+}
+
+/* Link-style button */
+.link-button {
+  background: none;
+  border: none;
+  color: #0066cc;
+  text-decoration: underline;
+  cursor: pointer;
+  padding: 0;
+  font: inherit;
 }

extension/src/ui/connect.tsx

@@ -19,15 +19,22 @@ import { createRoot } from 'react-dom/client';
 import { Button, TabItem  } from './tabItem.js';
 import type { TabInfo } from './tabItem.js';
 
-type StatusType = 'connected' | 'error' | 'connecting';
+type Status =
+  | { type: 'connecting'; message: string }
+  | { type: 'connected'; message: string }
+  | { type: 'error'; message: string }
+  | { type: 'error'; versionMismatch: { extensionVersion: string; } };
+
+const SUPPORTED_PROTOCOL_VERSION = 1;
 
 const ConnectApp: React.FC = () => {
   const [tabs, setTabs] = useState<TabInfo[]>([]);
-  const [status, setStatus] = useState<{ type: StatusType; message: string } | null>(null);
+  const [status, setStatus] = useState<Status | null>(null);
   const [showButtons, setShowButtons] = useState(true);
   const [showTabList, setShowTabList] = useState(true);
   const [clientInfo, setClientInfo] = useState('unknown');
   const [mcpRelayUrl, setMcpRelayUrl] = useState('');
+  const [newTab, setNewTab] = useState<boolean>(false);
 
   useEffect(() => {
     const params = new URLSearchParams(window.location.search);
@@ -54,15 +61,44 @@ const ConnectApp: React.FC = () => {
       return;
     }
 
+    const parsedVersion = parseInt(params.get('protocolVersion') ?? '', 10);
+    const requiredVersion = isNaN(parsedVersion) ? 1 : parsedVersion;
+    if (requiredVersion > SUPPORTED_PROTOCOL_VERSION) {
+      const extensionVersion = chrome.runtime.getManifest().version;
+      setShowButtons(false);
+      setShowTabList(false);
+      setStatus({
+        type: 'error',
+        versionMismatch: {
+          extensionVersion,
+        }
+      });
+      return;
+    }
+
     void connectToMCPRelay(relayUrl);
-    void loadTabs();
+
+    // If this is a browser_navigate command, hide the tab list and show simple allow/reject
+    if (params.get('newTab') === 'true') {
+      setNewTab(true);
+      setShowTabList(false);
+    } else {
+      void loadTabs();
+    }
+  }, []);
+
+  const handleReject = useCallback((message: string) => {
+    setShowButtons(false);
+    setShowTabList(false);
+    setStatus({ type: 'error', message });
   }, []);
 
   const connectToMCPRelay = useCallback(async (mcpRelayUrl: string) => {
-    const response = await chrome.runtime.sendMessage({ type: 'connectToMCPRelay', mcpRelayUrl });
+
+    const response = await chrome.runtime.sendMessage({ type: 'connectToMCPRelay', mcpRelayUrl  });
     if (!response.success)
-      setStatus({ type: 'error', message: 'Failed to connect to MCP relay: ' + response.error });
-  }, []);
+      handleReject(response.error);
+  }, [handleReject]);
 
   const loadTabs = useCallback(async () => {
     const response = await chrome.runtime.sendMessage({ type: 'getTabs' });
@@ -72,7 +108,7 @@ const ConnectApp: React.FC = () => {
       setStatus({ type: 'error', message: 'Failed to load tabs: ' + response.error });
   }, []);
 
-  const handleConnectToTab = useCallback(async (tab: TabInfo) => {
+  const handleConnectToTab = useCallback(async (tab?: TabInfo) => {
     setShowButtons(false);
     setShowTabList(false);
 
@@ -80,8 +116,8 @@ const ConnectApp: React.FC = () => {
       const response = await chrome.runtime.sendMessage({
         type: 'connectToTab',
         mcpRelayUrl,
-        tabId: tab.id,
-        windowId: tab.windowId,
+        tabId: tab?.id,
+        windowId: tab?.windowId,
       });
 
       if (response?.success) {
@@ -100,33 +136,40 @@ const ConnectApp: React.FC = () => {
     }
   }, [clientInfo, mcpRelayUrl]);
 
-  const handleReject = useCallback(() => {
-    setShowButtons(false);
-    setShowTabList(false);
-    setStatus({ type: 'error', message: 'Connection rejected. This tab can be closed.' });
-  }, []);
-
   useEffect(() => {
     const listener = (message: any) => {
       if (message.type === 'connectionTimeout')
-        handleReject();
+        handleReject('Connection timed out.');
     };
     chrome.runtime.onMessage.addListener(listener);
     return () => {
       chrome.runtime.onMessage.removeListener(listener);
     };
-  }, []);
+  }, [handleReject]);
 
   return (
     <div className='app-container'>
       <div className='content-wrapper'>
         {status && (
           <div className='status-container'>
-            <StatusBanner type={status.type} message={status.message} />
+            <StatusBanner status={status} />
             {showButtons && (
-              <Button variant='reject' onClick={handleReject}>
-                Reject
-              </Button>
+              <div className='button-container'>
+                {newTab ? (
+                  <>
+                    <Button variant='primary' onClick={() => handleConnectToTab()}>
+                      Allow
+                    </Button>
+                    <Button variant='reject' onClick={() => handleReject('Connection rejected. This tab can be closed.')}>
+                      Reject
+                    </Button>
+                  </>
+                ) : (
+                  <Button variant='reject' onClick={() => handleReject('Connection rejected. This tab can be closed.')}>
+                    Reject
+                  </Button>
+                )}
+              </div>
             )}
           </div>
         )}
@@ -156,8 +199,30 @@ const ConnectApp: React.FC = () => {
   );
 };
 
-const StatusBanner: React.FC<{ type: StatusType; message: string }> = ({ type, message }) => {
-  return <div className={`status-banner ${type}`}>{message}</div>;
+const VersionMismatchError: React.FC<{ extensionVersion: string }> = ({ extensionVersion }) => {
+  const readmeUrl = 'https://github.com/microsoft/playwright-mcp/blob/main/extension/README.md';
+  const latestReleaseUrl = 'https://github.com/microsoft/playwright-mcp/releases/latest';
+  return (
+    <div>
+      Playwright MCP version trying to connect requires newer extension version (current version: {extensionVersion}).{' '}
+      <a href={latestReleaseUrl}>Click here</a> to download latest version of the extension, then drag and drop it into the Chrome Extensions page.{' '}
+      See <a href={readmeUrl} target='_blank' rel='noopener noreferrer'>installation instructions</a> for more details.
+    </div>
+  );
+};
+
+const StatusBanner: React.FC<{ status: Status }> = ({ status }) => {
+  return (
+    <div className={`status-banner ${status.type}`}>
+      {'versionMismatch' in status ? (
+        <VersionMismatchError
+          extensionVersion={status.versionMismatch.extensionVersion}
+        />
+      ) : (
+        status.message
+      )}
+    </div>
+  );
 };
 
 // Initialize the React app

extension/tests/extension.spec.ts

@@ -14,12 +14,14 @@
  * limitations under the License.
  */
 
+import fs from 'fs';
+import path from 'path';
 import { fileURLToPath } from 'url';
 import { chromium } from 'playwright';
 import { test as base, expect } from '../../tests/fixtures.js';
 
-import type { BrowserContext } from 'playwright';
 import type { Client } from '@modelcontextprotocol/sdk/client/index.js';
+import type { BrowserContext } from 'playwright';
 import type { StartClient } from '../../tests/fixtures.js';
 
 type BrowserWithExtension = {
@@ -27,14 +29,23 @@ type BrowserWithExtension = {
   launch: (mode?: 'disable-extension') => Promise<BrowserContext>;
 };
 
-const test = base.extend<{ browserWithExtension: BrowserWithExtension }>({
-  browserWithExtension: async ({ mcpBrowser }, use, testInfo) => {
+type TestFixtures = {
+  browserWithExtension: BrowserWithExtension,
+  pathToExtension: string,
+  useShortConnectionTimeout: (timeoutMs: number) => void
+  overrideProtocolVersion: (version: number) => void
+};
+
+const test = base.extend<TestFixtures>({
+  pathToExtension: async ({}, use) => {
+    await use(fileURLToPath(new URL('../dist', import.meta.url)));
+  },
+
+  browserWithExtension: async ({ mcpBrowser, pathToExtension }, use, testInfo) => {
     // The flags no longer work in Chrome since
     // https://chromium.googlesource.com/chromium/src/+/290ed8046692651ce76088914750cb659b65fb17%5E%21/chrome/browser/extensions/extension_service.cc?pli=1#
     test.skip('chromium' !== mcpBrowser, '--load-extension is not supported for official builds of Chromium');
 
-    const pathToExtension = fileURLToPath(new URL('../dist', import.meta.url));
-
     let browserContext: BrowserContext | undefined;
     const userDataDir = testInfo.outputPath('extension-user-data-dir');
     await use({
@@ -60,9 +71,22 @@ const test = base.extend<{ browserWithExtension: BrowserWithExtension }>({
         return browserContext;
       }
     });
-
     await browserContext?.close();
   },
+
+  useShortConnectionTimeout: async ({}, use) => {
+    await use((timeoutMs: number) => {
+      process.env.PWMCP_TEST_CONNECTION_TIMEOUT = timeoutMs.toString();
+    });
+    process.env.PWMCP_TEST_CONNECTION_TIMEOUT = undefined;
+  },
+
+  overrideProtocolVersion: async ({}, use) => {
+    await use((version: number) => {
+      process.env.PWMCP_TEST_PROTOCOL_VERSION = version.toString();
+    });
+    process.env.PWMCP_TEST_PROTOCOL_VERSION = undefined;
+  }
 });
 
 async function startAndCallConnectTool(browserWithExtension: BrowserWithExtension, startClient: StartClient): Promise<Client> {
@@ -99,6 +123,21 @@ async function startWithExtensionFlag(browserWithExtension: BrowserWithExtension
   return client;
 }
 
+const testWithOldExtensionVersion = test.extend({
+  pathToExtension: async ({}, use, testInfo) => {
+    const extensionDir = testInfo.outputPath('extension');
+    const oldPath = fileURLToPath(new URL('../dist', import.meta.url));
+
+    await fs.promises.cp(oldPath, extensionDir, { recursive: true });
+    const manifestPath = path.join(extensionDir, 'manifest.json');
+    const manifest = JSON.parse(await fs.promises.readFile(manifestPath, 'utf8'));
+    manifest.version = '0.0.1';
+    await fs.promises.writeFile(manifestPath, JSON.stringify(manifest, null, 2) + '\n');
+
+    await use(extensionDir);
+  },
+});
+
 for (const [mode, startClientMethod] of [
   ['connect-tool', startAndCallConnectTool],
   ['extension-flag', startWithExtensionFlag],
@@ -119,7 +158,8 @@ for (const [mode, startClientMethod] of [
     });
 
     const selectorPage = await confirmationPagePromise;
-    await selectorPage.locator('.tab-item', { hasText: 'Playwright MCP Extension' }).getByRole('button', { name: 'Connect' }).click();
+    // For browser_navigate command, the UI shows Allow/Reject buttons instead of tab selector
+    await selectorPage.getByRole('button', { name: 'Allow' }).click();
 
     expect(await navigateResponse).toHaveResponse({
       pageState: expect.stringContaining(`- generic [active] [ref=e1]: Hello, world!`),
@@ -160,8 +200,8 @@ for (const [mode, startClientMethod] of [
     expect(browserContext.pages()).toHaveLength(4);
   });
 
-  test(`extension not installed timeout (${mode})`, async ({ browserWithExtension, startClient, server }) => {
-    process.env.PWMCP_TEST_CONNECTION_TIMEOUT = '100';
+  test(`extension not installed timeout (${mode})`, async ({ browserWithExtension, startClient, server, useShortConnectionTimeout }) => {
+    useShortConnectionTimeout(100);
 
     const browserContext = await browserWithExtension.launch();
 
@@ -180,8 +220,88 @@ for (const [mode, startClientMethod] of [
     });
 
     await confirmationPagePromise;
+  });
 
-    process.env.PWMCP_TEST_CONNECTION_TIMEOUT = undefined;
+  testWithOldExtensionVersion(`works with old extension version (${mode})`, async ({ browserWithExtension, startClient, server, useShortConnectionTimeout }) => {
+    useShortConnectionTimeout(500);
+
+    // Prelaunch the browser, so that it is properly closed after the test.
+    const browserContext = await browserWithExtension.launch();
+
+    const client = await startClientMethod(browserWithExtension, startClient);
+
+    const confirmationPagePromise = browserContext.waitForEvent('page', page => {
+      return page.url().startsWith('chrome-extension://jakfalbnbhgkpmoaakfflhflbfpkailf/connect.html');
+    });
+
+    const navigateResponse = client.callTool({
+      name: 'browser_navigate',
+      arguments: { url: server.HELLO_WORLD },
+    });
+
+    const selectorPage = await confirmationPagePromise;
+    // For browser_navigate command, the UI shows Allow/Reject buttons instead of tab selector
+    await selectorPage.getByRole('button', { name: 'Allow' }).click();
+
+    expect(await navigateResponse).toHaveResponse({
+      pageState: expect.stringContaining(`- generic [active] [ref=e1]: Hello, world!`),
+    });
+  });
+
+  test(`extension needs update (${mode})`, async ({ browserWithExtension, startClient, server, useShortConnectionTimeout, overrideProtocolVersion }) => {
+    useShortConnectionTimeout(500);
+    overrideProtocolVersion(1000);
+
+    // Prelaunch the browser, so that it is properly closed after the test.
+    const browserContext = await browserWithExtension.launch();
+
+    const client = await startClientMethod(browserWithExtension, startClient);
+
+    const confirmationPagePromise = browserContext.waitForEvent('page', page => {
+      return page.url().startsWith('chrome-extension://jakfalbnbhgkpmoaakfflhflbfpkailf/connect.html');
+    });
+
+    const navigateResponse = client.callTool({
+      name: 'browser_navigate',
+      arguments: { url: server.HELLO_WORLD },
+    });
+
+    const confirmationPage = await confirmationPagePromise;
+    await expect(confirmationPage.locator('.status-banner')).toContainText(`Playwright MCP version trying to connect requires newer extension version`);
+
+    expect(await navigateResponse).toHaveResponse({
+      result: expect.stringContaining('Extension connection timeout.'),
+      isError: true,
+    });
   });
 
 }
+
+test(`custom executablePath`, async ({ startClient, server, useShortConnectionTimeout }) => {
+  useShortConnectionTimeout(1000);
+
+  const executablePath = test.info().outputPath('echo.sh');
+  await fs.promises.writeFile(executablePath, '#!/bin/bash\necho "Custom exec args: $@" > "$(dirname "$0")/output.txt"', { mode: 0o755 });
+
+  const { client } = await startClient({
+    args: [`--extension`],
+    config: {
+      browser: {
+        launchOptions: {
+          executablePath,
+        },
+      }
+    },
+  });
+
+  const navigateResponse = await client.callTool({
+    name: 'browser_navigate',
+    arguments: { url: server.HELLO_WORLD },
+    timeout: 1000,
+  });
+  expect(await navigateResponse).toHaveResponse({
+    result: expect.stringContaining('Extension connection timeout.'),
+    isError: true,
+  });
+  expect(await fs.promises.readFile(test.info().outputPath('output.txt'), 'utf8')).toContain('Custom exec args: chrome-extension://jakfalbnbhgkpmoaakfflhflbfpkailf/connect.html?');
+});

package-lock.json

@@ -1,12 +1,12 @@
 {
   "name": "@playwright/mcp",
-  "version": "0.0.34",
+  "version": "0.0.36",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "@playwright/mcp",
-      "version": "0.0.34",
+      "version": "0.0.36",
       "license": "Apache-2.0",
       "dependencies": {
         "@modelcontextprotocol/sdk": "^1.16.0",
@@ -14,8 +14,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"
@@ -27,7 +27,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",
@@ -703,13 +703,13 @@
       }
     },
     "node_modules/@playwright/test": {
-      "version": "1.55.0-alpha-2025-08-12",
-      "resolved": "https://registry.npmjs.org/@playwright/test/-/test-1.55.0-alpha-2025-08-12.tgz",
-      "integrity": "sha512-lyq9MDSd4UcOWx5292AYLBfbYYCstg8iLb+lk6LdM69ps6bwmPloZO3Ol3JO3FQQ63qAuW9VD0w+ZYKL0lRmQA==",
+      "version": "1.56.0-alpha-1756505518000",
+      "resolved": "https://registry.npmjs.org/@playwright/test/-/test-1.56.0-alpha-1756505518000.tgz",
+      "integrity": "sha512-BLTEYook8jXHONKqmOgcG/q6SLZIyyJClgc+YJGg/G3w3dg1pE2dtdO/gECFnM8FX9UY4DOa9c6eJVU1feHk/w==",
       "dev": true,
       "license": "Apache-2.0",
       "dependencies": {
-        "playwright": "1.55.0-alpha-2025-08-12"
+        "playwright": "1.56.0-alpha-1756505518000"
       },
       "bin": {
         "playwright": "cli.js"
@@ -3745,12 +3745,12 @@
       }
     },
     "node_modules/playwright": {
-      "version": "1.55.0-alpha-2025-08-12",
-      "resolved": "https://registry.npmjs.org/playwright/-/playwright-1.55.0-alpha-2025-08-12.tgz",
-      "integrity": "sha512-daZPM5gX0VTG6ae3/qOpEKc9NxoavkM2lfL0UIzTG0k+yK8ZeSPYo63iewZhVANsWRm0BT+XQ1NniAUOwWQ+xA==",
+      "version": "1.56.0-alpha-1756505518000",
+      "resolved": "https://registry.npmjs.org/playwright/-/playwright-1.56.0-alpha-1756505518000.tgz",
+      "integrity": "sha512-aChIG1Hly/pxzVdwOMArmOMNz4Wo2VyWBxLaMvLJaGWRPPB9+Sl1N8PRm6oH1CbbpFGpPvIeXl83LomkibShRA==",
       "license": "Apache-2.0",
       "dependencies": {
-        "playwright-core": "1.55.0-alpha-2025-08-12"
+        "playwright-core": "1.56.0-alpha-1756505518000"
       },
       "bin": {
         "playwright": "cli.js"
@@ -3763,9 +3763,9 @@
       }
     },
     "node_modules/playwright-core": {
-      "version": "1.55.0-alpha-2025-08-12",
-      "resolved": "https://registry.npmjs.org/playwright-core/-/playwright-core-1.55.0-alpha-2025-08-12.tgz",
-      "integrity": "sha512-4uxOd9xmeF6gqdsORzzlXd7p795vcACOiAGVHHEiTuFXsD83LYH+0C/SYLWB0Z+fAq4LdKGsy0qEfTm0JkY8Ig==",
+      "version": "1.56.0-alpha-1756505518000",
+      "resolved": "https://registry.npmjs.org/playwright-core/-/playwright-core-1.56.0-alpha-1756505518000.tgz",
+      "integrity": "sha512-qeM+G9jA+PkA3dSYZmqKrARnIgd53B+7Lm3e52wH3rPyZJ+IBhRvhW369iN8tVJunbmsr7fkU1+05K2c7q9y0g==",
       "license": "Apache-2.0",
       "bin": {
         "playwright-core": "cli.js"

package.json

@@ -1,6 +1,6 @@
 {
   "name": "@playwright/mcp",
-  "version": "0.0.34",
+  "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",

src/browserContextFactory.ts

@@ -42,27 +42,23 @@ export function contextFactory(config: FullConfig): BrowserContextFactory {
 export type ClientInfo = { name?: string, version?: string, rootPath?: string };
 
 export interface BrowserContextFactory {
-  readonly name: string;
-  readonly description: string;
-  createContext(clientInfo: ClientInfo, abortSignal: AbortSignal): Promise<{ browserContext: playwright.BrowserContext, close: () => Promise<void> }>;
+  createContext(clientInfo: ClientInfo, abortSignal: AbortSignal, toolName: string | undefined): Promise<{ browserContext: playwright.BrowserContext, close: () => Promise<void> }>;
 }
 
 class BaseContextFactory implements BrowserContextFactory {
-  readonly name: string;
-  readonly description: string;
   readonly config: FullConfig;
+  private _logName: string;
   protected _browserPromise: Promise<playwright.Browser> | undefined;
 
-  constructor(name: string, description: string, config: FullConfig) {
-    this.name = name;
-    this.description = description;
+  constructor(name: string, config: FullConfig) {
+    this._logName = name;
     this.config = config;
   }
 
   protected async _obtainBrowser(clientInfo: ClientInfo): Promise<playwright.Browser> {
     if (this._browserPromise)
       return this._browserPromise;
-    testDebug(`obtain browser (${this.name})`);
+    testDebug(`obtain browser (${this._logName})`);
     this._browserPromise = this._doObtainBrowser(clientInfo);
     void this._browserPromise.then(browser => {
       browser.on('disconnected', () => {
@@ -79,7 +75,7 @@ class BaseContextFactory implements BrowserContextFactory {
   }
 
   async createContext(clientInfo: ClientInfo): Promise<{ browserContext: playwright.BrowserContext, close: () => Promise<void> }> {
-    testDebug(`create browser context (${this.name})`);
+    testDebug(`create browser context (${this._logName})`);
     const browser = await this._obtainBrowser(clientInfo);
     const browserContext = await this._doCreateContext(browser);
     return { browserContext, close: () => this._closeBrowserContext(browserContext, browser) };
@@ -90,12 +86,12 @@ class BaseContextFactory implements BrowserContextFactory {
   }
 
   private async _closeBrowserContext(browserContext: playwright.BrowserContext, browser: playwright.Browser) {
-    testDebug(`close browser context (${this.name})`);
+    testDebug(`close browser context (${this._logName})`);
     if (browser.contexts().length === 1)
       this._browserPromise = undefined;
     await browserContext.close().catch(logUnhandledError);
     if (browser.contexts().length === 0) {
-      testDebug(`close browser (${this.name})`);
+      testDebug(`close browser (${this._logName})`);
       await browser.close().catch(logUnhandledError);
     }
   }
@@ -103,7 +99,7 @@ class BaseContextFactory implements BrowserContextFactory {
 
 class IsolatedContextFactory extends BaseContextFactory {
   constructor(config: FullConfig) {
-    super('isolated', 'Create a new isolated browser context', config);
+    super('isolated', config);
   }
 
   protected override async _doObtainBrowser(clientInfo: ClientInfo): Promise<playwright.Browser> {
@@ -128,7 +124,7 @@ class IsolatedContextFactory extends BaseContextFactory {
 
 class CdpContextFactory extends BaseContextFactory {
   constructor(config: FullConfig) {
-    super('cdp', 'Connect to a browser over CDP', config);
+    super('cdp', config);
   }
 
   protected override async _doObtainBrowser(): Promise<playwright.Browser> {
@@ -142,7 +138,7 @@ class CdpContextFactory extends BaseContextFactory {
 
 class RemoteContextFactory extends BaseContextFactory {
   constructor(config: FullConfig) {
-    super('remote', 'Connect to a browser using a remote endpoint', config);
+    super('remote', config);
   }
 
   protected override async _doObtainBrowser(): Promise<playwright.Browser> {

src/browserServerBackend.ts

@@ -21,7 +21,6 @@ import { logUnhandledError } from './utils/log.js';
 import { Response } from './response.js';
 import { SessionLog } from './sessionLog.js';
 import { filteredTools } from './tools.js';
-import { packageJSON } from './utils/package.js';
 import { toMcpTool } from './mcp/tool.js';
 
 import type { Tool } from './tools/tool.js';
@@ -30,9 +29,6 @@ import type * as mcpServer from './mcp/server.js';
 import type { ServerBackend } from './mcp/server.js';
 
 export class BrowserServerBackend implements ServerBackend {
-  name = 'Playwright';
-  version = packageJSON.version;
-
   private _tools: Tool[];
   private _context: Context | undefined;
   private _sessionLog: SessionLog | undefined;
@@ -45,7 +41,7 @@ export class BrowserServerBackend implements ServerBackend {
     this._tools = filteredTools(config);
   }
 
-  async initialize(clientVersion: mcpServer.ClientVersion, roots: mcpServer.Root[]): Promise<void> {
+  async initialize(server: mcpServer.Server, clientVersion: mcpServer.ClientVersion, roots: mcpServer.Root[]): Promise<void> {
     let rootPath: string | undefined;
     if (roots.length > 0) {
       const firstRootUri = roots[0]?.uri;
@@ -73,7 +69,7 @@ export class BrowserServerBackend implements ServerBackend {
     const parsedArguments = tool.schema.inputSchema.parse(rawArguments || {});
     const context = this._context!;
     const response = new Response(context, name, parsedArguments);
-    context.setRunningTool(true);
+    context.setRunningTool(name);
     try {
       await tool.handle(context, parsedArguments, response);
       await response.finish();
@@ -81,7 +77,7 @@ export class BrowserServerBackend implements ServerBackend {
     } catch (error: any) {
       response.addError(String(error));
     } finally {
-      context.setRunningTool(false);
+      context.setRunningTool(undefined);
     }
     return response.serialize();
   }

src/context.ts

@@ -50,7 +50,7 @@ export class Context {
 
   private static _allContexts: Set<Context> = new Set();
   private _closeBrowserContextPromise: Promise<void> | undefined;
-  private _isRunningTool: boolean = false;
+  private _runningToolName: string | undefined;
   private _abortController = new AbortController();
 
   constructor(options: ContextOptions) {
@@ -145,11 +145,11 @@ export class Context {
   }
 
   isRunningTool() {
-    return this._isRunningTool;
+    return this._runningToolName !== undefined;
   }
 
-  setRunningTool(isRunningTool: boolean) {
-    this._isRunningTool = isRunningTool;
+  setRunningTool(name: string | undefined) {
+    this._runningToolName = name;
   }
 
   private async _closeBrowserContextImpl() {
@@ -202,7 +202,7 @@ export class Context {
     if (this._closeBrowserContextPromise)
       throw new Error('Another browser context is being closed.');
     // TODO: move to the browser context factory to make it based on isolation mode.
-    const result = await this._browserContextFactory.createContext(this._clientInfo, this._abortController.signal);
+    const result = await this._browserContextFactory.createContext(this._clientInfo, this._abortController.signal, this._runningToolName);
     const { browserContext } = result;
     await this._setupRequestInterception(browserContext);
     if (this.sessionLog)

src/extension/cdpRelay.ts

@@ -26,11 +26,14 @@ import { spawn } from 'child_process';
 import http from 'http';
 import debug from 'debug';
 import { WebSocket, WebSocketServer } from 'ws';
-import { httpAddressToString } from '../utils/httpServer.js';
+import { httpAddressToString } from '../mcp/http.js';
 import { logUnhandledError } from '../utils/log.js';
-import { ManualPromise } from '../utils/manualPromise.js';
+import { ManualPromise } from '../mcp/manualPromise.js';
+import * as protocol from './protocol.js';
+
 import type websocket from 'ws';
 import type { ClientInfo } from '../browserContextFactory.js';
+import type { ExtensionCommand, ExtensionEvents } from './protocol.js';
 
 // @ts-ignore
 const { registry } = await import('playwright-core/lib/server/registry/index');
@@ -57,6 +60,7 @@ export class CDPRelayServer {
   private _wsHost: string;
   private _browserChannel: string;
   private _userDataDir?: string;
+  private _executablePath?: string;
   private _cdpPath: string;
   private _extensionPath: string;
   private _wss: WebSocketServer;
@@ -70,10 +74,11 @@ export class CDPRelayServer {
   private _nextSessionId: number = 1;
   private _extensionConnectionPromise!: ManualPromise<void>;
 
-  constructor(server: http.Server, browserChannel: string, userDataDir?: string) {
+  constructor(server: http.Server, browserChannel: string, userDataDir?: string, executablePath?: string) {
     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}`;
@@ -92,11 +97,11 @@ export class CDPRelayServer {
     return `${this._wsHost}${this._extensionPath}`;
   }
 
-  async ensureExtensionConnectionForMCPContext(clientInfo: ClientInfo, abortSignal: AbortSignal) {
+  async ensureExtensionConnectionForMCPContext(clientInfo: ClientInfo, abortSignal: AbortSignal, toolName: string | undefined) {
     debugLogger('Ensuring extension connection for MCP context');
     if (this._extensionConnection)
       return;
-    this._connectBrowser(clientInfo);
+    this._connectBrowser(clientInfo, toolName);
     debugLogger('Waiting for incoming extension connection');
     await Promise.race([
       this._extensionConnectionPromise,
@@ -108,19 +113,30 @@ export class CDPRelayServer {
     debugLogger('Extension connection established');
   }
 
-  private _connectBrowser(clientInfo: ClientInfo) {
+  private _connectBrowser(clientInfo: ClientInfo, toolName: string | undefined) {
     const mcpRelayEndpoint = `${this._wsHost}${this._extensionPath}`;
     // Need to specify "key" in the manifest.json to make the id stable when loading from file.
     const url = new URL('chrome-extension://jakfalbnbhgkpmoaakfflhflbfpkailf/connect.html');
     url.searchParams.set('mcpRelayUrl', mcpRelayEndpoint);
-    url.searchParams.set('client', JSON.stringify(clientInfo));
+    const client = {
+      name: clientInfo.name,
+      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: string[] = [];
     if (this._userDataDir)
@@ -222,7 +238,7 @@ export class CDPRelayServer {
     this._extensionConnectionPromise.resolve();
   }
 
-  private _handleExtensionMessage(method: string, params: any) {
+  private _handleExtensionMessage<M extends keyof ExtensionEvents>(method: M, params: ExtensionEvents[M]['params']) {
     switch (method) {
       case 'forwardCDPEvent':
         const sessionId = params.sessionId || this._connectedTabInfo?.sessionId;
@@ -232,10 +248,6 @@ export class CDPRelayServer {
           params: params.params
         });
         break;
-      case 'detachedFromTab':
-        debugLogger('← Debugger detached from tab:', params);
-        this._connectedTabInfo = undefined;
-        break;
     }
   }
 
@@ -272,7 +284,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++}`,
@@ -326,7 +338,7 @@ class ExtensionConnection {
   private readonly _callbacks = new Map<number, { resolve: (o: any) => void, reject: (e: Error) => void, error: Error }>();
   private _lastId = 0;
 
-  onmessage?: (method: string, params: any) => void;
+  onmessage?: <M extends keyof ExtensionEvents>(method: M, params: ExtensionEvents[M]['params']) => void;
   onclose?: (self: ExtensionConnection, reason: string) => void;
 
   constructor(ws: WebSocket) {
@@ -336,11 +348,11 @@ class ExtensionConnection {
     this._ws.on('error', this._onError.bind(this));
   }
 
-  async send(method: string, params?: any, sessionId?: string): Promise<any> {
+  async send<M extends keyof ExtensionCommand>(method: M, params: ExtensionCommand[M]['params']): Promise<any> {
     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 });
@@ -385,7 +397,7 @@ class ExtensionConnection {
     } else if (object.id) {
       debugLogger('← Extension: unexpected response', object);
     } else {
-      this.onmessage?.(object.method!, object.params);
+      this.onmessage?.(object.method! as keyof ExtensionEvents, object.params);
     }
   }
 

src/extension/extensionContextFactory.ts

@@ -16,7 +16,7 @@
 
 import debug from 'debug';
 import * as playwright from 'playwright';
-import { startHttpServer } from '../utils/httpServer.js';
+import { startHttpServer } from '../mcp/http.js';
 import { CDPRelayServer } from './cdpRelay.js';
 
 import type { BrowserContextFactory, ClientInfo } from '../browserContextFactory.js';
@@ -24,19 +24,18 @@ import type { BrowserContextFactory, ClientInfo } from '../browserContextFactory
 const debugLogger = debug('pw:mcp:relay');
 
 export class ExtensionContextFactory implements BrowserContextFactory {
-  name = 'extension';
-  description = 'Connect to a browser using the Playwright MCP extension';
-
   private _browserChannel: string;
   private _userDataDir?: string;
+  private _executablePath?: string;
 
-  constructor(browserChannel: string, userDataDir: string | undefined) {
+  constructor(browserChannel: string, userDataDir: string | undefined, executablePath: string | undefined) {
     this._browserChannel = browserChannel;
     this._userDataDir = userDataDir;
+    this._executablePath = executablePath;
   }
 
-  async createContext(clientInfo: ClientInfo, abortSignal: AbortSignal): Promise<{ browserContext: playwright.BrowserContext, close: () => Promise<void> }> {
-    const browser = await this._obtainBrowser(clientInfo, abortSignal);
+  async createContext(clientInfo: ClientInfo, abortSignal: AbortSignal, toolName: string | undefined): Promise<{ browserContext: playwright.BrowserContext, close: () => Promise<void> }> {
+    const browser = await this._obtainBrowser(clientInfo, abortSignal, toolName);
     return {
       browserContext: browser.contexts()[0],
       close: async () => {
@@ -46,9 +45,9 @@ export class ExtensionContextFactory implements BrowserContextFactory {
     };
   }
 
-  private async _obtainBrowser(clientInfo: ClientInfo, abortSignal: AbortSignal): Promise<playwright.Browser> {
+  private async _obtainBrowser(clientInfo: ClientInfo, abortSignal: AbortSignal, toolName: string | undefined): Promise<playwright.Browser> {
     const relay = await this._startRelay(abortSignal);
-    await relay.ensureExtensionConnectionForMCPContext(clientInfo, abortSignal);
+    await relay.ensureExtensionConnectionForMCPContext(clientInfo, abortSignal, toolName);
     return await playwright.chromium.connectOverCDP(relay.cdpEndpoint());
   }
 
@@ -58,7 +57,7 @@ export class ExtensionContextFactory implements BrowserContextFactory {
       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;

src/extension/protocol.ts

@@ -0,0 +1,42 @@
+/**
+ * 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;
+
+export type ExtensionCommand = {
+  'attachToTab': {
+    params: {};
+  };
+  'forwardCDPCommand': {
+    params: {
+      method: string,
+      sessionId?: string
+      params?: any,
+    };
+  };
+};
+
+export type ExtensionEvents = {
+  'forwardCDPEvent': {
+    params: {
+      method: string,
+      sessionId?: string
+      params?: any,
+    };
+  };
+};

src/index.ts

@@ -18,6 +18,7 @@ import { BrowserServerBackend } from './browserServerBackend.js';
 import { resolveConfig } from './config.js';
 import { contextFactory } from './browserContextFactory.js';
 import * as mcpServer from './mcp/server.js';
+import { packageJSON } from './utils/package.js';
 
 import type { Config } from '../config.js';
 import type { BrowserContext } from 'playwright';
@@ -27,7 +28,7 @@ import type { Server } from '@modelcontextprotocol/sdk/server/index.js';
 export async function createConnection(userConfig: Config = {}, contextGetter?: () => Promise<BrowserContext>): Promise<Server> {
   const config = await resolveConfig(userConfig);
   const factory = contextGetter ? new SimpleBrowserContextFactory(contextGetter) : contextFactory(config);
-  return mcpServer.createServer(new BrowserServerBackend(config, factory), false);
+  return mcpServer.createServer('Playwright', packageJSON.version, new BrowserServerBackend(config, factory), false);
 }
 
 class SimpleBrowserContextFactory implements BrowserContextFactory {

src/loopTools/context.ts

@@ -23,6 +23,7 @@ import { OpenAIDelegate } from '../loop/loopOpenAI.js';
 import { ClaudeDelegate } from '../loop/loopClaude.js';
 import { InProcessTransport } from '../mcp/inProcessTransport.js';
 import * as mcpServer from '../mcp/server.js';
+import { packageJSON } from '../utils/package.js';
 
 import type { LLMDelegate } from '../loop/loop.js';
 import type { FullConfig } from '../config.js';
@@ -44,9 +45,9 @@ export class Context {
   }
 
   static async create(config: FullConfig) {
-    const client = new Client({ name: 'Playwright Proxy', version: '1.0.0' });
+    const client = new Client({ name: 'Playwright Proxy', version: packageJSON.version });
     const browserContextFactory = contextFactory(config);
-    const server = mcpServer.createServer(new BrowserServerBackend(config, browserContextFactory), false);
+    const server = mcpServer.createServer('Playwright Subagent', packageJSON.version, new BrowserServerBackend(config, browserContextFactory), false);
     await client.connect(new InProcessTransport(server));
     await client.ping();
     return new Context(config, client);

src/loopTools/main.ts

@@ -17,7 +17,6 @@
 import dotenv from 'dotenv';
 
 import * as mcpServer from '../mcp/server.js';
-import * as mcpTransport from '../mcp/transport.js';
 import { packageJSON } from '../utils/package.js';
 import { Context } from './context.js';
 import { perform } from './perform.js';
@@ -30,13 +29,16 @@ import type { Tool } from './tool.js';
 
 export async function runLoopTools(config: FullConfig) {
   dotenv.config();
-  const serverBackendFactory = () => new LoopToolsServerBackend(config);
-  await mcpTransport.start(serverBackendFactory, config.server);
+  const serverBackendFactory = {
+    name: 'Playwright',
+    nameInConfig: 'playwright-loop',
+    version: packageJSON.version,
+    create: () => new LoopToolsServerBackend(config)
+  };
+  await mcpServer.start(serverBackendFactory, config.server);
 }
 
 class LoopToolsServerBackend implements ServerBackend {
-  readonly name = 'Playwright';
-  readonly version = packageJSON.version;
   private _config: FullConfig;
   private _context: Context | undefined;
   private _tools: Tool<any>[] = [perform, snapshot];

src/mcp/DEPS.list

@@ -1,2 +1 @@
 [*]
-../utils/

src/mcp/README.md

@@ -1 +1 @@
-- Generic MCP utils, no dependencies on Playwright here.
+- Generic MCP utils, no dependencies on anything.

src/mcp/http.ts

@@ -14,33 +14,62 @@
  * limitations under the License.
  */
 
+import assert from 'assert';
+import net from 'net';
 import http from 'http';
 import crypto from '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 { httpAddressToString, startHttpServer } from '../utils/httpServer.js';
 import * as mcpServer from './server.js';
 
 import type { ServerBackendFactory } from './server.js';
 
-export async function start(serverBackendFactory: ServerBackendFactory, options: { host?: string; port?: number }) {
-  if (options.port !== undefined) {
-    const httpServer = await startHttpServer(options);
-    startHttpTransport(httpServer, serverBackendFactory);
-  } else {
-    await startStdioTransport(serverBackendFactory);
-  }
-}
-
-async function startStdioTransport(serverBackendFactory: ServerBackendFactory) {
-  await mcpServer.connect(serverBackendFactory, new StdioServerTransport(), false);
-}
-
 const testDebug = debug('pw:mcp:test');
 
+export async function startHttpServer(config: { host?: string, port?: number }, abortSignal?: AbortSignal): Promise<http.Server> {
+  const { host, port } = config;
+  const httpServer = http.createServer();
+  decorateServer(httpServer);
+  await new Promise<void>((resolve, reject) => {
+    httpServer.on('error', reject);
+    abortSignal?.addEventListener('abort', () => {
+      httpServer.close();
+      reject(new Error('Aborted'));
+    });
+    httpServer.listen(port, host, () => {
+      resolve();
+      httpServer.removeListener('error', reject);
+    });
+  });
+  return httpServer;
+}
+
+export function httpAddressToString(address: string | net.AddressInfo | null): string {
+  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}`;
+}
+
+export async function installHttpTransport(httpServer: http.Server, serverBackendFactory: ServerBackendFactory) {
+  const sseSessions = new Map();
+  const streamableSessions = new Map();
+  httpServer.on('request', async (req, res) => {
+    const url = new URL(`http://localhost${req.url}`);
+    if (url.pathname.startsWith('/sse'))
+      await handleSSE(serverBackendFactory, req, res, url, sseSessions);
+    else
+      await handleStreamable(serverBackendFactory, req, res, streamableSessions);
+  });
+}
+
 async function handleSSE(serverBackendFactory: ServerBackendFactory, req: http.IncomingMessage, res: http.ServerResponse, url: URL, sessions: Map<string, SSEServerTransport>) {
   if (req.method === 'POST') {
     const sessionId = url.searchParams.get('sessionId');
@@ -109,29 +138,18 @@ async function handleStreamable(serverBackendFactory: ServerBackendFactory, req:
   res.end('Invalid request');
 }
 
-function startHttpTransport(httpServer: http.Server, serverBackendFactory: ServerBackendFactory) {
-  const sseSessions = new Map();
-  const streamableSessions = new Map();
-  httpServer.on('request', async (req, res) => {
-    const url = new URL(`http://localhost${req.url}`);
-    if (url.pathname.startsWith('/sse'))
-      await handleSSE(serverBackendFactory, req, res, url, sseSessions);
-    else
-      await handleStreamable(serverBackendFactory, req, res, streamableSessions);
+function decorateServer(server: net.Server) {
+  const sockets = new Set<net.Socket>();
+  server.on('connection', socket => {
+    sockets.add(socket);
+    socket.once('close', () => sockets.delete(socket));
   });
-  const url = httpAddressToString(httpServer.address());
-  const message = [
-    `Listening on ${url}`,
-    'Put this in your client config:',
-    JSON.stringify({
-      'mcpServers': {
-        'playwright': {
-          'url': `${url}/mcp`
-        }
-      }
-    }, undefined, 2),
-    'For legacy SSE transport support, you can use the /sse endpoint instead.',
-  ].join('\n');
-    // eslint-disable-next-line no-console
-  console.error(message);
+
+  const close = server.close;
+  server.close = (callback?: (err?: Error) => void) => {
+    for (const socket of sockets)
+      socket.destroy();
+    sockets.clear();
+    return close.call(server, callback);
+  };
 }

src/mcp/mdb.ts

@@ -0,0 +1,239 @@
+/**
+ * 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 debug from 'debug';
+import { z } from 'zod';
+
+import { Client } from '@modelcontextprotocol/sdk/client/index.js';
+import { PingRequestSchema } from '@modelcontextprotocol/sdk/types.js';
+import { StreamableHTTPClientTransport } from '@modelcontextprotocol/sdk/client/streamableHttp.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+
+import { defineToolSchema } from './tool.js';
+import * as mcpServer from './server.js';
+import * as mcpHttp from './http.js';
+import { wrapInProcess } from './server.js';
+import { ManualPromise } from './manualPromise.js';
+
+import type { Transport } from '@modelcontextprotocol/sdk/shared/transport.js';
+
+const mdbDebug = debug('pw:mcp:mdb');
+const errorsDebug = debug('pw:mcp:errors');
+
+export class MDBBackend implements mcpServer.ServerBackend {
+  private _stack: { client: Client, toolNames: string[], resultPromise: ManualPromise<mcpServer.CallToolResult> | undefined }[] = [];
+  private _interruptPromise: ManualPromise<mcpServer.CallToolResult> | undefined;
+  private _topLevelBackend: mcpServer.ServerBackend;
+  private _initialized = false;
+
+  constructor(topLevelBackend: mcpServer.ServerBackend) {
+    this._topLevelBackend = topLevelBackend;
+  }
+
+  async initialize(server: mcpServer.Server): Promise<void> {
+    if (this._initialized)
+      return;
+    this._initialized = true;
+    const transport = await wrapInProcess(this._topLevelBackend);
+    await this._pushClient(transport);
+  }
+
+  async listTools(): Promise<mcpServer.Tool[]> {
+    const response = await this._client().listTools();
+    return response.tools;
+  }
+
+  async callTool(name: string, args: mcpServer.CallToolRequest['params']['arguments']): Promise<mcpServer.CallToolResult> {
+    if (name === pushToolsSchema.name)
+      return await this._pushTools(pushToolsSchema.inputSchema.parse(args || {}));
+
+    const interruptPromise = new ManualPromise<mcpServer.CallToolResult>();
+    this._interruptPromise = interruptPromise;
+    let [entry] = this._stack;
+
+    // Pop the client while the tool is not found.
+    while (entry && !entry.toolNames.includes(name)) {
+      mdbDebug('popping client from stack for ', name);
+      this._stack.shift();
+      await entry.client.close();
+      entry = this._stack[0];
+    }
+    if (!entry)
+      throw new Error(`Tool ${name} not found in the tool stack`);
+
+    const resultPromise = new ManualPromise<mcpServer.CallToolResult>();
+    entry.resultPromise = resultPromise;
+
+    this._client().callTool({
+      name,
+      arguments: args,
+    }).then(result => {
+      resultPromise.resolve(result as mcpServer.CallToolResult);
+    }).catch(e => {
+      mdbDebug('error in client call', e);
+      if (this._stack.length < 2)
+        throw e;
+      this._stack.shift();
+      const prevEntry = this._stack[0];
+      void prevEntry.resultPromise!.then(result => resultPromise.resolve(result));
+    });
+    const result = await Promise.race([interruptPromise, resultPromise]);
+    if (interruptPromise.isDone())
+      mdbDebug('client call intercepted', result);
+    else
+      mdbDebug('client call result', result);
+    return result;
+  }
+
+  private _client(): Client {
+    const [entry] = this._stack;
+    if (!entry)
+      throw new Error('No debugging backend available');
+    return entry.client;
+  }
+
+  private async _pushTools(params: { mcpUrl: string, introMessage?: string }): Promise<mcpServer.CallToolResult> {
+    mdbDebug('pushing tools to the stack', params.mcpUrl);
+    const transport = new StreamableHTTPClientTransport(new URL(params.mcpUrl));
+    await this._pushClient(transport, params.introMessage);
+    return { content: [{ type: 'text', text: 'Tools pushed' }] };
+  }
+
+  private async _pushClient(transport: Transport, introMessage?: string): Promise<mcpServer.CallToolResult> {
+    mdbDebug('pushing client to the stack');
+    const client = new Client({ name: 'Internal client', version: '0.0.0' });
+    client.setRequestHandler(PingRequestSchema, () => ({}));
+    await client.connect(transport);
+    mdbDebug('connected to the new client');
+    const { tools } = await client.listTools();
+    this._stack.unshift({ client, toolNames: tools.map(tool => tool.name), resultPromise: undefined });
+    mdbDebug('new tools added to the stack:', tools.map(tool => tool.name));
+    mdbDebug('interrupting current call:', !!this._interruptPromise);
+    this._interruptPromise?.resolve({
+      content: [{
+        type: 'text',
+        text: introMessage || '',
+      }],
+    });
+    this._interruptPromise = undefined;
+    return { content: [{ type: 'text', text: 'Tools pushed' }] };
+  }
+}
+
+const pushToolsSchema = defineToolSchema({
+  name: 'mdb_push_tools',
+  title: 'Push MCP tools to the tools stack',
+  description: 'Push MCP tools to the tools stack',
+  inputSchema: z.object({
+    mcpUrl: z.string(),
+    introMessage: z.string().optional(),
+  }),
+  type: 'readOnly',
+});
+
+export type ServerBackendOnPause = mcpServer.ServerBackend & {
+  requestSelfDestruct?: () => void;
+};
+
+export async function runMainBackend(backendFactory: mcpServer.ServerBackendFactory, options?: { port?: number }): Promise<string | undefined> {
+  const mdbBackend = new MDBBackend(backendFactory.create());
+  // Start HTTP unconditionally.
+  const factory: mcpServer.ServerBackendFactory = {
+    ...backendFactory,
+    create: () => mdbBackend
+  };
+  const url = await startAsHttp(factory, { port: options?.port || 0 });
+  process.env.PLAYWRIGHT_DEBUGGER_MCP = url;
+
+  if (options?.port !== undefined)
+    return url;
+
+  // Start stdio conditionally.
+  await mcpServer.connect(factory, new StdioServerTransport(), false);
+}
+
+export async function runOnPauseBackendLoop(mdbUrl: string, backend: ServerBackendOnPause, introMessage: string) {
+  const wrappedBackend = new OnceTimeServerBackendWrapper(backend);
+
+  const factory = {
+    name: 'on-pause-backend',
+    nameInConfig: 'on-pause-backend',
+    version: '0.0.0',
+    create: () => wrappedBackend,
+  };
+
+  const httpServer = await mcpHttp.startHttpServer({ port: 0 });
+  await mcpHttp.installHttpTransport(httpServer, factory);
+  const url = mcpHttp.httpAddressToString(httpServer.address());
+
+  const client = new Client({ name: 'Internal client', version: '0.0.0' });
+  client.setRequestHandler(PingRequestSchema, () => ({}));
+  const transport = new StreamableHTTPClientTransport(new URL(mdbUrl));
+  await client.connect(transport);
+
+  const pushToolsResult = await client.callTool({
+    name: pushToolsSchema.name,
+    arguments: {
+      mcpUrl: url,
+      introMessage,
+    },
+  });
+  if (pushToolsResult.isError)
+    errorsDebug('Failed to push tools', pushToolsResult.content);
+  await transport.terminateSession();
+  await client.close();
+
+  await wrappedBackend.waitForClosed();
+  httpServer.close();
+}
+
+async function startAsHttp(backendFactory: mcpServer.ServerBackendFactory, options: { port: number }) {
+  const httpServer = await mcpHttp.startHttpServer(options);
+  await mcpHttp.installHttpTransport(httpServer, backendFactory);
+  return mcpHttp.httpAddressToString(httpServer.address());
+}
+
+
+class OnceTimeServerBackendWrapper implements mcpServer.ServerBackend {
+  private _backend: ServerBackendOnPause;
+  private _selfDestructPromise = new ManualPromise<void>();
+
+  constructor(backend: ServerBackendOnPause) {
+    this._backend = backend;
+    this._backend.requestSelfDestruct = () => this._selfDestructPromise.resolve();
+  }
+
+  async initialize(server: mcpServer.Server, clientVersion: mcpServer.ClientVersion, roots: mcpServer.Root[]): Promise<void> {
+    await this._backend.initialize?.(server, clientVersion, roots);
+  }
+
+  async listTools(): Promise<mcpServer.Tool[]> {
+    return this._backend.listTools();
+  }
+
+  async callTool(name: string, args: mcpServer.CallToolRequest['params']['arguments']): Promise<mcpServer.CallToolResult> {
+    return this._backend.callTool(name, args);
+  }
+
+  serverClosed(server: mcpServer.Server) {
+    this._backend.serverClosed?.(server);
+    this._selfDestructPromise.resolve();
+  }
+
+  async waitForClosed() {
+    await this._selfDestructPromise;
+  }
+}

src/mcp/proxyBackend.ts

@@ -14,16 +14,14 @@
  * limitations under the License.
  */
 
+import debug from 'debug';
 import { z } from 'zod';
 import { zodToJsonSchema } from 'zod-to-json-schema';
 
 import { Client } from '@modelcontextprotocol/sdk/client/index.js';
 import { ListRootsRequestSchema, PingRequestSchema } from '@modelcontextprotocol/sdk/types.js';
-import { logUnhandledError } from '../utils/log.js';
-import { packageJSON } from '../utils/package.js';
 
-
-import type { ServerBackend, ClientVersion, Root } from './server.js';
+import type { ServerBackend, ClientVersion, Root, Server } from './server.js';
 import type { Transport } from '@modelcontextprotocol/sdk/shared/transport.js';
 import type { Tool, CallToolResult, CallToolRequest } from '@modelcontextprotocol/sdk/types.js';
 
@@ -33,10 +31,9 @@ export type MCPProvider = {
   connect(): Promise<Transport>;
 };
 
-export class ProxyBackend implements ServerBackend {
-  name = 'Playwright MCP Client Switcher';
-  version = packageJSON.version;
+const errorsDebug = debug('pw:mcp:errors');
 
+export class ProxyBackend implements ServerBackend {
   private _mcpProviders: MCPProvider[];
   private _currentClient: Client | undefined;
   private _contextSwitchTool: Tool;
@@ -47,7 +44,7 @@ export class ProxyBackend implements ServerBackend {
     this._contextSwitchTool = this._defineContextSwitchTool();
   }
 
-  async initialize(clientVersion: ClientVersion, roots: Root[]): Promise<void> {
+  async initialize(server: Server, clientVersion: ClientVersion, roots: Root[]): Promise<void> {
     this._roots = roots;
     await this._setCurrentClient(this._mcpProviders[0]);
   }
@@ -72,7 +69,7 @@ export class ProxyBackend implements ServerBackend {
   }
 
   serverClosed?(): void {
-    void this._currentClient?.close().catch(logUnhandledError);
+    void this._currentClient?.close().catch(errorsDebug);
   }
 
   private async _callContextSwitchTool(params: any): Promise<CallToolResult> {
@@ -115,7 +112,7 @@ export class ProxyBackend implements ServerBackend {
     await this._currentClient?.close();
     this._currentClient = undefined;
 
-    const client = new Client({ name: 'Playwright MCP Proxy', version: packageJSON.version });
+    const client = new Client({ name: 'Playwright MCP Proxy', version: '0.0.0' });
     client.registerCapabilities({
       roots: {
         listRoots: true,

src/mcp/server.ts

@@ -15,10 +15,12 @@
  */
 
 import debug from 'debug';
+
 import { Server } from '@modelcontextprotocol/sdk/server/index.js';
 import { CallToolRequestSchema, ListToolsRequestSchema } from '@modelcontextprotocol/sdk/types.js';
-import { ManualPromise } from '../utils/manualPromise.js';
-import { logUnhandledError } from '../utils/log.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { httpAddressToString, installHttpTransport, startHttpServer } from './http.js';
+import { InProcessTransport } from './inProcessTransport.js';
 
 import type { Tool, CallToolResult, CallToolRequest, Root } from '@modelcontextprotocol/sdk/types.js';
 import type { Transport } from '@modelcontextprotocol/sdk/shared/transport.js';
@@ -26,28 +28,38 @@ export type { Server } from '@modelcontextprotocol/sdk/server/index.js';
 export type { Tool, CallToolResult, CallToolRequest, Root } from '@modelcontextprotocol/sdk/types.js';
 
 const serverDebug = debug('pw:mcp:server');
+const errorsDebug = debug('pw:mcp:errors');
 
 export type ClientVersion = { name: string, version: string };
+
 export interface ServerBackend {
-  name: string;
-  version: string;
-  initialize?(clientVersion: ClientVersion, roots: Root[]): Promise<void>;
+  initialize?(server: Server, clientVersion: ClientVersion, roots: Root[]): Promise<void>;
   listTools(): Promise<Tool[]>;
   callTool(name: string, args: CallToolRequest['params']['arguments']): Promise<CallToolResult>;
-  serverClosed?(): void;
+  serverClosed?(server: Server): void;
 }
 
-export type ServerBackendFactory = () => ServerBackend;
+export type ServerBackendFactory = {
+  name: string;
+  nameInConfig: string;
+  version: string;
+  create: () => ServerBackend;
+};
 
-export async function connect(serverBackendFactory: ServerBackendFactory, transport: Transport, runHeartbeat: boolean) {
-  const backend = serverBackendFactory();
-  const server = createServer(backend, runHeartbeat);
+export async function connect(factory: ServerBackendFactory, transport: Transport, runHeartbeat: boolean) {
+  const server = createServer(factory.name, factory.version, factory.create(), runHeartbeat);
   await server.connect(transport);
 }
 
-export function createServer(backend: ServerBackend, runHeartbeat: boolean): Server {
-  const initializedPromise = new ManualPromise<void>();
-  const server = new Server({ name: backend.name, version: backend.version }, {
+export async function wrapInProcess(backend: ServerBackend): Promise<Transport> {
+  const server = createServer('Internal', '0.0.0', backend, false);
+  return new InProcessTransport(server);
+}
+
+export function createServer(name: string, version: string, backend: ServerBackend, runHeartbeat: boolean): Server {
+  let initializedPromiseResolve = () => {};
+  const initializedPromise = new Promise<void>(resolve => initializedPromiseResolve = resolve);
+  const server = new Server({ name, version }, {
     capabilities: {
       tools: {},
     }
@@ -88,13 +100,13 @@ export function createServer(backend: ServerBackend, runHeartbeat: boolean): Ser
         clientRoots = roots;
       }
       const clientVersion = server.getClientVersion() ?? { name: 'unknown', version: 'unknown' };
-      await backend.initialize?.(clientVersion, clientRoots);
-      initializedPromise.resolve();
+      await backend.initialize?.(server, clientVersion, clientRoots);
+      initializedPromiseResolve();
     } catch (e) {
-      logUnhandledError(e);
+      errorsDebug(e);
     }
   });
-  addServerListener(server, 'close', () => backend.serverClosed?.());
+  addServerListener(server, 'close', () => backend.serverClosed?.(server));
   return server;
 }
 
@@ -120,3 +132,27 @@ function addServerListener(server: Server, event: 'close' | 'initialized', liste
     listener();
   };
 }
+
+export async function start(serverBackendFactory: ServerBackendFactory, options: { host?: string; port?: number }) {
+  if (options.port === undefined) {
+    await connect(serverBackendFactory, new StdioServerTransport(), false);
+    return;
+  }
+
+  const httpServer = await startHttpServer(options);
+  await installHttpTransport(httpServer, serverBackendFactory);
+  const url = httpAddressToString(httpServer.address());
+
+  const mcpConfig: any = { mcpServers: { } };
+  mcpConfig.mcpServers[serverBackendFactory.nameInConfig] = {
+    url: `${url}/mcp`
+  };
+  const message = [
+    `Listening on ${url}`,
+    'Put this in your client config:',
+    JSON.stringify(mcpConfig, undefined, 2),
+    'For legacy SSE transport support, you can use the /sse endpoint instead.',
+  ].join('\n');
+    // eslint-disable-next-line no-console
+  console.error(message);
+}

src/mcp/tool.ts

@@ -40,3 +40,7 @@ export function toMcpTool(tool: ToolSchema<any>): mcpServer.Tool {
     },
   };
 }
+
+export function defineToolSchema<Input extends z.Schema>(tool: ToolSchema<Input>): ToolSchema<Input> {
+  return tool;
+}

src/program.ts

@@ -16,7 +16,6 @@
 
 import { program, Option } from 'commander';
 import * as mcpServer from './mcp/server.js';
-import * as mcpTransport from './mcp/transport.js';
 import { commaSeparatedList, resolveCLIConfig, semicolonSeparatedList } from './config.js';
 import { packageJSON } from './utils/package.js';
 import { Context } from './context.js';
@@ -25,11 +24,9 @@ import { runLoopTools } from './loopTools/main.js';
 import { ProxyBackend } from './mcp/proxyBackend.js';
 import { BrowserServerBackend } from './browserServerBackend.js';
 import { ExtensionContextFactory } from './extension/extensionContextFactory.js';
-import { InProcessTransport } from './mcp/inProcessTransport.js';
 
+import { runVSCodeTools } from './vscode/host.js';
 import type { MCPProvider } from './mcp/proxyBackend.js';
-import type { FullConfig } from './config.js';
-import type { BrowserContextFactory } from './browserContextFactory.js';
 
 program
     .version('Version ' + packageJSON.version)
@@ -61,6 +58,7 @@ program
     .option('--user-data-dir <path>', 'path to the user data directory. If not specified, a temporary directory will be created.')
     .option('--viewport-size <size>', 'specify browser viewport size in pixels, for example "1280, 720"')
     .addOption(new Option('--connect-tool', 'Allow to switch between different browser connection methods.').hideHelp())
+    .addOption(new Option('--vscode', 'VS Code tools.').hideHelp())
     .addOption(new Option('--loop-tools', 'Run loop tools').hideHelp())
     .addOption(new Option('--vision', 'Legacy option, use --caps=vision instead').hideHelp())
     .action(async options => {
@@ -71,12 +69,24 @@ program
         console.error('The --vision option is deprecated, use --caps=vision instead');
         options.caps = 'vision';
       }
+
       const config = await resolveCLIConfig(options);
+      const browserContextFactory = contextFactory(config);
+      const extensionContextFactory = new ExtensionContextFactory(config.browser.launchOptions.channel || 'chrome', config.browser.userDataDir, config.browser.launchOptions.executablePath);
 
       if (options.extension) {
-        const contextFactory = createExtensionContextFactory(config);
-        const serverBackendFactory = () => new BrowserServerBackend(config, contextFactory);
-        await mcpTransport.start(serverBackendFactory, config.server);
+        const serverBackendFactory: mcpServer.ServerBackendFactory = {
+          name: 'Playwright w/ extension',
+          nameInConfig: 'playwright-extension',
+          version: packageJSON.version,
+          create: () => new BrowserServerBackend(config, extensionContextFactory)
+        };
+        await mcpServer.start(serverBackendFactory, config.server);
+        return;
+      }
+
+      if (options.vscode) {
+        await runVSCodeTools(config);
         return;
       }
 
@@ -85,11 +95,36 @@ program
         return;
       }
 
-      const browserContextFactory = contextFactory(config);
-      const providers: MCPProvider[] = [mcpProviderForBrowserContextFactory(config, browserContextFactory)];
-      if (options.connectTool)
-        providers.push(mcpProviderForBrowserContextFactory(config, createExtensionContextFactory(config)));
-      await mcpTransport.start(() => new ProxyBackend(providers), config.server);
+      if (options.connectTool) {
+        const providers: MCPProvider[] = [
+          {
+            name: 'default',
+            description: 'Starts standalone browser',
+            connect: () => mcpServer.wrapInProcess(new BrowserServerBackend(config, browserContextFactory)),
+          },
+          {
+            name: 'extension',
+            description: 'Connect to a browser using the Playwright MCP extension',
+            connect: () => mcpServer.wrapInProcess(new BrowserServerBackend(config, extensionContextFactory)),
+          },
+        ];
+        const factory: mcpServer.ServerBackendFactory = {
+          name: 'Playwright w/ switch',
+          nameInConfig: 'playwright-switch',
+          version: packageJSON.version,
+          create: () => new ProxyBackend(providers),
+        };
+        await mcpServer.start(factory, config.server);
+        return;
+      }
+
+      const factory: mcpServer.ServerBackendFactory = {
+        name: 'Playwright',
+        nameInConfig: 'playwright',
+        version: packageJSON.version,
+        create: () => new BrowserServerBackend(config, browserContextFactory)
+      };
+      await mcpServer.start(factory, config.server);
     });
 
 function setupExitWatchdog() {
@@ -108,19 +143,4 @@ function setupExitWatchdog() {
   process.on('SIGTERM', handleExit);
 }
 
-function createExtensionContextFactory(config: FullConfig) {
-  return new ExtensionContextFactory(config.browser.launchOptions.channel || 'chrome', config.browser.userDataDir);
-}
-
-function mcpProviderForBrowserContextFactory(config: FullConfig, browserContextFactory: BrowserContextFactory) {
-  return {
-    name: browserContextFactory.name,
-    description: browserContextFactory.description,
-    connect: async () => {
-      const server = mcpServer.createServer(new BrowserServerBackend(config, browserContextFactory), false);
-      return new InProcessTransport(server);
-    },
-  };
-}
-
 void program.parseAsync(process.argv);

src/tab.ts

@@ -18,7 +18,7 @@ import { EventEmitter } from 'events';
 import * as playwright from 'playwright';
 import { callOnPageNoTrace, waitForCompletion } from './tools/utils.js';
 import { logUnhandledError } from './utils/log.js';
-import { ManualPromise } from './utils/manualPromise.js';
+import { ManualPromise } from './mcp/manualPromise.js';
 import { ModalState } from './tools/tool.js';
 
 import type { Context } from './context.js';

src/tools.ts

@@ -19,8 +19,10 @@ import console from './tools/console.js';
 import dialogs from './tools/dialogs.js';
 import evaluate from './tools/evaluate.js';
 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 +30,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';
 
 import type { Tool } from './tools/tool.js';
 import type { FullConfig } from './config.js';
@@ -39,6 +41,7 @@ export const allTools: Tool<any>[] = [
   ...dialogs,
   ...evaluate,
   ...files,
+  ...form,
   ...install,
   ...keyboard,
   ...navigate,
@@ -49,6 +52,7 @@ export const allTools: Tool<any>[] = [
   ...snapshot,
   ...tabs,
   ...wait,
+  ...verify,
 ];
 
 export function filteredTools(config: FullConfig) {

src/tools/form.ts

@@ -0,0 +1,61 @@
+/**
+ * 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 { generateLocator } from './utils.js';
+import * as javascript from '../utils/codegen.js';
+
+const fillForm = defineTabTool({
+  capability: 'core',
+
+  schema: {
+    name: 'browser_fill_form',
+    title: 'Fill form',
+    description: 'Fill multiple form fields',
+    inputSchema: z.object({
+      fields: z.array(z.object({
+        name: z.string().describe('Human-readable field name'),
+        type: z.enum(['textbox', 'checkbox', 'radio', 'combobox', 'slider']).describe('Type of the field'),
+        ref: z.string().describe('Exact target field reference from the page snapshot'),
+        value: z.string().describe('Value to fill in the field. If the field is a checkbox, the value should be `true` or `false`. If the field is a combobox, the value should be the text of the option.'),
+      })).describe('Fields to fill in'),
+    }),
+    type: 'destructive',
+  },
+
+  handle: async (tab, params, response) => {
+    for (const field of params.fields) {
+      const locator = await tab.refLocator({ element: field.name, ref: field.ref });
+      const locatorSource = `await page.${await generateLocator(locator)}`;
+      if (field.type === 'textbox' || field.type === 'slider') {
+        await locator.fill(field.value);
+        response.addCode(`${locatorSource}.fill(${javascript.quote(field.value)});`);
+      } else if (field.type === 'checkbox' || field.type === 'radio') {
+        await locator.setChecked(field.value === 'true');
+        response.addCode(`${locatorSource}.setChecked(${javascript.quote(field.value)});`);
+      } else if (field.type === 'combobox') {
+        await locator.selectOption({ label: field.value });
+        response.addCode(`${locatorSource}.selectOption(${javascript.quote(field.value)});`);
+      }
+    }
+  },
+});
+
+export default [
+  fillForm,
+];

src/tools/navigate.ts

@@ -56,24 +56,7 @@ const goBack = defineTabTool({
   },
 });
 
-const goForward = defineTabTool({
-  capability: 'core',
-  schema: {
-    name: 'browser_navigate_forward',
-    title: 'Go forward',
-    description: 'Go forward to the next page',
-    inputSchema: z.object({}),
-    type: 'readOnly',
-  },
-  handle: async (tab, params, response) => {
-    await tab.page.goForward();
-    response.setIncludeSnapshot();
-    response.addCode(`await page.goForward();`);
-  },
-});
-
 export default [
   navigate,
   goBack,
-  goForward,
 ];

src/tools/tabs.ts

@@ -17,85 +17,48 @@
 import { z } from 'zod';
 import { defineTool } from './tool.js';
 
-const listTabs = defineTool({
+const browserTabs = defineTool({
   capability: 'core-tabs',
 
   schema: {
-    name: 'browser_tab_list',
-    title: 'List tabs',
-    description: 'List browser tabs',
-    inputSchema: z.object({}),
-    type: 'readOnly',
-  },
-
-  handle: async (context, params, response) => {
-    await context.ensureTab();
-    response.setIncludeTabs();
-  },
-});
-
-const selectTab = defineTool({
-  capability: 'core-tabs',
-
-  schema: {
-    name: 'browser_tab_select',
-    title: 'Select a tab',
-    description: 'Select a tab by index',
+    name: 'browser_tabs',
+    title: 'Manage tabs',
+    description: 'List, create, close, or select a browser tab.',
     inputSchema: z.object({
-      index: z.number().describe('The index of the tab to select'),
-    }),
-    type: 'readOnly',
-  },
-
-  handle: async (context, params, response) => {
-    await context.selectTab(params.index);
-    response.setIncludeSnapshot();
-  },
-});
-
-const newTab = defineTool({
-  capability: 'core-tabs',
-
-  schema: {
-    name: 'browser_tab_new',
-    title: 'Open a new tab',
-    description: 'Open a new tab',
-    inputSchema: z.object({
-      url: z.string().optional().describe('The URL to navigate to in the new tab. If not provided, the new tab will be blank.'),
-    }),
-    type: 'readOnly',
-  },
-
-  handle: async (context, params, response) => {
-    const tab = await context.newTab();
-    if (params.url)
-      await tab.navigate(params.url);
-    response.setIncludeSnapshot();
-  },
-});
-
-const closeTab = defineTool({
-  capability: 'core-tabs',
-
-  schema: {
-    name: 'browser_tab_close',
-    title: 'Close a tab',
-    description: 'Close a tab',
-    inputSchema: z.object({
-      index: z.number().optional().describe('The index of the tab to close. Closes current tab if not provided.'),
+      action: z.enum(['list', 'new', 'close', 'select']).describe('Operation to perform'),
+      index: z.number().optional().describe('Tab index, used for close/select. If omitted for close, current tab is closed.'),
     }),
     type: 'destructive',
   },
 
   handle: async (context, params, response) => {
-    await context.closeTab(params.index);
-    response.setIncludeSnapshot();
+    switch (params.action) {
+      case 'list': {
+        await context.ensureTab();
+        response.setIncludeTabs();
+        return;
+      }
+      case 'new': {
+        await context.newTab();
+        response.setIncludeTabs();
+        return;
+      }
+      case 'close': {
+        await context.closeTab(params.index);
+        response.setIncludeSnapshot();
+        return;
+      }
+      case 'select': {
+        if (params.index === undefined)
+          throw new Error('Tab index is required');
+        await context.selectTab(params.index);
+        response.setIncludeSnapshot();
+        return;
+      }
+    }
   },
 });
 
 export default [
-  listTabs,
-  newTab,
-  selectTab,
-  closeTab,
+  browserTabs,
 ];

src/tools/verify.ts

@@ -0,0 +1,149 @@
+/**
+ * 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 as any, { 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: string[] = [];
+    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,
+];

src/utils/httpServer.ts

@@ -1,44 +0,0 @@
-/**
- * Copyright (c) Microsoft Corporation.
- *
- * Licensed under the Apache License, Version 2.0 (the "License");
- * you may not use this file except in compliance with the License.
- * You may obtain a copy of the License at
- *
- *     http://www.apache.org/licenses/LICENSE-2.0
- *
- * Unless required by applicable law or agreed to in writing, software
- * distributed under the License is distributed on an "AS IS" BASIS,
- * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
- * See the License for the specific language governing permissions and
- * limitations under the License.
- */
-
-import assert from 'assert';
-import http from 'http';
-
-import type * as net from 'net';
-
-export async function startHttpServer(config: { host?: string, port?: number }): Promise<http.Server> {
-  const { host, port } = config;
-  const httpServer = http.createServer();
-  await new Promise<void>((resolve, reject) => {
-    httpServer.on('error', reject);
-    httpServer.listen(port, host, () => {
-      resolve();
-      httpServer.removeListener('error', reject);
-    });
-  });
-  return httpServer;
-}
-
-export function httpAddressToString(address: string | net.AddressInfo | null): string {
-  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}`;
-}

src/vscode/DEPS.list

@@ -0,0 +1,6 @@
+[*]
+../mcp/
+../utils/
+../config.js
+../browserServerBackend.js
+../browserContextFactory.js

src/vscode/host.ts

@@ -0,0 +1,149 @@
+/**
+ * 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 { fileURLToPath } from 'url';
+import path from 'path';
+import { z } from 'zod';
+import { zodToJsonSchema } from 'zod-to-json-schema';
+
+
+import { Client } from '@modelcontextprotocol/sdk/client/index.js';
+import { ListRootsRequestSchema, PingRequestSchema } from '@modelcontextprotocol/sdk/types.js';
+import { StdioClientTransport } from '@modelcontextprotocol/sdk/client/stdio.js';
+import * as mcpServer from '../mcp/server.js';
+import { logUnhandledError } from '../utils/log.js';
+import { packageJSON } from '../utils/package.js';
+
+import { FullConfig } from '../config.js';
+import { BrowserServerBackend } from '../browserServerBackend.js';
+import { contextFactory } from '../browserContextFactory.js';
+import type { Transport } from '@modelcontextprotocol/sdk/shared/transport.js';
+import type { ClientVersion, ServerBackend } from '../mcp/server.js';
+import type { Root, Tool, CallToolResult, CallToolRequest } from '@modelcontextprotocol/sdk/types.js';
+
+const contextSwitchOptions = z.object({
+  connectionString: z.string().optional().describe('The connection string to use to connect to the browser'),
+  lib: z.string().optional().describe('The library to use for the connection'),
+});
+
+class VSCodeProxyBackend implements ServerBackend {
+  name = 'Playwright MCP Client Switcher';
+  version = packageJSON.version;
+
+  private _currentClient: Client | undefined;
+  private _contextSwitchTool: Tool;
+  private _roots: Root[] = [];
+  private _clientVersion?: ClientVersion;
+
+  constructor(private readonly _config: FullConfig, private readonly _defaultTransportFactory: () => Promise<Transport>) {
+    this._contextSwitchTool = this._defineContextSwitchTool();
+  }
+
+  async initialize(server: mcpServer.Server, clientVersion: ClientVersion, roots: Root[]): Promise<void> {
+    this._clientVersion = clientVersion;
+    this._roots = roots;
+    const transport = await this._defaultTransportFactory();
+    await this._setCurrentClient(transport);
+  }
+
+  async listTools(): Promise<Tool[]> {
+    const response = await this._currentClient!.listTools();
+    return [
+      ...response.tools,
+      this._contextSwitchTool,
+    ];
+  }
+
+  async callTool(name: string, args: CallToolRequest['params']['arguments']): Promise<CallToolResult> {
+    if (name === this._contextSwitchTool.name)
+      return this._callContextSwitchTool(args as any);
+    return await this._currentClient!.callTool({
+      name,
+      arguments: args,
+    }) as CallToolResult;
+  }
+
+  serverClosed?(server: mcpServer.Server): void {
+    void this._currentClient?.close().catch(logUnhandledError);
+  }
+
+  private async _callContextSwitchTool(params: z.infer<typeof contextSwitchOptions>): Promise<CallToolResult> {
+    if (!params.connectionString || !params.lib) {
+      const transport = await this._defaultTransportFactory();
+      await this._setCurrentClient(transport);
+      return {
+        content: [{ type: 'text', text: '### Result\nSuccessfully disconnected.\n' }],
+      };
+    }
+
+    await this._setCurrentClient(
+        new StdioClientTransport({
+          command: process.execPath,
+          cwd: process.cwd(),
+          args: [
+            path.join(fileURLToPath(import.meta.url), '..', 'main.js'),
+            JSON.stringify(this._config),
+            params.connectionString,
+            params.lib,
+          ],
+        })
+    );
+    return {
+      content: [{ type: 'text', text: '### Result\nSuccessfully connected.\n' }],
+    };
+  }
+
+  private _defineContextSwitchTool(): Tool {
+    return {
+      name: 'browser_connect',
+      description: 'Do not call, this tool is used in the integration with the Playwright VS Code Extension and meant for programmatic usage only.',
+      inputSchema: zodToJsonSchema(contextSwitchOptions, { strictUnions: true }) as Tool['inputSchema'],
+      annotations: {
+        title: 'Connect to a browser running in VS Code.',
+        readOnlyHint: true,
+        openWorldHint: false,
+      },
+    };
+  }
+
+  private async _setCurrentClient(transport: Transport) {
+    await this._currentClient?.close();
+    this._currentClient = undefined;
+
+    const client = new Client(this._clientVersion!);
+    client.registerCapabilities({
+      roots: {
+        listRoots: true,
+      },
+    });
+    client.setRequestHandler(ListRootsRequestSchema, () => ({ roots: this._roots }));
+    client.setRequestHandler(PingRequestSchema, () => ({}));
+
+    await client.connect(transport);
+    this._currentClient = client;
+  }
+}
+
+export async function runVSCodeTools(config: FullConfig) {
+  const serverBackendFactory: mcpServer.ServerBackendFactory = {
+    name: 'Playwright w/ vscode',
+    nameInConfig: 'playwright-vscode',
+    version: packageJSON.version,
+    create: () => new VSCodeProxyBackend(config, () => mcpServer.wrapInProcess(new BrowserServerBackend(config, contextFactory(config))))
+  };
+  await mcpServer.start(serverBackendFactory, config.server);
+  return;
+}

src/vscode/main.ts

@@ -0,0 +1,75 @@
+/**
+ * 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 { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import * as mcpServer from '../mcp/server.js';
+import { BrowserServerBackend } from '../browserServerBackend.js';
+import { BrowserContextFactory, ClientInfo } from '../browserContextFactory.js';
+import type { FullConfig } from '../config.js';
+import type { BrowserContext } from 'playwright-core';
+
+class VSCodeBrowserContextFactory implements BrowserContextFactory {
+  name = 'vscode';
+  description = 'Connect to a browser running in the Playwright VS Code extension';
+
+  constructor(private _config: FullConfig, private _playwright: typeof import('playwright'), private _connectionString: string) {}
+
+  async createContext(clientInfo: ClientInfo, abortSignal: AbortSignal): Promise<{ browserContext: BrowserContext; close: () => Promise<void>; }> {
+    let launchOptions: any = this._config.browser.launchOptions;
+    if (this._config.browser.userDataDir) {
+      launchOptions = {
+        ...launchOptions,
+        ...this._config.browser.contextOptions,
+        userDataDir: this._config.browser.userDataDir,
+      };
+    }
+    const connectionString = new URL(this._connectionString);
+    connectionString.searchParams.set('launch-options', JSON.stringify(launchOptions));
+
+    const browserType = this._playwright.chromium; // it could also be firefox or webkit, we just need some browser type to call `connect` on
+    const browser = await browserType.connect(connectionString.toString());
+
+    const context = browser.contexts()[0] ?? await browser.newContext(this._config.browser.contextOptions);
+
+    return {
+      browserContext: context,
+      close: async () => {
+        await browser.close();
+      }
+    };
+  }
+}
+
+async function main(config: FullConfig, connectionString: string, lib: string) {
+  const playwright = await import(lib).then(mod => mod.default ?? mod);
+  const factory = new VSCodeBrowserContextFactory(config, playwright, connectionString);
+  await mcpServer.connect(
+      {
+        name: 'Playwright MCP',
+        nameInConfig: 'playwright-vscode',
+        create: () => new BrowserServerBackend(config, factory),
+        version: 'unused'
+      },
+      new StdioServerTransport(),
+      false
+  );
+}
+
+await main(
+    JSON.parse(process.argv[2]),
+    process.argv[3],
+    process.argv[4]
+);

tests/capabilities.spec.ts

@@ -24,6 +24,7 @@ test('test snapshot tool list', async ({ client }) => {
     'browser_drag',
     'browser_evaluate',
     'browser_file_upload',
+    'browser_fill_form',
     'browser_handle_dialog',
     'browser_hover',
     'browser_select_option',
@@ -31,16 +32,12 @@ test('test snapshot tool list', async ({ client }) => {
     'browser_close',
     'browser_install',
     'browser_navigate_back',
-    'browser_navigate_forward',
     'browser_navigate',
     'browser_network_requests',
     'browser_press_key',
     'browser_resize',
     'browser_snapshot',
-    'browser_tab_close',
-    'browser_tab_list',
-    'browser_tab_new',
-    'browser_tab_select',
+    'browser_tabs',
     'browser_take_screenshot',
     'browser_wait_for',
   ]));
@@ -58,6 +55,7 @@ test('test tool list proxy mode', async ({ startClient }) => {
     'browser_drag',
     'browser_evaluate',
     'browser_file_upload',
+    'browser_fill_form',
     'browser_handle_dialog',
     'browser_hover',
     'browser_select_option',
@@ -65,16 +63,12 @@ test('test tool list proxy mode', async ({ startClient }) => {
     'browser_close',
     'browser_install',
     'browser_navigate_back',
-    'browser_navigate_forward',
     'browser_navigate',
     'browser_network_requests',
     'browser_press_key',
     'browser_resize',
     'browser_snapshot',
-    'browser_tab_close',
-    'browser_tab_list',
-    'browser_tab_new',
-    'browser_tab_select',
+    'browser_tabs',
     'browser_take_screenshot',
     'browser_wait_for',
   ]));

tests/evaluate.spec.ts

@@ -57,6 +57,25 @@ test('browser_evaluate (element)', async ({ client, server }) => {
   });
 });
 
+test('browser_evaluate object', async ({ client, server }) => {
+  expect(await client.callTool({
+    name: 'browser_navigate',
+    arguments: { url: server.HELLO_WORLD },
+  })).toHaveResponse({
+    pageState: expect.stringContaining(`- Page Title: Title`),
+  });
+
+  expect(await client.callTool({
+    name: 'browser_evaluate',
+    arguments: {
+      function: '() => ({ title: document.title, url: document.URL })',
+    },
+  })).toHaveResponse({
+    result: JSON.stringify({ title: 'Title', url: server.HELLO_WORLD }, null, 2),
+    code: `await page.evaluate('() => ({ title: document.title, url: document.URL })');`,
+  });
+});
+
 test('browser_evaluate (error)', async ({ client, server }) => {
   expect(await client.callTool({
     name: 'browser_navigate',

tests/fixtures.ts

@@ -31,6 +31,7 @@ import type { Transport } from '@modelcontextprotocol/sdk/shared/transport.js';
 import type { Stream } from 'stream';
 
 export type TestOptions = {
+  mcpArgs: string[] | undefined;
   mcpBrowser: string | undefined;
   mcpMode: 'docker' | undefined;
 };
@@ -65,17 +66,19 @@ type WorkerFixtures = {
 
 export const test = baseTest.extend<TestFixtures & TestOptions, WorkerFixtures>({
 
+  mcpArgs: [undefined, { option: true }],
+
   client: async ({ startClient }, use) => {
     const { client } = await startClient();
     await use(client);
   },
 
-  startClient: async ({ mcpHeadless, mcpBrowser, mcpMode }, use, testInfo) => {
+  startClient: async ({ mcpHeadless, mcpBrowser, mcpMode, mcpArgs }, use, testInfo) => {
     const configDir = path.dirname(test.info().config.configFile!);
     const clients: Client[] = [];
 
     await use(async options => {
-      const args: string[] = [];
+      const args: string[] = mcpArgs ?? [];
       if (process.env.CI && process.platform === 'linux')
         args.push('--no-sandbox');
       if (mcpHeadless)

tests/form.spec.ts

@@ -0,0 +1,123 @@
+/**
+ * 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 { test, expect } from './fixtures.js';
+
+test('browser_fill_form (textbox)', async ({ client, server }) => {
+  server.setContent('/', `
+    <!DOCTYPE html>
+    <html>
+      <body>
+        <form>
+          <label>
+            <input type="text" id="name" name="name" />
+            Name
+          </label>
+          <label>
+            <input type="email" id="email" name="email" />
+            Email
+          </label>
+          <label>
+            <input type="range" id="age" name="age" min="18" max="100" />
+            Age
+          </label>
+          <label>
+            <select id="country" name="country">
+              <option value="">Choose a country</option>
+              <option value="us">United States</option>
+              <option value="uk">United Kingdom</option>
+            </select>
+            Country
+          </label>
+          <label>
+            <input type="checkbox" name="subscribe" value="newsletter" />
+            Subscribe to newsletter
+          </label>
+        </form>
+      </body>
+    </html>
+  `, 'text/html');
+
+  await client.callTool({
+    name: 'browser_navigate',
+    arguments: { url: server.PREFIX },
+  });
+
+  expect(await client.callTool({
+    name: 'browser_fill_form',
+    arguments: {
+      fields: [
+        {
+          name: 'Name textbox',
+          type: 'textbox',
+          ref: 'e4',
+          value: 'John Doe'
+        },
+        {
+          name: 'Email textbox',
+          type: 'textbox',
+          ref: 'e6',
+          value: 'john.doe@example.com'
+        },
+        {
+          name: 'Age textbox',
+          type: 'slider',
+          ref: 'e8',
+          value: '25'
+        },
+        {
+          name: 'Country select',
+          type: 'combobox',
+          ref: 'e10',
+          value: 'United States'
+        },
+        {
+          name: 'Subscribe checkbox',
+          type: 'checkbox',
+          ref: 'e12',
+          value: 'true'
+        },
+      ]
+    },
+  })).toHaveResponse({
+    code: `await page.getByRole('textbox', { name: 'Name' }).fill('John Doe');
+await page.getByRole('textbox', { name: 'Email' }).fill('john.doe@example.com');
+await page.getByRole('slider', { name: 'Age' }).fill('25');
+await page.getByLabel('Choose a country United').selectOption('United States');
+await page.getByRole('checkbox', { name: 'Subscribe to newsletter' }).setChecked('true');`,
+  });
+
+  const response = await client.callTool({
+    name: 'browser_snapshot',
+    arguments: {
+    },
+  });
+  expect.soft(response).toHaveResponse({
+    pageState: expect.stringMatching(/textbox "Name".*John Doe/),
+  });
+  expect.soft(response).toHaveResponse({
+    pageState: expect.stringMatching(/textbox "Email".*john.doe@example.com/),
+  });
+  expect.soft(response).toHaveResponse({
+    pageState: expect.stringMatching(/slider "Age".*"25"/),
+  });
+  expect.soft(response).toHaveResponse({
+    pageState: expect.stringContaining('option \"United States\" [selected]'),
+  });
+  expect.soft(response).toHaveResponse({
+    pageState: expect.stringContaining('checkbox \"Subscribe to newsletter\" [checked]'),
+  });
+});

tests/mdb.spec.ts

@@ -0,0 +1,217 @@
+/**
+ * Copyright (c) Microsoft Corporation.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+import { z } from 'zod';
+import zodToJsonSchema from 'zod-to-json-schema';
+import { Client } from '@modelcontextprotocol/sdk/client/index.js';
+import { StreamableHTTPClientTransport } from '@modelcontextprotocol/sdk/client/streamableHttp.js';
+
+import { runMainBackend, runOnPauseBackendLoop } from '../src/mcp/mdb.js';
+
+import { test, expect } from './fixtures.js';
+
+import type * as mcpServer from '../src/mcp/server.js';
+import type { ServerBackendOnPause } from '../src/mcp/mdb.js';
+
+test('call top level tool', async () => {
+  const { mdbUrl } = await startMDBAndCLI();
+  const mdbClient = await createMDBClient(mdbUrl);
+
+  const { tools } = await mdbClient.client.listTools();
+  expect(tools).toEqual([{
+    name: 'cli_echo',
+    description: 'Echo a message',
+    inputSchema: expect.any(Object),
+  }, {
+    name: 'cli_pause_in_gdb',
+    description: 'Pause in gdb',
+    inputSchema: expect.any(Object),
+  }, {
+    name: 'cli_pause_in_gdb_twice',
+    description: 'Pause in gdb twice',
+    inputSchema: expect.any(Object),
+  }
+  ]);
+
+  const echoResult = await mdbClient.client.callTool({
+    name: 'cli_echo',
+    arguments: {
+      message: 'Hello, world!',
+    },
+  });
+  expect(echoResult.content).toEqual([{ type: 'text', text: 'Echo: Hello, world!' }]);
+
+  await mdbClient.close();
+});
+
+test('pause on error', async () => {
+  const { mdbUrl } = await startMDBAndCLI();
+  const mdbClient = await createMDBClient(mdbUrl);
+
+  // Make a call that results in a recoverable error.
+  const interruptResult = await mdbClient.client.callTool({
+    name: 'cli_pause_in_gdb',
+    arguments: {},
+  });
+  expect(interruptResult.content).toEqual([{ type: 'text', text: 'Paused on exception' }]);
+
+  // List new inner tools.
+  const { tools } = await mdbClient.client.listTools();
+  expect(tools).toEqual([
+    expect.objectContaining({
+      name: 'gdb_bt',
+    }),
+    expect.objectContaining({
+      name: 'gdb_continue',
+    }),
+  ]);
+
+  // Call the new inner tool.
+  const btResult = await mdbClient.client.callTool({
+    name: 'gdb_bt',
+    arguments: {},
+  });
+  expect(btResult.content).toEqual([{ type: 'text', text: 'Backtrace' }]);
+
+  // Continue execution.
+  const continueResult = await mdbClient.client.callTool({
+    name: 'gdb_continue',
+    arguments: {},
+  });
+  expect(continueResult.content).toEqual([{ type: 'text', text: 'Done' }]);
+
+  await mdbClient.close();
+});
+
+test('pause on error twice', async () => {
+  const { mdbUrl } = await startMDBAndCLI();
+  const mdbClient = await createMDBClient(mdbUrl);
+
+  // Make a call that results in a recoverable error.
+  const result = await mdbClient.client.callTool({
+    name: 'cli_pause_in_gdb_twice',
+    arguments: {},
+  });
+  expect(result.content).toEqual([{ type: 'text', text: 'Paused on exception 1' }]);
+
+  // Continue execution.
+  const continueResult1 = await mdbClient.client.callTool({
+    name: 'gdb_continue',
+    arguments: {},
+  });
+  expect(continueResult1.content).toEqual([{ type: 'text', text: 'Paused on exception 2' }]);
+
+  const continueResult2 = await mdbClient.client.callTool({
+    name: 'gdb_continue',
+    arguments: {},
+  });
+  expect(continueResult2.content).toEqual([{ type: 'text', text: 'Done' }]);
+
+  await mdbClient.close();
+});
+
+async function startMDBAndCLI(): Promise<{ mdbUrl: string }> {
+  const mdbUrlBox = { mdbUrl: undefined as string | undefined };
+  const cliBackendFactory = {
+    name: 'CLI',
+    nameInConfig: 'cli',
+    version: '0.0.0',
+    create: () => new CLIBackend(mdbUrlBox)
+  };
+
+  const mdbUrl = (await runMainBackend(cliBackendFactory, { port: 0 }))!;
+  mdbUrlBox.mdbUrl = mdbUrl;
+  return { mdbUrl };
+}
+
+async function createMDBClient(mdbUrl: string): Promise<{ client: Client, close: () => Promise<void> }> {
+  const client = new Client({ name: 'Internal client', version: '0.0.0' });
+  const transport = new StreamableHTTPClientTransport(new URL(mdbUrl));
+  await client.connect(transport);
+  return {
+    client,
+    close: async () => {
+      await transport.terminateSession();
+      await client.close();
+    }
+  };
+}
+
+class CLIBackend implements mcpServer.ServerBackend {
+  constructor(private readonly mdbUrlBox: { mdbUrl: string | undefined }) {}
+
+  async listTools(): Promise<mcpServer.Tool[]> {
+    return [{
+      name: 'cli_echo',
+      description: 'Echo a message',
+      inputSchema: zodToJsonSchema(z.object({ message: z.string() })) as any,
+    }, {
+      name: 'cli_pause_in_gdb',
+      description: 'Pause in gdb',
+      inputSchema: zodToJsonSchema(z.object({})) as any,
+    }, {
+      name: 'cli_pause_in_gdb_twice',
+      description: 'Pause in gdb twice',
+      inputSchema: zodToJsonSchema(z.object({})) as any,
+    }];
+  }
+
+  async callTool(name: string, args: mcpServer.CallToolRequest['params']['arguments']): Promise<mcpServer.CallToolResult> {
+    if (name === 'cli_echo')
+      return { content: [{ type: 'text', text: 'Echo: ' + (args?.message as string) }] };
+    if (name === 'cli_pause_in_gdb') {
+      await runOnPauseBackendLoop(this.mdbUrlBox.mdbUrl!, new GDBBackend(), 'Paused on exception');
+      return { content: [{ type: 'text', text: 'Done' }] };
+    }
+    if (name === 'cli_pause_in_gdb_twice') {
+      await runOnPauseBackendLoop(this.mdbUrlBox.mdbUrl!, new GDBBackend(), 'Paused on exception 1');
+      await runOnPauseBackendLoop(this.mdbUrlBox.mdbUrl!, new GDBBackend(), 'Paused on exception 2');
+      return { content: [{ type: 'text', text: 'Done' }] };
+    }
+    throw new Error(`Unknown tool: ${name}`);
+  }
+}
+
+class GDBBackend implements ServerBackendOnPause {
+  private _server!: mcpServer.Server;
+
+  async initialize(server: mcpServer.Server): Promise<void> {
+    this._server = server;
+  }
+
+  async listTools(): Promise<mcpServer.Tool[]> {
+    return [{
+      name: 'gdb_bt',
+      description: 'Print backtrace',
+      inputSchema: zodToJsonSchema(z.object({})) as any,
+    }, {
+      name: 'gdb_continue',
+      description: 'Continue execution',
+      inputSchema: zodToJsonSchema(z.object({})) as any,
+    }];
+  }
+
+  async callTool(name: string, args: mcpServer.CallToolRequest['params']['arguments']): Promise<mcpServer.CallToolResult> {
+    if (name === 'gdb_bt')
+      return { content: [{ type: 'text', text: 'Backtrace' }] };
+    if (name === 'gdb_continue') {
+      (this as ServerBackendOnPause).requestSelfDestruct?.();
+      // Stall
+      await new Promise(f => setTimeout(f, 1000));
+    }
+    throw new Error(`Unknown tool: ${name}`);
+  }
+}

tests/roots.spec.ts

@@ -68,12 +68,12 @@ test('check that trace is saved in workspace', async ({ startClient, server }, t
   expect(file).toContain('traces');
 });
 
-test('should list all tools when listRoots is slow', async ({ startClient, server }, testInfo) => {
+test('should list all tools when listRoots is slow', async ({ startClient }) => {
   const { client } = await startClient({
     clientName: 'Another custom client',
     roots: [],
     rootsResponseDelay: 1000,
   });
   const tools = await client.listTools();
-  expect(tools.tools.length).toBeGreaterThan(20);
+  expect(tools.tools.length).toBeGreaterThan(10);
 });

tests/screenshot.spec.ts

@@ -300,7 +300,10 @@ test('browser_take_screenshot (viewport without snapshot)', async ({ startClient
 
   // Ensure we have a tab but don't navigate anywhere (no snapshot captured)
   expect(await client.callTool({
-    name: 'browser_tab_list',
+    name: 'browser_tabs',
+    arguments: {
+      action: 'list',
+    },
   })).toHaveResponse({
     tabs: `- 0: (current) [] (about:blank)`,
   });

tests/tabs.spec.ts

@@ -19,8 +19,14 @@ import { test, expect } from './fixtures.js';
 import type { Client } from '@modelcontextprotocol/sdk/client/index.js';
 
 async function createTab(client: Client, title: string, body: string) {
+  await client.callTool({
+    name: 'browser_tabs',
+    arguments: {
+      action: 'new',
+    },
+  });
   return await client.callTool({
-    name: 'browser_tab_new',
+    name: 'browser_navigate',
     arguments: {
       url: `data:text/html,<title>${title}</title><body>${body}</body>`,
     },
@@ -29,7 +35,10 @@ async function createTab(client: Client, title: string, body: string) {
 
 test('list initial tabs', async ({ client }) => {
   expect(await client.callTool({
-    name: 'browser_tab_list',
+    name: 'browser_tabs',
+    arguments: {
+      action: 'list',
+    },
   })).toHaveResponse({
     tabs: `- 0: (current) [] (about:blank)`,
   });
@@ -38,7 +47,10 @@ test('list initial tabs', async ({ client }) => {
 test('list first tab', async ({ client }) => {
   await createTab(client, 'Tab one', 'Body one');
   expect(await client.callTool({
-    name: 'browser_tab_list',
+    name: 'browser_tabs',
+    arguments: {
+      action: 'list',
+    },
   })).toHaveResponse({
     tabs: `- 0: [] (about:blank)
 - 1: (current) [Tab one] (data:text/html,<title>Tab one</title><body>Body one</body>)`,
@@ -75,8 +87,9 @@ test('select tab', async ({ client }) => {
   await createTab(client, 'Tab two', 'Body two');
 
   expect(await client.callTool({
-    name: 'browser_tab_select',
+    name: 'browser_tabs',
     arguments: {
+      action: 'select',
       index: 1,
     },
   })).toHaveResponse({
@@ -90,6 +103,19 @@ test('select tab', async ({ client }) => {
 - generic [active] [ref=e1]: Body one
 \`\`\``),
   });
+
+  expect(await client.callTool({
+    name: 'browser_tabs',
+    arguments: {
+      action: 'select',
+      index: 0,
+    },
+  })).toHaveResponse({
+    tabs: `- 0: (current) [] (about:blank)
+- 1: [Tab one] (data:text/html,<title>Tab one</title><body>Body one</body>)
+- 2: [Tab two] (data:text/html,<title>Tab two</title><body>Body two</body>)`,
+    pageState: expect.stringContaining(`- Page URL: about:blank`),
+  });
 });
 
 test('close tab', async ({ client }) => {
@@ -97,8 +123,9 @@ test('close tab', async ({ client }) => {
   await createTab(client, 'Tab two', 'Body two');
 
   expect(await client.callTool({
-    name: 'browser_tab_close',
+    name: 'browser_tabs',
     arguments: {
+      action: 'close',
       index: 2,
     },
   })).toHaveResponse({

tests/verify.spec.ts

@@ -0,0 +1,522 @@
+/**
+ * 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 { test, expect } from './fixtures.js';
+
+test.use({ mcpArgs: ['--caps=verify'] });
+
+test('browser_verify_element_visible', async ({ client, server }) => {
+  server.setContent('/', `
+    <title>Test Page</title>
+    <button>Submit</button>
+    <h1>Welcome</h1>
+    <div role="alert" aria-label="Success message"></div>
+  `, 'text/html');
+
+  await client.callTool({
+    name: 'browser_navigate',
+    arguments: { url: server.PREFIX },
+  });
+
+  expect(await client.callTool({
+    name: 'browser_verify_element_visible',
+    arguments: {
+      role: 'button',
+      accessibleName: 'Submit',
+    },
+  })).toHaveResponse({
+    result: 'Done',
+    code: `await expect(page.getByRole('button', { name: 'Submit' })).toBeVisible();`,
+  });
+
+  expect(await client.callTool({
+    name: 'browser_verify_element_visible',
+    arguments: {
+      role: 'heading',
+      accessibleName: 'Welcome',
+    },
+  })).toHaveResponse({
+    result: 'Done',
+    code: `await expect(page.getByRole('heading', { name: 'Welcome' })).toBeVisible();`,
+  });
+
+  expect(await client.callTool({
+    name: 'browser_verify_element_visible',
+    arguments: {
+      role: 'alert',
+      accessibleName: 'Success message',
+    },
+  })).toHaveResponse({
+    result: 'Done',
+    code: `await expect(page.getByRole('alert', { name: 'Success message' })).toBeVisible();`,
+  });
+});
+
+test('browser_verify_element_visible (not found)', async ({ client, server }) => {
+  server.setContent('/', `
+    <title>Test Page</title>
+    <button>Submit</button>
+  `, 'text/html');
+
+  await client.callTool({
+    name: 'browser_navigate',
+    arguments: { url: server.PREFIX },
+  });
+
+  expect(await client.callTool({
+    name: 'browser_verify_element_visible',
+    arguments: {
+      role: 'button',
+      accessibleName: 'Cancel',
+    },
+  })).toHaveResponse({
+    isError: true,
+    result: 'Element with role "button" and accessible name "Cancel" not found',
+  });
+});
+
+test('browser_verify_text_visible', async ({ client, server }) => {
+  server.setContent('/', `
+    <title>Test Page</title>
+    <p>Hello world</p>
+    <div>Welcome to our site</div>
+    <span>Status: Active</span>
+  `, 'text/html');
+
+  await client.callTool({
+    name: 'browser_navigate',
+    arguments: { url: server.PREFIX },
+  });
+
+  expect(await client.callTool({
+    name: 'browser_verify_text_visible',
+    arguments: {
+      text: 'Hello world',
+    },
+  })).toHaveResponse({
+    result: 'Done',
+    code: `await expect(page.getByText('Hello world')).toBeVisible();`,
+  });
+
+  expect(await client.callTool({
+    name: 'browser_verify_text_visible',
+    arguments: {
+      text: 'Welcome to our site',
+    },
+  })).toHaveResponse({
+    result: 'Done',
+    code: `await expect(page.getByText('Welcome to our site')).toBeVisible();`,
+  });
+
+  expect(await client.callTool({
+    name: 'browser_verify_text_visible',
+    arguments: {
+      text: 'Status: Active',
+    },
+  })).toHaveResponse({
+    result: 'Done',
+    code: `await expect(page.getByText('Status: Active')).toBeVisible();`,
+  });
+});
+
+test('browser_verify_text_visible (not found)', async ({ client, server }) => {
+  server.setContent('/', `
+    <title>Test Page</title>
+    <p>Hello world</p>
+  `, 'text/html');
+
+  await client.callTool({
+    name: 'browser_navigate',
+    arguments: { url: server.PREFIX },
+  });
+
+  expect(await client.callTool({
+    name: 'browser_verify_text_visible',
+    arguments: {
+      text: 'Goodbye world',
+    },
+  })).toHaveResponse({
+    isError: true,
+    result: 'Text not found',
+  });
+});
+
+test('browser_verify_text_visible (with quotes)', async ({ client, server }) => {
+  server.setContent('/', `
+    <title>Test Page</title>
+    <p>She said "Hello world"</p>
+    <div>It's a beautiful day</div>
+  `, 'text/html');
+
+  await client.callTool({
+    name: 'browser_navigate',
+    arguments: { url: server.PREFIX },
+  });
+
+  expect(await client.callTool({
+    name: 'browser_verify_text_visible',
+    arguments: {
+      text: 'She said "Hello world"',
+    },
+  })).toHaveResponse({
+    result: 'Done',
+    code: `await expect(page.getByText('She said "Hello world"')).toBeVisible();`,
+  });
+
+  expect(await client.callTool({
+    name: 'browser_verify_text_visible',
+    arguments: {
+      text: "It's a beautiful day",
+    },
+  })).toHaveResponse({
+    result: 'Done',
+    code: `await expect(page.getByText('It\\'s a beautiful day')).toBeVisible();`,
+  });
+});
+
+test('browser_verify_list_visible', async ({ client, server }) => {
+  server.setContent('/', `
+    <title>Test Page</title>
+    <ul>
+      <li>Apple</li>
+      <li>Banana</li>
+      <li>Cherry</li>
+    </ul>
+  `, 'text/html');
+
+  await client.callTool({
+    name: 'browser_navigate',
+    arguments: { url: server.PREFIX },
+  });
+
+  expect(await client.callTool({
+    name: 'browser_verify_list_visible',
+    arguments: {
+      element: 'Fruit list',
+      ref: 'e2',
+      items: ['Apple', 'Banana', 'Cherry'],
+    },
+  })).toHaveResponse({
+    result: 'Done',
+    code: expect.stringContaining(`await expect(page.locator('body')).toMatchAriaSnapshot(\`
+- list:
+  - listitem: "Apple"
+  - listitem: "Banana"
+  - listitem: "Cherry"
+\`);`),
+  });
+});
+
+test('browser_verify_list_visible (partial items)', async ({ client, server }) => {
+  server.setContent('/', `
+    <title>Test Page</title>
+    <ul>
+      <li>Apple</li>
+      <li>Banana</li>
+      <li>Cherry</li>
+      <li>Date</li>
+    </ul>
+  `, 'text/html');
+
+  await client.callTool({
+    name: 'browser_navigate',
+    arguments: { url: server.PREFIX },
+  });
+
+  expect(await client.callTool({
+    name: 'browser_verify_list_visible',
+    arguments: {
+      element: 'Fruit list',
+      ref: 'e2',
+      items: ['Apple', 'Cherry'],
+    },
+  })).toHaveResponse({
+    result: 'Done',
+    code: expect.stringContaining(`await expect(page.locator('body')).toMatchAriaSnapshot(\`
+- list:
+  - listitem: "Apple"
+  - listitem: "Cherry"
+\`);`),
+  });
+});
+
+test('browser_verify_list_visible (item not found)', async ({ client, server }) => {
+  server.setContent('/', `
+    <title>Test Page</title>
+    <ul>
+      <li>Apple</li>
+      <li>Banana</li>
+    </ul>
+  `, 'text/html');
+
+  await client.callTool({
+    name: 'browser_navigate',
+    arguments: { url: server.PREFIX },
+  });
+
+  expect(await client.callTool({
+    name: 'browser_verify_list_visible',
+    arguments: {
+      element: 'Fruit list',
+      ref: 'e2',
+      items: ['Apple', 'Cherry'],
+    },
+  })).toHaveResponse({
+    isError: true,
+    result: 'Item "Cherry" not found',
+  });
+});
+
+test('browser_verify_value (textbox)', async ({ client, server }) => {
+  server.setContent('/', `
+    <title>Test Page</title>
+    <form>
+      <input type="text" aria-label="Name" value="John Doe" />
+      <input type="email" aria-label="Email" value="john@example.com" />
+    </form>
+  `, 'text/html');
+
+  await client.callTool({
+    name: 'browser_navigate',
+    arguments: { url: server.PREFIX },
+  });
+
+  expect(await client.callTool({
+    name: 'browser_verify_value',
+    arguments: {
+      type: 'textbox',
+      element: 'Name textbox',
+      ref: 'e3',
+      value: 'John Doe',
+    },
+  })).toHaveResponse({
+    result: 'Done',
+    code: expect.stringContaining(`await expect(page.getByRole('textbox', { name: 'Name' })).toHaveValue('John Doe');`),
+  });
+
+  expect(await client.callTool({
+    name: 'browser_verify_value',
+    arguments: {
+      type: 'textbox',
+      element: 'Email textbox',
+      ref: 'e4',
+      value: 'john@example.com',
+    },
+  })).toHaveResponse({
+    result: 'Done',
+    code: expect.stringContaining(`await expect(page.getByRole('textbox', { name: 'Email' })).toHaveValue('john@example.com');`),
+  });
+});
+
+test('browser_verify_value (textbox wrong value)', async ({ client, server }) => {
+  server.setContent('/', `
+    <title>Test Page</title>
+    <form>
+      <input type="text" name="name" value="John Doe" />
+    </form>
+  `, 'text/html');
+
+  await client.callTool({
+    name: 'browser_navigate',
+    arguments: { url: server.PREFIX },
+  });
+
+  expect(await client.callTool({
+    name: 'browser_verify_value',
+    arguments: {
+      type: 'textbox',
+      element: 'Name textbox',
+      ref: 'e3',
+      value: 'Jane Smith',
+    },
+  })).toHaveResponse({
+    isError: true,
+    result: 'Expected value "Jane Smith", but got "John Doe"',
+  });
+});
+
+test('browser_verify_value (checkbox checked)', async ({ client, server }) => {
+  server.setContent('/', `
+    <title>Test Page</title>
+    <form>
+      <input type="checkbox" name="subscribe" checked />
+      <label for="subscribe">Subscribe to newsletter</label>
+    </form>
+  `, 'text/html');
+
+  await client.callTool({
+    name: 'browser_navigate',
+    arguments: { url: server.PREFIX },
+  });
+
+  expect(await client.callTool({
+    name: 'browser_verify_value',
+    arguments: {
+      type: 'checkbox',
+      element: 'Subscribe checkbox',
+      ref: 'e3',
+      value: 'true',
+    },
+  })).toHaveResponse({
+    result: 'Done',
+    code: expect.stringContaining(`await expect(page.getByRole('checkbox')).toBeChecked();`),
+  });
+});
+
+test('browser_verify_value (checkbox unchecked)', async ({ client, server }) => {
+  server.setContent('/', `
+    <title>Test Page</title>
+    <form>
+      <input type="checkbox" name="subscribe" />
+      <label for="subscribe">Subscribe to newsletter</label>
+    </form>
+  `, 'text/html');
+
+  await client.callTool({
+    name: 'browser_navigate',
+    arguments: { url: server.PREFIX },
+  });
+
+  expect(await client.callTool({
+    name: 'browser_verify_value',
+    arguments: {
+      type: 'checkbox',
+      element: 'Subscribe checkbox',
+      ref: 'e3',
+      value: 'false',
+    },
+  })).toHaveResponse({
+    result: 'Done',
+    code: expect.stringContaining(`await expect(page.getByRole('checkbox')).not.toBeChecked();`),
+  });
+});
+
+test('browser_verify_value (checkbox wrong value)', async ({ client, server }) => {
+  server.setContent('/', `
+    <title>Test Page</title>
+    <form>
+      <input type="checkbox" name="subscribe" checked />
+      <label for="subscribe">Subscribe to newsletter</label>
+    </form>
+  `, 'text/html');
+
+  await client.callTool({
+    name: 'browser_navigate',
+    arguments: { url: server.PREFIX },
+  });
+
+  expect(await client.callTool({
+    name: 'browser_verify_value',
+    arguments: {
+      type: 'checkbox',
+      element: 'Subscribe checkbox',
+      ref: 'e3',
+      value: 'false',
+    },
+  })).toHaveResponse({
+    isError: true,
+    result: 'Expected value "false", but got "true"',
+  });
+});
+
+test('browser_verify_value (radio checked)', async ({ client, server }) => {
+  server.setContent('/', `
+    <title>Test Page</title>
+    <form>
+      <label for="red">Red</label>
+      <input id="red" type="radio" name="color" value="red" checked />
+      <label for="blue">Blue</label>
+      <input id="blue" type="radio" name="color" value="blue" />
+    </form>
+  `, 'text/html');
+
+  await client.callTool({
+    name: 'browser_navigate',
+    arguments: { url: server.PREFIX },
+  });
+
+  expect(await client.callTool({
+    name: 'browser_verify_value',
+    arguments: {
+      type: 'radio',
+      element: 'Color radio',
+      ref: 'e3',
+      value: 'true',
+    },
+  })).toHaveResponse({
+    result: 'Done',
+    code: expect.stringContaining(`await expect(page.getByRole('radio', { name: 'Red' })).toBeChecked();`),
+  });
+});
+
+test('browser_verify_value (slider)', async ({ client, server }) => {
+  server.setContent('/', `
+    <title>Test Page</title>
+    <form>
+      <input type="range" name="volume" min="0" max="100" value="75" />
+      <label>Volume</label>
+    </form>
+  `, 'text/html');
+
+  await client.callTool({
+    name: 'browser_navigate',
+    arguments: { url: server.PREFIX },
+  });
+
+  expect(await client.callTool({
+    name: 'browser_verify_value',
+    arguments: {
+      type: 'slider',
+      element: 'Volume slider',
+      ref: 'e3',
+      value: '75',
+    },
+  })).toHaveResponse({
+    result: 'Done',
+    code: expect.stringContaining(`await expect(page.getByRole('slider')).toHaveValue('75');`),
+  });
+});
+
+test('browser_verify_value (combobox)', async ({ client, server }) => {
+  server.setContent('/', `
+    <title>Test Page</title>
+    <form>
+      <select name="country">
+        <option>Choose a country</option>
+        <option selected>United States</option>
+        <option>United Kingdom</option>
+      </select>
+    </form>
+  `, 'text/html');
+
+  await client.callTool({
+    name: 'browser_navigate',
+    arguments: { url: server.PREFIX },
+  });
+
+  expect(await client.callTool({
+    name: 'browser_verify_value',
+    arguments: {
+      type: 'combobox',
+      element: 'Country select',
+      ref: 'e3',
+      value: 'United States',
+    },
+  })).toHaveResponse({
+    result: 'Done',
+    code: expect.stringContaining(`await expect(page.getByRole('combobox')).toHaveValue('United States');`),
+  });
+});

tests/vscode.spec.ts

@@ -0,0 +1,54 @@
+/**
+ * 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 { test, expect } from './fixtures.js';
+
+test('browser_connect(vscode) works', async ({ startClient, playwright, browserName }) => {
+  const { client } = await startClient({
+    args: ['--vscode'],
+  });
+
+  const server = await playwright[browserName].launchServer();
+
+  expect(await client.callTool({
+    name: 'browser_connect',
+    arguments: {
+      connectionString: server.wsEndpoint(),
+      lib: import.meta.resolve('playwright'),
+    }
+  })).toHaveResponse({
+    result: 'Successfully connected.'
+  });
+
+  expect(await client.callTool({
+    name: 'browser_navigate',
+    arguments: {
+      url: 'data:text/html,foo'
+    }
+  })).toHaveResponse({
+    pageState: expect.stringContaining('foo'),
+  });
+
+  await server.close();
+
+  expect(await client.callTool({
+    name: 'browser_snapshot',
+    arguments: {}
+  }), 'it actually used the server').toHaveResponse({
+    isError: true,
+    result: expect.stringContaining('ECONNREFUSED')
+  });
+});

utils/update-readme.js

@@ -30,6 +30,7 @@ const capabilities = {
   'core-install': 'Browser installation',
   'vision': 'Coordinate-based (opt-in via --caps=vision)',
   'pdf': 'PDF generation (opt-in via --caps=pdf)',
+  'verify': 'Verify (opt-in via --caps=verify)',
 };
 
 const toolsByCapability = Object.fromEntries(Object.entries(capabilities).map(([capability, title]) => [title, allTools.filter(tool => tool.capability === capability).sort((a, b) => a.schema.name.localeCompare(b.schema.name))]));