chore: mark v0.0.32 (#768 )

chore: do not snapshot on fill (#767 )
chore(extension): reject second http connection (#766 )
2025-07-25 16:40:31 -07:00 · 2025-07-25 15:54:18 -07:00 · 2025-07-25 14:46:48 -07:00 · 2025-07-25 12:18:02 -07:00 · 2025-07-25 12:17:51 -07:00 · 2025-07-25 09:51:01 -07:00
72 changed files with 2630 additions and 1621 deletions
--- a/.gitignore
+++ b/.gitignore
@@ -3,6 +3,7 @@ node_modules/
 test-results/
 playwright-report/
 .vscode/mcp.json
-
 .idea
 .DS_Store
+.env
+sessions/
--- a/README.md
+++ b/README.md
@@ -88,6 +88,18 @@ Follow the MCP install [guide](https://github.com/google-gemini/gemini-cli/blob/
 Go to `Advanced settings` -> `Extensions` -> `Add custom extension`. Name to your liking, use type `STDIO`, and set the `command` to `npx @playwright/mcp`. Click "Add Extension".
 </details>

+<details>
+<summary>LM Studio</summary>
+
+#### Click the button to install:
+
+[![Add MCP Server playwright to LM Studio](https://files.lmstudio.ai/deeplink/mcp-install-light.svg)](https://lmstudio.ai/install-mcp?name=playwright&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyJAcGxheXdyaWdodC9tY3BAbGF0ZXN0Il19)
+
+#### Or install manually:
+
+Go to `Program` in the right sidebar -> `Install` -> `Edit mcp.json`. Use the standard config above.
+</details>
+
 <details>
 <summary>Qodo Gen</summary>

@@ -162,6 +174,8 @@ Playwright MCP server supports following arguments. They can be provided in the
                               example ".com,chromium.org,.domain.com"
  --proxy-server <proxy>       specify proxy server, for example
                               "http://myproxy:3128" or "socks5://myproxy:8080"
+  --save-session               Whether to save the Playwright MCP session into
+                               the output directory.
  --save-trace                 Whether to save the Playwright Trace of the
                               session into the output directory.
  --storage-state <path>       path to the storage state file for isolated
--- a/config.d.ts
+++ b/config.d.ts
@@ -85,6 +85,11 @@ export type Config = {
   */
  capabilities?: ToolCapability[];

+  /**
+   * Whether to save the Playwright session into the output directory.
+   */
+  saveSession?: boolean;
+
  /**
   * Whether to save the Playwright trace of the session into the output directory.
   */
--- a/eslint.config.mjs
+++ b/eslint.config.mjs
@@ -192,6 +192,31 @@ const languageOptions = {
  }
 };

+const importOrderRules = {
+  "import/order": [
+    2,
+    {
+      groups: [
+        "builtin",
+        "external",
+        "internal",
+        ["parent", "sibling"],
+        "index",
+        "type",
+      ],
+    },
+  ],
+  "import/consistent-type-specifier-style": [2, "prefer-top-level"],
+};
+
+const noFloatingPromisesRules = {
+  "@typescript-eslint/no-floating-promises": "error",
+};
+
+const noBooleanCompareRules = {
+  "@typescript-eslint/no-unnecessary-boolean-literal-compare": 2,
+};
+
 export default [
  {
    ignores: ["**/*.js"],
@@ -200,6 +225,11 @@ export default [
    files: ["**/*.ts", "**/*.tsx"],
    plugins,
    languageOptions,
-    rules: baseRules,
+    rules: {
+      ...baseRules,
+      ...importOrderRules,
+      ...noFloatingPromisesRules,
+      ...noBooleanCompareRules,
+    },
  },
 ];
--- a/extension/connect.html
+++ b/extension/connect.html
@@ -19,14 +19,16 @@
  <title>Playwright MCP extension</title>
 </head>
 <body>
-  <div class="header">
-    <h3>Playwright MCP extension</h3>
-  </div>
+  <h3>Playwright MCP extension</h3>
  <div id="status-container"></div>
  <div class="button-row">
    <button id="continue-btn">Continue</button>
    <button id="reject-btn">Reject</button>
  </div>
+  <div id="tab-list-container">
+    <h4>Select page to expose to MCP server:</h4>
+    <div id="tab-list"></div>
+  </div>
  <script src="lib/connect.js"></script>
 </body>
 </html> 
--- a/extension/src/background.ts
+++ b/extension/src/background.ts
@@ -19,6 +19,10 @@ import { RelayConnection, debugLog } from './relayConnection.js';
 type PageMessage = {
  type: 'connectToMCPRelay';
  mcpRelayUrl: string;
+  tabId: number;
+  windowId: number;
+} | {
+  type: 'getTabs';
 };

 class TabShareExtension {
@@ -35,20 +39,20 @@ class TabShareExtension {
  private _onMessage(message: PageMessage, sender: chrome.runtime.MessageSender, sendResponse: (response: any) => void) {
    switch (message.type) {
      case 'connectToMCPRelay':
-        const tabId = sender.tab?.id;
-        if (!tabId) {
-          sendResponse({ success: false, error: 'No tab id' });
-          return true;
-        }
-        this._connectTab(tabId, message.mcpRelayUrl!).then(
+        this._connectTab(message.tabId, message.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
+      case 'getTabs':
+        this._getTabs().then(
+            tabs => sendResponse({ success: true, tabs, currentTabId: sender.tab?.id }),
+            (error: any) => sendResponse({ success: false, error: error.message }));
+        return true;
    }
    return false;
  }

-  private async _connectTab(tabId: number, mcpRelayUrl: string): Promise<void> {
+  private async _connectTab(tabId: number, windowId: number, mcpRelayUrl: string): Promise<void> {
    try {
      debugLog(`Connecting tab ${tabId} to bridge at ${mcpRelayUrl}`);
      const socket = new WebSocket(mcpRelayUrl);
@@ -58,8 +62,7 @@ class TabShareExtension {
        setTimeout(() => reject(new Error('Connection timeout')), 5000);
      });

-      const connection = new RelayConnection(socket);
-      connection.setConnectedTabId(tabId);
+      const connection = new RelayConnection(socket, tabId);
      const connectionClosed = (m: string) => {
        debugLog(m);
        if (this._activeConnection === connection) {
@@ -71,11 +74,15 @@ class TabShareExtension {
      socket.onerror = error => connectionClosed(`WebSocket error: ${error}`);
      this._activeConnection = connection;

-      await this._setConnectedTabId(tabId);
-      debugLog(`Tab ${tabId} connected successfully`);
+      await Promise.all([
+        this._setConnectedTabId(tabId),
+        chrome.tabs.update(tabId, { active: true }),
+        chrome.windows.update(windowId, { focused: true }),
+      ]);
+      debugLog(`Connected to MCP bridge`);
    } catch (error: any) {
-      debugLog(`Failed to connect tab ${tabId}:`, error.message);
      await this._setConnectedTabId(null);
+      debugLog(`Failed to connect tab ${tabId}:`, error.message);
      throw error;
    }
  }
@@ -96,14 +103,22 @@ class TabShareExtension {
  }

  private async _onTabRemoved(tabId: number): Promise<void> {
-    if (this._connectedTabId === tabId)
-      this._activeConnection!.setConnectedTabId(null);
+    if (this._connectedTabId !== tabId)
+      return;
+    this._activeConnection?.close('Browser tab closed');
+    this._activeConnection = undefined;
+    this._connectedTabId = null;
  }

  private async _onTabUpdated(tabId: number, changeInfo: chrome.tabs.TabChangeInfo, tab: chrome.tabs.Tab): Promise<void> {
    if (changeInfo.status === 'complete' && this._connectedTabId === tabId)
      await this._setConnectedTabId(tabId);
  }
+
+  private async _getTabs(): Promise<chrome.tabs.Tab[]> {
+    const tabs = await chrome.tabs.query({});
+    return tabs;
+  }
 }

 new TabShareExtension();
--- a/extension/src/connect.ts
+++ b/extension/src/connect.ts
@@ -14,57 +14,159 @@
 * limitations under the License.
 */

-document.addEventListener('DOMContentLoaded', async () => {
-  const statusContainer = document.getElementById('status-container') as HTMLElement;
-  const continueBtn = document.getElementById('continue-btn') as HTMLButtonElement;
-  const rejectBtn = document.getElementById('reject-btn') as HTMLButtonElement;
-  const buttonRow = document.querySelector('.button-row') as HTMLElement;
+interface TabInfo {
+  id: number;
+  windowId: number;
+  title: string;
+  url: string;
+  favIconUrl?: string;
+}

-  function showStatus(type: 'connected' | 'error' | 'connecting', message: string) {
+class ConnectPage {
+  private _tabList: HTMLElement;
+  private _tabListContainer: HTMLElement;
+  private _statusContainer: HTMLElement;
+  private _selectedTab: TabInfo | undefined;
+
+  constructor() {
+    this._tabList = document.getElementById('tab-list')!;
+    this._tabListContainer = document.getElementById('tab-list-container')!;
+    this._statusContainer = document.getElementById('status-container') as HTMLElement;
+    this._addButtonHandlers();
+    void this._loadTabs();
+  }
+
+  private _addButtonHandlers() {
+    const continueBtn = document.getElementById('continue-btn') as HTMLButtonElement;
+    const rejectBtn = document.getElementById('reject-btn') as HTMLButtonElement;
+    const buttonRow = document.querySelector('.button-row') as HTMLElement;
+
+    const params = new URLSearchParams(window.location.search);
+    const mcpRelayUrl = params.get('mcpRelayUrl');
+
+    if (!mcpRelayUrl) {
+      buttonRow.style.display = 'none';
+      this._showStatus('error', 'Missing mcpRelayUrl parameter in URL.');
+      return;
+    }
+
+    let clientInfo = 'unknown';
+    try {
+      const client = JSON.parse(params.get('client') || '{}');
+      clientInfo = `${client.name}/${client.version}`;
+    } catch (e) {
+      this._showStatus('error', 'Failed to parse client version.');
+      return;
+    }
+
+    this._showStatus('connecting', `MCP client "${clientInfo}" is trying to connect. Do you want to continue?`);
+
+    rejectBtn.addEventListener('click', async () => {
+      buttonRow.style.display = 'none';
+      this._tabListContainer.style.display = 'none';
+      this._showStatus('error', 'Connection rejected. This tab can be closed.');
+    });
+
+    continueBtn.addEventListener('click', async () => {
+      buttonRow.style.display = 'none';
+      this._tabListContainer.style.display = 'none';
+      try {
+        const selectedTab = this._selectedTab;
+        if (!selectedTab) {
+          this._showStatus('error', 'Tab not selected.');
+          return;
+        }
+        const response = await chrome.runtime.sendMessage({
+          type: 'connectToMCPRelay',
+          mcpRelayUrl,
+          tabId: selectedTab.id,
+          windowId: selectedTab.windowId,
+        });
+        if (response?.success)
+          this._showStatus('connected', `MCP client "${clientInfo}" connected.`);
+        else
+          this._showStatus('error', response?.error || `MCP client "${clientInfo}" failed to connect.`);
+      } catch (e) {
+        this._showStatus('error', `MCP client "${clientInfo}" failed to connect: ${e}`);
+      }
+    });
+  }
+
+  private async _loadTabs(): Promise<void> {
+    try {
+      const response = await chrome.runtime.sendMessage({ type: 'getTabs' });
+      if (response.success)
+        this._populateTabList(response.tabs, response.currentTabId);
+      else
+        this._showStatus('error', 'Failed to load tabs: ' + response.error);
+    } catch (error) {
+      this._showStatus('error', 'Failed to communicate with background script: ' + error);
+    }
+  }
+
+  private _populateTabList(tabs: TabInfo[], currentTabId: number): void {
+    this._tabList.replaceChildren();
+    this._selectedTab = tabs.find(tab => tab.id === currentTabId);
+
+    tabs.forEach((tab, index) => {
+      const tabElement = this._createTabElement(tab);
+      this._tabList.appendChild(tabElement);
+    });
+  }
+
+  private _createTabElement(tab: TabInfo): HTMLElement {
+    const disabled = tab.url.startsWith('chrome://');
+
+    const tabInfoDiv = document.createElement('div');
+    tabInfoDiv.className = 'tab-info';
+    tabInfoDiv.style.padding = '5px';
+    if (disabled)
+      tabInfoDiv.style.opacity = '0.5';
+
+    const radioButton = document.createElement('input');
+    radioButton.type = 'radio';
+    radioButton.name = 'tab-selection';
+    radioButton.checked = tab.id === this._selectedTab?.id;
+    radioButton.id = `tab-${tab.id}`;
+    radioButton.addEventListener('change', e => {
+      if (radioButton.checked)
+        this._selectedTab = tab;
+    });
+    if (disabled)
+      radioButton.disabled = true;
+
+    const favicon = document.createElement('img');
+    favicon.className = 'tab-favicon';
+    if (tab.favIconUrl)
+      favicon.src = tab.favIconUrl;
+    favicon.alt = '';
+    favicon.style.height = '16px';
+    favicon.style.width = '16px';
+
+    const title = document.createElement('span');
+    title.style.paddingLeft = '5px';
+    title.className = 'tab-title';
+    title.textContent = tab.title || 'Untitled';
+
+    const url = document.createElement('span');
+    url.style.paddingLeft = '5px';
+    url.className = 'tab-url';
+    url.textContent = tab.url;
+
+    tabInfoDiv.appendChild(radioButton);
+    tabInfoDiv.appendChild(favicon);
+    tabInfoDiv.appendChild(title);
+    tabInfoDiv.appendChild(url);
+
+    return tabInfoDiv;
+  }
+
+  private _showStatus(type: 'connected' | 'error' | 'connecting', message: string) {
    const div = document.createElement('div');
    div.className = `status ${type}`;
    div.textContent = message;
-    statusContainer.replaceChildren(div);
+    this._statusContainer.replaceChildren(div);
  }
+}

-  const params = new URLSearchParams(window.location.search);
-  const mcpRelayUrl = params.get('mcpRelayUrl');
-
-  if (!mcpRelayUrl) {
-    buttonRow.style.display = 'none';
-    showStatus('error', 'Missing mcpRelayUrl parameter in URL.');
-    return;
-  }
-
-  let clientInfo = 'unknown';
-  try {
-    const client = JSON.parse(params.get('client') || '{}');
-    clientInfo = `${client.name}/${client.version}`;
-  } catch (e) {
-    showStatus('error', 'Failed to parse client version.');
-    return;
-  }
-
-  showStatus('connecting', `MCP client "${clientInfo}" is trying to connect. Do you want to continue?`);
-
-  rejectBtn.addEventListener('click', async () => {
-    buttonRow.style.display = 'none';
-    showStatus('error', 'Connection rejected. This tab can be closed.');
-  });
-
-  continueBtn.addEventListener('click', async () => {
-    buttonRow.style.display = 'none';
-    try {
-      const response = await chrome.runtime.sendMessage({
-        type: 'connectToMCPRelay',
-        mcpRelayUrl
-      });
-      if (response?.success)
-        showStatus('connected', `MCP client "${clientInfo}" connected.`);
-      else
-        showStatus('error', response?.error || `MCP client "${clientInfo}" failed to connect.`);
-    } catch (e) {
-      showStatus('error', `MCP client "${clientInfo}" failed to connect: ${e}`);
-    }
-  });
-});
+new ConnectPage();
--- a/extension/src/relayConnection.ts
+++ b/extension/src/relayConnection.ts
@@ -37,13 +37,13 @@ type ProtocolResponse = {
 };

 export class RelayConnection {
-  private _debuggee: chrome.debugger.Debuggee = {};
-  private _rootSessionId = '';
+  private _debuggee: chrome.debugger.Debuggee;
  private _ws: WebSocket;
  private _eventListener: (source: chrome.debugger.DebuggerSession, method: string, params: any) => void;
  private _detachListener: (source: chrome.debugger.Debuggee, reason: string) => void;

-  constructor(ws: WebSocket) {
+  constructor(ws: WebSocket, tabId: number) {
+    this._debuggee = { tabId };
    this._ws = ws;
    this._ws.onmessage = this._onMessage.bind(this);
    // Store listeners for cleanup
@@ -53,20 +53,10 @@ export class RelayConnection {
    chrome.debugger.onDetach.addListener(this._detachListener);
  }

-  setConnectedTabId(tabId: number | null): void {
-    if (!tabId) {
-      this._debuggee = { };
-      this._rootSessionId = '';
-      return;
-    }
-    this._debuggee = { tabId };
-    this._rootSessionId = `pw-tab-${tabId}`;
-  }
-
-  close(message?: string): void {
+  close(message: string): void {
    chrome.debugger.onEvent.removeListener(this._eventListener);
    chrome.debugger.onDetach.removeListener(this._detachListener);
-    this._ws.close(1000, message || 'Connection closed');
+    this._ws.close(1000, message);
  }

  private async _detachDebugger(): Promise<void> {
@@ -77,7 +67,7 @@ export class RelayConnection {
    if (source.tabId !== this._debuggee.tabId)
      return;
    debugLog('Forwarding CDP event:', method, params);
-    const sessionId = source.sessionId || this._rootSessionId;
+    const sessionId = source.sessionId;
    this._sendMessage({
      method: 'forwardCDPEvent',
      params: {
@@ -98,6 +88,7 @@ export class RelayConnection {
        reason,
      },
    });
+    this._debuggee = { };
  }

  private _onMessage(event: MessageEvent): void {
@@ -137,7 +128,6 @@ export class RelayConnection {
      await chrome.debugger.attach(this._debuggee, '1.3');
      const result: any = await chrome.debugger.sendCommand(this._debuggee, 'Target.getTargetInfo');
      return {
-        sessionId: this._rootSessionId,
        targetInfo: result?.targetInfo,
      };
    }
@@ -148,10 +138,10 @@ export class RelayConnection {
    if (message.method === 'forwardCDPCommand') {
      const { sessionId, method, params } = message.params;
      debugLog('CDP command:', method, params);
-      const debuggerSession: chrome.debugger.DebuggerSession = { ...this._debuggee };
-      // Pass session id, unless it's the root session.
-      if (sessionId && sessionId !== this._rootSessionId)
-        debuggerSession.sessionId = sessionId;
+      const debuggerSession: chrome.debugger.DebuggerSession = {
+        ...this._debuggee,
+        sessionId,
+      };
      // Forward CDP command to chrome.debugger
      return await chrome.debugger.sendCommand(
          debuggerSession,
--- a/index.d.ts
+++ b/index.d.ts
@@ -19,10 +19,5 @@ import type { Server } from '@modelcontextprotocol/sdk/server/index.js';
 import type { Config } from './config.js';
 import type { BrowserContext } from 'playwright';

-export type Connection = {
-  server: Server;
-  close(): Promise<void>;
-};
-
-export declare function createConnection(config?: Config, contextGetter?: () => Promise<BrowserContext>): Promise<Connection>;
+export declare function createConnection(config?: Config, contextGetter?: () => Promise<BrowserContext>): Promise<Server>;
 export {};
--- a/package-lock.json
+++ b/package-lock.json
@@ -1,17 +1,18 @@
 {
  "name": "@playwright/mcp",
-  "version": "0.0.31",
+  "version": "0.0.32",
  "lockfileVersion": 3,
  "requires": true,
  "packages": {
    "": {
      "name": "@playwright/mcp",
-      "version": "0.0.31",
+      "version": "0.0.32",
      "license": "Apache-2.0",
      "dependencies": {
        "@modelcontextprotocol/sdk": "^1.16.0",
        "commander": "^13.1.0",
        "debug": "^4.4.1",
+        "dotenv": "^17.2.0",
        "mime": "^4.0.7",
        "playwright": "1.55.0-alpha-1752701791000",
        "playwright-core": "1.55.0-alpha-1752701791000",
@@ -22,6 +23,7 @@
        "mcp-server-playwright": "cli.js"
      },
      "devDependencies": {
+        "@anthropic-ai/sdk": "^0.57.0",
        "@eslint/eslintrc": "^3.2.0",
        "@eslint/js": "^9.19.0",
        "@playwright/test": "1.55.0-alpha-1752701791000",
@@ -36,12 +38,23 @@
        "eslint": "^9.19.0",
        "eslint-plugin-import": "^2.31.0",
        "eslint-plugin-notice": "^1.0.0",
+        "openai": "^5.10.2",
        "typescript": "^5.8.2"
      },
      "engines": {
        "node": ">=18"
      }
    },
+    "node_modules/@anthropic-ai/sdk": {
+      "version": "0.57.0",
+      "resolved": "https://registry.npmjs.org/@anthropic-ai/sdk/-/sdk-0.57.0.tgz",
+      "integrity": "sha512-z5LMy0MWu0+w2hflUgj4RlJr1R+0BxKXL7ldXTO8FasU8fu599STghO+QKwId2dAD0d464aHtU+ChWuRHw4FNw==",
+      "dev": true,
+      "license": "MIT",
+      "bin": {
+        "anthropic-ai-sdk": "bin/cli"
+      }
+    },
    "node_modules/@eslint-community/eslint-utils": {
      "version": "4.5.1",
      "resolved": "https://registry.npmjs.org/@eslint-community/eslint-utils/-/eslint-utils-4.5.1.tgz",
@@ -72,9 +85,9 @@
      }
    },
    "node_modules/@eslint/config-array": {
-      "version": "0.19.2",
-      "resolved": "https://registry.npmjs.org/@eslint/config-array/-/config-array-0.19.2.tgz",
-      "integrity": "sha512-GNKqxfHG2ySmJOBSHg7LxeUx4xpuCoFjacmlCoYWEbaPXLwvfIjixRI12xCQZeULksQb23uiA8F40w5TojpV7w==",
+      "version": "0.21.0",
+      "resolved": "https://registry.npmjs.org/@eslint/config-array/-/config-array-0.21.0.tgz",
+      "integrity": "sha512-ENIdc4iLu0d93HeYirvKmrzshzofPw6VkZRKQGe9Nv46ZnWUzcF1xV01dcvEg/1wXUR61OmmlSfyeyO7EvjLxQ==",
      "dev": true,
      "license": "Apache-2.0",
      "dependencies": {
@@ -87,9 +100,9 @@
      }
    },
    "node_modules/@eslint/config-helpers": {
-      "version": "0.1.0",
-      "resolved": "https://registry.npmjs.org/@eslint/config-helpers/-/config-helpers-0.1.0.tgz",
-      "integrity": "sha512-kLrdPDJE1ckPo94kmPPf9Hfd0DU0Jw6oKYrhe+pwSC0iTUInmTa+w6fw8sGgcfkFJGNdWOUeOaDM4quW4a7OkA==",
+      "version": "0.3.0",
+      "resolved": "https://registry.npmjs.org/@eslint/config-helpers/-/config-helpers-0.3.0.tgz",
+      "integrity": "sha512-ViuymvFmcJi04qdZeDc2whTHryouGcDlaxPqarTD0ZE10ISpxGUVZGZDx4w01upyIynL3iu6IXH2bS1NhclQMw==",
      "dev": true,
      "license": "Apache-2.0",
      "engines": {
@@ -97,9 +110,9 @@
      }
    },
    "node_modules/@eslint/core": {
-      "version": "0.12.0",
-      "resolved": "https://registry.npmjs.org/@eslint/core/-/core-0.12.0.tgz",
-      "integrity": "sha512-cmrR6pytBuSMTaBweKoGMwu3EiHiEC+DoyupPmlZ0HxBJBtIxwe+j/E4XPIKNx+Q74c8lXKPwYawBf5glsTkHg==",
+      "version": "0.15.1",
+      "resolved": "https://registry.npmjs.org/@eslint/core/-/core-0.15.1.tgz",
+      "integrity": "sha512-bkOp+iumZCCbt1K1CmWf0R9pM5yKpDv+ZXtvSyQpudrI9kuFLp+bM2WOPXImuD/ceQuaa8f5pj93Y7zyECIGNA==",
      "dev": true,
      "license": "Apache-2.0",
      "dependencies": {
@@ -110,9 +123,9 @@
      }
    },
    "node_modules/@eslint/eslintrc": {
-      "version": "3.3.0",
-      "resolved": "https://registry.npmjs.org/@eslint/eslintrc/-/eslintrc-3.3.0.tgz",
-      "integrity": "sha512-yaVPAiNAalnCZedKLdR21GOGILMLKPyqSLWaAjQFvYA2i/ciDi8ArYVr69Anohb6cH2Ukhqti4aFnYyPm8wdwQ==",
+      "version": "3.3.1",
+      "resolved": "https://registry.npmjs.org/@eslint/eslintrc/-/eslintrc-3.3.1.tgz",
+      "integrity": "sha512-gtF186CXhIl1p4pJNGZw8Yc6RlshoePRvE0X91oPGb3vZ8pM3qOS9W9NGPat9LziaBV7XrJWGylNQXkGcnM3IQ==",
      "dev": true,
      "license": "MIT",
      "dependencies": {
@@ -134,13 +147,16 @@
      }
    },
    "node_modules/@eslint/js": {
-      "version": "9.22.0",
-      "resolved": "https://registry.npmjs.org/@eslint/js/-/js-9.22.0.tgz",
-      "integrity": "sha512-vLFajx9o8d1/oL2ZkpMYbkLv8nDB6yaIwFNt7nI4+I80U/z03SxmfOMsLbvWr3p7C+Wnoh//aOu2pQW8cS0HCQ==",
+      "version": "9.31.0",
+      "resolved": "https://registry.npmjs.org/@eslint/js/-/js-9.31.0.tgz",
+      "integrity": "sha512-LOm5OVt7D4qiKCqoiPbA7LWmI+tbw1VbTUowBcUMgQSuM6poJufkFkYDcQpo5KfgD39TnNySV26QjOh7VFpSyw==",
      "dev": true,
      "license": "MIT",
      "engines": {
        "node": "^18.18.0 || ^20.9.0 || >=21.1.0"
+      },
+      "funding": {
+        "url": "https://eslint.org/donate"
      }
    },
    "node_modules/@eslint/object-schema": {
@@ -154,13 +170,13 @@
      }
    },
    "node_modules/@eslint/plugin-kit": {
-      "version": "0.2.7",
-      "resolved": "https://registry.npmjs.org/@eslint/plugin-kit/-/plugin-kit-0.2.7.tgz",
-      "integrity": "sha512-JubJ5B2pJ4k4yGxaNLdbjrnk9d/iDz6/q8wOilpIowd6PJPgaxCuHBnBszq7Ce2TyMrywm5r4PnKm6V3iiZF+g==",
+      "version": "0.3.4",
+      "resolved": "https://registry.npmjs.org/@eslint/plugin-kit/-/plugin-kit-0.3.4.tgz",
+      "integrity": "sha512-Ul5l+lHEcw3L5+k8POx6r74mxEYKG5kOb6Xpy2gCRW6zweT6TEhAf8vhxGgjhqrd/VO/Dirhsb+1hNpD1ue9hw==",
      "dev": true,
      "license": "Apache-2.0",
      "dependencies": {
-        "@eslint/core": "^0.12.0",
+        "@eslint/core": "^0.15.1",
        "levn": "^0.4.1"
      },
      "engines": {
@@ -595,9 +611,9 @@
      }
    },
    "node_modules/@typescript-eslint/typescript-estree/node_modules/brace-expansion": {
-      "version": "2.0.1",
-      "resolved": "https://registry.npmjs.org/brace-expansion/-/brace-expansion-2.0.1.tgz",
-      "integrity": "sha512-XnAIvQ8eM+kC6aULx6wuQiwVsnzsi9d3WxzV3FpWTGA19F621kwdbsAcFKXgKUHZWsy+mY6iL1sHTxWEFCytDA==",
+      "version": "2.0.2",
+      "resolved": "https://registry.npmjs.org/brace-expansion/-/brace-expansion-2.0.2.tgz",
+      "integrity": "sha512-Jt0vHyM+jmUBqojB7E1NIYadt0vI0Qxjxd2TErW94wDz+E2LAm5vKMXXwg6ZZBTHPuUlDgQHKXvjGBdfcF1ZDQ==",
      "dev": true,
      "license": "MIT",
      "dependencies": {
@@ -689,9 +705,9 @@
      }
    },
    "node_modules/acorn": {
-      "version": "8.14.1",
-      "resolved": "https://registry.npmjs.org/acorn/-/acorn-8.14.1.tgz",
-      "integrity": "sha512-OvQ/2pUDKmgfCg++xsTX1wGxfTaszcHVcTctW4UJB4hibJx2HXxxO5UmVgyjMa+ZDsiaf5wWLXYpRWMmBI0QHg==",
+      "version": "8.15.0",
+      "resolved": "https://registry.npmjs.org/acorn/-/acorn-8.15.0.tgz",
+      "integrity": "sha512-NZyJarBfL7nWwIq+FDL6Zp/yHEhePMNnnJ0y3qfieCrmNvYct8uvtiV41UvlSe6apAfk0fY1FbWx+NwfmpvtTg==",
      "dev": true,
      "license": "MIT",
      "bin": {
@@ -924,9 +940,9 @@
      }
    },
    "node_modules/brace-expansion": {
-      "version": "1.1.11",
-      "resolved": "https://registry.npmjs.org/brace-expansion/-/brace-expansion-1.1.11.tgz",
-      "integrity": "sha512-iCuPHDFgrHX7H2vEI/5xpz07zSHB00TpugqhmYtVmMO6518mCuRMoOYFldEBl0g187ufozdaHgWKcYFb61qGiA==",
+      "version": "1.1.12",
+      "resolved": "https://registry.npmjs.org/brace-expansion/-/brace-expansion-1.1.12.tgz",
+      "integrity": "sha512-9T9UjW3r0UW5c1Q7GTwllptXwhvYmEzFhzMfZ9H7FQWt+uZePjZPjBP/W1ZEyZ1twGWom5/56TF4lPcqjnDHcg==",
      "dev": true,
      "license": "MIT",
      "dependencies": {
@@ -1269,6 +1285,18 @@
        "node": ">=0.10.0"
      }
    },
+    "node_modules/dotenv": {
+      "version": "17.2.0",
+      "resolved": "https://registry.npmjs.org/dotenv/-/dotenv-17.2.0.tgz",
+      "integrity": "sha512-Q4sgBT60gzd0BB0lSyYD3xM4YxrXA9y4uBDof1JNYGzOXrQdQ6yX+7XIAqoFOGQFOTK1D3Hts5OllpxMDZFONQ==",
+      "license": "BSD-2-Clause",
+      "engines": {
+        "node": ">=12"
+      },
+      "funding": {
+        "url": "https://dotenvx.com"
+      }
+    },
    "node_modules/dunder-proto": {
      "version": "1.0.1",
      "resolved": "https://registry.npmjs.org/dunder-proto/-/dunder-proto-1.0.1.tgz",
@@ -1461,20 +1489,20 @@
      }
    },
    "node_modules/eslint": {
-      "version": "9.22.0",
-      "resolved": "https://registry.npmjs.org/eslint/-/eslint-9.22.0.tgz",
-      "integrity": "sha512-9V/QURhsRN40xuHXWjV64yvrzMjcz7ZyNoF2jJFmy9j/SLk0u1OLSZgXi28MrXjymnjEGSR80WCdab3RGMDveQ==",
+      "version": "9.31.0",
+      "resolved": "https://registry.npmjs.org/eslint/-/eslint-9.31.0.tgz",
+      "integrity": "sha512-QldCVh/ztyKJJZLr4jXNUByx3gR+TDYZCRXEktiZoUR3PGy4qCmSbkxcIle8GEwGpb5JBZazlaJ/CxLidXdEbQ==",
      "dev": true,
      "license": "MIT",
      "dependencies": {
        "@eslint-community/eslint-utils": "^4.2.0",
        "@eslint-community/regexpp": "^4.12.1",
-        "@eslint/config-array": "^0.19.2",
-        "@eslint/config-helpers": "^0.1.0",
-        "@eslint/core": "^0.12.0",
-        "@eslint/eslintrc": "^3.3.0",
-        "@eslint/js": "9.22.0",
-        "@eslint/plugin-kit": "^0.2.7",
+        "@eslint/config-array": "^0.21.0",
+        "@eslint/config-helpers": "^0.3.0",
+        "@eslint/core": "^0.15.0",
+        "@eslint/eslintrc": "^3.3.1",
+        "@eslint/js": "9.31.0",
+        "@eslint/plugin-kit": "^0.3.1",
        "@humanfs/node": "^0.16.6",
        "@humanwhocodes/module-importer": "^1.0.1",
        "@humanwhocodes/retry": "^0.4.2",
@@ -1485,9 +1513,9 @@
        "cross-spawn": "^7.0.6",
        "debug": "^4.3.2",
        "escape-string-regexp": "^4.0.0",
-        "eslint-scope": "^8.3.0",
-        "eslint-visitor-keys": "^4.2.0",
-        "espree": "^10.3.0",
+        "eslint-scope": "^8.4.0",
+        "eslint-visitor-keys": "^4.2.1",
+        "espree": "^10.4.0",
        "esquery": "^1.5.0",
        "esutils": "^2.0.2",
        "fast-deep-equal": "^3.1.3",
@@ -1641,9 +1669,9 @@
      }
    },
    "node_modules/eslint-scope": {
-      "version": "8.3.0",
-      "resolved": "https://registry.npmjs.org/eslint-scope/-/eslint-scope-8.3.0.tgz",
-      "integrity": "sha512-pUNxi75F8MJ/GdeKtVLSbYg4ZI34J6C0C7sbL4YOp2exGwen7ZsuBqKzUhXd0qMQ362yET3z+uPwKeg/0C2XCQ==",
+      "version": "8.4.0",
+      "resolved": "https://registry.npmjs.org/eslint-scope/-/eslint-scope-8.4.0.tgz",
+      "integrity": "sha512-sNXOfKCn74rt8RICKMvJS7XKV/Xk9kA7DyJr8mJik3S7Cwgy3qlkkmyS2uQB3jiJg6VNdZd/pDBJu0nvG2NlTg==",
      "dev": true,
      "license": "BSD-2-Clause",
      "dependencies": {
@@ -1671,9 +1699,9 @@
      }
    },
    "node_modules/eslint/node_modules/eslint-visitor-keys": {
-      "version": "4.2.0",
-      "resolved": "https://registry.npmjs.org/eslint-visitor-keys/-/eslint-visitor-keys-4.2.0.tgz",
-      "integrity": "sha512-UyLnSehNt62FFhSwjZlHmeokpRK59rcz29j+F1/aDgbkbRTk7wIc9XzdoasMUbRNKDM0qQt/+BJ4BrpFeABemw==",
+      "version": "4.2.1",
+      "resolved": "https://registry.npmjs.org/eslint-visitor-keys/-/eslint-visitor-keys-4.2.1.tgz",
+      "integrity": "sha512-Uhdk5sfqcee/9H/rCOJikYz67o0a2Tw2hGRPOG2Y1R2dg7brRe1uG0yaNQDHu+TO/uQPF/5eCapvYSmHUjt7JQ==",
      "dev": true,
      "license": "Apache-2.0",
      "engines": {
@@ -1684,15 +1712,15 @@
      }
    },
    "node_modules/espree": {
-      "version": "10.3.0",
-      "resolved": "https://registry.npmjs.org/espree/-/espree-10.3.0.tgz",
-      "integrity": "sha512-0QYC8b24HWY8zjRnDTL6RiHfDbAWn63qb4LMj1Z4b076A4une81+z03Kg7l7mn/48PUTqoLptSXez8oknU8Clg==",
+      "version": "10.4.0",
+      "resolved": "https://registry.npmjs.org/espree/-/espree-10.4.0.tgz",
+      "integrity": "sha512-j6PAQ2uUr79PZhBjP5C5fhl8e39FmRnOjsD5lGnWrFU8i2G776tBK7+nP8KuQUTTyAZUwfQqXAgrVH5MbH9CYQ==",
      "dev": true,
      "license": "BSD-2-Clause",
      "dependencies": {
-        "acorn": "^8.14.0",
+        "acorn": "^8.15.0",
        "acorn-jsx": "^5.3.2",
-        "eslint-visitor-keys": "^4.2.0"
+        "eslint-visitor-keys": "^4.2.1"
      },
      "engines": {
        "node": "^18.18.0 || ^20.9.0 || >=21.1.0"
@@ -1702,9 +1730,9 @@
      }
    },
    "node_modules/espree/node_modules/eslint-visitor-keys": {
-      "version": "4.2.0",
-      "resolved": "https://registry.npmjs.org/eslint-visitor-keys/-/eslint-visitor-keys-4.2.0.tgz",
-      "integrity": "sha512-UyLnSehNt62FFhSwjZlHmeokpRK59rcz29j+F1/aDgbkbRTk7wIc9XzdoasMUbRNKDM0qQt/+BJ4BrpFeABemw==",
+      "version": "4.2.1",
+      "resolved": "https://registry.npmjs.org/eslint-visitor-keys/-/eslint-visitor-keys-4.2.1.tgz",
+      "integrity": "sha512-Uhdk5sfqcee/9H/rCOJikYz67o0a2Tw2hGRPOG2Y1R2dg7brRe1uG0yaNQDHu+TO/uQPF/5eCapvYSmHUjt7JQ==",
      "dev": true,
      "license": "Apache-2.0",
      "engines": {
@@ -3151,6 +3179,28 @@
        "wrappy": "1"
      }
    },
+    "node_modules/openai": {
+      "version": "5.10.2",
+      "resolved": "https://registry.npmjs.org/openai/-/openai-5.10.2.tgz",
+      "integrity": "sha512-n+vi74LzHtvlKcDPn9aApgELGiu5CwhaLG40zxLTlFQdoSJCLACORIPC2uVQ3JEYAbqapM+XyRKFy2Thej7bIw==",
+      "dev": true,
+      "license": "Apache-2.0",
+      "bin": {
+        "openai": "bin/cli"
+      },
+      "peerDependencies": {
+        "ws": "^8.18.0",
+        "zod": "^3.23.8"
+      },
+      "peerDependenciesMeta": {
+        "ws": {
+          "optional": true
+        },
+        "zod": {
+          "optional": true
+        }
+      }
+    },
    "node_modules/optionator": {
      "version": "0.9.4",
      "resolved": "https://registry.npmjs.org/optionator/-/optionator-0.9.4.tgz",
--- a/package.json
+++ b/package.json
@@ -1,6 +1,6 @@
 {
  "name": "@playwright/mcp",
-  "version": "0.0.31",
+  "version": "0.0.32",
  "description": "Playwright Tools for MCP",
  "type": "module",
  "repository": {
@@ -19,6 +19,7 @@
    "build": "tsc",
    "build:extension": "tsc --project extension",
    "lint": "npm run update-readme && eslint . && tsc --noEmit",
+    "lint-fix": "eslint . --fix",
    "update-readme": "node utils/update-readme.js",
    "watch": "tsc --watch",
    "watch:extension": "tsc --watch --project extension",
@@ -41,6 +42,7 @@
    "@modelcontextprotocol/sdk": "^1.16.0",
    "commander": "^13.1.0",
    "debug": "^4.4.1",
+    "dotenv": "^17.2.0",
    "mime": "^4.0.7",
    "playwright": "1.55.0-alpha-1752701791000",
    "playwright-core": "1.55.0-alpha-1752701791000",
@@ -48,6 +50,7 @@
    "zod-to-json-schema": "^3.24.4"
  },
  "devDependencies": {
+    "@anthropic-ai/sdk": "^0.57.0",
    "@eslint/eslintrc": "^3.2.0",
    "@eslint/js": "^9.19.0",
    "@playwright/test": "1.55.0-alpha-1752701791000",
@@ -62,6 +65,7 @@
    "eslint": "^9.19.0",
    "eslint-plugin-import": "^2.31.0",
    "eslint-plugin-notice": "^1.0.0",
+    "openai": "^5.10.2",
    "typescript": "^5.8.2"
  },
  "bin": {
--- a/src/browserContextFactory.ts
+++ b/src/browserContextFactory.ts
@@ -217,7 +217,7 @@ async function injectCdpPort(browserConfig: FullConfig['browser']) {
    (browserConfig.launchOptions as any).cdpPort = await findFreePort();
 }

-async function findFreePort() {
+async function findFreePort(): Promise<number> {
  return new Promise((resolve, reject) => {
    const server = net.createServer();
    server.listen(0, () => {
--- a/src/browserServerBackend.ts
+++ b/src/browserServerBackend.ts
@@ -0,0 +1,69 @@
+/**
+ * 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 { FullConfig } from './config.js';
+import { Context } from './context.js';
+import { logUnhandledError } from './log.js';
+import { Response } from './response.js';
+import { SessionLog } from './sessionLog.js';
+import { filteredTools } from './tools.js';
+import { packageJSON } from './package.js';
+
+import type { BrowserContextFactory } from './browserContextFactory.js';
+import type * as mcpServer from './mcp/server.js';
+import type { ServerBackend } from './mcp/server.js';
+import type { Tool } from './tools/tool.js';
+
+export class BrowserServerBackend implements ServerBackend {
+  name = 'Playwright';
+  version = packageJSON.version;
+  onclose?: () => void;
+
+  private _tools: Tool[];
+  private _context: Context;
+  private _sessionLog: SessionLog | undefined;
+
+  constructor(config: FullConfig, browserContextFactory: BrowserContextFactory) {
+    this._tools = filteredTools(config);
+    this._context = new Context(this._tools, config, browserContextFactory);
+  }
+
+  async initialize() {
+    this._sessionLog = this._context.config.saveSession ? await SessionLog.create(this._context.config) : undefined;
+  }
+
+  tools(): mcpServer.ToolSchema<any>[] {
+    return this._tools.map(tool => tool.schema);
+  }
+
+  async callTool(schema: mcpServer.ToolSchema<any>, parsedArguments: any) {
+    const response = new Response(this._context, schema.name, parsedArguments);
+    const tool = this._tools.find(tool => tool.schema.name === schema.name)!;
+    await tool.handle(this._context, parsedArguments, response);
+    if (this._sessionLog)
+      await this._sessionLog.log(response);
+    return await response.serialize();
+  }
+
+  serverInitialized(version: mcpServer.ClientVersion | undefined) {
+    this._context.clientVersion = version;
+  }
+
+  serverClosed() {
+    this.onclose?.();
+    void this._context.dispose().catch(logUnhandledError);
+  }
+}
--- a/src/config.ts
+++ b/src/config.ts
@@ -18,10 +18,9 @@ import fs from 'fs';
 import os from 'os';
 import path from 'path';
 import { devices } from 'playwright';
-
+import { sanitizeForFilePath } from './tools/utils.js';
 import type { Config, ToolCapability } from '../config.js';
 import type { BrowserContextOptions, LaunchOptions } from 'playwright';
-import { sanitizeForFilePath } from './tools/utils.js';

 export type CLIOptions = {
  allowedOrigins?: string[];
@@ -43,6 +42,7 @@ export type CLIOptions = {
  port?: number;
  proxyBypass?: string;
  proxyServer?: string;
+  saveSession?: boolean;
  saveTrace?: boolean;
  storageState?: string;
  userAgent?: string;
@@ -190,6 +190,7 @@ export function configFromCLIOptions(cliOptions: CLIOptions): Config {
      allowedOrigins: cliOptions.allowedOrigins,
      blockedOrigins: cliOptions.blockedOrigins,
    },
+    saveSession: cliOptions.saveSession,
    saveTrace: cliOptions.saveTrace,
    outputDir: cliOptions.outputDir,
    imageResponses: cliOptions.imageResponses,
--- a/src/connection.ts
+++ b/src/connection.ts
@@ -1,96 +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 { Server as McpServer } from '@modelcontextprotocol/sdk/server/index.js';
-import { CallToolRequestSchema, ListToolsRequestSchema, Tool as McpTool } from '@modelcontextprotocol/sdk/types.js';
-import { zodToJsonSchema } from 'zod-to-json-schema';
-
-import { Context } from './context.js';
-import { allTools } from './tools.js';
-import { packageJSON } from './package.js';
-
-import { FullConfig } from './config.js';
-
-import type { BrowserContextFactory } from './browserContextFactory.js';
-
-export function createConnection(config: FullConfig, browserContextFactory: BrowserContextFactory): Connection {
-  const tools = allTools.filter(tool => tool.capability.startsWith('core') || config.capabilities?.includes(tool.capability));
-  const context = new Context(tools, config, browserContextFactory);
-  const server = new McpServer({ name: 'Playwright', version: packageJSON.version }, {
-    capabilities: {
-      tools: {},
-    }
-  });
-
-  server.setRequestHandler(ListToolsRequestSchema, async () => {
-    return {
-      tools: tools.map(tool => ({
-        name: tool.schema.name,
-        description: tool.schema.description,
-        inputSchema: zodToJsonSchema(tool.schema.inputSchema),
-        annotations: {
-          title: tool.schema.title,
-          readOnlyHint: tool.schema.type === 'readOnly',
-          destructiveHint: tool.schema.type === 'destructive',
-          openWorldHint: true,
-        },
-      })) as McpTool[],
-    };
-  });
-
-  server.setRequestHandler(CallToolRequestSchema, async request => {
-    const errorResult = (...messages: string[]) => ({
-      content: [{ type: 'text', text: messages.join('\n') }],
-      isError: true,
-    });
-    const tool = tools.find(tool => tool.schema.name === request.params.name);
-    if (!tool)
-      return errorResult(`Tool "${request.params.name}" not found`);
-
-
-    const modalStates = context.modalStates().map(state => state.type);
-    if (tool.clearsModalState && !modalStates.includes(tool.clearsModalState))
-      return errorResult(`The tool "${request.params.name}" can only be used when there is related modal state present.`, ...context.modalStatesMarkdown());
-    if (!tool.clearsModalState && modalStates.length)
-      return errorResult(`Tool "${request.params.name}" does not handle the modal state.`, ...context.modalStatesMarkdown());
-
-    try {
-      return await context.run(tool, request.params.arguments);
-    } catch (error) {
-      return errorResult(String(error));
-    }
-  });
-
-  return new Connection(server, context);
-}
-
-export class Connection {
-  readonly server: McpServer;
-  readonly context: Context;
-
-  constructor(server: McpServer, context: Context) {
-    this.server = server;
-    this.context = context;
-    this.server.oninitialized = () => {
-      this.context.clientVersion = this.server.getClientVersion();
-    };
-  }
-
-  async close() {
-    await this.server.close();
-    await this.context.close();
-  }
-}
--- a/src/context.ts
+++ b/src/context.ts
@@ -17,19 +17,13 @@
 import debug from 'debug';
 import * as playwright from 'playwright';

-import { callOnPageNoTrace, waitForCompletion } from './tools/utils.js';
-import { ManualPromise } from './manualPromise.js';
+import { logUnhandledError } from './log.js';
 import { Tab } from './tab.js';
-import { outputFile } from './config.js';

-import type { ModalState, Tool, ToolActionResult } from './tools/tool.js';
+import type { Tool } from './tools/tool.js';
 import type { FullConfig } from './config.js';
 import type { BrowserContextFactory } from './browserContextFactory.js';

-type PendingAction = {
-  dialogShown: ManualPromise<void>;
-};
-
 const testDebug = debug('pw:mcp:test');

 export class Context {
@@ -39,54 +33,34 @@ export class Context {
  private _browserContextFactory: BrowserContextFactory;
  private _tabs: Tab[] = [];
  private _currentTab: Tab | undefined;
-  private _modalStates: (ModalState & { tab: Tab })[] = [];
-  private _pendingAction: PendingAction | undefined;
-  private _downloads: { download: playwright.Download, finished: boolean, outputFile: string }[] = [];
  clientVersion: { name: string; version: string; } | undefined;

+  private static _allContexts: Set<Context> = new Set();
+  private _closeBrowserContextPromise: Promise<void> | undefined;
+
  constructor(tools: Tool[], config: FullConfig, browserContextFactory: BrowserContextFactory) {
    this.tools = tools;
    this.config = config;
    this._browserContextFactory = browserContextFactory;
    testDebug('create context');
+    Context._allContexts.add(this);
  }

-  clientSupportsImages(): boolean {
-    if (this.config.imageResponses === 'omit')
-      return false;
-    return true;
-  }
-
-  modalStates(): ModalState[] {
-    return this._modalStates;
-  }
-
-  setModalState(modalState: ModalState, inTab: Tab) {
-    this._modalStates.push({ ...modalState, tab: inTab });
-  }
-
-  clearModalState(modalState: ModalState) {
-    this._modalStates = this._modalStates.filter(state => state !== modalState);
-  }
-
-  modalStatesMarkdown(): string[] {
-    const result: string[] = ['### Modal state'];
-    if (this._modalStates.length === 0)
-      result.push('- There is no modal state present');
-    for (const state of this._modalStates) {
-      const tool = this.tools.find(tool => tool.clearsModalState === state.type);
-      result.push(`- [${state.description}]: can be handled by the "${tool?.schema.name}" tool`);
-    }
-    return result;
+  static async disposeAll() {
+    await Promise.all([...Context._allContexts].map(context => context.dispose()));
  }

  tabs(): Tab[] {
    return this._tabs;
  }

+  currentTab(): Tab | undefined {
+    return this._currentTab;
+  }
+
  currentTabOrDie(): Tab {
    if (!this._currentTab)
-      throw new Error('No current snapshot available. Capture a snapshot or navigate to a new location first.');
+      throw new Error('No open pages available. Use the "browser_navigate" tool to navigate to a page first.');
    return this._currentTab;
  }

@@ -98,8 +72,12 @@ export class Context {
  }

  async selectTab(index: number) {
-    this._currentTab = this._tabs[index];
-    await this._currentTab.page.bringToFront();
+    const tab = this._tabs[index];
+    if (!tab)
+      throw new Error(`Tab ${index} not found`);
+    await tab.page.bringToFront();
+    this._currentTab = tab;
+    return tab;
  }

  async ensureTab(): Promise<Tab> {
@@ -109,9 +87,18 @@ export class Context {
    return this._currentTab!;
  }

-  async listTabsMarkdown(): Promise<string> {
-    if (!this._tabs.length)
-      return '### No tabs open';
+  async listTabsMarkdown(force: boolean = false): Promise<string[]> {
+    if (this._tabs.length === 1 && !force)
+      return [];
+
+    if (!this._tabs.length) {
+      return [
+        '### No open tabs',
+        'Use the "browser_navigate" tool to navigate to a page first.',
+        '',
+      ];
+    }
+
    const lines: string[] = ['### Open tabs'];
    for (let i = 0; i < this._tabs.length; i++) {
      const tab = this._tabs[i];
@@ -120,158 +107,17 @@ export class Context {
      const current = tab === this._currentTab ? ' (current)' : '';
      lines.push(`- ${i}:${current} [${title}] (${url})`);
    }
-    return lines.join('\n');
+    lines.push('');
+    return lines;
  }

-  async closeTab(index: number | undefined) {
+  async closeTab(index: number | undefined): Promise<string> {
    const tab = index === undefined ? this._currentTab : this._tabs[index];
-    await tab?.page.close();
-    return await this.listTabsMarkdown();
-  }
-
-  async run(tool: Tool, params: Record<string, unknown> | undefined) {
-    // Tab management is done outside of the action() call.
-    const toolResult = await tool.handle(this, tool.schema.inputSchema.parse(params || {}));
-    const { code, action, waitForNetwork, captureSnapshot, resultOverride } = toolResult;
-
-    if (resultOverride)
-      return resultOverride;
-
-    if (!this._currentTab) {
-      return {
-        content: [{
-          type: 'text',
-          text: 'No open pages available. Use the "browser_navigate" tool to navigate to a page first.',
-        }],
-      };
-    }
-
-    const tab = this.currentTabOrDie();
-    // TODO: race against modal dialogs to resolve clicks.
-    const actionResult = await this._raceAgainstModalDialogs(async () => {
-      try {
-        if (waitForNetwork)
-          return await waitForCompletion(this, tab, async () => action?.()) ?? undefined;
-        else
-          return await action?.() ?? undefined;
-      } finally {
-        if (captureSnapshot && !this._javaScriptBlocked())
-          await tab.captureSnapshot();
-      }
-    });
-
-    const result: string[] = [];
-    result.push(`### Ran Playwright code
-\`\`\`js
-${code.join('\n')}
-\`\`\``);
-
-    if (this.modalStates().length) {
-      result.push('', ...this.modalStatesMarkdown());
-      return {
-        content: [{
-          type: 'text',
-          text: result.join('\n'),
-        }],
-      };
-    }
-
-    const messages = tab.takeRecentConsoleMessages();
-    if (messages.length) {
-      result.push('', `### New console messages`);
-      for (const message of messages)
-        result.push(`- ${trim(message.toString(), 100)}`);
-    }
-
-    if (this._downloads.length) {
-      result.push('', '### Downloads');
-      for (const entry of this._downloads) {
-        if (entry.finished)
-          result.push(`- Downloaded file ${entry.download.suggestedFilename()} to ${entry.outputFile}`);
-        else
-          result.push(`- Downloading file ${entry.download.suggestedFilename()} ...`);
-      }
-    }
-
-    if (captureSnapshot && tab.hasSnapshot()) {
-      if (this.tabs().length > 1)
-        result.push('', await this.listTabsMarkdown());
-
-      if (this.tabs().length > 1)
-        result.push('', '### Current tab');
-      else
-        result.push('', '### Page state');
-
-      result.push(
-          `- Page URL: ${tab.page.url()}`,
-          `- Page Title: ${await tab.title()}`
-      );
-      result.push(tab.snapshotOrDie().text());
-    }
-
-    const content = actionResult?.content ?? [];
-
-    return {
-      content: [
-        ...content,
-        {
-          type: 'text',
-          text: result.join('\n'),
-        }
-      ],
-    };
-  }
-
-  async waitForTimeout(time: number) {
-    if (!this._currentTab || this._javaScriptBlocked()) {
-      await new Promise(f => setTimeout(f, time));
-      return;
-    }
-
-    await callOnPageNoTrace(this._currentTab.page, page => {
-      return page.evaluate(() => new Promise(f => setTimeout(f, 1000)));
-    });
-  }
-
-  private async _raceAgainstModalDialogs(action: () => Promise<ToolActionResult>): Promise<ToolActionResult> {
-    this._pendingAction = {
-      dialogShown: new ManualPromise(),
-    };
-
-    let result: ToolActionResult | undefined;
-    try {
-      await Promise.race([
-        action().then(r => result = r),
-        this._pendingAction.dialogShown,
-      ]);
-    } finally {
-      this._pendingAction = undefined;
-    }
-    return result;
-  }
-
-  private _javaScriptBlocked(): boolean {
-    return this._modalStates.some(state => state.type === 'dialog');
-  }
-
-  dialogShown(tab: Tab, dialog: playwright.Dialog) {
-    this.setModalState({
-      type: 'dialog',
-      description: `"${dialog.type()}" dialog with message "${dialog.message()}"`,
-      dialog,
-    }, tab);
-    this._pendingAction?.dialogShown.resolve();
-  }
-
-  async downloadStarted(tab: Tab, download: playwright.Download) {
-    const entry = {
-      download,
-      finished: false,
-      outputFile: await outputFile(this.config, download.suggestedFilename())
-    };
-    this._downloads.push(entry);
-    await download.saveAs(entry.outputFile);
-    entry.finished = true;
+    if (!tab)
+      throw new Error(`Tab ${index} not found`);
+    const url = tab.page.url();
+    await tab.page.close();
+    return url;
  }

  private _onPageCreated(page: playwright.Page) {
@@ -282,7 +128,6 @@ ${code.join('\n')}
  }

  private _onPageClosed(tab: Tab) {
-    this._modalStates = this._modalStates.filter(state => state.tab !== tab);
    const index = this._tabs.indexOf(tab);
    if (index === -1)
      return;
@@ -291,10 +136,17 @@ ${code.join('\n')}
    if (this._currentTab === tab)
      this._currentTab = this._tabs[Math.min(index, this._tabs.length - 1)];
    if (!this._tabs.length)
-      void this.close();
+      void this.closeBrowserContext();
  }

-  async close() {
+  async closeBrowserContext() {
+    if (!this._closeBrowserContextPromise)
+      this._closeBrowserContextPromise = this._closeBrowserContextImpl().catch(logUnhandledError);
+    await this._closeBrowserContextPromise;
+    this._closeBrowserContextPromise = undefined;
+  }
+
+  private async _closeBrowserContextImpl() {
    if (!this._browserContextPromise)
      return;

@@ -310,6 +162,11 @@ ${code.join('\n')}
    });
  }

+  async dispose() {
+    await this.closeBrowserContext();
+    Context._allContexts.delete(this);
+  }
+
  private async _setupRequestInterception(context: playwright.BrowserContext) {
    if (this.config.network?.allowedOrigins?.length) {
      await context.route('**', route => route.abort('blockedbyclient'));
@@ -335,6 +192,8 @@ ${code.join('\n')}
  }

  private async _setupBrowserContext(): Promise<{ browserContext: playwright.BrowserContext, close: () => Promise<void> }> {
+    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.clientVersion!);
    const { browserContext } = result;
@@ -353,9 +212,3 @@ ${code.join('\n')}
    return result;
  }
 }
-
-function trim(text: string, maxLength: number) {
-  if (text.length <= maxLength)
-    return text;
-  return text.slice(0, maxLength) + '...';
-}
--- a/src/extension/cdpRelay.ts
+++ b/src/extension/cdpRelay.ts
@@ -22,15 +22,18 @@
 * - /extension/guid - Extension connection for chrome.debugger forwarding
 */

+import http from 'http';
+import { spawn } from 'child_process';
 import { WebSocket, WebSocketServer } from 'ws';
-import type websocket from 'ws';
-import http from 'node:http';
 import debug from 'debug';
-import { promisify } from 'node:util';
-import { exec } from 'node:child_process';
-import { httpAddressToString, startHttpServer } from '../transport.js';
-import { BrowserContextFactory } from '../browserContextFactory.js';
-import { Browser, chromium, type BrowserContext } from 'playwright';
+import * as playwright from 'playwright';
+// @ts-ignore
+const { registry } = await import('playwright-core/lib/server/registry/index');
+import { httpAddressToString, startHttpServer } from '../httpServer.js';
+import { logUnhandledError } from '../log.js';
+import { ManualPromise } from '../manualPromise.js';
+import type { BrowserContextFactory } from '../browserContextFactory.js';
+import type websocket from 'ws';

 const debugLogger = debug('pw:mcp:relay');

@@ -52,6 +55,7 @@ type CDPResponse = {

 export class CDPRelayServer {
  private _wsHost: string;
+  private _browserChannel: string;
  private _cdpPath: string;
  private _extensionPath: string;
  private _wss: WebSocketServer;
@@ -62,19 +66,18 @@ export class CDPRelayServer {
    // Page sessionId that should be used by this connection.
    sessionId: string;
  } | undefined;
-  private _extensionConnectionPromise: Promise<void>;
-  private _extensionConnectionResolve: (() => void) | null = null;
+  private _nextSessionId: number = 1;
+  private _extensionConnectionPromise!: ManualPromise<void>;

-  constructor(server: http.Server) {
+  constructor(server: http.Server, browserChannel: string) {
    this._wsHost = httpAddressToString(server.address()).replace(/^http/, 'ws');
+    this._browserChannel = browserChannel;

    const uuid = crypto.randomUUID();
    this._cdpPath = `/cdp/${uuid}`;
    this._extensionPath = `/extension/${uuid}`;

-    this._extensionConnectionPromise = new Promise(resolve => {
-      this._extensionConnectionResolve = resolve;
-    });
+    this._resetExtensionConnection();
    this._wss = new WebSocketServer({ server });
    this._wss.on('connection', this._onConnection.bind(this));
  }
@@ -88,10 +91,13 @@ export class CDPRelayServer {
  }

  async ensureExtensionConnectionForMCPContext(clientInfo: { name: string, version: string }) {
+    debugLogger('Ensuring extension connection for MCP context');
    if (this._extensionConnection)
      return;
    await this._connectBrowser(clientInfo);
+    debugLogger('Waiting for incoming extension connection');
    await this._extensionConnectionPromise;
+    debugLogger('Extension connection established');
  }

  private async _connectBrowser(clientInfo: { name: string, version: string }) {
@@ -101,17 +107,29 @@ export class CDPRelayServer {
    url.searchParams.set('mcpRelayUrl', mcpRelayEndpoint);
    url.searchParams.set('client', JSON.stringify(clientInfo));
    const href = url.toString();
-    const command = `'/Applications/Google Chrome.app/Contents/MacOS/Google Chrome' '${href}'`;
-    try {
-      await promisify(exec)(command);
-    } catch (err) {
-      debugLogger('Failed to run command:', err);
-    }
+    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.`);
+
+    spawn(executablePath, [href], {
+      windowsHide: true,
+      detached: true,
+      shell: false,
+      stdio: 'ignore',
+    });
  }

  stop(): void {
-    this._playwrightConnection?.close();
-    this._extensionConnection?.close();
+    this.closeConnections('Server stopped');
+    this._wss.close();
+  }
+
+  closeConnections(reason: string) {
+    this._closePlaywrightConnection(reason);
+    this._closeExtensionConnection(reason);
  }

  private _onConnection(ws: WebSocket, request: http.IncomingMessage): void {
@@ -128,21 +146,26 @@ export class CDPRelayServer {
  }

  private _handlePlaywrightConnection(ws: WebSocket): void {
+    if (this._playwrightConnection) {
+      debugLogger('Rejecting second Playwright connection');
+      ws.close(1000, 'Another CDP client already connected');
+      return;
+    }
    this._playwrightConnection = ws;
    ws.on('message', async data => {
      try {
        const message = JSON.parse(data.toString());
        await this._handlePlaywrightMessage(message);
-      } catch (error) {
-        debugLogger('Error parsing Playwright message:', error);
+      } catch (error: any) {
+        debugLogger(`Error while handling Playwright message\n${data.toString()}\n`, error);
      }
    });
    ws.on('close', () => {
-      if (this._playwrightConnection === ws) {
-        this._playwrightConnection = null;
-        this._closeExtensionConnection();
-        debugLogger('Playwright MCP disconnected');
-      }
+      if (this._playwrightConnection !== ws)
+        return;
+      this._playwrightConnection = null;
+      this._closeExtensionConnection('Playwright client disconnected');
+      debugLogger('Playwright WebSocket closed');
    });
    ws.on('error', error => {
      debugLogger('Playwright WebSocket error:', error);
@@ -150,13 +173,23 @@ export class CDPRelayServer {
    debugLogger('Playwright MCP connected');
  }

-  private _closeExtensionConnection() {
+  private _closeExtensionConnection(reason: string) {
+    this._extensionConnection?.close(reason);
+    this._extensionConnectionPromise.reject(new Error(reason));
+    this._resetExtensionConnection();
+  }
+
+  private _resetExtensionConnection() {
    this._connectedTabInfo = undefined;
-    this._extensionConnection?.close();
    this._extensionConnection = null;
-    this._extensionConnectionPromise = new Promise(resolve => {
-      this._extensionConnectionResolve = resolve;
-    });
+    this._extensionConnectionPromise = new ManualPromise();
+    void this._extensionConnectionPromise.catch(logUnhandledError);
+  }
+
+  private _closePlaywrightConnection(reason: string) {
+    if (this._playwrightConnection?.readyState === WebSocket.OPEN)
+      this._playwrightConnection.close(1000, reason);
+    this._playwrightConnection = null;
  }

  private _handleExtensionConnection(ws: WebSocket): void {
@@ -165,19 +198,23 @@ export class CDPRelayServer {
      return;
    }
    this._extensionConnection = new ExtensionConnection(ws);
-    this._extensionConnection.onclose = c => {
-      if (this._extensionConnection === c)
-        this._extensionConnection = null;
+    this._extensionConnection.onclose = (c, reason) => {
+      debugLogger('Extension WebSocket closed:', reason, c === this._extensionConnection);
+      if (this._extensionConnection !== c)
+        return;
+      this._resetExtensionConnection();
+      this._closePlaywrightConnection(`Extension disconnected: ${reason}`);
    };
    this._extensionConnection.onmessage = this._handleExtensionMessage.bind(this);
-    this._extensionConnectionResolve?.();
+    this._extensionConnectionPromise.resolve();
  }

  private _handleExtensionMessage(method: string, params: any) {
    switch (method) {
      case 'forwardCDPEvent':
+        const sessionId = params.sessionId || this._connectedTabInfo?.sessionId;
        this._sendToPlaywright({
-          sessionId: params.sessionId,
+          sessionId,
          method: params.method,
          params: params.params
        });
@@ -191,91 +228,72 @@ export class CDPRelayServer {

  private async _handlePlaywrightMessage(message: CDPCommand): Promise<void> {
    debugLogger('← Playwright:', `${message.method} (id=${message.id})`);
-    if (!this._extensionConnection) {
-      debugLogger('Extension not connected, sending error to Playwright');
-      this._sendToPlaywright({
-        id: message.id,
-        error: { message: 'Extension not connected' }
-      });
-      return;
-    }
-    if (await this._interceptCDPCommand(message))
-      return;
-    await this._forwardToExtension(message);
-  }
-
-  private async _interceptCDPCommand(message: CDPCommand): Promise<boolean> {
-    switch (message.method) {
-      case 'Browser.getVersion': {
-        this._sendToPlaywright({
-          id: message.id,
-          result: {
-            protocolVersion: '1.3',
-            product: 'Chrome/Extension-Bridge',
-            userAgent: 'CDP-Bridge-Server/1.0.0',
-          }
-        });
-        return true;
-      }
-      case 'Browser.setDownloadBehavior': {
-        this._sendToPlaywright({
-          id: message.id
-        });
-        return true;
-      }
-      case 'Target.setAutoAttach': {
-        // Simulate auto-attach behavior with real target info
-        if (!message.sessionId) {
-          this._connectedTabInfo = await this._extensionConnection!.send('attachToTab');
-          debugLogger('Simulating auto-attach for target:', message);
-          this._sendToPlaywright({
-            method: 'Target.attachedToTarget',
-            params: {
-              sessionId: this._connectedTabInfo!.sessionId,
-              targetInfo: {
-                ...this._connectedTabInfo!.targetInfo,
-                attached: true,
-              },
-              waitingForDebugger: false
-            }
-          });
-          this._sendToPlaywright({
-            id: message.id
-          });
-        } else {
-          await this._forwardToExtension(message);
-        }
-        return true;
-      }
-      case 'Target.getTargetInfo': {
-        debugLogger('Target.getTargetInfo', message);
-        this._sendToPlaywright({
-          id: message.id,
-          result: this._connectedTabInfo?.targetInfo
-        });
-        return true;
-      }
-    }
-    return false;
-  }
-
-  private async _forwardToExtension(message: CDPCommand): Promise<void> {
+    const { id, sessionId, method, params } = message;
    try {
-      if (!this._extensionConnection)
-        throw new Error('Extension not connected');
-      const { id, sessionId, method, params } = message;
-      const result = await this._extensionConnection.send('forwardCDPCommand', { sessionId, method, params });
+      const result = await this._handleCDPCommand(method, params, sessionId);
      this._sendToPlaywright({ id, sessionId, result });
    } catch (e) {
      debugLogger('Error in the extension:', e);
      this._sendToPlaywright({
-        id: message.id,
-        sessionId: message.sessionId,
+        id,
+        sessionId,
        error: { message: (e as Error).message }
      });
    }
  }

+  private async _handleCDPCommand(method: string, params: any, sessionId: string | undefined): Promise<any> {
+    switch (method) {
+      case 'Browser.getVersion': {
+        return {
+          protocolVersion: '1.3',
+          product: 'Chrome/Extension-Bridge',
+          userAgent: 'CDP-Bridge-Server/1.0.0',
+        };
+      }
+      case 'Browser.setDownloadBehavior': {
+        return { };
+      }
+      case 'Target.setAutoAttach': {
+        // Forward child session handling.
+        if (sessionId)
+          break;
+        // Simulate auto-attach behavior with real target info
+        const { targetInfo } = await this._extensionConnection!.send('attachToTab');
+        this._connectedTabInfo = {
+          targetInfo,
+          sessionId: `pw-tab-${this._nextSessionId++}`,
+        };
+        debugLogger('Simulating auto-attach');
+        this._sendToPlaywright({
+          method: 'Target.attachedToTarget',
+          params: {
+            sessionId: this._connectedTabInfo.sessionId,
+            targetInfo: {
+              ...this._connectedTabInfo.targetInfo,
+              attached: true,
+            },
+            waitingForDebugger: false
+          }
+        });
+        return { };
+      }
+      case 'Target.getTargetInfo': {
+        return this._connectedTabInfo?.targetInfo;
+      }
+    }
+    return await this._forwardToExtension(method, params, sessionId);
+  }
+
+  private async _forwardToExtension(method: string, params: any, sessionId: string | undefined): Promise<any> {
+    if (!this._extensionConnection)
+      throw new Error('Extension not connected');
+    // Top level sessionId is only passed between the relay and the client.
+    if (this._connectedTabInfo?.sessionId === sessionId)
+      sessionId = undefined;
+    return await this._extensionConnection.send('forwardCDPCommand', { sessionId, method, params });
+  }
+
  private _sendToPlaywright(message: CDPResponse): void {
    debugLogger('→ Playwright:', `${message.method ?? `response(id=${message.id})`}`);
    this._playwrightConnection?.send(JSON.stringify(message));
@@ -284,44 +302,64 @@ export class CDPRelayServer {

 class ExtensionContextFactory implements BrowserContextFactory {
  private _relay: CDPRelayServer;
-  private _browserPromise: Promise<Browser> | undefined;
+  private _browserPromise: Promise<playwright.Browser> | undefined;

  constructor(relay: CDPRelayServer) {
    this._relay = relay;
  }

-  async createContext(clientInfo: { name: string, version: string }): Promise<{ browserContext: BrowserContext, close: () => Promise<void> }> {
+  async createContext(clientInfo: { name: string, version: string }): Promise<{ browserContext: playwright.BrowserContext, close: () => Promise<void> }> {
    // First call will establish the connection to the extension.
    if (!this._browserPromise)
      this._browserPromise = this._obtainBrowser(clientInfo);
    const browser = await this._browserPromise;
    return {
      browserContext: browser.contexts()[0],
-      close: async () => {}
+      close: async () => {
+        debugLogger('close() called for browser context, ignoring');
+      }
    };
  }

-  private async _obtainBrowser(clientInfo: { name: string, version: string }): Promise<Browser> {
+  clientDisconnected() {
+    this._relay.closeConnections('MCP client disconnected');
+    this._browserPromise = undefined;
+  }
+
+  private async _obtainBrowser(clientInfo: { name: string, version: string }): Promise<playwright.Browser> {
    await this._relay.ensureExtensionConnectionForMCPContext(clientInfo);
-    return await chromium.connectOverCDP(this._relay.cdpEndpoint());
+    const browser = await playwright.chromium.connectOverCDP(this._relay.cdpEndpoint());
+    browser.on('disconnected', () => {
+      this._browserPromise = undefined;
+      debugLogger('Browser disconnected');
+    });
+    return browser;
  }
 }

-export async function startCDPRelayServer(port: number) {
-  const httpServer = await startHttpServer({ port });
-  const cdpRelayServer = new CDPRelayServer(httpServer);
-  process.on('exit', () => cdpRelayServer.stop());
+export async function startCDPRelayServer(browserChannel: string, abortController: AbortController) {
+  const httpServer = await startHttpServer({});
+  const cdpRelayServer = new CDPRelayServer(httpServer, browserChannel);
+  abortController.signal.addEventListener('abort', () => cdpRelayServer.stop());
  debugLogger(`CDP relay server started, extension endpoint: ${cdpRelayServer.extensionEndpoint()}.`);
  return new ExtensionContextFactory(cdpRelayServer);
 }

+type ExtensionResponse = {
+  id?: number;
+  method?: string;
+  params?: any;
+  result?: any;
+  error?: string;
+};
+
 class ExtensionConnection {
  private readonly _ws: WebSocket;
-  private readonly _callbacks = new Map<number, { resolve: (o: any) => void, reject: (e: Error) => void }>();
+  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;
-  onclose?: (self: ExtensionConnection) => void;
+  onclose?: (self: ExtensionConnection, reason: string) => void;

  constructor(ws: WebSocket) {
    this._ws = ws;
@@ -332,18 +370,19 @@ class ExtensionConnection {

  async send(method: string, params?: any, sessionId?: string): Promise<any> {
    if (this._ws.readyState !== WebSocket.OPEN)
-      throw new Error('WebSocket closed');
+      throw new Error(`Unexpected WebSocket state: ${this._ws.readyState}`);
    const id = ++this._lastId;
    this._ws.send(JSON.stringify({ id, method, params, sessionId }));
+    const error = new Error(`Protocol error: ${method}`);
    return new Promise((resolve, reject) => {
-      this._callbacks.set(id, { resolve, reject });
+      this._callbacks.set(id, { resolve, reject, error });
    });
  }

-  close(message?: string) {
+  close(message: string) {
    debugLogger('closing extension connection:', message);
-    this._ws.close(1000, message ?? 'Connection closed');
-    this.onclose?.(this);
+    if (this._ws.readyState === WebSocket.OPEN)
+      this._ws.close(1000, message);
  }

  private _onMessage(event: websocket.RawData) {
@@ -364,24 +403,28 @@ class ExtensionConnection {
    }
  }

-  private _handleParsedMessage(object: any) {
+  private _handleParsedMessage(object: ExtensionResponse) {
    if (object.id && this._callbacks.has(object.id)) {
      const callback = this._callbacks.get(object.id)!;
      this._callbacks.delete(object.id);
-      if (object.error)
-        callback.reject(new Error(object.error.message));
-      else
+      if (object.error) {
+        const error = callback.error;
+        error.message = object.error;
+        callback.reject(error);
+      } else {
        callback.resolve(object.result);
+      }
    } else if (object.id) {
      debugLogger('← Extension: unexpected response', object);
    } else {
-      this.onmessage?.(object.method, object.params);
+      this.onmessage?.(object.method!, object.params);
    }
  }

  private _onClose(event: websocket.CloseEvent) {
    debugLogger(`<ws closed> code=${event.code} reason=${event.reason}`);
    this._dispose();
+    this.onclose?.(this, event.reason);
  }

  private _onError(event: websocket.ErrorEvent) {
--- a/src/extension/main.ts
+++ b/src/extension/main.ts
@@ -14,22 +14,26 @@
 * limitations under the License.
 */

-import { resolveCLIConfig } from '../config.js';
-import { startHttpServer, startHttpTransport, startStdioTransport } from '../transport.js';
-import { Server } from '../server.js';
 import { startCDPRelayServer } from './cdpRelay.js';
+import { BrowserServerBackend } from '../browserServerBackend.js';
+import * as mcpTransport from '../mcp/transport.js';

-export async function runWithExtension(options: any) {
-  const config = await resolveCLIConfig({ });
-  const contextFactory = await startCDPRelayServer(9225);
+import type { FullConfig } from '../config.js';

-  const server = new Server(config, contextFactory);
-  server.setupExitWatchdog();
+export async function runWithExtension(config: FullConfig, abortController: AbortController) {
+  const contextFactory = await startCDPRelayServer(config.browser.launchOptions.channel || 'chrome', abortController);

-  if (options.port !== undefined) {
-    const httpServer = await startHttpServer({ port: options.port });
-    startHttpTransport(httpServer, server);
-  } else {
-    await startStdioTransport(server);
-  }
+  let backend: BrowserServerBackend | undefined;
+  const serverBackendFactory = () => {
+    if (backend)
+      throw new Error('Another MCP client is still connected. Only one connection at a time is allowed.');
+    backend = new BrowserServerBackend(config, contextFactory);
+    backend.onclose = () => {
+      contextFactory.clientDisconnected();
+      backend = undefined;
+    };
+    return backend;
+  };
+
+  await mcpTransport.start(serverBackendFactory, config.server);
 }
--- a/src/httpServer.ts
+++ b/src/httpServer.ts
@@ -14,219 +14,31 @@
 * limitations under the License.
 */

-import fs from 'fs';
-import path from 'path';
+import assert from 'assert';
 import http from 'http';
-import net from 'net';

-import mime from 'mime';
+import type * as net from 'net';

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

-import { createConnection as createConnectionImpl } from './connection.js';
-import type { Connection } from '../index.js';
+import { BrowserServerBackend } from './browserServerBackend.js';
 import { resolveConfig } from './config.js';
 import { contextFactory } from './browserContextFactory.js';
+import * as mcpServer from './mcp/server.js';

 import type { Config } from '../config.js';
 import type { BrowserContext } from 'playwright';
 import type { BrowserContextFactory } from './browserContextFactory.js';
+import type { Server } from '@modelcontextprotocol/sdk/server/index.js';

-export async function createConnection(userConfig: Config = {}, contextGetter?: () => Promise<BrowserContext>): Promise<Connection> {
+export async function createConnection(userConfig: Config = {}, contextGetter?: () => Promise<BrowserContext>): Promise<Server> {
  const config = await resolveConfig(userConfig);
  const factory = contextGetter ? new SimpleBrowserContextFactory(contextGetter) : contextFactory(config.browser);
-  return createConnectionImpl(config, factory);
+  return mcpServer.createServer(new BrowserServerBackend(config, factory), false);
 }

 class SimpleBrowserContextFactory implements BrowserContextFactory {
--- a/src/loop/loop.ts
+++ b/src/loop/loop.ts
@@ -0,0 +1,108 @@
+/**
+ * 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 type { Tool, ImageContent, TextContent } from '@modelcontextprotocol/sdk/types.js';
+import type { Client } from '@modelcontextprotocol/sdk/client/index.js';
+
+export type LLMToolCall = {
+  name: string;
+  arguments: any;
+  id: string;
+};
+
+export type LLMTool = {
+  name: string;
+  description: string;
+  inputSchema: any;
+};
+
+export type LLMMessage =
+  | { role: 'user'; content: string }
+  | { role: 'assistant'; content: string; toolCalls?: LLMToolCall[] }
+  | { role: 'tool'; toolCallId: string; content: string; isError?: boolean };
+
+export type LLMConversation = {
+  messages: LLMMessage[];
+  tools: LLMTool[];
+};
+
+export interface LLMDelegate {
+  createConversation(task: string, tools: Tool[], oneShot: boolean): LLMConversation;
+  makeApiCall(conversation: LLMConversation): Promise<LLMToolCall[]>;
+  addToolResults(conversation: LLMConversation, results: Array<{ toolCallId: string; content: string; isError?: boolean }>): void;
+  checkDoneToolCall(toolCall: LLMToolCall): string | null;
+}
+
+export async function runTask(delegate: LLMDelegate, client: Client, task: string, oneShot: boolean = false): Promise<LLMMessage[]> {
+  const { tools } = await client.listTools();
+  const taskContent = oneShot ? `Perform following task: ${task}.` : `Perform following task: ${task}. Once the task is complete, call the "done" tool.`;
+  const conversation = delegate.createConversation(taskContent, tools, oneShot);
+
+  for (let iteration = 0; iteration < 5; ++iteration) {
+    debug('history')('Making API call for iteration', iteration);
+    const toolCalls = await delegate.makeApiCall(conversation);
+    if (toolCalls.length === 0)
+      throw new Error('Call the "done" tool when the task is complete.');
+
+    const toolResults: Array<{ toolCallId: string; content: string; isError?: boolean }> = [];
+    for (const toolCall of toolCalls) {
+      const doneResult = delegate.checkDoneToolCall(toolCall);
+      if (doneResult !== null)
+        return conversation.messages;
+
+      const { name, arguments: args, id } = toolCall;
+      try {
+        debug('tool')(name, args);
+        const response = await client.callTool({
+          name,
+          arguments: args,
+        });
+        const responseContent = (response.content || []) as (TextContent | ImageContent)[];
+        debug('tool')(responseContent);
+        const text = responseContent.filter(part => part.type === 'text').map(part => part.text).join('\n');
+
+        toolResults.push({
+          toolCallId: id,
+          content: text,
+        });
+      } catch (error) {
+        debug('tool')(error);
+        toolResults.push({
+          toolCallId: id,
+          content: `Error while executing tool "${name}": ${error instanceof Error ? error.message : String(error)}\n\nPlease try to recover and complete the task.`,
+          isError: true,
+        });
+
+        // Skip remaining tool calls for this iteration
+        for (const remainingToolCall of toolCalls.slice(toolCalls.indexOf(toolCall) + 1)) {
+          toolResults.push({
+            toolCallId: remainingToolCall.id,
+            content: `This tool call is skipped due to previous error.`,
+            isError: true,
+          });
+        }
+        break;
+      }
+    }
+
+    delegate.addToolResults(conversation, toolResults);
+    if (oneShot)
+      return conversation.messages;
+  }
+
+  throw new Error('Failed to perform step, max attempts reached');
+}
--- a/src/loop/loopClaude.ts
+++ b/src/loop/loopClaude.ts
@@ -0,0 +1,177 @@
+/**
+ * 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 type Anthropic from '@anthropic-ai/sdk';
+import type { LLMDelegate, LLMConversation, LLMToolCall, LLMTool } from './loop.js';
+import type { Tool } from '@modelcontextprotocol/sdk/types.js';
+
+const model = 'claude-sonnet-4-20250514';
+
+export class ClaudeDelegate implements LLMDelegate {
+  private _anthropic: Anthropic | undefined;
+
+  async anthropic(): Promise<Anthropic> {
+    if (!this._anthropic) {
+      const anthropic = await import('@anthropic-ai/sdk');
+      this._anthropic = new anthropic.Anthropic();
+    }
+    return this._anthropic;
+  }
+
+  createConversation(task: string, tools: Tool[], oneShot: boolean): LLMConversation {
+    const llmTools: LLMTool[] = tools.map(tool => ({
+      name: tool.name,
+      description: tool.description || '',
+      inputSchema: tool.inputSchema,
+    }));
+
+    if (!oneShot) {
+      llmTools.push({
+        name: 'done',
+        description: 'Call this tool when the task is complete.',
+        inputSchema: {
+          type: 'object',
+          properties: {},
+        },
+      });
+    }
+
+    return {
+      messages: [{
+        role: 'user',
+        content: task
+      }],
+      tools: llmTools,
+    };
+  }
+
+  async makeApiCall(conversation: LLMConversation): Promise<LLMToolCall[]> {
+    // Convert generic messages to Claude format
+    const claudeMessages: Anthropic.Messages.MessageParam[] = [];
+
+    for (const message of conversation.messages) {
+      if (message.role === 'user') {
+        claudeMessages.push({
+          role: 'user',
+          content: message.content
+        });
+      } else if (message.role === 'assistant') {
+        const content: Anthropic.Messages.ContentBlock[] = [];
+
+        // Add text content
+        if (message.content) {
+          content.push({
+            type: 'text',
+            text: message.content,
+            citations: []
+          });
+        }
+
+        // Add tool calls
+        if (message.toolCalls) {
+          for (const toolCall of message.toolCalls) {
+            content.push({
+              type: 'tool_use',
+              id: toolCall.id,
+              name: toolCall.name,
+              input: toolCall.arguments
+            });
+          }
+        }
+
+        claudeMessages.push({
+          role: 'assistant',
+          content
+        });
+      } else if (message.role === 'tool') {
+        // Tool results are added differently - we need to find if there's already a user message with tool results
+        const lastMessage = claudeMessages[claudeMessages.length - 1];
+        const toolResult: Anthropic.Messages.ToolResultBlockParam = {
+          type: 'tool_result',
+          tool_use_id: message.toolCallId,
+          content: message.content,
+          is_error: message.isError,
+        };
+
+        if (lastMessage && lastMessage.role === 'user' && Array.isArray(lastMessage.content)) {
+          // Add to existing tool results message
+          (lastMessage.content as Anthropic.Messages.ToolResultBlockParam[]).push(toolResult);
+        } else {
+          // Create new tool results message
+          claudeMessages.push({
+            role: 'user',
+            content: [toolResult]
+          });
+        }
+      }
+    }
+
+    // Convert generic tools to Claude format
+    const claudeTools: Anthropic.Messages.Tool[] = conversation.tools.map(tool => ({
+      name: tool.name,
+      description: tool.description,
+      input_schema: tool.inputSchema,
+    }));
+
+    const anthropic = await this.anthropic();
+    const response = await anthropic.messages.create({
+      model,
+      max_tokens: 10000,
+      messages: claudeMessages,
+      tools: claudeTools,
+    });
+
+    // Extract tool calls and add assistant message to generic conversation
+    const toolCalls = response.content.filter(block => block.type === 'tool_use') as Anthropic.Messages.ToolUseBlock[];
+    const textContent = response.content.filter(block => block.type === 'text').map(block => (block as Anthropic.Messages.TextBlock).text).join('');
+
+    const llmToolCalls: LLMToolCall[] = toolCalls.map(toolCall => ({
+      name: toolCall.name,
+      arguments: toolCall.input as any,
+      id: toolCall.id,
+    }));
+
+    // Add assistant message to generic conversation
+    conversation.messages.push({
+      role: 'assistant',
+      content: textContent,
+      toolCalls: llmToolCalls.length > 0 ? llmToolCalls : undefined
+    });
+
+    return llmToolCalls;
+  }
+
+  addToolResults(
+    conversation: LLMConversation,
+    results: Array<{ toolCallId: string; content: string; isError?: boolean }>
+  ): void {
+    for (const result of results) {
+      conversation.messages.push({
+        role: 'tool',
+        toolCallId: result.toolCallId,
+        content: result.content,
+        isError: result.isError,
+      });
+    }
+  }
+
+  checkDoneToolCall(toolCall: LLMToolCall): string | null {
+    if (toolCall.name === 'done')
+      return (toolCall.arguments as { result: string }).result;
+
+    return null;
+  }
+}
--- a/src/loop/loopOpenAI.ts
+++ b/src/loop/loopOpenAI.ts
@@ -0,0 +1,168 @@
+/**
+ * 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 type OpenAI from 'openai';
+import type { LLMDelegate, LLMConversation, LLMToolCall, LLMTool } from './loop.js';
+import type { Tool } from '@modelcontextprotocol/sdk/types.js';
+
+const model = 'gpt-4.1';
+
+export class OpenAIDelegate implements LLMDelegate {
+  private _openai: OpenAI | undefined;
+
+  async openai(): Promise<OpenAI> {
+    if (!this._openai) {
+      const oai = await import('openai');
+      this._openai = new oai.OpenAI();
+    }
+    return this._openai;
+  }
+
+  createConversation(task: string, tools: Tool[], oneShot: boolean): LLMConversation {
+    const genericTools: LLMTool[] = tools.map(tool => ({
+      name: tool.name,
+      description: tool.description || '',
+      inputSchema: tool.inputSchema,
+    }));
+
+    if (!oneShot) {
+      genericTools.push({
+        name: 'done',
+        description: 'Call this tool when the task is complete.',
+        inputSchema: {
+          type: 'object',
+          properties: {},
+        },
+      });
+    }
+
+    return {
+      messages: [{
+        role: 'user',
+        content: task
+      }],
+      tools: genericTools,
+    };
+  }
+
+  async makeApiCall(conversation: LLMConversation): Promise<LLMToolCall[]> {
+    // Convert generic messages to OpenAI format
+    const openaiMessages: OpenAI.Chat.Completions.ChatCompletionMessageParam[] = [];
+
+    for (const message of conversation.messages) {
+      if (message.role === 'user') {
+        openaiMessages.push({
+          role: 'user',
+          content: message.content
+        });
+      } else if (message.role === 'assistant') {
+        const toolCalls: OpenAI.Chat.Completions.ChatCompletionMessageToolCall[] = [];
+
+        if (message.toolCalls) {
+          for (const toolCall of message.toolCalls) {
+            toolCalls.push({
+              id: toolCall.id,
+              type: 'function',
+              function: {
+                name: toolCall.name,
+                arguments: JSON.stringify(toolCall.arguments)
+              }
+            });
+          }
+        }
+
+        const assistantMessage: OpenAI.Chat.Completions.ChatCompletionAssistantMessageParam = {
+          role: 'assistant'
+        };
+
+        if (message.content)
+          assistantMessage.content = message.content;
+
+        if (toolCalls.length > 0)
+          assistantMessage.tool_calls = toolCalls;
+
+        openaiMessages.push(assistantMessage);
+      } else if (message.role === 'tool') {
+        openaiMessages.push({
+          role: 'tool',
+          tool_call_id: message.toolCallId,
+          content: message.content,
+        });
+      }
+    }
+
+    // Convert generic tools to OpenAI format
+    const openaiTools: OpenAI.Chat.Completions.ChatCompletionTool[] = conversation.tools.map(tool => ({
+      type: 'function',
+      function: {
+        name: tool.name,
+        description: tool.description,
+        parameters: tool.inputSchema,
+      },
+    }));
+
+    const openai = await this.openai();
+    const response = await openai.chat.completions.create({
+      model,
+      messages: openaiMessages,
+      tools: openaiTools,
+      tool_choice: 'auto'
+    });
+
+    const message = response.choices[0].message;
+
+    // Extract tool calls and add assistant message to generic conversation
+    const toolCalls = message.tool_calls || [];
+    const genericToolCalls: LLMToolCall[] = toolCalls.map(toolCall => {
+      const functionCall = toolCall.function;
+      return {
+        name: functionCall.name,
+        arguments: JSON.parse(functionCall.arguments),
+        id: toolCall.id,
+      };
+    });
+
+    // Add assistant message to generic conversation
+    conversation.messages.push({
+      role: 'assistant',
+      content: message.content || '',
+      toolCalls: genericToolCalls.length > 0 ? genericToolCalls : undefined
+    });
+
+    return genericToolCalls;
+  }
+
+  addToolResults(
+    conversation: LLMConversation,
+    results: Array<{ toolCallId: string; content: string; isError?: boolean }>
+  ): void {
+    for (const result of results) {
+      conversation.messages.push({
+        role: 'tool',
+        toolCallId: result.toolCallId,
+        content: result.content,
+        isError: result.isError,
+      });
+    }
+  }
+
+  checkDoneToolCall(toolCall: LLMToolCall): string | null {
+    if (toolCall.name === 'done')
+      return toolCall.arguments.result;
+
+    return null;
+  }
+}
--- a/src/loop/main.ts
+++ b/src/loop/main.ts
@@ -0,0 +1,72 @@
+/**
+ * Copyright (c) Microsoft Corporation.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+/* eslint-disable no-console */
+
+import path from 'path';
+import url from 'url';
+import dotenv from 'dotenv';
+
+import { StdioClientTransport } from '@modelcontextprotocol/sdk/client/stdio.js';
+import { Client } from '@modelcontextprotocol/sdk/client/index.js';
+import { program } from 'commander';
+import { OpenAIDelegate } from './loopOpenAI.js';
+import { ClaudeDelegate } from './loopClaude.js';
+import { runTask } from './loop.js';
+
+import type { LLMDelegate } from './loop.js';
+
+dotenv.config();
+
+const __filename = url.fileURLToPath(import.meta.url);
+
+async function run(delegate: LLMDelegate) {
+  const transport = new StdioClientTransport({
+    command: 'node',
+    args: [
+      path.resolve(__filename, '../../../cli.js'),
+      '--save-session',
+      '--output-dir', path.resolve(__filename, '../../../sessions')
+    ],
+    stderr: 'inherit',
+    env: process.env as Record<string, string>,
+  });
+
+  const client = new Client({ name: 'test', version: '1.0.0' });
+  await client.connect(transport);
+  await client.ping();
+
+  for (const task of tasks) {
+    const messages = await runTask(delegate, client, task);
+    for (const message of messages)
+      console.log(`${message.role}: ${message.content}`);
+  }
+  await client.close();
+}
+
+const tasks = [
+  'Open https://playwright.dev/',
+];
+
+program
+    .option('--model <model>', 'model to use')
+    .action(async options => {
+      if (options.model === 'claude')
+        await run(new ClaudeDelegate());
+      else
+        await run(new OpenAIDelegate());
+    });
+void program.parseAsync(process.argv);
--- a/src/loopTools/context.ts
+++ b/src/loopTools/context.ts
@@ -0,0 +1,77 @@
+/**
+ * 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 { Client } from '@modelcontextprotocol/sdk/client/index.js';
+import { contextFactory } from '../browserContextFactory.js';
+import { BrowserServerBackend } from '../browserServerBackend.js';
+import { Context as BrowserContext } from '../context.js';
+import { runTask } from '../loop/loop.js';
+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 type { LLMDelegate } from '../loop/loop.js';
+import type { FullConfig } from '../config.js';
+
+export class Context {
+  readonly config: FullConfig;
+  private _client: Client;
+  private _delegate: LLMDelegate;
+
+  constructor(config: FullConfig, client: Client) {
+    this.config = config;
+    this._client = client;
+    if (process.env.OPENAI_API_KEY)
+      this._delegate = new OpenAIDelegate();
+    else if (process.env.ANTHROPIC_API_KEY)
+      this._delegate = new ClaudeDelegate();
+    else
+      throw new Error('No LLM API key found. Please set OPENAI_API_KEY or ANTHROPIC_API_KEY environment variable.');
+  }
+
+  static async create(config: FullConfig) {
+    const client = new Client({ name: 'Playwright Proxy', version: '1.0.0' });
+    const browserContextFactory = contextFactory(config.browser);
+    const server = mcpServer.createServer(new BrowserServerBackend(config, browserContextFactory), false);
+    await client.connect(new InProcessTransport(server));
+    await client.ping();
+    return new Context(config, client);
+  }
+
+  async runTask(task: string, oneShot: boolean = false): Promise<mcpServer.ToolResponse> {
+    const messages = await runTask(this._delegate, this._client!, task, oneShot);
+    const lines: string[] = [];
+
+    // Skip the first message, which is the user's task.
+    for (const message of messages.slice(1)) {
+      // Trim out all page snapshots.
+      if (!message.content.trim())
+        continue;
+      const index = oneShot ? -1 : message.content.indexOf('### Page state');
+      const trimmedContent = index === -1 ? message.content : message.content.substring(0, index);
+      lines.push(`[${message.role}]:`, trimmedContent);
+    }
+
+    return {
+      content: [{ type: 'text', text: lines.join('\n') }],
+    };
+  }
+
+  async close() {
+    await BrowserContext.disposeAll();
+  }
+}
--- a/src/loopTools/main.ts
+++ b/src/loopTools/main.ts
@@ -0,0 +1,63 @@
+/**
+ * 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 dotenv from 'dotenv';
+
+import * as mcpServer from '../mcp/server.js';
+import * as mcpTransport from '../mcp/transport.js';
+import { packageJSON } from '../package.js';
+import { Context } from './context.js';
+import { perform } from './perform.js';
+import { snapshot } from './snapshot.js';
+
+import type { FullConfig } from '../config.js';
+import type { ServerBackend } from '../mcp/server.js';
+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);
+}
+
+class LoopToolsServerBackend implements ServerBackend {
+  readonly name = 'Playwright';
+  readonly version = packageJSON.version;
+  private _config: FullConfig;
+  private _context: Context | undefined;
+  private _tools: Tool<any>[] = [perform, snapshot];
+
+  constructor(config: FullConfig) {
+    this._config = config;
+  }
+
+  async initialize() {
+    this._context = await Context.create(this._config);
+  }
+
+  tools(): mcpServer.ToolSchema<any>[] {
+    return this._tools.map(tool => tool.schema);
+  }
+
+  async callTool(schema: mcpServer.ToolSchema<any>, parsedArguments: any): Promise<mcpServer.ToolResponse> {
+    const tool = this._tools.find(tool => tool.schema.name === schema.name)!;
+    return await tool.handle(this._context!, parsedArguments);
+  }
+
+  serverClosed() {
+    void this._context!.close();
+  }
+}
--- a/src/loopTools/perform.ts
+++ b/src/loopTools/perform.ts
@@ -0,0 +1,36 @@
+/**
+ * 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 { defineTool } from './tool.js';
+
+const performSchema = z.object({
+  task: z.string().describe('The task to perform with the browser'),
+});
+
+export const perform = defineTool({
+  schema: {
+    name: 'browser_perform',
+    title: 'Perform a task with the browser',
+    description: 'Perform a task with the browser. It can click, type, export, capture screenshot, drag, hover, select options, etc.',
+    inputSchema: performSchema,
+    type: 'destructive',
+  },
+
+  handle: async (context, params) => {
+    return await context.runTask(params.task);
+  },
+});
--- a/src/loopTools/snapshot.ts
+++ b/src/loopTools/snapshot.ts
@@ -0,0 +1,32 @@
+/**
+ * Copyright (c) Microsoft Corporation.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+import { z } from 'zod';
+import { defineTool } from './tool.js';
+
+export const snapshot = defineTool({
+  schema: {
+    name: 'browser_snapshot',
+    title: 'Take a snapshot of the browser',
+    description: 'Take a snapshot of the browser to read what is on the page.',
+    inputSchema: z.object({}),
+    type: 'readOnly',
+  },
+
+  handle: async (context, params) => {
+    return await context.runTask('Capture browser snapshot', true);
+  },
+});
--- a/src/loopTools/tool.ts
+++ b/src/loopTools/tool.ts
@@ -0,0 +1,29 @@
+/**
+ * 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 type { z } from 'zod';
+import type * as mcpServer from '../mcp/server.js';
+import type { Context } from './context.js';
+
+
+export type Tool<Input extends z.Schema = z.Schema> = {
+  schema: mcpServer.ToolSchema<Input>;
+  handle: (context: Context, params: z.output<Input>) => Promise<mcpServer.ToolResponse>;
+};
+
+export function defineTool<Input extends z.Schema>(tool: Tool<Input>): Tool<Input> {
+  return tool;
+}
--- a/src/mcp/README.md
+++ b/src/mcp/README.md
@@ -0,0 +1 @@
+- Generic MCP utils, no dependencies on Playwright here.
--- a/src/mcp/inProcessTransport.ts
+++ b/src/mcp/inProcessTransport.ts
@@ -0,0 +1,92 @@
+/**
+ * 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 type { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import type { Transport, TransportSendOptions } from '@modelcontextprotocol/sdk/shared/transport.js';
+import type { JSONRPCMessage, MessageExtraInfo } from '@modelcontextprotocol/sdk/types.js';
+
+export class InProcessTransport implements Transport {
+  private _server: Server;
+  private _serverTransport: InProcessServerTransport;
+  private _connected: boolean = false;
+
+  constructor(server: Server) {
+    this._server = server;
+    this._serverTransport = new InProcessServerTransport(this);
+  }
+
+  async start(): Promise<void> {
+    if (this._connected)
+      throw new Error('InprocessTransport already started!');
+
+    await this._server.connect(this._serverTransport);
+    this._connected = true;
+  }
+
+  async send(message: JSONRPCMessage, options?: TransportSendOptions): Promise<void> {
+    if (!this._connected)
+      throw new Error('Transport not connected');
+
+
+    this._serverTransport._receiveFromClient(message);
+  }
+
+  async close(): Promise<void> {
+    if (this._connected) {
+      this._connected = false;
+      this.onclose?.();
+      this._serverTransport.onclose?.();
+    }
+  }
+
+  onclose?: (() => void) | undefined;
+  onerror?: ((error: Error) => void) | undefined;
+  onmessage?: ((message: JSONRPCMessage, extra?: MessageExtraInfo) => void) | undefined;
+  sessionId?: string | undefined;
+  setProtocolVersion?: ((version: string) => void) | undefined;
+
+  _receiveFromServer(message: JSONRPCMessage, extra?: MessageExtraInfo): void {
+    this.onmessage?.(message, extra);
+  }
+}
+
+class InProcessServerTransport implements Transport {
+  private _clientTransport: InProcessTransport;
+
+  constructor(clientTransport: InProcessTransport) {
+    this._clientTransport = clientTransport;
+  }
+
+  async start(): Promise<void> {
+  }
+
+  async send(message: JSONRPCMessage, options?: TransportSendOptions): Promise<void> {
+    this._clientTransport._receiveFromServer(message);
+  }
+
+  async close(): Promise<void> {
+    this.onclose?.();
+  }
+
+  onclose?: (() => void) | undefined;
+  onerror?: ((error: Error) => void) | undefined;
+  onmessage?: ((message: JSONRPCMessage, extra?: MessageExtraInfo) => void) | undefined;
+  sessionId?: string | undefined;
+  setProtocolVersion?: ((version: string) => void) | undefined;
+  _receiveFromClient(message: JSONRPCMessage): void {
+    this.onmessage?.(message);
+  }
+}
--- a/src/mcp/server.ts
+++ b/src/mcp/server.ts
@@ -0,0 +1,131 @@
+/**
+ * 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 { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { CallToolRequestSchema, ListToolsRequestSchema } from '@modelcontextprotocol/sdk/types.js';
+import { zodToJsonSchema } from 'zod-to-json-schema';
+
+import type { ImageContent, Implementation, TextContent } from '@modelcontextprotocol/sdk/types.js';
+import type { Transport } from '@modelcontextprotocol/sdk/shared/transport.js';
+
+export type ClientVersion = Implementation;
+
+export type ToolResponse = {
+  content: (TextContent | ImageContent)[];
+  isError?: boolean;
+};
+
+export type ToolSchema<Input extends z.Schema> = {
+  name: string;
+  title: string;
+  description: string;
+  inputSchema: Input;
+  type: 'readOnly' | 'destructive';
+};
+
+export type ToolHandler = (toolName: string, params: any) => Promise<ToolResponse>;
+
+export interface ServerBackend {
+  name: string;
+  version: string;
+  initialize?(): Promise<void>;
+  tools(): ToolSchema<any>[];
+  callTool(schema: ToolSchema<any>, parsedArguments: any): Promise<ToolResponse>;
+  serverInitialized?(version: ClientVersion | undefined): void;
+  serverClosed?(): void;
+}
+
+export type ServerBackendFactory = () => ServerBackend;
+
+export async function connect(serverBackendFactory: ServerBackendFactory, transport: Transport, runHeartbeat: boolean) {
+  const backend = serverBackendFactory();
+  await backend.initialize?.();
+  const server = createServer(backend, runHeartbeat);
+  await server.connect(transport);
+}
+
+export function createServer(backend: ServerBackend, runHeartbeat: boolean): Server {
+  const server = new Server({ name: backend.name, version: backend.version }, {
+    capabilities: {
+      tools: {},
+    }
+  });
+
+  const tools = backend.tools();
+  server.setRequestHandler(ListToolsRequestSchema, async () => {
+    return { tools: tools.map(tool => ({
+      name: tool.name,
+      description: tool.description,
+      inputSchema: zodToJsonSchema(tool.inputSchema),
+      annotations: {
+        title: tool.title,
+        readOnlyHint: tool.type === 'readOnly',
+        destructiveHint: tool.type === 'destructive',
+        openWorldHint: true,
+      },
+    })) };
+  });
+
+  let heartbeatRunning = false;
+  server.setRequestHandler(CallToolRequestSchema, async request => {
+    if (runHeartbeat && !heartbeatRunning) {
+      heartbeatRunning = true;
+      startHeartbeat(server);
+    }
+
+    const errorResult = (...messages: string[]) => ({
+      content: [{ type: 'text', text: messages.join('\n') }],
+      isError: true,
+    });
+    const tool = tools.find(tool => tool.name === request.params.name) as ToolSchema<any>;
+    if (!tool)
+      return errorResult(`Tool "${request.params.name}" not found`);
+
+    try {
+      return await backend.callTool(tool, tool.inputSchema.parse(request.params.arguments || {}));
+    } catch (error) {
+      return errorResult(String(error));
+    }
+  });
+
+  addServerListener(server, 'initialized', () => backend.serverInitialized?.(server.getClientVersion()));
+  addServerListener(server, 'close', () => backend.serverClosed?.());
+  return server;
+}
+
+const startHeartbeat = (server: Server) => {
+  const beat = () => {
+    Promise.race([
+      server.ping(),
+      new Promise((_, reject) => setTimeout(() => reject(new Error('ping timeout')), 5000)),
+    ]).then(() => {
+      setTimeout(beat, 3000);
+    }).catch(() => {
+      void server.close();
+    });
+  };
+
+  beat();
+};
+
+function addServerListener(server: Server, event: 'close' | 'initialized', listener: () => void) {
+  const oldListener = server[`on${event}`];
+  server[`on${event}`] = () => {
+    oldListener?.();
+    listener();
+  };
+}
--- a/src/mcp/transport.ts
+++ b/src/mcp/transport.ts
@@ -14,28 +14,34 @@
 * limitations under the License.
 */

-import http from 'node:http';
-import assert from 'node:assert';
-import crypto from 'node:crypto';
-
+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 '../httpServer.js';
+import * as mcpServer from './server.js';

-import { logUnhandledError } from './log.js';
+import type { ServerBackendFactory } from './server.js';

-import type { AddressInfo } from 'node:net';
-import type { Server } from './server.js';
-import type { Connection } from './connection.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);
+  }
+}

-export async function startStdioTransport(server: Server) {
-  await server.createConnection(new StdioServerTransport());
+async function startStdioTransport(serverBackendFactory: ServerBackendFactory) {
+  await mcpServer.connect(serverBackendFactory, new StdioServerTransport(), false);
 }

 const testDebug = debug('pw:mcp:test');

-async function handleSSE(server: Server, req: http.IncomingMessage, res: http.ServerResponse, url: URL, sessions: Map<string, SSEServerTransport>) {
+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');
    if (!sessionId) {
@@ -54,11 +60,10 @@ async function handleSSE(server: Server, req: http.IncomingMessage, res: http.Se
    const transport = new SSEServerTransport('/sse', res);
    sessions.set(transport.sessionId, transport);
    testDebug(`create SSE session: ${transport.sessionId}`);
-    const connection = await server.createConnection(transport);
+    await mcpServer.connect(serverBackendFactory, transport, false);
    res.on('close', () => {
      testDebug(`delete SSE session: ${transport.sessionId}`);
      sessions.delete(transport.sessionId);
-      void connection.close().catch(logUnhandledError);
    });
    return;
  }
@@ -67,10 +72,10 @@ async function handleSSE(server: Server, req: http.IncomingMessage, res: http.Se
  res.end('Method not allowed');
 }

-async function handleStreamable(server: Server, req: http.IncomingMessage, res: http.ServerResponse, sessions: Map<string, { transport: StreamableHTTPServerTransport, connection: Connection }>) {
+async function handleStreamable(serverBackendFactory: ServerBackendFactory, req: http.IncomingMessage, res: http.ServerResponse, sessions: Map<string, StreamableHTTPServerTransport>) {
  const sessionId = req.headers['mcp-session-id'] as string | undefined;
  if (sessionId) {
-    const { transport } = sessions.get(sessionId) ?? {};
+    const transport = sessions.get(sessionId);
    if (!transport) {
      res.statusCode = 404;
      res.end('Session not found');
@@ -84,18 +89,16 @@ async function handleStreamable(server: Server, req: http.IncomingMessage, res:
      sessionIdGenerator: () => crypto.randomUUID(),
      onsessioninitialized: async sessionId => {
        testDebug(`create http session: ${transport.sessionId}`);
-        const connection = await server.createConnection(transport);
-        sessions.set(sessionId, { transport, connection });
+        await mcpServer.connect(serverBackendFactory, transport, true);
+        sessions.set(sessionId, transport);
      }
    });

    transport.onclose = () => {
-      const result = transport.sessionId ? sessions.get(transport.sessionId) : undefined;
-      if (!result)
+      if (!transport.sessionId)
        return;
-      sessions.delete(result.transport.sessionId!);
+      sessions.delete(transport.sessionId);
      testDebug(`delete http session: ${transport.sessionId}`);
-      result.connection.close().catch(logUnhandledError);
    };

    await transport.handleRequest(req, res);
@@ -106,28 +109,15 @@ async function handleStreamable(server: Server, req: http.IncomingMessage, res:
  res.end('Invalid request');
 }

-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 startHttpTransport(httpServer: http.Server, mcpServer: Server) {
-  const sseSessions = new Map<string, SSEServerTransport>();
+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(mcpServer, req, res, url, sseSessions);
+      await handleSSE(serverBackendFactory, req, res, url, sseSessions);
    else
-      await handleStreamable(mcpServer, req, res, streamableSessions);
+      await handleStreamable(serverBackendFactory, req, res, streamableSessions);
  });
  const url = httpAddressToString(httpServer.address());
  const message = [
@@ -145,14 +135,3 @@ export function startHttpTransport(httpServer: http.Server, mcpServer: Server) {
    // eslint-disable-next-line no-console
  console.error(message);
 }
-
-export function httpAddressToString(address: string | 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}`;
-}
--- a/src/package.ts
+++ b/src/package.ts
@@ -14,9 +14,9 @@
 * limitations under the License.
 */

-import fs from 'node:fs';
-import url from 'node:url';
-import path from 'node:path';
+import fs from 'fs';
+import path from 'path';
+import url from 'url';

 const __filename = url.fileURLToPath(import.meta.url);
 export const packageJSON = JSON.parse(fs.readFileSync(path.join(path.dirname(__filename), '..', 'package.json'), 'utf8'));
--- a/src/pageSnapshot.ts
+++ b/src/pageSnapshot.ts
@@ -1,55 +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 * as playwright from 'playwright';
-import { callOnPageNoTrace } from './tools/utils.js';
-
-type PageEx = playwright.Page & {
-  _snapshotForAI: () => Promise<string>;
-};
-
-export class PageSnapshot {
-  private _page: playwright.Page;
-  private _text!: string;
-
-  constructor(page: playwright.Page) {
-    this._page = page;
-  }
-
-  static async create(page: playwright.Page): Promise<PageSnapshot> {
-    const snapshot = new PageSnapshot(page);
-    await snapshot._build();
-    return snapshot;
-  }
-
-  text(): string {
-    return this._text;
-  }
-
-  private async _build() {
-    const snapshot = await callOnPageNoTrace(this._page, page => (page as PageEx)._snapshotForAI());
-    this._text = [
-      `- Page Snapshot:`,
-      '```yaml',
-      snapshot,
-      '```',
-    ].join('\n');
-  }
-
-  refLocator(params: { element: string, ref: string }): playwright.Locator {
-    return this._page.locator(`aria-ref=${params.ref}`).describe(params.element);
-  }
-}
--- a/src/program.ts
+++ b/src/program.ts
@@ -18,11 +18,14 @@ import { program, Option } from 'commander';
 // @ts-ignore
 import { startTraceViewerServer } from 'playwright-core/lib/server';

-import { startHttpServer, startHttpTransport, startStdioTransport } from './transport.js';
+import * as mcpTransport from './mcp/transport.js';
 import { commaSeparatedList, resolveCLIConfig, semicolonSeparatedList } from './config.js';
-import { Server } from './server.js';
 import { packageJSON } from './package.js';
 import { runWithExtension } from './extension/main.js';
+import { BrowserServerBackend } from './browserServerBackend.js';
+import { Context } from './context.js';
+import { contextFactory } from './browserContextFactory.js';
+import { runLoopTools } from './loopTools/main.js';

 program
    .version('Version ' + packageJSON.version)
@@ -46,18 +49,17 @@ program
    .option('--port <port>', 'port to listen on for SSE transport.')
    .option('--proxy-bypass <bypass>', 'comma-separated domains to bypass proxy, for example ".com,chromium.org,.domain.com"')
    .option('--proxy-server <proxy>', 'specify proxy server, for example "http://myproxy:3128" or "socks5://myproxy:8080"')
+    .option('--save-session', 'Whether to save the Playwright MCP session into the output directory.')
    .option('--save-trace', 'Whether to save the Playwright Trace of the session into the output directory.')
    .option('--storage-state <path>', 'path to the storage state file for isolated sessions.')
    .option('--user-agent <ua string>', 'specify user agent string')
    .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('--extension', 'Connect to a running browser instance (Edge/Chrome only). Requires the "Playwright MCP Bridge" browser extension to be installed.').hideHelp())
+    .addOption(new Option('--loop-tools', 'Run loop tools').hideHelp())
    .addOption(new Option('--vision', 'Legacy option, use --caps=vision instead').hideHelp())
    .action(async options => {
-      if (options.extension) {
-        await runWithExtension(options);
-        return;
-      }
+      const abortController = setupExitWatchdog();

      if (options.vision) {
        // eslint-disable-next-line no-console
@@ -66,15 +68,18 @@ program
      }
      const config = await resolveCLIConfig(options);

-      const server = new Server(config);
-      server.setupExitWatchdog();
-
-      if (config.server.port !== undefined) {
-        const httpServer = await startHttpServer(config.server);
-        startHttpTransport(httpServer, server);
-      } else {
-        await startStdioTransport(server);
+      if (options.extension) {
+        await runWithExtension(config, abortController);
+        return;
      }
+      if (options.loopTools) {
+        await runLoopTools(config);
+        return;
+      }
+
+      const browserContextFactory = contextFactory(config.browser);
+      const serverBackendFactory = () => new BrowserServerBackend(config, browserContextFactory);
+      await mcpTransport.start(serverBackendFactory, config.server);

      if (config.saveTrace) {
        const server = await startTraceViewerServer();
@@ -85,4 +90,25 @@ program
      }
    });

+function setupExitWatchdog() {
+  const abortController = new AbortController();
+
+  let isExiting = false;
+  const handleExit = async () => {
+    if (isExiting)
+      return;
+    isExiting = true;
+    setTimeout(() => process.exit(0), 15000);
+    abortController.abort('Process exiting');
+    await Context.disposeAll();
+    process.exit(0);
+  };
+
+  process.stdin.on('close', handleExit);
+  process.on('SIGINT', handleExit);
+  process.on('SIGTERM', handleExit);
+
+  return abortController;
+}
+
 void program.parseAsync(process.argv);
--- a/src/response.ts
+++ b/src/response.ts
@@ -0,0 +1,121 @@
+/**
+ * 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 type  { ImageContent, TextContent } from '@modelcontextprotocol/sdk/types.js';
+import type { Context } from './context.js';
+
+export class Response {
+  private _result: string[] = [];
+  private _code: string[] = [];
+  private _images: { contentType: string, data: Buffer }[] = [];
+  private _context: Context;
+  private _includeSnapshot = false;
+  private _includeTabs = false;
+  private _snapshot: string | undefined;
+
+  readonly toolName: string;
+  readonly toolArgs: Record<string, any>;
+
+  constructor(context: Context, toolName: string, toolArgs: Record<string, any>) {
+    this._context = context;
+    this.toolName = toolName;
+    this.toolArgs = toolArgs;
+  }
+
+  addResult(result: string) {
+    this._result.push(result);
+  }
+
+  result() {
+    return this._result.join('\n');
+  }
+
+  addCode(code: string) {
+    this._code.push(code);
+  }
+
+  code() {
+    return this._code.join('\n');
+  }
+
+  addImage(image: { contentType: string, data: Buffer }) {
+    this._images.push(image);
+  }
+
+  images() {
+    return this._images;
+  }
+
+  setIncludeSnapshot() {
+    this._includeSnapshot = true;
+  }
+
+  setIncludeTabs() {
+    this._includeTabs = true;
+  }
+
+  async snapshot(): Promise<string> {
+    if (this._snapshot !== undefined)
+      return this._snapshot;
+    if (this._includeSnapshot && this._context.currentTab())
+      this._snapshot = await this._context.currentTabOrDie().captureSnapshot();
+    else
+      this._snapshot = '';
+    return this._snapshot;
+  }
+
+  async serialize(): Promise<{ content: (TextContent | ImageContent)[] }> {
+    const response: string[] = [];
+
+    // Start with command result.
+    if (this._result.length) {
+      response.push('### Result');
+      response.push(this._result.join('\n'));
+      response.push('');
+    }
+
+    // Add code if it exists.
+    if (this._code.length) {
+      response.push(`### Ran Playwright code
+\`\`\`js
+${this._code.join('\n')}
+\`\`\``);
+      response.push('');
+    }
+
+    // List browser tabs.
+    if (this._includeSnapshot || this._includeTabs)
+      response.push(...(await this._context.listTabsMarkdown(this._includeTabs)));
+
+    // Add snapshot if provided.
+    const snapshot = await this.snapshot();
+    if (snapshot)
+      response.push(snapshot, '');
+
+    // Main response part
+    const content: (TextContent | ImageContent)[] = [
+      { type: 'text', text: response.join('\n') },
+    ];
+
+    // Image attachments.
+    if (this._context.config.imageResponses !== 'omit') {
+      for (const image of this._images)
+        content.push({ type: 'image', data: image.data.toString('base64'), mimeType: image.contentType });
+    }
+
+    return { content };
+  }
+}
--- a/src/server.ts
+++ b/src/server.ts
@@ -1,59 +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 { createConnection } from './connection.js';
-import { contextFactory as defaultContextFactory } from './browserContextFactory.js';
-
-import type { FullConfig } from './config.js';
-import type { Connection } from './connection.js';
-import type { Transport } from '@modelcontextprotocol/sdk/shared/transport.js';
-import type { BrowserContextFactory } from './browserContextFactory.js';
-
-export class Server {
-  readonly config: FullConfig;
-  private _connectionList: Connection[] = [];
-  private _browserConfig: FullConfig['browser'];
-  private _contextFactory: BrowserContextFactory;
-
-  constructor(config: FullConfig, contextFactory?: BrowserContextFactory) {
-    this.config = config;
-    this._browserConfig = config.browser;
-    this._contextFactory = contextFactory ?? defaultContextFactory(this._browserConfig);
-  }
-
-  async createConnection(transport: Transport): Promise<Connection> {
-    const connection = createConnection(this.config, this._contextFactory);
-    this._connectionList.push(connection);
-    await connection.server.connect(transport);
-    return connection;
-  }
-
-  setupExitWatchdog() {
-    let isExiting = false;
-    const handleExit = async () => {
-      if (isExiting)
-        return;
-      isExiting = true;
-      setTimeout(() => process.exit(0), 15000);
-      await Promise.all(this._connectionList.map(connection => connection.close()));
-      process.exit(0);
-    };
-
-    process.stdin.on('close', handleExit);
-    process.on('SIGINT', handleExit);
-    process.on('SIGTERM', handleExit);
-  }
-}
--- a/src/sessionLog.ts
+++ b/src/sessionLog.ts
@@ -0,0 +1,92 @@
+/**
+ * Copyright (c) Microsoft Corporation.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+import fs from 'fs';
+import path from 'path';
+
+import { outputFile  } from './config.js';
+import { Response } from './response.js';
+import type { FullConfig } from './config.js';
+
+let sessionOrdinal = 0;
+
+export class SessionLog {
+  private _folder: string;
+  private _file: string;
+  private _ordinal = 0;
+
+  constructor(sessionFolder: string) {
+    this._folder = sessionFolder;
+    this._file = path.join(this._folder, 'session.md');
+  }
+
+  static async create(config: FullConfig): Promise<SessionLog> {
+    const sessionFolder = await outputFile(config, `session-${(++sessionOrdinal).toString().padStart(3, '0')}`);
+    await fs.promises.mkdir(sessionFolder, { recursive: true });
+    // eslint-disable-next-line no-console
+    console.error(`Session: ${sessionFolder}`);
+    return new SessionLog(sessionFolder);
+  }
+
+  async log(response: Response) {
+    const prefix = `${(++this._ordinal).toString().padStart(3, '0')}`;
+    const lines: string[] = [
+      `### Tool: ${response.toolName}`,
+      ``,
+      `- Args`,
+      '```json',
+      JSON.stringify(response.toolArgs, null, 2),
+      '```',
+    ];
+    if (response.result()) {
+      lines.push(
+          `- Result`,
+          '```',
+          response.result(),
+          '```');
+    }
+
+    if (response.code()) {
+      lines.push(
+          `- Code`,
+          '```js',
+          response.code(),
+          '```');
+    }
+
+    const snapshot = await response.snapshot();
+    if (snapshot) {
+      const fileName = `${prefix}.snapshot.yml`;
+      await fs.promises.writeFile(path.join(this._folder, fileName), snapshot);
+      lines.push(`- Snapshot: ${fileName}`);
+    }
+
+    for (const image of response.images()) {
+      const fileName = `${prefix}.screenshot.${extension(image.contentType)}`;
+      await fs.promises.writeFile(path.join(this._folder, fileName), image.data);
+      lines.push(`- Screenshot: ${fileName}`);
+    }
+
+    lines.push('', '');
+    await fs.promises.appendFile(this._file, lines.join('\n'));
+  }
+}
+
+function extension(contentType: string): 'jpg' | 'png' {
+  if (contentType === 'image/jpeg')
+    return 'jpg';
+  return 'png';
+}
--- a/src/tab.ts
+++ b/src/tab.ts
@@ -14,24 +14,40 @@
 * limitations under the License.
 */

+import { EventEmitter } from 'events';
 import * as playwright from 'playwright';
-
-import { PageSnapshot } from './pageSnapshot.js';
-import { callOnPageNoTrace } from './tools/utils.js';
+import { callOnPageNoTrace, waitForCompletion } from './tools/utils.js';
 import { logUnhandledError } from './log.js';
+import { ManualPromise } from './manualPromise.js';
+import { ModalState } from './tools/tool.js';
+import { outputFile } from './config.js';

 import type { Context } from './context.js';

-export class Tab {
+type PageEx = playwright.Page & {
+  _snapshotForAI: () => Promise<string>;
+};
+
+export const TabEvents = {
+  modalState: 'modalState'
+};
+
+export type TabEventsInterface = {
+  [TabEvents.modalState]: [modalState: ModalState];
+};
+
+export class Tab extends EventEmitter<TabEventsInterface> {
  readonly context: Context;
  readonly page: playwright.Page;
  private _consoleMessages: ConsoleMessage[] = [];
  private _recentConsoleMessages: ConsoleMessage[] = [];
  private _requests: Map<playwright.Request, playwright.Response | null> = new Map();
-  private _snapshot: PageSnapshot | undefined;
  private _onPageClose: (tab: Tab) => void;
+  private _modalStates: ModalState[] = [];
+  private _downloads: { download: playwright.Download, finished: boolean, outputFile: string }[] = [];

  constructor(context: Context, page: playwright.Page, onPageClose: (tab: Tab) => void) {
+    super();
    this.context = context;
    this.page = page;
    this._onPageClose = onPageClose;
@@ -41,20 +57,63 @@ export class Tab {
    page.on('response', response => this._requests.set(response.request(), response));
    page.on('close', () => this._onClose());
    page.on('filechooser', chooser => {
-      this.context.setModalState({
+      this.setModalState({
        type: 'fileChooser',
        description: 'File chooser',
        fileChooser: chooser,
-      }, this);
+      });
    });
-    page.on('dialog', dialog => this.context.dialogShown(this, dialog));
+    page.on('dialog', dialog => this._dialogShown(dialog));
    page.on('download', download => {
-      void this.context.downloadStarted(this, download);
+      void this._downloadStarted(download);
    });
    page.setDefaultNavigationTimeout(60000);
    page.setDefaultTimeout(5000);
  }

+  modalStates(): ModalState[] {
+    return this._modalStates;
+  }
+
+  setModalState(modalState: ModalState) {
+    this._modalStates.push(modalState);
+    this.emit(TabEvents.modalState, modalState);
+  }
+
+  clearModalState(modalState: ModalState) {
+    this._modalStates = this._modalStates.filter(state => state !== modalState);
+  }
+
+  modalStatesMarkdown(): string[] {
+    const result: string[] = ['### Modal state'];
+    if (this._modalStates.length === 0)
+      result.push('- There is no modal state present');
+    for (const state of this._modalStates) {
+      const tool = this.context.tools.filter(tool => 'clearsModalState' in tool).find(tool => tool.clearsModalState === state.type);
+      result.push(`- [${state.description}]: can be handled by the "${tool?.schema.name}" tool`);
+    }
+    return result;
+  }
+
+  private _dialogShown(dialog: playwright.Dialog) {
+    this.setModalState({
+      type: 'dialog',
+      description: `"${dialog.type()}" dialog with message "${dialog.message()}"`,
+      dialog,
+    });
+  }
+
+  private async _downloadStarted(download: playwright.Download) {
+    const entry = {
+      download,
+      finished: false,
+      outputFile: await outputFile(this.context.config, download.suggestedFilename())
+    };
+    this._downloads.push(entry);
+    await download.saveAs(entry.outputFile);
+    entry.finished = true;
+  }
+
  private _clearCollectedArtifacts() {
    this._consoleMessages.length = 0;
    this._recentConsoleMessages.length = 0;
@@ -95,26 +154,19 @@ export class Tab {
      // on chromium, the download event is fired *after* page.goto rejects, so we wait a lil bit
      const download = await Promise.race([
        downloadEvent,
-        new Promise(resolve => setTimeout(resolve, 1000)),
+        new Promise(resolve => setTimeout(resolve, 3000)),
      ]);
      if (!download)
        throw e;
+      // Make sure other "download" listeners are notified first.
+      await new Promise(resolve => setTimeout(resolve, 500));
+      return;
    }

    // Cap load event to 5 seconds, the page is operational at this point.
    await this.waitForLoadState('load', { timeout: 5000 });
  }

-  hasSnapshot(): boolean {
-    return !!this._snapshot;
-  }
-
-  snapshotOrDie(): PageSnapshot {
-    if (!this._snapshot)
-      throw new Error('No snapshot available');
-    return this._snapshot;
-  }
-
  consoleMessages(): ConsoleMessage[] {
    return this._consoleMessages;
  }
@@ -123,15 +175,103 @@ export class Tab {
    return this._requests;
  }

-  async captureSnapshot() {
-    this._snapshot = await PageSnapshot.create(this.page);
+  private _takeRecentConsoleMarkdown(): string[] {
+    if (!this._recentConsoleMessages.length)
+      return [];
+    const result = this._recentConsoleMessages.map(message => {
+      return `- ${trim(message.toString(), 100)}`;
+    });
+    return [`### New console messages`, ...result, ''];
  }

-  takeRecentConsoleMessages(): ConsoleMessage[] {
-    const result = this._recentConsoleMessages.slice();
-    this._recentConsoleMessages.length = 0;
+  private _listDownloadsMarkdown(): string[] {
+    if (!this._downloads.length)
+      return [];
+
+    const result: string[] = ['### Downloads'];
+    for (const entry of this._downloads) {
+      if (entry.finished)
+        result.push(`- Downloaded file ${entry.download.suggestedFilename()} to ${entry.outputFile}`);
+      else
+        result.push(`- Downloading file ${entry.download.suggestedFilename()} ...`);
+    }
+    result.push('');
    return result;
  }
+
+  async captureSnapshot(): Promise<string> {
+    const result: string[] = [];
+    if (this.modalStates().length) {
+      result.push(...this.modalStatesMarkdown());
+      return result.join('\n');
+    }
+
+    result.push(...this._takeRecentConsoleMarkdown());
+    result.push(...this._listDownloadsMarkdown());
+
+    await this._raceAgainstModalStates(async () => {
+      const snapshot = await (this.page as PageEx)._snapshotForAI();
+      result.push(
+          `### Page state`,
+          `- Page URL: ${this.page.url()}`,
+          `- Page Title: ${await this.page.title()}`,
+          `- Page Snapshot:`,
+          '```yaml',
+          snapshot,
+          '```',
+      );
+    });
+    return result.join('\n');
+  }
+
+  private _javaScriptBlocked(): boolean {
+    return this._modalStates.some(state => state.type === 'dialog');
+  }
+
+  private async _raceAgainstModalStates(action: () => Promise<void>): Promise<ModalState | undefined> {
+    if (this.modalStates().length)
+      return this.modalStates()[0];
+
+    const promise = new ManualPromise<ModalState>();
+    const listener = (modalState: ModalState) => promise.resolve(modalState);
+    this.once(TabEvents.modalState, listener);
+
+    return await Promise.race([
+      action().then(() => {
+        this.off(TabEvents.modalState, listener);
+        return undefined;
+      }),
+      promise,
+    ]);
+  }
+
+  async waitForCompletion(callback: () => Promise<void>) {
+    await this._raceAgainstModalStates(() => waitForCompletion(this, callback));
+  }
+
+  async refLocator(params: { element: string, ref: string }): Promise<playwright.Locator> {
+    return (await this.refLocators([params]))[0];
+  }
+
+  async refLocators(params: { element: string, ref: string }[]): Promise<playwright.Locator[]> {
+    const snapshot = await (this.page as PageEx)._snapshotForAI();
+    return params.map(param => {
+      if (!snapshot.includes(`[ref=${param.ref}]`))
+        throw new Error(`Ref ${param.ref} not found in the current page snapshot. Try capturing new snapshot.`);
+      return this.page.locator(`aria-ref=${param.ref}`).describe(param.element);
+    });
+  }
+
+  async waitForTimeout(time: number) {
+    if (this._javaScriptBlocked()) {
+      await new Promise(f => setTimeout(f, time));
+      return;
+    }
+
+    await callOnPageNoTrace(this.page, page => {
+      return page.evaluate(() => new Promise(f => setTimeout(f, 1000)));
+    });
+  }
 }

 export type ConsoleMessage = {
@@ -162,3 +302,9 @@ function pageErrorToConsoleMessage(errorOrValue: Error | any): ConsoleMessage {
    toString: () => String(errorOrValue),
  };
 }
+
+function trim(text: string, maxLength: number) {
+  if (text.length <= maxLength)
+    return text;
+  return text.slice(0, maxLength) + '...';
+}
--- a/src/tools.ts
+++ b/src/tools.ts
@@ -31,6 +31,7 @@ import wait from './tools/wait.js';
 import mouse from './tools/mouse.js';

 import type { Tool } from './tools/tool.js';
+import type { FullConfig } from './config.js';

 export const allTools: Tool<any>[] = [
  ...common,
@@ -49,3 +50,7 @@ export const allTools: Tool<any>[] = [
  ...tabs,
  ...wait,
 ];
+
+export function filteredTools(config: FullConfig) {
+  return allTools.filter(tool => tool.capability.startsWith('core') || config.capabilities?.includes(tool.capability));
+}
--- a/src/tools/common.ts
+++ b/src/tools/common.ts
@@ -15,7 +15,7 @@
 */

 import { z } from 'zod';
-import { defineTool } from './tool.js';
+import { defineTabTool, defineTool } from './tool.js';

 const close = defineTool({
  capability: 'core',
@@ -28,17 +28,14 @@ const close = defineTool({
    type: 'readOnly',
  },

-  handle: async context => {
-    await context.close();
-    return {
-      code: [`await page.close()`],
-      captureSnapshot: false,
-      waitForNetwork: false,
-    };
+  handle: async (context, params, response) => {
+    await context.closeBrowserContext();
+    response.setIncludeTabs();
+    response.addCode(`await page.close()`);
  },
 });

-const resize = defineTool({
+const resize = defineTabTool({
  capability: 'core',
  schema: {
    name: 'browser_resize',
@@ -51,24 +48,13 @@ const resize = defineTool({
    type: 'readOnly',
  },

-  handle: async (context, params) => {
-    const tab = context.currentTabOrDie();
+  handle: async (tab, params, response) => {
+    response.addCode(`// Resize browser window to ${params.width}x${params.height}`);
+    response.addCode(`await page.setViewportSize({ width: ${params.width}, height: ${params.height} });`);

-    const code = [
-      `// Resize browser window to ${params.width}x${params.height}`,
-      `await page.setViewportSize({ width: ${params.width}, height: ${params.height} });`
-    ];
-
-    const action = async () => {
+    await tab.waitForCompletion(async () => {
      await tab.page.setViewportSize({ width: params.width, height: params.height });
-    };
-
-    return {
-      code,
-      action,
-      captureSnapshot: true,
-      waitForNetwork: true
-    };
+    });
  },
 });

--- a/src/tools/console.ts
+++ b/src/tools/console.ts
@@ -15,9 +15,9 @@
 */

 import { z } from 'zod';
-import { defineTool } from './tool.js';
+import { defineTabTool } from './tool.js';

-const console = defineTool({
+const console = defineTabTool({
  capability: 'core',
  schema: {
    name: 'browser_console_messages',
@@ -26,19 +26,8 @@ const console = defineTool({
    inputSchema: z.object({}),
    type: 'readOnly',
  },
-  handle: async context => {
-    const messages = context.currentTabOrDie().consoleMessages();
-    const log = messages.map(message => message.toString()).join('\n');
-    return {
-      code: [`// <internal code to get console messages>`],
-      action: async () => {
-        return {
-          content: [{ type: 'text', text: log }]
-        };
-      },
-      captureSnapshot: false,
-      waitForNetwork: false,
-    };
+  handle: async (tab, params, response) => {
+    tab.consoleMessages().map(message => response.addResult(message.toString()));
  },
 });

--- a/src/tools/dialogs.ts
+++ b/src/tools/dialogs.ts
@@ -15,9 +15,9 @@
 */

 import { z } from 'zod';
-import { defineTool } from './tool.js';
+import { defineTabTool } from './tool.js';

-const handleDialog = defineTool({
+const handleDialog = defineTabTool({
  capability: 'core',

  schema: {
@@ -31,27 +31,20 @@ const handleDialog = defineTool({
    type: 'destructive',
  },

-  handle: async (context, params) => {
-    const dialogState = context.modalStates().find(state => state.type === 'dialog');
+  handle: async (tab, params, response) => {
+    response.setIncludeSnapshot();
+
+    const dialogState = tab.modalStates().find(state => state.type === 'dialog');
    if (!dialogState)
      throw new Error('No dialog visible');

-    if (params.accept)
-      await dialogState.dialog.accept(params.promptText);
-    else
-      await dialogState.dialog.dismiss();
-
-    context.clearModalState(dialogState);
-
-    const code = [
-      `// <internal code to handle "${dialogState.dialog.type()}" dialog>`,
-    ];
-
-    return {
-      code,
-      captureSnapshot: true,
-      waitForNetwork: false,
-    };
+    tab.clearModalState(dialogState);
+    await tab.waitForCompletion(async () => {
+      if (params.accept)
+        await dialogState.dialog.accept(params.promptText);
+      else
+        await dialogState.dialog.dismiss();
+    });
  },

  clearsModalState: 'dialog',
--- a/src/tools/evaluate.ts
+++ b/src/tools/evaluate.ts
@@ -16,7 +16,7 @@

 import { z } from 'zod';

-import { defineTool } from './tool.js';
+import { defineTabTool } from './tool.js';
 import * as javascript from '../javascript.js';
 import { generateLocator } from './utils.js';

@@ -28,7 +28,7 @@ const evaluateSchema = z.object({
  ref: z.string().optional().describe('Exact target element reference from the page snapshot'),
 });

-const evaluate = defineTool({
+const evaluate = defineTabTool({
  capability: 'core',
  schema: {
    name: 'browser_evaluate',
@@ -38,31 +38,22 @@ const evaluate = defineTool({
    type: 'destructive',
  },

-  handle: async (context, params) => {
-    const tab = context.currentTabOrDie();
-    const code: string[] = [];
+  handle: async (tab, params, response) => {
+    response.setIncludeSnapshot();

    let locator: playwright.Locator | undefined;
    if (params.ref && params.element) {
-      const snapshot = tab.snapshotOrDie();
-      locator = snapshot.refLocator({ ref: params.ref, element: params.element });
-      code.push(`await page.${await generateLocator(locator)}.evaluate(${javascript.quote(params.function)});`);
+      locator = await tab.refLocator({ ref: params.ref, element: params.element });
+      response.addCode(`await page.${await generateLocator(locator)}.evaluate(${javascript.quote(params.function)});`);
    } else {
-      code.push(`await page.evaluate(${javascript.quote(params.function)});`);
+      response.addCode(`await page.evaluate(${javascript.quote(params.function)});`);
    }

-    return {
-      code,
-      action: async () => {
-        const receiver = locator ?? tab.page as any;
-        const result = await receiver._evaluateFunction(params.function);
-        return {
-          content: [{ type: 'text', text: '- Result: ' + (JSON.stringify(result, null, 2) || 'undefined') }],
-        };
-      },
-      captureSnapshot: false,
-      waitForNetwork: false,
-    };
+    await tab.waitForCompletion(async () => {
+      const receiver = locator ?? tab.page as any;
+      const result = await receiver._evaluateFunction(params.function);
+      response.addResult(JSON.stringify(result, null, 2) || 'undefined');
+    });
  },
 });

--- a/src/tools/files.ts
+++ b/src/tools/files.ts
@@ -15,9 +15,9 @@
 */

 import { z } from 'zod';
-import { defineTool } from './tool.js';
+import { defineTabTool } from './tool.js';

-const uploadFile = defineTool({
+const uploadFile = defineTabTool({
  capability: 'core',

  schema: {
@@ -30,26 +30,20 @@ const uploadFile = defineTool({
    type: 'destructive',
  },

-  handle: async (context, params) => {
-    const modalState = context.modalStates().find(state => state.type === 'fileChooser');
+  handle: async (tab, params, response) => {
+    response.setIncludeSnapshot();
+
+    const modalState = tab.modalStates().find(state => state.type === 'fileChooser');
    if (!modalState)
      throw new Error('No file chooser visible');

-    const code = [
-      `// <internal code to chose files ${params.paths.join(', ')}`,
-    ];
+    response.addCode(`// Select files for upload`);
+    response.addCode(`await fileChooser.setFiles(${JSON.stringify(params.paths)})`);

-    const action = async () => {
+    tab.clearModalState(modalState);
+    await tab.waitForCompletion(async () => {
      await modalState.fileChooser.setFiles(params.paths);
-      context.clearModalState(modalState);
-    };
-
-    return {
-      code,
-      action,
-      captureSnapshot: true,
-      waitForNetwork: true,
-    };
+    });
  },
  clearsModalState: 'fileChooser',
 });
--- a/src/tools/install.ts
+++ b/src/tools/install.ts
@@ -16,11 +16,10 @@

 import { fork } from 'child_process';
 import path from 'path';
-
+import { fileURLToPath } from 'url';
 import { z } from 'zod';
 import { defineTool } from './tool.js';

-import { fileURLToPath } from 'node:url';

 const install = defineTool({
  capability: 'core-install',
@@ -32,7 +31,7 @@ const install = defineTool({
    type: 'destructive',
  },

-  handle: async context => {
+  handle: async (context, params, response) => {
    const channel = context.config.browser?.launchOptions?.channel ?? context.config.browser?.browserName ?? 'chrome';
    const cliUrl = import.meta.resolve('playwright/package.json');
    const cliPath = path.join(fileURLToPath(cliUrl), '..', 'cli.js');
@@ -50,11 +49,7 @@ const install = defineTool({
          reject(new Error(`Failed to install browser: ${output.join('')}`));
      });
    });
-    return {
-      code: [`// Browser ${channel} installed`],
-      captureSnapshot: false,
-      waitForNetwork: false,
-    };
+    response.setIncludeTabs();
  },
 });

--- a/src/tools/keyboard.ts
+++ b/src/tools/keyboard.ts
@@ -16,12 +16,12 @@

 import { z } from 'zod';

-import { defineTool } from './tool.js';
+import { defineTabTool } from './tool.js';
 import { elementSchema } from './snapshot.js';
 import { generateLocator } from './utils.js';
 import * as javascript from '../javascript.js';

-const pressKey = defineTool({
+const pressKey = defineTabTool({
  capability: 'core',

  schema: {
@@ -34,22 +34,14 @@ const pressKey = defineTool({
    type: 'destructive',
  },

-  handle: async (context, params) => {
-    const tab = context.currentTabOrDie();
+  handle: async (tab, params, response) => {
+    response.setIncludeSnapshot();
+    response.addCode(`// Press ${params.key}`);
+    response.addCode(`await page.keyboard.press('${params.key}');`);

-    const code = [
-      `// Press ${params.key}`,
-      `await page.keyboard.press('${params.key}');`,
-    ];
-
-    const action = () => tab.page.keyboard.press(params.key);
-
-    return {
-      code,
-      action,
-      captureSnapshot: true,
-      waitForNetwork: true
-    };
+    await tab.waitForCompletion(async () => {
+      await tab.page.keyboard.press(params.key);
+    });
  },
 });

@@ -59,7 +51,7 @@ const typeSchema = elementSchema.extend({
  slowly: z.boolean().optional().describe('Whether to type one character at a time. Useful for triggering key handlers in the page. By default entire text is filled in at once.'),
 });

-const type = defineTool({
+const type = defineTabTool({
  capability: 'core',
  schema: {
    name: 'browser_type',
@@ -69,35 +61,27 @@ const type = defineTool({
    type: 'destructive',
  },

-  handle: async (context, params) => {
-    const snapshot = context.currentTabOrDie().snapshotOrDie();
-    const locator = snapshot.refLocator(params);
+  handle: async (tab, params, response) => {
+    const locator = await tab.refLocator(params);

-    const code: string[] = [];
-    const steps: (() => Promise<void>)[] = [];
+    await tab.waitForCompletion(async () => {
+      if (params.slowly) {
+        response.setIncludeSnapshot();
+        response.addCode(`// Press "${params.text}" sequentially into "${params.element}"`);
+        response.addCode(`await page.${await generateLocator(locator)}.pressSequentially(${javascript.quote(params.text)});`);
+        await locator.pressSequentially(params.text);
+      } else {
+        response.addCode(`// Fill "${params.text}" into "${params.element}"`);
+        response.addCode(`await page.${await generateLocator(locator)}.fill(${javascript.quote(params.text)});`);
+        await locator.fill(params.text);
+      }

-    if (params.slowly) {
-      code.push(`// Press "${params.text}" sequentially into "${params.element}"`);
-      code.push(`await page.${await generateLocator(locator)}.pressSequentially(${javascript.quote(params.text)});`);
-      steps.push(() => locator.pressSequentially(params.text));
-    } else {
-      code.push(`// Fill "${params.text}" into "${params.element}"`);
-      code.push(`await page.${await generateLocator(locator)}.fill(${javascript.quote(params.text)});`);
-      steps.push(() => locator.fill(params.text));
-    }
-
-    if (params.submit) {
-      code.push(`// Submit text`);
-      code.push(`await page.${await generateLocator(locator)}.press('Enter');`);
-      steps.push(() => locator.press('Enter'));
-    }
-
-    return {
-      code,
-      action: () => steps.reduce((acc, step) => acc.then(step), Promise.resolve()),
-      captureSnapshot: true,
-      waitForNetwork: true,
-    };
+      if (params.submit) {
+        response.setIncludeSnapshot();
+        response.addCode(`await page.${await generateLocator(locator)}.press('Enter');`);
+        await locator.press('Enter');
+      }
+    });
  },
 });

--- a/src/tools/mouse.ts
+++ b/src/tools/mouse.ts
@@ -15,13 +15,13 @@
 */

 import { z } from 'zod';
-import { defineTool } from './tool.js';
+import { defineTabTool } from './tool.js';

 const elementSchema = z.object({
  element: z.string().describe('Human-readable element description used to obtain permission to interact with the element'),
 });

-const mouseMove = defineTool({
+const mouseMove = defineTabTool({
  capability: 'vision',
  schema: {
    name: 'browser_mouse_move_xy',
@@ -34,23 +34,17 @@ const mouseMove = defineTool({
    type: 'readOnly',
  },

-  handle: async (context, params) => {
-    const tab = context.currentTabOrDie();
-    const code = [
-      `// Move mouse to (${params.x}, ${params.y})`,
-      `await page.mouse.move(${params.x}, ${params.y});`,
-    ];
-    const action = () => tab.page.mouse.move(params.x, params.y);
-    return {
-      code,
-      action,
-      captureSnapshot: false,
-      waitForNetwork: false
-    };
+  handle: async (tab, params, response) => {
+    response.addCode(`// Move mouse to (${params.x}, ${params.y})`);
+    response.addCode(`await page.mouse.move(${params.x}, ${params.y});`);
+
+    await tab.waitForCompletion(async () => {
+      await tab.page.mouse.move(params.x, params.y);
+    });
  },
 });

-const mouseClick = defineTool({
+const mouseClick = defineTabTool({
  capability: 'vision',
  schema: {
    name: 'browser_mouse_click_xy',
@@ -63,29 +57,23 @@ const mouseClick = defineTool({
    type: 'destructive',
  },

-  handle: async (context, params) => {
-    const tab = context.currentTabOrDie();
-    const code = [
-      `// Click mouse at coordinates (${params.x}, ${params.y})`,
-      `await page.mouse.move(${params.x}, ${params.y});`,
-      `await page.mouse.down();`,
-      `await page.mouse.up();`,
-    ];
-    const action = async () => {
+  handle: async (tab, params, response) => {
+    response.setIncludeSnapshot();
+
+    response.addCode(`// Click mouse at coordinates (${params.x}, ${params.y})`);
+    response.addCode(`await page.mouse.move(${params.x}, ${params.y});`);
+    response.addCode(`await page.mouse.down();`);
+    response.addCode(`await page.mouse.up();`);
+
+    await tab.waitForCompletion(async () => {
      await tab.page.mouse.move(params.x, params.y);
      await tab.page.mouse.down();
      await tab.page.mouse.up();
-    };
-    return {
-      code,
-      action,
-      captureSnapshot: false,
-      waitForNetwork: true,
-    };
+    });
  },
 });

-const mouseDrag = defineTool({
+const mouseDrag = defineTabTool({
  capability: 'vision',
  schema: {
    name: 'browser_mouse_drag_xy',
@@ -100,30 +88,21 @@ const mouseDrag = defineTool({
    type: 'destructive',
  },

-  handle: async (context, params) => {
-    const tab = context.currentTabOrDie();
+  handle: async (tab, params, response) => {
+    response.setIncludeSnapshot();

-    const code = [
-      `// Drag mouse from (${params.startX}, ${params.startY}) to (${params.endX}, ${params.endY})`,
-      `await page.mouse.move(${params.startX}, ${params.startY});`,
-      `await page.mouse.down();`,
-      `await page.mouse.move(${params.endX}, ${params.endY});`,
-      `await page.mouse.up();`,
-    ];
+    response.addCode(`// Drag mouse from (${params.startX}, ${params.startY}) to (${params.endX}, ${params.endY})`);
+    response.addCode(`await page.mouse.move(${params.startX}, ${params.startY});`);
+    response.addCode(`await page.mouse.down();`);
+    response.addCode(`await page.mouse.move(${params.endX}, ${params.endY});`);
+    response.addCode(`await page.mouse.up();`);

-    const action = async () => {
+    await tab.waitForCompletion(async () => {
      await tab.page.mouse.move(params.startX, params.startY);
      await tab.page.mouse.down();
      await tab.page.mouse.move(params.endX, params.endY);
      await tab.page.mouse.up();
-    };
-
-    return {
-      code,
-      action,
-      captureSnapshot: false,
-      waitForNetwork: true,
-    };
+    });
  },
 });

--- a/src/tools/navigate.ts
+++ b/src/tools/navigate.ts
@@ -15,7 +15,7 @@
 */

 import { z } from 'zod';
-import { defineTool } from './tool.js';
+import { defineTool, defineTabTool } from './tool.js';

 const navigate = defineTool({
  capability: 'core',
@@ -30,24 +30,17 @@ const navigate = defineTool({
    type: 'destructive',
  },

-  handle: async (context, params) => {
+  handle: async (context, params, response) => {
    const tab = await context.ensureTab();
    await tab.navigate(params.url);

-    const code = [
-      `// Navigate to ${params.url}`,
-      `await page.goto('${params.url}');`,
-    ];
-
-    return {
-      code,
-      captureSnapshot: true,
-      waitForNetwork: false,
-    };
+    response.setIncludeSnapshot();
+    response.addCode(`// Navigate to ${params.url}`);
+    response.addCode(`await page.goto('${params.url}');`);
  },
 });

-const goBack = defineTool({
+const goBack = defineTabTool({
  capability: 'core',
  schema: {
    name: 'browser_navigate_back',
@@ -57,23 +50,15 @@ const goBack = defineTool({
    type: 'readOnly',
  },

-  handle: async context => {
-    const tab = await context.ensureTab();
+  handle: async (tab, params, response) => {
    await tab.page.goBack();
-    const code = [
-      `// Navigate back`,
-      `await page.goBack();`,
-    ];
-
-    return {
-      code,
-      captureSnapshot: true,
-      waitForNetwork: false,
-    };
+    response.setIncludeSnapshot();
+    response.addCode(`// Navigate back`);
+    response.addCode(`await page.goBack();`);
  },
 });

-const goForward = defineTool({
+const goForward = defineTabTool({
  capability: 'core',
  schema: {
    name: 'browser_navigate_forward',
@@ -82,18 +67,11 @@ const goForward = defineTool({
    inputSchema: z.object({}),
    type: 'readOnly',
  },
-  handle: async context => {
-    const tab = context.currentTabOrDie();
+  handle: async (tab, params, response) => {
    await tab.page.goForward();
-    const code = [
-      `// Navigate forward`,
-      `await page.goForward();`,
-    ];
-    return {
-      code,
-      captureSnapshot: true,
-      waitForNetwork: false,
-    };
+    response.setIncludeSnapshot();
+    response.addCode(`// Navigate forward`);
+    response.addCode(`await page.goForward();`);
  },
 });

--- a/src/tools/network.ts
+++ b/src/tools/network.ts
@@ -15,11 +15,11 @@
 */

 import { z } from 'zod';
-import { defineTool } from './tool.js';
+import { defineTabTool } from './tool.js';

 import type * as playwright from 'playwright';

-const requests = defineTool({
+const requests = defineTabTool({
  capability: 'core',

  schema: {
@@ -30,19 +30,9 @@ const requests = defineTool({
    type: 'readOnly',
  },

-  handle: async context => {
-    const requests = context.currentTabOrDie().requests();
-    const log = [...requests.entries()].map(([request, response]) => renderRequest(request, response)).join('\n');
-    return {
-      code: [`// <internal code to list network requests>`],
-      action: async () => {
-        return {
-          content: [{ type: 'text', text: log }]
-        };
-      },
-      captureSnapshot: false,
-      waitForNetwork: false,
-    };
+  handle: async (tab, params, response) => {
+    const requests = tab.requests();
+    [...requests.entries()].forEach(([req, res]) => response.addResult(renderRequest(req, res)));
  },
 });

--- a/src/tools/pdf.ts
+++ b/src/tools/pdf.ts
@@ -15,7 +15,7 @@
 */

 import { z } from 'zod';
-import { defineTool } from './tool.js';
+import { defineTabTool } from './tool.js';

 import * as javascript from '../javascript.js';
 import { outputFile } from '../config.js';
@@ -24,7 +24,7 @@ const pdfSchema = z.object({
  filename: z.string().optional().describe('File name to save the pdf to. Defaults to `page-{timestamp}.pdf` if not specified.'),
 });

-const pdf = defineTool({
+const pdf = defineTabTool({
  capability: 'pdf',

  schema: {
@@ -35,21 +35,12 @@ const pdf = defineTool({
    type: 'readOnly',
  },

-  handle: async (context, params) => {
-    const tab = context.currentTabOrDie();
-    const fileName = await outputFile(context.config, params.filename ?? `page-${new Date().toISOString()}.pdf`);
-
-    const code = [
-      `// Save page as ${fileName}`,
-      `await page.pdf(${javascript.formatObject({ path: fileName })});`,
-    ];
-
-    return {
-      code,
-      action: async () => tab.page.pdf({ path: fileName }).then(() => {}),
-      captureSnapshot: false,
-      waitForNetwork: false,
-    };
+  handle: async (tab, params, response) => {
+    const fileName = await outputFile(tab.context.config, params.filename ?? `page-${new Date().toISOString()}.pdf`);
+    response.addCode(`// Save page as ${fileName}`);
+    response.addCode(`await page.pdf(${javascript.formatObject({ path: fileName })});`);
+    response.addResult(`Saved page as ${fileName}`);
+    await tab.page.pdf({ path: fileName });
  },
 });

--- a/src/tools/screenshot.ts
+++ b/src/tools/screenshot.ts
@@ -16,7 +16,7 @@

 import { z } from 'zod';

-import { defineTool } from './tool.js';
+import { defineTabTool } from './tool.js';
 import * as javascript from '../javascript.js';
 import { outputFile } from '../config.js';
 import { generateLocator } from './utils.js';
@@ -41,7 +41,7 @@ const screenshotSchema = z.object({
  path: ['fullPage']
 });

-const screenshot = defineTool({
+const screenshot = defineTabTool({
  capability: 'core',
  schema: {
    name: 'browser_take_screenshot',
@@ -51,11 +51,9 @@ const screenshot = defineTool({
    type: 'readOnly',
  },

-  handle: async (context, params) => {
-    const tab = context.currentTabOrDie();
-    const snapshot = tab.snapshotOrDie();
+  handle: async (tab, params, response) => {
    const fileType = params.raw ? 'png' : 'jpeg';
-    const fileName = await outputFile(context.config, params.filename ?? `page-${new Date().toISOString()}.${fileType}`);
+    const fileName = await outputFile(tab.context.config, params.filename ?? `page-${new Date().toISOString()}.${fileType}`);
    const options: playwright.PageScreenshotOptions = {
      type: fileType,
      quality: fileType === 'png' ? undefined : 50,
@@ -66,35 +64,22 @@ const screenshot = defineTool({
    const isElementScreenshot = params.element && params.ref;

    const screenshotTarget = isElementScreenshot ? params.element : (params.fullPage ? 'full page' : 'viewport');
-    const code = [
-      `// Screenshot ${screenshotTarget} and save it as ${fileName}`,
-    ];
+    response.addCode(`// Screenshot ${screenshotTarget} and save it as ${fileName}`);

-    const locator = params.ref ? snapshot.refLocator({ element: params.element || '', ref: params.ref }) : null;
+    // Only get snapshot when element screenshot is needed
+    const locator = params.ref ? await tab.refLocator({ element: params.element || '', ref: params.ref }) : null;

    if (locator)
-      code.push(`await page.${await generateLocator(locator)}.screenshot(${javascript.formatObject(options)});`);
+      response.addCode(`await page.${await generateLocator(locator)}.screenshot(${javascript.formatObject(options)});`);
    else
-      code.push(`await page.screenshot(${javascript.formatObject(options)});`);
+      response.addCode(`await page.screenshot(${javascript.formatObject(options)});`);

-    const includeBase64 = context.clientSupportsImages();
-    const action = async () => {
-      const screenshot = locator ? await locator.screenshot(options) : await tab.page.screenshot(options);
-      return {
-        content: includeBase64 ? [{
-          type: 'image' as 'image',
-          data: screenshot.toString('base64'),
-          mimeType: fileType === 'png' ? 'image/png' : 'image/jpeg',
-        }] : []
-      };
-    };
-
-    return {
-      code,
-      action,
-      captureSnapshot: false,
-      waitForNetwork: false,
-    };
+    const buffer = locator ? await locator.screenshot(options) : await tab.page.screenshot(options);
+    response.addResult(`Took the ${screenshotTarget} screenshot and saved it as ${fileName}`);
+    response.addImage({
+      contentType: fileType === 'png' ? 'image/png' : 'image/jpeg',
+      data: buffer
+    });
  }
 });

--- a/src/tools/snapshot.ts
+++ b/src/tools/snapshot.ts
@@ -16,7 +16,7 @@

 import { z } from 'zod';

-import { defineTool } from './tool.js';
+import { defineTabTool, defineTool } from './tool.js';
 import * as javascript from '../javascript.js';
 import { generateLocator } from './utils.js';

@@ -30,14 +30,9 @@ const snapshot = defineTool({
    type: 'readOnly',
  },

-  handle: async context => {
+  handle: async (context, params, response) => {
    await context.ensureTab();
-
-    return {
-      code: [`// <internal code to capture accessibility snapshot>`],
-      captureSnapshot: true,
-      waitForNetwork: false,
-    };
+    response.setIncludeSnapshot();
  },
 });

@@ -51,7 +46,7 @@ const clickSchema = elementSchema.extend({
  button: z.enum(['left', 'right', 'middle']).optional().describe('Button to click, defaults to left'),
 });

-const click = defineTool({
+const click = defineTabTool({
  capability: 'core',
  schema: {
    name: 'browser_click',
@@ -61,31 +56,31 @@ const click = defineTool({
    type: 'destructive',
  },

-  handle: async (context, params) => {
-    const tab = context.currentTabOrDie();
-    const locator = tab.snapshotOrDie().refLocator(params);
+  handle: async (tab, params, response) => {
+    response.setIncludeSnapshot();
+
+    const locator = await tab.refLocator(params);
    const button = params.button;
    const buttonAttr = button ? `{ button: '${button}' }` : '';

-    const code: string[] = [];
    if (params.doubleClick) {
-      code.push(`// Double click ${params.element}`);
-      code.push(`await page.${await generateLocator(locator)}.dblclick(${buttonAttr});`);
+      response.addCode(`// Double click ${params.element}`);
+      response.addCode(`await page.${await generateLocator(locator)}.dblclick(${buttonAttr});`);
    } else {
-      code.push(`// Click ${params.element}`);
-      code.push(`await page.${await generateLocator(locator)}.click(${buttonAttr});`);
+      response.addCode(`// Click ${params.element}`);
+      response.addCode(`await page.${await generateLocator(locator)}.click(${buttonAttr});`);
    }

-    return {
-      code,
-      action: () => params.doubleClick ? locator.dblclick({ button }) : locator.click({ button }),
-      captureSnapshot: true,
-      waitForNetwork: true,
-    };
+    await tab.waitForCompletion(async () => {
+      if (params.doubleClick)
+        await locator.dblclick({ button });
+      else
+        await locator.click({ button });
+    });
  },
 });

-const drag = defineTool({
+const drag = defineTabTool({
  capability: 'core',
  schema: {
    name: 'browser_drag',
@@ -100,26 +95,23 @@ const drag = defineTool({
    type: 'destructive',
  },

-  handle: async (context, params) => {
-    const snapshot = context.currentTabOrDie().snapshotOrDie();
-    const startLocator = snapshot.refLocator({ ref: params.startRef, element: params.startElement });
-    const endLocator = snapshot.refLocator({ ref: params.endRef, element: params.endElement });
+  handle: async (tab, params, response) => {
+    response.setIncludeSnapshot();

-    const code = [
-      `// Drag ${params.startElement} to ${params.endElement}`,
-      `await page.${await generateLocator(startLocator)}.dragTo(page.${await generateLocator(endLocator)});`
-    ];
+    const [startLocator, endLocator] = await tab.refLocators([
+      { ref: params.startRef, element: params.startElement },
+      { ref: params.endRef, element: params.endElement },
+    ]);

-    return {
-      code,
-      action: () => startLocator.dragTo(endLocator),
-      captureSnapshot: true,
-      waitForNetwork: true,
-    };
+    await tab.waitForCompletion(async () => {
+      await startLocator.dragTo(endLocator);
+    });
+
+    response.addCode(`await page.${await generateLocator(startLocator)}.dragTo(page.${await generateLocator(endLocator)});`);
  },
 });

-const hover = defineTool({
+const hover = defineTabTool({
  capability: 'core',
  schema: {
    name: 'browser_hover',
@@ -129,21 +121,15 @@ const hover = defineTool({
    type: 'readOnly',
  },

-  handle: async (context, params) => {
-    const snapshot = context.currentTabOrDie().snapshotOrDie();
-    const locator = snapshot.refLocator(params);
+  handle: async (tab, params, response) => {
+    response.setIncludeSnapshot();

-    const code = [
-      `// Hover over ${params.element}`,
-      `await page.${await generateLocator(locator)}.hover();`
-    ];
+    const locator = await tab.refLocator(params);
+    response.addCode(`await page.${await generateLocator(locator)}.hover();`);

-    return {
-      code,
-      action: () => locator.hover(),
-      captureSnapshot: true,
-      waitForNetwork: true,
-    };
+    await tab.waitForCompletion(async () => {
+      await locator.hover();
+    });
  },
 });

@@ -151,7 +137,7 @@ const selectOptionSchema = elementSchema.extend({
  values: z.array(z.string()).describe('Array of values to select in the dropdown. This can be a single value or multiple values.'),
 });

-const selectOption = defineTool({
+const selectOption = defineTabTool({
  capability: 'core',
  schema: {
    name: 'browser_select_option',
@@ -161,21 +147,16 @@ const selectOption = defineTool({
    type: 'destructive',
  },

-  handle: async (context, params) => {
-    const snapshot = context.currentTabOrDie().snapshotOrDie();
-    const locator = snapshot.refLocator(params);
+  handle: async (tab, params, response) => {
+    response.setIncludeSnapshot();

-    const code = [
-      `// Select options [${params.values.join(', ')}] in ${params.element}`,
-      `await page.${await generateLocator(locator)}.selectOption(${javascript.formatObject(params.values)});`
-    ];
+    const locator = await tab.refLocator(params);
+    response.addCode(`// Select options [${params.values.join(', ')}] in ${params.element}`);
+    response.addCode(`await page.${await generateLocator(locator)}.selectOption(${javascript.formatObject(params.values)});`);

-    return {
-      code,
-      action: () => locator.selectOption(params.values).then(() => {}),
-      captureSnapshot: true,
-      waitForNetwork: true,
-    };
+    await tab.waitForCompletion(async () => {
+      await locator.selectOption(params.values);
+    });
  },
 });

--- a/src/tools/tabs.ts
+++ b/src/tools/tabs.ts
@@ -28,19 +28,9 @@ const listTabs = defineTool({
    type: 'readOnly',
  },

-  handle: async context => {
+  handle: async (context, params, response) => {
    await context.ensureTab();
-    return {
-      code: [`// <internal code to list tabs>`],
-      captureSnapshot: false,
-      waitForNetwork: false,
-      resultOverride: {
-        content: [{
-          type: 'text',
-          text: await context.listTabsMarkdown(),
-        }],
-      },
-    };
+    response.setIncludeTabs();
  },
 });

@@ -57,17 +47,9 @@ const selectTab = defineTool({
    type: 'readOnly',
  },

-  handle: async (context, params) => {
+  handle: async (context, params, response) => {
    await context.selectTab(params.index);
-    const code = [
-      `// <internal code to select tab ${params.index}>`,
-    ];
-
-    return {
-      code,
-      captureSnapshot: true,
-      waitForNetwork: false
-    };
+    response.setIncludeSnapshot();
  },
 });

@@ -84,19 +66,11 @@ const newTab = defineTool({
    type: 'readOnly',
  },

-  handle: async (context, params) => {
-    await context.newTab();
+  handle: async (context, params, response) => {
+    const tab = await context.newTab();
    if (params.url)
-      await context.currentTabOrDie().navigate(params.url);
-
-    const code = [
-      `// <internal code to open a new tab>`,
-    ];
-    return {
-      code,
-      captureSnapshot: true,
-      waitForNetwork: false
-    };
+      await tab.navigate(params.url);
+    response.setIncludeSnapshot();
  },
 });

@@ -113,16 +87,9 @@ const closeTab = defineTool({
    type: 'destructive',
  },

-  handle: async (context, params) => {
+  handle: async (context, params, response) => {
    await context.closeTab(params.index);
-    const code = [
-      `// <internal code to close tab ${params.index}>`,
-    ];
-    return {
-      code,
-      captureSnapshot: true,
-      waitForNetwork: false
-    };
+    response.setIncludeSnapshot();
  },
 });

--- a/src/tools/tool.ts
+++ b/src/tools/tool.ts
@@ -14,21 +14,13 @@
 * limitations under the License.
 */

-import type { ImageContent, TextContent } from '@modelcontextprotocol/sdk/types.js';
 import type { z } from 'zod';
 import type { Context } from '../context.js';
 import type * as playwright from 'playwright';
 import type { ToolCapability } from '../../config.js';
-
-export type ToolSchema<Input extends InputType> = {
-  name: string;
-  title: string;
-  description: string;
-  inputSchema: Input;
-  type: 'readOnly' | 'destructive';
-};
-
-type InputType = z.Schema;
+import type { Tab } from '../tab.js';
+import type { Response } from '../response.js';
+import type { ToolSchema } from '../mcp/server.js';

 export type FileUploadModalState = {
  type: 'fileChooser';
@@ -44,23 +36,34 @@ export type DialogModalState = {

 export type ModalState = FileUploadModalState | DialogModalState;

-export type ToolActionResult = { content?: (ImageContent | TextContent)[] } | undefined | void;
-
-export type ToolResult = {
-  code: string[];
-  action?: () => Promise<ToolActionResult>;
-  captureSnapshot: boolean;
-  waitForNetwork: boolean;
-  resultOverride?: ToolActionResult;
+export type Tool<Input extends z.Schema = z.Schema> = {
+  capability: ToolCapability;
+  schema: ToolSchema<Input>;
+  handle: (context: Context, params: z.output<Input>, response: Response) => Promise<void>;
 };

-export type Tool<Input extends InputType = InputType> = {
+export function defineTool<Input extends z.Schema>(tool: Tool<Input>): Tool<Input> {
+  return tool;
+}
+
+export type TabTool<Input extends z.Schema = z.Schema> = {
  capability: ToolCapability;
  schema: ToolSchema<Input>;
  clearsModalState?: ModalState['type'];
-  handle: (context: Context, params: z.output<Input>) => Promise<ToolResult>;
+  handle: (tab: Tab, params: z.output<Input>, response: Response) => Promise<void>;
 };

-export function defineTool<Input extends InputType>(tool: Tool<Input>): Tool<Input> {
-  return tool;
+export function defineTabTool<Input extends z.Schema>(tool: TabTool<Input>): Tool<Input> {
+  return {
+    ...tool,
+    handle: async (context, params, response) => {
+      const tab = context.currentTabOrDie();
+      const modalStates = tab.modalStates().map(state => state.type);
+      if (tool.clearsModalState && !modalStates.includes(tool.clearsModalState))
+        throw new Error(`The tool "${tool.schema.name}" can only be used when there is related modal state present.\n` + tab.modalStatesMarkdown().join('\n'));
+      if (!tool.clearsModalState && modalStates.length)
+        throw new Error(`Tool "${tool.schema.name}" does not handle the modal state.\n` + tab.modalStatesMarkdown().join('\n'));
+      return tool.handle(tab, params, response);
+    },
+  };
 }
--- a/src/tools/utils.ts
+++ b/src/tools/utils.ts
@@ -18,10 +18,9 @@
 import { asLocator } from 'playwright-core/lib/utils';

 import type * as playwright from 'playwright';
-import type { Context } from '../context.js';
 import type { Tab } from '../tab.js';

-export async function waitForCompletion<R>(context: Context, tab: Tab, callback: () => Promise<R>): Promise<R> {
+export async function waitForCompletion<R>(tab: Tab, callback: () => Promise<R>): Promise<R> {
  const requests = new Set<playwright.Request>();
  let frameNavigated = false;
  let waitCallback: () => void = () => {};
@@ -65,7 +64,7 @@ export async function waitForCompletion<R>(context: Context, tab: Tab, callback:
    if (!requests.size && !frameNavigated)
      waitCallback();
    await waitBarrier;
-    await context.waitForTimeout(1000);
+    await tab.waitForTimeout(1000);
    return result;
  } finally {
    dispose();
--- a/src/tools/wait.ts
+++ b/src/tools/wait.ts
@@ -32,7 +32,7 @@ const wait = defineTool({
    type: 'readOnly',
  },

-  handle: async (context, params) => {
+  handle: async (context, params, response) => {
    if (!params.text && !params.textGone && !params.time)
      throw new Error('Either time, text or textGone must be provided');

@@ -57,11 +57,8 @@ const wait = defineTool({
      await locator.waitFor({ state: 'visible' });
    }

-    return {
-      code,
-      captureSnapshot: true,
-      waitForNetwork: false,
-    };
+    response.addResult(`Waited for ${params.text || params.textGone || params.time}`);
+    response.setIncludeSnapshot();
  },
 });

--- a/tests/cdp.spec.ts
+++ b/tests/cdp.spec.ts
@@ -41,17 +41,11 @@ test('cdp server reuse tab', async ({ cdpServer, startClient, server }) => {
      element: 'Hello, world!',
      ref: 'f0',
    },
-  })).toHaveTextContent(`Error: No current snapshot available. Capture a snapshot or navigate to a new location first.`);
+  })).toHaveTextContent(`Error: No open pages available. Use the \"browser_navigate\" tool to navigate to a page first.`);

  expect(await client.callTool({
    name: 'browser_snapshot',
-  })).toHaveTextContent(`
-### Ran Playwright code
-\`\`\`js
-// <internal code to capture accessibility snapshot>
-\`\`\`
-
-### Page state
+  })).toHaveTextContent(`### Page state
 - Page URL: ${server.HELLO_WORLD}
 - Page Title: Title
 - Page Snapshot:
--- a/tests/console.spec.ts
+++ b/tests/console.spec.ts
@@ -38,6 +38,7 @@ test('browser_console_messages', async ({ client, server }) => {
    name: 'browser_console_messages',
  });
  expect(resource).toHaveTextContent([
+    '### Result',
    `[LOG] Hello, world! @ ${server.PREFIX}:4`,
    `[ERROR] Error @ ${server.PREFIX}:5`,
  ].join('\n'));
--- a/tests/core.spec.ts
+++ b/tests/core.spec.ts
@@ -120,64 +120,6 @@ await page.getByRole('listbox').selectOption(['bar', 'baz']);
 `);
 });

-test('browser_type', async ({ client, server }) => {
-  server.setContent('/', `
-    <!DOCTYPE html>
-    <html>
-      <input type='keypress' onkeypress="console.log('Key pressed:', event.key, ', Text:', event.target.value)"></input>
-    </html>
-  `, 'text/html');
-
-  await client.callTool({
-    name: 'browser_navigate',
-    arguments: {
-      url: server.PREFIX,
-    },
-  });
-  await client.callTool({
-    name: 'browser_type',
-    arguments: {
-      element: 'textbox',
-      ref: 'e2',
-      text: 'Hi!',
-      submit: true,
-    },
-  });
-  expect(await client.callTool({
-    name: 'browser_console_messages',
-  })).toHaveTextContent(/\[LOG\] Key pressed: Enter , Text: Hi!/);
-});
-
-test('browser_type (slowly)', async ({ client, server }) => {
-  server.setContent('/', `
-    <input type='text' onkeydown="console.log('Key pressed:', event.key, 'Text:', event.target.value)"></input>
-  `, 'text/html');
-
-  await client.callTool({
-    name: 'browser_navigate',
-    arguments: {
-      url: server.PREFIX,
-    },
-  });
-  await client.callTool({
-    name: 'browser_type',
-    arguments: {
-      element: 'textbox',
-      ref: 'e2',
-      text: 'Hi!',
-      submit: true,
-      slowly: true,
-    },
-  });
-  const response = await client.callTool({
-    name: 'browser_console_messages',
-  });
-  expect(response).toHaveTextContent(/\[LOG\] Key pressed: H Text: /);
-  expect(response).toHaveTextContent(/\[LOG\] Key pressed: i Text: H/);
-  expect(response).toHaveTextContent(/\[LOG\] Key pressed: ! Text: Hi/);
-  expect(response).toHaveTextContent(/\[LOG\] Key pressed: Enter Text: Hi!/);
-});
-
 test('browser_resize', async ({ client, server }) => {
  server.setContent('/', `
    <title>Resize Test</title>
@@ -242,7 +184,7 @@ test('old locator error message', async ({ client, server }) => {
      element: 'Button 2',
      ref: 'e3',
    },
-  })).toContainTextContent('Ref not found');
+  })).toContainTextContent('Ref e3 not found in the current page snapshot. Try capturing new snapshot.');
 });

 test('visibility: hidden > visible should be shown', { annotation: { type: 'issue', description: 'https://github.com/microsoft/playwright-mcp/issues/535' } }, async ({ client, server }) => {
--- a/tests/dialogs.spec.ts
+++ b/tests/dialogs.spec.ts
@@ -36,7 +36,8 @@ await page.getByRole('button', { name: 'Button' }).click();
 \`\`\`

 ### Modal state
- ["alert" dialog with message "Alert"]: can be handled by the "browser_handle_dialog" tool`);
+- ["alert" dialog with message "Alert"]: can be handled by the "browser_handle_dialog" tool
+`);

  const result = await client.callTool({
    name: 'browser_handle_dialog',
@@ -46,17 +47,7 @@ await page.getByRole('button', { name: 'Button' }).click();
  });

  expect(result).not.toContainTextContent('### Modal state');
-  expect(result).toContainTextContent(`### Ran Playwright code
-\`\`\`js
-// <internal code to handle "alert" dialog>
-\`\`\`
-
-### Page state
- Page URL: ${server.PREFIX}
- Page Title: 
- Page Snapshot:
-\`\`\`yaml
- button "Button"`);
+  expect(result).toContainTextContent(`Page Snapshot:`);
 });

 test('two alert dialogs', async ({ client, server }) => {
@@ -85,7 +76,8 @@ await page.getByRole('button', { name: 'Button' }).click();
 \`\`\`

 ### Modal state
- ["alert" dialog with message "Alert 1"]: can be handled by the "browser_handle_dialog" tool`);
+- ["alert" dialog with message "Alert 1"]: can be handled by the "browser_handle_dialog" tool
+`);

  const result = await client.callTool({
    name: 'browser_handle_dialog',
@@ -94,9 +86,9 @@ await page.getByRole('button', { name: 'Button' }).click();
    },
  });

-  expect(result).toContainTextContent(`
-### Modal state
- ["alert" dialog with message "Alert 2"]: can be handled by the "browser_handle_dialog" tool`);
+  expect(result).toContainTextContent(`### Modal state
+- ["alert" dialog with message "Alert 2"]: can be handled by the "browser_handle_dialog" tool
+`);

  const result2 = await client.callTool({
    name: 'browser_handle_dialog',
@@ -138,7 +130,6 @@ test('confirm dialog (true)', async ({ client, server }) => {
  });

  expect(result).not.toContainTextContent('### Modal state');
-  expect(result).toContainTextContent('// <internal code to handle "confirm" dialog>');
  expect(result).toContainTextContent(`- Page Snapshot:
 \`\`\`yaml
 - generic [active] [ref=e1]: "true"
@@ -165,7 +156,8 @@ test('confirm dialog (false)', async ({ client, server }) => {
      ref: 'e2',
    },
  })).toContainTextContent(`### Modal state
- ["confirm" dialog with message "Confirm"]: can be handled by the "browser_handle_dialog" tool`);
+- ["confirm" dialog with message "Confirm"]: can be handled by the "browser_handle_dialog" tool
+`);

  const result = await client.callTool({
    name: 'browser_handle_dialog',
@@ -200,7 +192,8 @@ test('prompt dialog', async ({ client, server }) => {
      ref: 'e2',
    },
  })).toContainTextContent(`### Modal state
- ["prompt" dialog with message "Prompt"]: can be handled by the "browser_handle_dialog" tool`);
+- ["prompt" dialog with message "Prompt"]: can be handled by the "browser_handle_dialog" tool
+`);

  const result = await client.callTool({
    name: 'browser_handle_dialog',
@@ -236,7 +229,8 @@ await page.getByRole('button', { name: 'Button' }).click();
 \`\`\`

 ### Modal state
- ["alert" dialog with message "Alert"]: can be handled by the "browser_handle_dialog" tool`);
+- ["alert" dialog with message "Alert"]: can be handled by the "browser_handle_dialog" tool
+`);

  const result = await client.callTool({
    name: 'browser_handle_dialog',
@@ -246,12 +240,7 @@ await page.getByRole('button', { name: 'Button' }).click();
  });

  expect(result).not.toContainTextContent('### Modal state');
-  expect(result).toContainTextContent(`### Ran Playwright code
-\`\`\`js
-// <internal code to handle "alert" dialog>
-\`\`\`
-
-### Page state
+  expect(result).toContainTextContent(`### Page state
 - Page URL: ${server.PREFIX}
 - Page Title: 
 - Page Snapshot:
--- a/tests/evaluate.spec.ts
+++ b/tests/evaluate.spec.ts
@@ -47,7 +47,8 @@ test('browser_evaluate (element)', async ({ client, server }) => {
      element: 'body',
      ref: 'e1',
    },
-  })).toContainTextContent(`- Result: "red"`);
+  })).toContainTextContent(`### Result
+"red"`);
 });

 test('browser_evaluate (error)', async ({ client, server }) => {
--- a/tests/files.spec.ts
+++ b/tests/files.spec.ts
@@ -14,8 +14,8 @@
 * limitations under the License.
 */

-import { test, expect } from './fixtures.js';
 import fs from 'fs/promises';
+import { test, expect } from './fixtures.js';

 test('browser_file_upload', async ({ client, server }, testInfo) => {
  server.setContent('/', `
@@ -38,7 +38,7 @@ test('browser_file_upload', async ({ client, server }, testInfo) => {
      name: 'browser_file_upload',
      arguments: { paths: [] },
    })).toHaveTextContent(`
-The tool "browser_file_upload" can only be used when there is related modal state present.
+Error: The tool "browser_file_upload" can only be used when there is related modal state present.
 ### Modal state
 - There is no modal state present
      `.trim());
@@ -88,7 +88,7 @@ The tool "browser_file_upload" can only be used when there is related modal stat
      },
    });

-    expect(response).toContainTextContent(`Tool "browser_click" does not handle the modal state.
+    expect(response).toContainTextContent(`Error: Tool "browser_click" does not handle the modal state.
 ### Modal state
 - [File chooser]: can be handled by the "browser_file_upload" tool`);
  }
@@ -113,8 +113,7 @@ test('clicking on download link emits download', async ({ startClient, server, m
      ref: 'e2',
    },
  });
-  await expect.poll(() => client.callTool({ name: 'browser_snapshot' })).toContainTextContent(`
-### Downloads
+  await expect.poll(() => client.callTool({ name: 'browser_snapshot' })).toContainTextContent(`### Downloads
 - Downloaded file test.txt to ${testInfo.outputPath('output', 'test.txt')}`);
 });

@@ -123,7 +122,7 @@ test('navigating to download link emits download', async ({ startClient, server,
    config: { outputDir: testInfo.outputPath('output') },
  });

-  test.skip(mcpBrowser === 'webkit' && process.platform === 'linux', 'https://github.com/microsoft/playwright/blob/8e08fdb52c27bb75de9bf87627bf740fadab2122/tests/library/download.spec.ts#L436');
+  test.skip(mcpBrowser !== 'chromium', 'This test is racy');
  server.route('/download', (req, res) => {
    res.writeHead(200, {
      'Content-Type': 'text/plain',
--- a/tests/install.spec.ts
+++ b/tests/install.spec.ts
@@ -20,5 +20,5 @@ test('browser_install', async ({ client, mcpBrowser }) => {
  test.skip(mcpBrowser !== 'chromium', 'Test only chromium');
  expect(await client.callTool({
    name: 'browser_install',
-  })).toContainTextContent(`No open pages available.`);
+  })).toContainTextContent(`### No open tabs`);
 });
--- a/tests/launch.spec.ts
+++ b/tests/launch.spec.ts
@@ -27,7 +27,13 @@ test('test reopen browser', async ({ startClient, server, mcpMode }) => {

  expect(await client.callTool({
    name: 'browser_close',
-  })).toContainTextContent('No open pages available');
+  })).toContainTextContent(`### Ran Playwright code
+\`\`\`js
+await page.close()
+\`\`\`
+
+### No open tabs
+Use the "browser_navigate" tool to navigate to a page first.`);

  expect(await client.callTool({
    name: 'browser_navigate',
--- a/tests/library.spec.ts
+++ b/tests/library.spec.ts
@@ -13,9 +13,9 @@
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */
+import child_process from 'child_process';
+import fs from 'fs/promises';
 import { test, expect } from './fixtures.js';
-import fs from 'node:fs/promises';
-import child_process from 'node:child_process';

 test('library can be used from CommonJS', { annotation: { type: 'issue', description: 'https://github.com/microsoft/playwright-mcp/issues/456' } }, async ({}, testInfo) => {
  const file = testInfo.outputPath('main.cjs');
--- a/tests/network.spec.ts
+++ b/tests/network.spec.ts
@@ -40,6 +40,7 @@ test('browser_network_requests', async ({ client, server }) => {

  await expect.poll(() => client.callTool({
    name: 'browser_network_requests',
-  })).toHaveTextContent(`[GET] ${`${server.PREFIX}`} => [200] OK
+  })).toHaveTextContent(`### Result
+[GET] ${`${server.PREFIX}`} => [200] OK
 [GET] ${`${server.PREFIX}json`} => [200] OK`);
 });
--- a/tests/pdf.spec.ts
+++ b/tests/pdf.spec.ts
@@ -65,14 +65,7 @@ test('save as pdf (filename: output.pdf)', async ({ startClient, mcpBrowser, ser
    arguments: {
      filename: 'output.pdf',
    },
-  })).toEqual({
-    content: [
-      {
-        type: 'text',
-        text: expect.stringContaining(`output.pdf`),
-      },
-    ],
-  });
+  })).toContainTextContent(`output.pdf`);

  const files = [...fs.readdirSync(outputDir)];

--- a/tests/screenshot.spec.ts
+++ b/tests/screenshot.spec.ts
@@ -31,15 +31,15 @@ test('browser_take_screenshot (viewport)', async ({ startClient, server }, testI
    name: 'browser_take_screenshot',
  })).toEqual({
    content: [
+      {
+        text: expect.stringContaining(`Screenshot viewport and save it as`),
+        type: 'text',
+      },
      {
        data: expect.any(String),
        mimeType: 'image/jpeg',
        type: 'image',
      },
-      {
-        text: expect.stringContaining(`Screenshot viewport and save it as`),
-        type: 'text',
-      },
    ],
  });
 });
@@ -61,15 +61,15 @@ test('browser_take_screenshot (element)', async ({ startClient, server }, testIn
    },
  })).toEqual({
    content: [
+      {
+        text: expect.stringContaining(`page.getByText('Hello, world!').screenshot`),
+        type: 'text',
+      },
      {
        data: expect.any(String),
        mimeType: 'image/jpeg',
        type: 'image',
      },
-      {
-        text: expect.stringContaining(`page.getByText('Hello, world!').screenshot`),
-        type: 'text',
-      },
    ],
  });
 });
@@ -111,17 +111,17 @@ for (const raw of [undefined, true]) {
      arguments: { raw },
    })).toEqual({
      content: [
-        {
-          data: expect.any(String),
-          mimeType: `image/${ext}`,
-          type: 'image',
-        },
        {
          text: expect.stringMatching(
              new RegExp(`page-\\d{4}-\\d{2}-\\d{2}T\\d{2}-\\d{2}-\\d{2}\\-\\d{3}Z\\.${ext}`)
          ),
          type: 'text',
        },
+        {
+          data: expect.any(String),
+          mimeType: `image/${ext}`,
+          type: 'image',
+        },
      ],
    });

@@ -153,15 +153,15 @@ test('browser_take_screenshot (filename: "output.jpeg")', async ({ startClient,
    },
  })).toEqual({
    content: [
+      {
+        text: expect.stringContaining(`output.jpeg`),
+        type: 'text',
+      },
      {
        data: expect.any(String),
        mimeType: 'image/jpeg',
        type: 'image',
      },
-      {
-        text: expect.stringContaining(`output.jpeg`),
-        type: 'text',
-      },
    ],
  });

@@ -216,15 +216,15 @@ test('browser_take_screenshot (fullPage: true)', async ({ startClient, server },
    arguments: { fullPage: true },
  })).toEqual({
    content: [
+      {
+        text: expect.stringContaining(`Screenshot full page and save it as`),
+        type: 'text',
+      },
      {
        data: expect.any(String),
        mimeType: 'image/jpeg',
        type: 'image',
      },
-      {
-        text: expect.stringContaining(`Screenshot full page and save it as`),
-        type: 'text',
-      },
    ],
  });
 });
@@ -250,3 +250,31 @@ test('browser_take_screenshot (fullPage with element should error)', async ({ st
  expect(result.isError).toBe(true);
  expect(result.content?.[0]?.text).toContain('fullPage cannot be used with element screenshots');
 });
+
+test('browser_take_screenshot (viewport without snapshot)', async ({ startClient, server }, testInfo) => {
+  const { client } = await startClient({
+    config: { outputDir: testInfo.outputPath('output') },
+  });
+
+  // Ensure we have a tab but don't navigate anywhere (no snapshot captured)
+  expect(await client.callTool({
+    name: 'browser_tab_list',
+  })).toContainTextContent('about:blank');
+
+  // This should work without requiring a snapshot since it's a viewport screenshot
+  expect(await client.callTool({
+    name: 'browser_take_screenshot',
+  })).toEqual({
+    content: [
+      {
+        text: expect.stringContaining(`Screenshot viewport and save it as`),
+        type: 'text',
+      },
+      {
+        data: expect.any(String),
+        mimeType: 'image/jpeg',
+        type: 'image',
+      },
+    ],
+  });
+});
--- a/tests/tabs.spec.ts
+++ b/tests/tabs.spec.ts
@@ -44,12 +44,14 @@ test('list first tab', async ({ client }) => {
 });

 test('create new tab', async ({ client }) => {
-  expect(await createTab(client, 'Tab one', 'Body one')).toContainTextContent(`
-### Open tabs
+  const result = await createTab(client, 'Tab one', 'Body one');
+  expect(result).toContainTextContent(`### Open tabs
 - 0: [] (about:blank)
 - 1: (current) [Tab one] (data:text/html,<title>Tab one</title><body>Body one</body>)
+`);

-### Current tab
+  expect(result).toContainTextContent(`
+### Page state
 - Page URL: data:text/html,<title>Tab one</title><body>Body one</body>
 - Page Title: Tab one
 - Page Snapshot:
@@ -57,13 +59,15 @@ test('create new tab', async ({ client }) => {
 - generic [active] [ref=e1]: Body one
 \`\`\``);

-  expect(await createTab(client, 'Tab two', 'Body two')).toContainTextContent(`
-### Open tabs
+  const result2 = await createTab(client, 'Tab two', 'Body two');
+  expect(result2).toContainTextContent(`### Open tabs
 - 0: [] (about:blank)
 - 1: [Tab one] (data:text/html,<title>Tab one</title><body>Body one</body>)
 - 2: (current) [Tab two] (data:text/html,<title>Tab two</title><body>Body two</body>)
+`);

-### Current tab
+  expect(result2).toContainTextContent(`
+### Page state
 - Page URL: data:text/html,<title>Tab two</title><body>Body two</body>
 - Page Title: Tab two
 - Page Snapshot:
@@ -75,23 +79,20 @@ test('create new tab', async ({ client }) => {
 test('select tab', async ({ client }) => {
  await createTab(client, 'Tab one', 'Body one');
  await createTab(client, 'Tab two', 'Body two');
-  expect(await client.callTool({
+
+  const result = await client.callTool({
    name: 'browser_tab_select',
    arguments: {
      index: 1,
    },
-  })).toHaveTextContent(`
-### Ran Playwright code
-\`\`\`js
-// <internal code to select tab 1>
-\`\`\`
-
-### Open tabs
+  });
+  expect(result).toContainTextContent(`### Open tabs
 - 0: [] (about:blank)
 - 1: (current) [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>)
+- 2: [Tab two] (data:text/html,<title>Tab two</title><body>Body two</body>)`);

-### Current tab
+  expect(result).toContainTextContent(`
+### Page state
 - Page URL: data:text/html,<title>Tab one</title><body>Body one</body>
 - Page Title: Tab one
 - Page Snapshot:
@@ -103,22 +104,19 @@ test('select tab', async ({ client }) => {
 test('close tab', async ({ client }) => {
  await createTab(client, 'Tab one', 'Body one');
  await createTab(client, 'Tab two', 'Body two');
-  expect(await client.callTool({
+
+  const result = await client.callTool({
    name: 'browser_tab_close',
    arguments: {
      index: 2,
    },
-  })).toHaveTextContent(`
-### Ran Playwright code
-\`\`\`js
-// <internal code to close tab 2>
-\`\`\`
-
-### Open tabs
+  });
+  expect(result).toContainTextContent(`### Open tabs
 - 0: [] (about:blank)
- 1: (current) [Tab one] (data:text/html,<title>Tab one</title><body>Body one</body>)
+- 1: (current) [Tab one] (data:text/html,<title>Tab one</title><body>Body one</body>)`);

-### Current tab
+  expect(result).toContainTextContent(`
+### Page state
 - Page URL: data:text/html,<title>Tab one</title><body>Body one</body>
 - Page Title: Tab one
 - Page Snapshot:
--- a/tests/type.spec.ts
+++ b/tests/type.spec.ts
@@ -0,0 +1,119 @@
+/**
+ * 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_type', async ({ client, server }) => {
+  server.setContent('/', `
+    <!DOCTYPE html>
+    <html>
+      <input type='keypress' onkeypress="console.log('Key pressed:', event.key, ', Text:', event.target.value)"></input>
+    </html>
+  `, 'text/html');
+
+  await client.callTool({
+    name: 'browser_navigate',
+    arguments: {
+      url: server.PREFIX,
+    },
+  });
+
+  {
+    const response = await client.callTool({
+      name: 'browser_type',
+      arguments: {
+        element: 'textbox',
+        ref: 'e2',
+        text: 'Hi!',
+        submit: true,
+      },
+    });
+    expect(response).toContainTextContent(`fill('Hi!');`);
+    expect(response).toContainTextContent(`- textbox`);
+  }
+
+  expect(await client.callTool({
+    name: 'browser_console_messages',
+  })).toHaveTextContent(/\[LOG\] Key pressed: Enter , Text: Hi!/);
+});
+
+test('browser_type (slowly)', async ({ client, server }) => {
+  server.setContent('/', `
+    <input type='text' onkeydown="console.log('Key pressed:', event.key, 'Text:', event.target.value)"></input>
+  `, 'text/html');
+
+  await client.callTool({
+    name: 'browser_navigate',
+    arguments: {
+      url: server.PREFIX,
+    },
+  });
+  {
+    const response = await client.callTool({
+      name: 'browser_type',
+      arguments: {
+        element: 'textbox',
+        ref: 'e2',
+        text: 'Hi!',
+        slowly: true,
+      },
+    });
+
+    expect(response).toContainTextContent(`pressSequentially('Hi!');`);
+    expect(response).toContainTextContent(`- textbox`);
+  }
+  const response = await client.callTool({
+    name: 'browser_console_messages',
+  });
+  expect(response).toHaveTextContent(/\[LOG\] Key pressed: H Text: /);
+  expect(response).toHaveTextContent(/\[LOG\] Key pressed: i Text: H/);
+  expect(response).toHaveTextContent(/\[LOG\] Key pressed: ! Text: Hi/);
+});
+
+test('browser_type (no submit)', async ({ client, server }) => {
+  server.setContent('/', `
+    <input type='text' oninput="console.log('New value: ' + event.target.value)"></input>
+  `, 'text/html');
+
+  {
+    const response = await client.callTool({
+      name: 'browser_navigate',
+      arguments: {
+        url: server.PREFIX,
+      },
+    });
+    expect(response).toContainTextContent(`- textbox`);
+  }
+  {
+    const response = await client.callTool({
+      name: 'browser_type',
+      arguments: {
+        element: 'textbox',
+        ref: 'e2',
+        text: 'Hi!',
+      },
+    });
+    expect(response).toContainTextContent(`fill('Hi!');`);
+    // Should yield no snapshot.
+    expect(response).not.toContainTextContent(`- textbox`);
+  }
+  {
+    const response = await client.callTool({
+      name: 'browser_console_messages',
+    });
+    expect(response).toHaveTextContent(/\[LOG\] New value: Hi!/);
+  }
+});
Author	SHA1	Message	Date
Pavel Feldman	04988d8fac	chore: mark v0.0.32 (#768 )	2025-07-25 16:40:31 -07:00
Pavel Feldman	2bf57e22c6	chore: do not snapshot on fill (#767 )	2025-07-25 15:54:18 -07:00
Yury Semikhatsky	dbf113d5e4	chore(extension): reject second http connection (#766 )	2025-07-25 14:46:48 -07:00
Pavel Feldman	6710a78641	Revert "chore: recommend sse by default" (#765 ) Reverts microsoft/playwright-mcp#758 Sounds like the stock streamable implementation is to spec, so we can keep it.	2025-07-25 12:18:02 -07:00
Pavel Feldman	a9b9fb85da	chore: ping client and disconnect on connection termination (#764 )	2025-07-25 12:17:51 -07:00
Yury Semikhatsky	26a2a6fc83	chore: recommend sse by default (#758 )	2025-07-25 09:51:01 -07:00
Pavel Feldman	e934d5e23e	chore: retain the source code from the underlying tools (#756 )	2025-07-24 17:08:35 -07:00
Pavel Feldman	ecfa10448b	chore: extract loop tools into a separate folder (#755 )	2025-07-24 16:22:03 -07:00
Yury Semikhatsky	e153ac3b7c	chore(extension): exit gracefully when waiting for extension connection (#754 )	2025-07-24 16:02:02 -07:00
Pavel Feldman	e0fb748ccc	chore: wire one tool in-process (#753 )	2025-07-24 15:25:32 -07:00
Pavel Feldman	c63b7823e1	chore: extract pure mcp server helpers (#751 )	2025-07-24 12:57:01 -07:00
Yury Semikhatsky	bd34e9d7e9	chore(extension): page selector for MCP (#750 )	2025-07-24 12:01:35 -07:00
Yury Semikhatsky	c72d0320f4	chore(extension): use free port (#735 )	2025-07-24 10:25:13 -07:00
Pavel Feldman	da8a244f33	chore: one tool experiment (#746 )	2025-07-24 10:09:01 -07:00
Pavel Feldman	31a4fb3d07	chore: unify loops (#745 )	2025-07-23 17:42:53 -07:00
Yury Semikhatsky	bc120baa78	chore: do not double close connection (#744 )	2025-07-23 17:41:15 -07:00
Pavel Feldman	2c5eac89a8	chore: add eval script (#743 )	2025-07-23 10:31:37 -07:00
christian-lms	288f1b863b	docs: Add LM Studio installation instructions (#688 )	2025-07-23 08:22:13 -07:00
Yury Semikhatsky	53e3e37991	chore(extension): terminate all connections when tab closes (#741 )	2025-07-22 22:23:00 -07:00
Pavel Feldman	b1a0f775cf	chore: save session log (#740 )	2025-07-22 20:06:03 -07:00
Pavel Feldman	6320b08173	chore: follow up on tab snapshot capture (#739 )	2025-07-22 17:43:42 -07:00
Pavel Feldman	601a74305c	chore: introduce response type (#738 )	2025-07-22 16:36:21 -07:00
Yury Semikhatsky	c2b98dc70b	chore(extension): handle root session id in the relay (#737 )	2025-07-22 13:49:39 -07:00
Yury Semikhatsky	70862ce456	chore(extension): propagate errors to the client (#736 )	2025-07-22 13:13:27 -07:00
Pavel Feldman	468c84eb8f	chore: move state to tab, do not cache snapshot (#730 )	2025-07-22 07:53:33 -07:00
Yury Semikhatsky	cfcca40b90	chore(extension): find installed chrome (#728 )	2025-07-21 17:57:38 -07:00
Pavel Feldman	f1826b96b6	chore: align lint w/ playwright (#729 )	2025-07-21 17:07:13 -07:00
Copilot	eeeab4f042	fix: browser_take_screenshot to not require snapshot unless element is specified (#725 )	2025-07-21 10:52:06 -07:00
				`@@ -0,0 +1 @@`
				`- Generic MCP utils, no dependencies on Playwright here.`