chore: mark v0.0.32 (#768)

Reverts microsoft/playwright-mcp#758

Sounds like the stock streamable implementation is to spec, so we can
keep it.

.github/workflows/ci.yml

@@ -30,31 +30,56 @@ jobs:
       matrix:
         os: [ubuntu-latest, macos-latest, windows-latest]
     runs-on: ${{ matrix.os }}
-
     steps:
     - uses: actions/checkout@v4
+    - name: Use Node.js 18
+      uses: actions/setup-node@v4
+      with:
+        # https://github.com/microsoft/playwright-mcp/issues/344
+        node-version: '18.19'
+        cache: 'npm'
+    - name: Install dependencies
+      run: npm ci
+    - name: Playwright install
+      run: npx playwright install --with-deps
+    - name: Install MS Edge
+      # MS Edge is not preinstalled on macOS runners.
+      if: ${{ matrix.os == 'macos-latest' }}
+      run: npx playwright install msedge
+    - name: Build
+      run: npm run build
+    - name: Run tests
+      run: npm test
 
+  test_docker:
+    runs-on: ubuntu-latest
+    steps:
+    - uses: actions/checkout@v4
     - name: Use Node.js 18
       uses: actions/setup-node@v4
       with:
         node-version: '18'
         cache: 'npm'
-
     - name: Install dependencies
       run: npm ci
-
     - name: Playwright install
-      run: npx playwright install --with-deps
-
-    - name: Install MS Edge
-      if: ${{ matrix.os == 'macos-latest' }} # MS Edge is not preinstalled on macOS runners.
-      run: npx playwright install msedge
-
+      run: npx playwright install --with-deps chromium
     - name: Build
       run: npm run build
-
-    - name: Install Playwright browsers
-      run: npx playwright install --with-deps
-
+    - name: Set up Docker Buildx
+      uses: docker/setup-buildx-action@v3
+    - name: Build and push
+      uses: docker/build-push-action@v6
+      with:
+        tags: playwright-mcp-dev:latest
+        cache-from: type=gha
+        cache-to: type=gha,mode=max
+        load: true
     - name: Run tests
-      run: npm test -- --forbid-only
+      shell: bash
+      run: |
+        # Used for the Docker tests to share the test-results folder with the container.
+        umask 0000
+        npm run test -- --project=chromium-docker
+      env:
+        MCP_IN_DOCKER: 1

.github/workflows/copilot-setup-steps.yml

@@ -0,0 +1,44 @@
+name: "Copilot Setup Steps"
+
+# Automatically run the setup steps when they are changed to allow for easy validation, and
+# allow manual testing through the repository's "Actions" tab
+on:
+  workflow_dispatch:
+  push:
+    paths:
+      - .github/workflows/copilot-setup-steps.yml
+  pull_request:
+    paths:
+      - .github/workflows/copilot-setup-steps.yml
+
+jobs:
+  # The job MUST be called `copilot-setup-steps` or it will not be picked up by Copilot.
+  copilot-setup-steps:
+    runs-on: ubuntu-latest
+
+    # Set the permissions to the lowest permissions possible needed for your steps.
+    # Copilot will be given its own token for its operations.
+    permissions:
+      # If you want to clone the repository as part of your setup steps, for example to install dependencies, you'll need the `contents: read` permission. If you don't clone the repository in your setup steps, Copilot will do this for you automatically after the steps complete.
+      contents: read
+
+    # You can define any steps you want, and they will run before the agent starts.
+    # If you do not check out your code, Copilot will do this for you.
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Set up Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: "18.19"
+          cache: "npm"
+
+      - name: Install JavaScript dependencies
+        run: npm ci
+
+      - name: Playwright install
+        run: npx playwright install --with-deps
+
+      - name: Build
+        run: npm run build

.github/workflows/publish.yml

@@ -7,7 +7,7 @@ jobs:
     runs-on: ubuntu-latest
     permissions:
       contents: read
-      id-token: write
+      id-token: write # Needed for npm provenance
     steps:
       - uses: actions/checkout@v4
       - uses: actions/setup-node@v4
@@ -21,4 +21,50 @@ jobs:
       - run: npm run ctest
       - run: npm publish --provenance
         env:
-          NODE_AUTH_TOKEN: ${{secrets.NPM_TOKEN}}
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
+
+  publish-docker:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      id-token: write # Needed for OIDC login to Azure
+    environment: allow-publishing-docker-to-acr
+    steps:
+      - uses: actions/checkout@v4
+      - name: Set up QEMU # Needed for multi-platform builds (e.g., arm64 on amd64 runner)
+        uses: docker/setup-qemu-action@v3
+      - name: Set up Docker Buildx # Needed for multi-platform builds
+        uses: docker/setup-buildx-action@v3
+      - name: Azure Login via OIDC
+        uses: azure/login@v2
+        with:
+          client-id: ${{ secrets.AZURE_DOCKER_CLIENT_ID }}
+          tenant-id: ${{ secrets.AZURE_DOCKER_TENANT_ID }}
+          subscription-id: ${{ secrets.AZURE_DOCKER_SUBSCRIPTION_ID }}
+      - name: Login to ACR
+        run: az acr login --name playwright
+      - name: Build and push Docker image
+        id: build-push
+        uses: docker/build-push-action@v6
+        with:
+          context: .
+          file: ./Dockerfile # Adjust path if your Dockerfile is elsewhere
+          platforms: linux/amd64,linux/arm64
+          push: true
+          tags: |
+            playwright.azurecr.io/public/playwright/mcp:${{ github.event.release.tag_name }}
+            playwright.azurecr.io/public/playwright/mcp:latest
+      - uses: oras-project/setup-oras@v1
+      - name: Set oras tags
+        run: |
+          attach_eol_manifest() {
+            local image="$1"
+            local today=$(date -u +'%Y-%m-%d')
+            # oras is re-using Docker credentials, so we don't need to login.
+            # Following the advice in https://portal.microsofticm.com/imp/v3/incidents/incident/476783820/summary
+            oras attach --artifact-type application/vnd.microsoft.artifact.lifecycle --annotation "vnd.microsoft.artifact.lifecycle.end-of-life.date=$today" $image
+          }
+          # for each tag, attach the eol manifest
+          for tag in $(echo ${{ steps.build-push.outputs.metadata['image.name'] }} | tr ',' '\n'); do
+            attach_eol_manifest $tag
+          done

.gitignore

@@ -3,6 +3,7 @@ node_modules/
 test-results/
 playwright-report/
 .vscode/mcp.json
-
 .idea
 .DS_Store
+.env
+sessions/

Dockerfile

@@ -1,22 +1,69 @@
-FROM node:22-bookworm-slim
+ARG PLAYWRIGHT_BROWSERS_PATH=/ms-playwright
+
+# ------------------------------
+# Base
+# ------------------------------
+# Base stage: Contains only the minimal dependencies required for runtime
+# (node_modules and Playwright system dependencies)
+FROM node:22-bookworm-slim AS base
+
+ARG PLAYWRIGHT_BROWSERS_PATH
+ENV PLAYWRIGHT_BROWSERS_PATH=${PLAYWRIGHT_BROWSERS_PATH}
 
 # Set the working directory
 WORKDIR /app
 
-# Copy package.json and package-lock.json at this stage to leverage the build cache
-COPY package*.json ./
+RUN --mount=type=cache,target=/root/.npm,sharing=locked,id=npm-cache \
+    --mount=type=bind,source=package.json,target=package.json \
+    --mount=type=bind,source=package-lock.json,target=package-lock.json \
+  npm ci --omit=dev && \
+  # Install system dependencies for playwright
+  npx -y playwright-core install-deps chromium
 
-# Install dependencies
-RUN npm ci
+# ------------------------------
+# Builder
+# ------------------------------
+FROM base AS builder
 
-# Install chromium and its dependencies, but only for headless mode
-RUN npx -y playwright install --with-deps --only-shell chromium
+RUN --mount=type=cache,target=/root/.npm,sharing=locked,id=npm-cache \
+    --mount=type=bind,source=package.json,target=package.json \
+    --mount=type=bind,source=package-lock.json,target=package-lock.json \
+  npm ci
 
 # Copy the rest of the app
-COPY . .
+COPY *.json *.js *.ts .
+COPY src src/
 
 # Build the app
 RUN npm run build
 
+# ------------------------------
+# Browser
+# ------------------------------
+# Cache optimization:
+# - Browser is downloaded only when node_modules or Playwright system dependencies change
+# - Cache is reused when only source code changes
+FROM base AS browser
+
+RUN npx -y playwright-core install --no-shell chromium
+
+# ------------------------------
+# Runtime
+# ------------------------------
+FROM base
+
+ARG PLAYWRIGHT_BROWSERS_PATH
+ARG USERNAME=node
+ENV NODE_ENV=production
+
+# Set the correct ownership for the runtime user on production `node_modules`
+RUN chown -R ${USERNAME}:${USERNAME} node_modules
+
+USER ${USERNAME}
+
+COPY --from=browser --chown=${USERNAME}:${USERNAME} ${PLAYWRIGHT_BROWSERS_PATH} ${PLAYWRIGHT_BROWSERS_PATH}
+COPY --chown=${USERNAME}:${USERNAME} cli.js package.json ./
+COPY --from=builder --chown=${USERNAME}:${USERNAME} /app/lib /app/lib
+
 # Run in headless and only with chromium (other browsers need more dependencies not included in this image)
-ENTRYPOINT ["node", "cli.js", "--headless", "--browser", "chromium"]
+ENTRYPOINT ["node", "cli.js", "--headless", "--browser", "chromium", "--no-sandbox"]

README.md

@@ -4,25 +4,24 @@ A Model Context Protocol (MCP) server that provides browser automation capabilit
 
 ### Key Features
 
-- **Fast and lightweight**: Uses Playwright's accessibility tree, not pixel-based input.
-- **LLM-friendly**: No vision models needed, operates purely on structured data.
-- **Deterministic tool application**: Avoids ambiguity common with screenshot-based approaches.
+- **Fast and lightweight**. Uses Playwright's accessibility tree, not pixel-based input.
+- **LLM-friendly**. No vision models needed, operates purely on structured data.
+- **Deterministic tool application**. Avoids ambiguity common with screenshot-based approaches.
 
-### Use Cases
-
-- Web navigation and form-filling
-- Data extraction from structured content
-- Automated testing driven by LLMs
-- General-purpose browser interaction for agents
+### Requirements
+- Node.js 18 or newer
+- VS Code, Cursor, Windsurf, Claude Desktop, Goose or any other MCP client
 
 <!--
 // Generate using:
 node utils/generate-links.js
 -->
 
-[<img src="https://img.shields.io/badge/VS_Code-VS_Code?style=flat-square&label=Install%20Server&color=0098FF" alt="Install in VS Code">](https://insiders.vscode.dev/redirect?url=vscode%3Amcp%2Finstall%3F%257B%2522name%2522%253A%2522playwright%2522%252C%2522command%2522%253A%2522npx%2522%252C%2522args%2522%253A%255B%2522%2540playwright%252Fmcp%2540latest%2522%255D%257D) [<img alt="Install in VS Code Insiders" src="https://img.shields.io/badge/VS_Code_Insiders-VS_Code_Insiders?style=flat-square&label=Install%20Server&color=24bfa5">](https://insiders.vscode.dev/redirect?url=vscode-insiders%3Amcp%2Finstall%3F%257B%2522name%2522%253A%2522playwright%2522%252C%2522command%2522%253A%2522npx%2522%252C%2522args%2522%253A%255B%2522%2540playwright%252Fmcp%2540latest%2522%255D%257D)
+### Getting started
 
-### Example config
+First, install the Playwright MCP server with your client.
+
+**Standard config** works in most of the tools:
 
 ```js
 {
@@ -37,20 +36,88 @@ node utils/generate-links.js
 }
 ```
 
-### Table of Contents
+[<img src="https://img.shields.io/badge/VS_Code-VS_Code?style=flat-square&label=Install%20Server&color=0098FF" alt="Install in VS Code">](https://insiders.vscode.dev/redirect?url=vscode%3Amcp%2Finstall%3F%257B%2522name%2522%253A%2522playwright%2522%252C%2522command%2522%253A%2522npx%2522%252C%2522args%2522%253A%255B%2522%2540playwright%252Fmcp%2540latest%2522%255D%257D) [<img alt="Install in VS Code Insiders" src="https://img.shields.io/badge/VS_Code_Insiders-VS_Code_Insiders?style=flat-square&label=Install%20Server&color=24bfa5">](https://insiders.vscode.dev/redirect?url=vscode-insiders%3Amcp%2Finstall%3F%257B%2522name%2522%253A%2522playwright%2522%252C%2522command%2522%253A%2522npx%2522%252C%2522args%2522%253A%255B%2522%2540playwright%252Fmcp%2540latest%2522%255D%257D)
 
-- [Installation in VS Code](#installation-in-vs-code)
-- [Command line](#command-line)
-- [User profile](#user-profile)
-- [Configuration file](#configuration-file)
-- [Running on Linux](#running-on-linux)
-- [Docker](#docker)
-- [Programmatic usage](#programmatic-usage)
-- [Tool modes](#tool-modes)
 
-### Installation in VS Code
+<details>
+<summary>Claude Code</summary>
 
-You can install the Playwright MCP server using the VS Code CLI:
+Use the Claude Code CLI to add the Playwright MCP server:
+
+```bash
+claude mcp add playwright npx @playwright/mcp@latest
+```
+</details>
+
+<details>
+<summary>Claude Desktop</summary>
+
+Follow the MCP install [guide](https://modelcontextprotocol.io/quickstart/user), use the standard config above.
+
+</details>
+
+<details>
+<summary>Cursor</summary>
+
+#### Click the button to install:
+
+[![Install MCP Server](https://cursor.com/deeplink/mcp-install-dark.svg)](https://cursor.com/install-mcp?name=playwright&config=eyJjb21tYW5kIjoibnB4IEBwbGF5d3JpZ2h0L21jcEBsYXRlc3QifQ%3D%3D)
+
+#### Or install manually:
+
+Go to `Cursor Settings` -> `MCP` -> `Add new MCP Server`. Name to your liking, use `command` type with the command `npx @playwright/mcp`. You can also verify config or add command like arguments via clicking `Edit`.
+
+</details>
+
+<details>
+<summary>Gemini CLI</summary>
+
+Follow the MCP install [guide](https://github.com/google-gemini/gemini-cli/blob/main/docs/tools/mcp-server.md#configure-the-mcp-server-in-settingsjson), use the standard config above.
+
+</details>
+
+<details>
+<summary>Goose</summary>
+
+#### Click the button to install:
+
+[![Install in Goose](https://block.github.io/goose/img/extension-install-dark.svg)](https://block.github.io/goose/extension?cmd=npx&arg=%40playwright%2Fmcp%40latest&id=playwright&name=Playwright&description=Interact%20with%20web%20pages%20through%20structured%20accessibility%20snapshots%20using%20Playwright)
+
+#### Or install manually:
+
+Go to `Advanced settings` -> `Extensions` -> `Add custom extension`. Name to your liking, use type `STDIO`, and set the `command` to `npx @playwright/mcp`. Click "Add Extension".
+</details>
+
+<details>
+<summary>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>
+
+Open [Qodo Gen](https://docs.qodo.ai/qodo-documentation/qodo-gen) chat panel in VSCode or IntelliJ → Connect more tools → + Add new MCP → Paste the standard config above.
+
+Click <code>Save</code>.
+</details>
+
+<details>
+<summary>VS Code</summary>
+
+#### Click the button to install:
+
+[<img src="https://img.shields.io/badge/VS_Code-VS_Code?style=flat-square&label=Install%20Server&color=0098FF" alt="Install in VS Code">](https://insiders.vscode.dev/redirect?url=vscode%3Amcp%2Finstall%3F%257B%2522name%2522%253A%2522playwright%2522%252C%2522command%2522%253A%2522npx%2522%252C%2522args%2522%253A%255B%2522%2540playwright%252Fmcp%2540latest%2522%255D%257D) [<img alt="Install in VS Code Insiders" src="https://img.shields.io/badge/VS_Code_Insiders-VS_Code_Insiders?style=flat-square&label=Install%20Server&color=24bfa5">](https://insiders.vscode.dev/redirect?url=vscode-insiders%3Amcp%2Finstall%3F%257B%2522name%2522%253A%2522playwright%2522%252C%2522command%2522%253A%2522npx%2522%252C%2522args%2522%253A%255B%2522%2540playwright%252Fmcp%2540latest%2522%255D%257D)
+
+#### Or install manually:
+
+Follow the MCP install [guide](https://code.visualstudio.com/docs/copilot/chat/mcp-servers#_add-an-mcp-server), use the standard config above. You can also install the Playwright MCP server using the VS Code CLI:
 
 ```bash
 # For VS Code
@@ -58,42 +125,123 @@ code --add-mcp '{"name":"playwright","command":"npx","args":["@playwright/mcp@la
 ```
 
 After installation, the Playwright MCP server will be available for use with your GitHub Copilot agent in VS Code.
+</details>
 
-### Command line
+<details>
+<summary>Windsurf</summary>
 
-The Playwright MCP server supports the following command-line options:
+Follow Windsurf MCP [documentation](https://docs.windsurf.com/windsurf/cascade/mcp). Use the standard config above.
 
-- `--browser <browser>`: Browser or chrome channel to use. Possible values:
-  - `chrome`, `firefox`, `webkit`, `msedge`
-  - Chrome channels: `chrome-beta`, `chrome-canary`, `chrome-dev`
-  - Edge channels: `msedge-beta`, `msedge-canary`, `msedge-dev`
-  - Default: `chrome`
-- `--caps <caps>`: Comma-separated list of capabilities to enable, possible values: tabs, pdf, history, wait, files, install. Default is all.
-- `--cdp-endpoint <endpoint>`: CDP endpoint to connect to
-- `--executable-path <path>`: Path to the browser executable
-- `--headless`: Run browser in headless mode (headed by default)
-- `--device`: Emulate mobile device
-- `--user-data-dir <path>`: Path to the user data directory
-- `--port <port>`: Port to listen on for SSE transport
-- `--host <host>`: Host to bind server to. Default is localhost. Use 0.0.0.0 to bind to all interfaces.
-- `--vision`: Run server that uses screenshots (Aria snapshots are used by default)
-- `--config <path>`: Path to the configuration file
+</details>
+
+### Configuration
+
+Playwright MCP server supports following arguments. They can be provided in the JSON configuration above, as a part of the `"args"` list:
+
+<!--- Options generated by update-readme.js -->
+
+```
+> npx @playwright/mcp@latest --help
+  --allowed-origins <origins>  semicolon-separated list of origins to allow the
+                               browser to request. Default is to allow all.
+  --blocked-origins <origins>  semicolon-separated list of origins to block the
+                               browser from requesting. Blocklist is evaluated
+                               before allowlist. If used without the allowlist,
+                               requests not matching the blocklist are still
+                               allowed.
+  --block-service-workers      block service workers
+  --browser <browser>          browser or chrome channel to use, possible
+                               values: chrome, firefox, webkit, msedge.
+  --caps <caps>                comma-separated list of additional capabilities
+                               to enable, possible values: vision, pdf.
+  --cdp-endpoint <endpoint>    CDP endpoint to connect to.
+  --config <path>              path to the configuration file.
+  --device <device>            device to emulate, for example: "iPhone 15"
+  --executable-path <path>     path to the browser executable.
+  --headless                   run browser in headless mode, headed by default
+  --host <host>                host to bind server to. Default is localhost. Use
+                               0.0.0.0 to bind to all interfaces.
+  --ignore-https-errors        ignore https errors
+  --isolated                   keep the browser profile in memory, do not save
+                               it to disk.
+  --image-responses <mode>     whether to send image responses to the client.
+                               Can be "allow" or "omit", Defaults to "allow".
+  --no-sandbox                 disable the sandbox for all process types that
+                               are normally sandboxed.
+  --output-dir <path>          path to the directory for output files.
+  --port <port>                port to listen on for SSE transport.
+  --proxy-bypass <bypass>      comma-separated domains to bypass proxy, for
+                               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
+                               sessions.
+  --user-agent <ua string>     specify user agent string
+  --user-data-dir <path>       path to the user data directory. If not
+                               specified, a temporary directory will be created.
+  --viewport-size <size>       specify browser viewport size in pixels, for
+                               example "1280, 720"
+```
+
+<!--- End of options generated section -->
 
 ### User profile
 
-Playwright MCP will launch the browser with the new profile, located at
+You can run Playwright MCP with persistent profile like a regular browser (default), or in the isolated contexts for the testing sessions.
 
-```
-- `%USERPROFILE%\AppData\Local\ms-playwright\mcp-{channel}-profile` on Windows
-- `~/Library/Caches/ms-playwright/mcp-{channel}-profile` on macOS
-- `~/.cache/ms-playwright/mcp-{channel}-profile` on Linux
+**Persistent profile**
+
+All the logged in information will be stored in the persistent profile, you can delete it between sessions if you'd like to clear the offline state.
+Persistent profile is located at the following locations and you can override it with the `--user-data-dir` argument.
+
+```bash
+# Windows
+%USERPROFILE%\AppData\Local\ms-playwright\mcp-{channel}-profile
+
+# macOS
+- ~/Library/Caches/ms-playwright/mcp-{channel}-profile
+
+# Linux
+- ~/.cache/ms-playwright/mcp-{channel}-profile
 ```
 
-All the logged in information will be stored in that profile, you can delete it between sessions if you'd like to clear the offline state.
+**Isolated**
+
+In the isolated mode, each session is started in the isolated profile. Every time you ask MCP to close the browser,
+the session is closed and all the storage state for this session is lost. You can provide initial storage state
+to the browser via the config's `contextOptions` or via the `--storage-state` argument. Learn more about the storage
+state [here](https://playwright.dev/docs/auth).
+
+```js
+{
+  "mcpServers": {
+    "playwright": {
+      "command": "npx",
+      "args": [
+        "@playwright/mcp@latest",
+        "--isolated",
+        "--storage-state={path/to/storage.json}"
+      ]
+    }
+  }
+}
+```
 
 ### Configuration file
 
-The Playwright MCP server can be configured using a JSON configuration file. Here's the complete configuration format:
+The Playwright MCP server can be configured using a JSON configuration file. You can specify the configuration file
+using the `--config` command line option:
+
+```bash
+npx @playwright/mcp@latest --config path/to/config.json
+```
+
+<details>
+<summary>Configuration file schema</summary>
 
 ```typescript
 {
@@ -102,6 +250,9 @@ The Playwright MCP server can be configured using a JSON configuration file. Her
     // Browser type to use (chromium, firefox, or webkit)
     browserName?: 'chromium' | 'firefox' | 'webkit';
 
+    // Keep the browser profile in memory, do not save it to disk.
+    isolated?: boolean;
+
     // Path to user data directory for browser profile persistence
     userDataDir?: string;
 
@@ -134,62 +285,58 @@ The Playwright MCP server can be configured using a JSON configuration file. Her
     host?: string;  // Host to bind to (default: localhost)
   },
 
-  // List of enabled capabilities
+  // List of additional capabilities
   capabilities?: Array<
-    'core' |    // Core browser automation
     'tabs' |    // Tab management
-    'pdf' |     // PDF generation
-    'history' | // Browser history
-    'wait' |    // Wait utilities
-    'files' |   // File handling
     'install' | // Browser installation
-    'testing'   // Testing
+    'pdf' |     // PDF generation
+    'vision' |  // Coordinate-based interactions
   >;
 
-  // Enable vision mode (screenshots instead of accessibility snapshots)
-  vision?: boolean;
-
   // Directory for output files
   outputDir?: string;
 
-  // Tool-specific configurations
-  tools?: {
-    browser_take_screenshot?: {
-      // Disable base64-encoded image responses
-      omitBase64?: boolean;
-    }
-  }
+  // Network configuration
+  network?: {
+    // List of origins to allow the browser to request. Default is to allow all. Origins matching both `allowedOrigins` and `blockedOrigins` will be blocked.
+    allowedOrigins?: string[];
+
+    // List of origins to block the browser to request. Origins matching both `allowedOrigins` and `blockedOrigins` will be blocked.
+    blockedOrigins?: string[];
+  };
+ 
+  /**
+   * Whether to send image responses to the client. Can be "allow" or "omit". 
+   * Defaults to "allow".
+   */
+  imageResponses?: 'allow' | 'omit';
 }
 ```
+</details>
 
-You can specify the configuration file using the `--config` command line option:
-
-```bash
-npx @playwright/mcp@latest --config path/to/config.json
-```
-
-### Running on Linux
+### Standalone MCP server
 
 When running headed browser on system w/o display or from worker processes of the IDEs,
-run the MCP server from environment with the DISPLAY and pass the `--port` flag to enable SSE transport.
+run the MCP server from environment with the DISPLAY and pass the `--port` flag to enable HTTP transport.
 
 ```bash
 npx @playwright/mcp@latest --port 8931
 ```
 
-And then in MCP client config, set the `url` to the SSE endpoint:
+And then in MCP client config, set the `url` to the HTTP endpoint:
 
 ```js
 {
   "mcpServers": {
     "playwright": {
-      "url": "http://localhost:8931/sse"
+      "url": "http://localhost:8931/mcp"
     }
   }
 }
 ```
 
-### Docker
+<details>
+<summary><b>Docker</b></summary>
 
 **NOTE:** The Docker implementation only supports headless chromium at the moment.
 
@@ -198,7 +345,7 @@ And then in MCP client config, set the `url` to the SSE endpoint:
   "mcpServers": {
     "playwright": {
       "command": "docker",
-      "args": ["run", "-i", "--rm", "--init", "mcp/playwright"]
+      "args": ["run", "-i", "--rm", "--init", "--pull=always", "mcr.microsoft.com/playwright/mcp"]
     }
   }
 }
@@ -207,95 +354,207 @@ And then in MCP client config, set the `url` to the SSE endpoint:
 You can build the Docker image yourself.
 
 ```
-docker build -t mcp/playwright .
+docker build -t mcr.microsoft.com/playwright/mcp .
 ```
+</details>
 
-### Programmatic usage
+<details>
+<summary><b>Programmatic usage</b></summary>
 
 ```js
 import http from 'http';
 
-import { createServer } from '@playwright/mcp';
+import { createConnection } from '@playwright/mcp';
 import { SSEServerTransport } from '@modelcontextprotocol/sdk/server/sse.js';
 
 http.createServer(async (req, res) => {
   // ...
 
   // Creates a headless Playwright MCP server with SSE transport
-  const mcpServer = await createServer({ headless: true });
+  const connection = await createConnection({ browser: { launchOptions: { headless: true } } });
   const transport = new SSEServerTransport('/messages', res);
-  await mcpServer.connect(transport);
+  await connection.sever.connect(transport);
 
   // ...
 });
 ```
+</details>
 
-### Tool modes
+### Tools
 
-The tools are available in two modes:
+<!--- Tools generated by update-readme.js -->
 
-1. **Snapshot Mode** (default): Uses accessibility snapshots for better performance and reliability
-2. **Vision Mode**: Uses screenshots for visual-based interactions
-
-To use Vision Mode, add the `--vision` flag when starting the server:
-
-```js
-{
-  "mcpServers": {
-    "playwright": {
-      "command": "npx",
-      "args": [
-        "@playwright/mcp@latest",
-        "--vision"
-      ]
-    }
-  }
-}
-```
-
-Vision Mode works best with the computer use models that are able to interact with elements using
-X Y coordinate space, based on the provided screenshot.
-
-
-<!--- Generated by update-readme.js -->
-
-### Snapshot-based Interactions
-
-<!-- NOTE: This has been generated via update-readme.js -->
-
-- **browser_snapshot**
-  - Description: Capture accessibility snapshot of the current page, this is better than screenshot
-  - Parameters: None
+<details>
+<summary><b>Core automation</b></summary>
 
 <!-- NOTE: This has been generated via update-readme.js -->
 
 - **browser_click**
+  - Title: Click
   - Description: Perform click on a web page
   - Parameters:
     - `element` (string): Human-readable element description used to obtain permission to interact with the element
     - `ref` (string): Exact target element reference from the page snapshot
+    - `doubleClick` (boolean, optional): Whether to perform a double click instead of a single click
+    - `button` (string, optional): Button to click, defaults to left
+  - Read-only: **false**
+
+<!-- NOTE: This has been generated via update-readme.js -->
+
+- **browser_close**
+  - Title: Close browser
+  - Description: Close the page
+  - Parameters: None
+  - Read-only: **true**
+
+<!-- NOTE: This has been generated via update-readme.js -->
+
+- **browser_console_messages**
+  - Title: Get console messages
+  - Description: Returns all console messages
+  - Parameters: None
+  - Read-only: **true**
 
 <!-- NOTE: This has been generated via update-readme.js -->
 
 - **browser_drag**
+  - Title: Drag mouse
   - Description: Perform drag and drop between two elements
   - Parameters:
     - `startElement` (string): Human-readable source element description used to obtain the permission to interact with the element
     - `startRef` (string): Exact source element reference from the page snapshot
     - `endElement` (string): Human-readable target element description used to obtain the permission to interact with the element
     - `endRef` (string): Exact target element reference from the page snapshot
+  - Read-only: **false**
+
+<!-- NOTE: This has been generated via update-readme.js -->
+
+- **browser_evaluate**
+  - Title: Evaluate JavaScript
+  - Description: Evaluate JavaScript expression on page or element
+  - Parameters:
+    - `function` (string): () => { /* code */ } or (element) => { /* code */ } when element is provided
+    - `element` (string, optional): Human-readable element description used to obtain permission to interact with the element
+    - `ref` (string, optional): Exact target element reference from the page snapshot
+  - Read-only: **false**
+
+<!-- NOTE: This has been generated via update-readme.js -->
+
+- **browser_file_upload**
+  - Title: Upload files
+  - Description: Upload one or multiple files
+  - Parameters:
+    - `paths` (array): The absolute paths to the files to upload. Can be a single file or multiple files.
+  - Read-only: **false**
+
+<!-- NOTE: This has been generated via update-readme.js -->
+
+- **browser_handle_dialog**
+  - Title: Handle a dialog
+  - Description: Handle a dialog
+  - Parameters:
+    - `accept` (boolean): Whether to accept the dialog.
+    - `promptText` (string, optional): The text of the prompt in case of a prompt dialog.
+  - Read-only: **false**
 
 <!-- NOTE: This has been generated via update-readme.js -->
 
 - **browser_hover**
+  - Title: Hover mouse
   - Description: Hover over element on page
   - Parameters:
     - `element` (string): Human-readable element description used to obtain permission to interact with the element
     - `ref` (string): Exact target element reference from the page snapshot
+  - Read-only: **true**
+
+<!-- NOTE: This has been generated via update-readme.js -->
+
+- **browser_navigate**
+  - Title: Navigate to a URL
+  - Description: Navigate to a URL
+  - Parameters:
+    - `url` (string): The URL to navigate to
+  - Read-only: **false**
+
+<!-- NOTE: This has been generated via update-readme.js -->
+
+- **browser_navigate_back**
+  - Title: Go back
+  - Description: Go back to the previous page
+  - Parameters: None
+  - Read-only: **true**
+
+<!-- NOTE: This has been generated via update-readme.js -->
+
+- **browser_navigate_forward**
+  - Title: Go forward
+  - Description: Go forward to the next page
+  - Parameters: None
+  - Read-only: **true**
+
+<!-- NOTE: This has been generated via update-readme.js -->
+
+- **browser_network_requests**
+  - Title: List network requests
+  - Description: Returns all network requests since loading the page
+  - Parameters: None
+  - Read-only: **true**
+
+<!-- NOTE: This has been generated via update-readme.js -->
+
+- **browser_press_key**
+  - Title: Press a key
+  - Description: Press a key on the keyboard
+  - Parameters:
+    - `key` (string): Name of the key to press or a character to generate, such as `ArrowLeft` or `a`
+  - Read-only: **false**
+
+<!-- NOTE: This has been generated via update-readme.js -->
+
+- **browser_resize**
+  - Title: Resize browser window
+  - Description: Resize the browser window
+  - Parameters:
+    - `width` (number): Width of the browser window
+    - `height` (number): Height of the browser window
+  - Read-only: **true**
+
+<!-- NOTE: This has been generated via update-readme.js -->
+
+- **browser_select_option**
+  - Title: Select option
+  - Description: Select an option in a dropdown
+  - Parameters:
+    - `element` (string): Human-readable element description used to obtain permission to interact with the element
+    - `ref` (string): Exact target element reference from the page snapshot
+    - `values` (array): Array of values to select in the dropdown. This can be a single value or multiple values.
+  - Read-only: **false**
+
+<!-- NOTE: This has been generated via update-readme.js -->
+
+- **browser_snapshot**
+  - Title: Page snapshot
+  - Description: Capture accessibility snapshot of the current page, this is better than screenshot
+  - Parameters: None
+  - Read-only: **true**
+
+<!-- NOTE: This has been generated via update-readme.js -->
+
+- **browser_take_screenshot**
+  - Title: Take a screenshot
+  - Description: Take a screenshot of the current page. You can't perform actions based on the screenshot, use browser_snapshot for actions.
+  - Parameters:
+    - `raw` (boolean, optional): Whether to return without compression (in PNG format). Default is false, which returns a JPEG image.
+    - `filename` (string, optional): File name to save the screenshot to. Defaults to `page-{timestamp}.{png|jpeg}` if not specified.
+    - `element` (string, optional): Human-readable element description used to obtain permission to screenshot the element. If not provided, the screenshot will be taken of viewport. If element is provided, ref must be provided too.
+    - `ref` (string, optional): Exact target element reference from the page snapshot. If not provided, the screenshot will be taken of viewport. If ref is provided, element must be provided too.
+    - `fullPage` (boolean, optional): When true, takes a screenshot of the full scrollable page, instead of the currently visible viewport. Cannot be used with element screenshots.
+  - Read-only: **true**
 
 <!-- NOTE: This has been generated via update-readme.js -->
 
 - **browser_type**
+  - Title: Type text
   - Description: Type text into editable element
   - Parameters:
     - `element` (string): Human-readable element description used to obtain permission to interact with the element
@@ -303,198 +562,127 @@ X Y coordinate space, based on the provided screenshot.
     - `text` (string): Text to type into the element
     - `submit` (boolean, optional): Whether to submit entered text (press Enter after)
     - `slowly` (boolean, optional): 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.
+  - Read-only: **false**
 
 <!-- NOTE: This has been generated via update-readme.js -->
 
-- **browser_select_option**
-  - Description: Select an option in a dropdown
+- **browser_wait_for**
+  - Title: Wait for
+  - Description: Wait for text to appear or disappear or a specified time to pass
   - Parameters:
-    - `element` (string): Human-readable element description used to obtain permission to interact with the element
-    - `ref` (string): Exact target element reference from the page snapshot
-    - `values` (array): Array of values to select in the dropdown. This can be a single value or multiple values.
+    - `time` (number, optional): The time to wait in seconds
+    - `text` (string, optional): The text to wait for
+    - `textGone` (string, optional): The text to wait for to disappear
+  - Read-only: **true**
+
+</details>
+
+<details>
+<summary><b>Tab management</b></summary>
 
 <!-- NOTE: This has been generated via update-readme.js -->
 
-- **browser_take_screenshot**
-  - Description: Take a screenshot of the current page. You can't perform actions based on the screenshot, use browser_snapshot for actions.
+- **browser_tab_close**
+  - Title: Close a tab
+  - Description: Close a tab
   - Parameters:
-    - `raw` (boolean, optional): Whether to return without compression (in PNG format). Default is false, which returns a JPEG image.
-    - `element` (string, optional): Human-readable element description used to obtain permission to screenshot the element. If not provided, the screenshot will be taken of viewport. If element is provided, ref must be provided too.
-    - `ref` (string, optional): Exact target element reference from the page snapshot. If not provided, the screenshot will be taken of viewport. If ref is provided, element must be provided too.
-
-### Vision-based Interactions
+    - `index` (number, optional): The index of the tab to close. Closes current tab if not provided.
+  - Read-only: **false**
 
 <!-- NOTE: This has been generated via update-readme.js -->
 
-- **browser_screen_capture**
-  - Description: Take a screenshot of the current page
+- **browser_tab_list**
+  - Title: List tabs
+  - Description: List browser tabs
   - Parameters: None
+  - Read-only: **true**
 
 <!-- NOTE: This has been generated via update-readme.js -->
 
-- **browser_screen_move_mouse**
-  - Description: Move mouse to a given position
+- **browser_tab_new**
+  - Title: Open a new tab
+  - Description: Open a new tab
+  - Parameters:
+    - `url` (string, optional): The URL to navigate to in the new tab. If not provided, the new tab will be blank.
+  - Read-only: **true**
+
+<!-- NOTE: This has been generated via update-readme.js -->
+
+- **browser_tab_select**
+  - Title: Select a tab
+  - Description: Select a tab by index
+  - Parameters:
+    - `index` (number): The index of the tab to select
+  - Read-only: **true**
+
+</details>
+
+<details>
+<summary><b>Browser installation</b></summary>
+
+<!-- NOTE: This has been generated via update-readme.js -->
+
+- **browser_install**
+  - Title: Install the browser specified in the config
+  - Description: Install the browser specified in the config. Call this if you get an error about the browser not being installed.
+  - Parameters: None
+  - Read-only: **false**
+
+</details>
+
+<details>
+<summary><b>Coordinate-based (opt-in via --caps=vision)</b></summary>
+
+<!-- NOTE: This has been generated via update-readme.js -->
+
+- **browser_mouse_click_xy**
+  - Title: Click
+  - Description: Click left mouse button at a given position
   - Parameters:
     - `element` (string): Human-readable element description used to obtain permission to interact with the element
     - `x` (number): X coordinate
     - `y` (number): Y coordinate
+  - Read-only: **false**
 
 <!-- NOTE: This has been generated via update-readme.js -->
 
-- **browser_screen_click**
-  - Description: Click left mouse button
-  - Parameters:
-    - `element` (string): Human-readable element description used to obtain permission to interact with the element
-    - `x` (number): X coordinate
-    - `y` (number): Y coordinate
-
-<!-- NOTE: This has been generated via update-readme.js -->
-
-- **browser_screen_drag**
-  - Description: Drag left mouse button
+- **browser_mouse_drag_xy**
+  - Title: Drag mouse
+  - Description: Drag left mouse button to a given position
   - Parameters:
     - `element` (string): Human-readable element description used to obtain permission to interact with the element
     - `startX` (number): Start X coordinate
     - `startY` (number): Start Y coordinate
     - `endX` (number): End X coordinate
     - `endY` (number): End Y coordinate
+  - Read-only: **false**
 
 <!-- NOTE: This has been generated via update-readme.js -->
 
-- **browser_screen_type**
-  - Description: Type text
+- **browser_mouse_move_xy**
+  - Title: Move mouse
+  - Description: Move mouse to a given position
   - Parameters:
-    - `text` (string): Text to type into the element
-    - `submit` (boolean, optional): Whether to submit entered text (press Enter after)
+    - `element` (string): Human-readable element description used to obtain permission to interact with the element
+    - `x` (number): X coordinate
+    - `y` (number): Y coordinate
+  - Read-only: **true**
 
-### Tab Management
+</details>
 
-<!-- NOTE: This has been generated via update-readme.js -->
-
-- **browser_tab_list**
-  - Description: List browser tabs
-  - Parameters: None
-
-<!-- NOTE: This has been generated via update-readme.js -->
-
-- **browser_tab_new**
-  - Description: Open a new tab
-  - Parameters:
-    - `url` (string, optional): The URL to navigate to in the new tab. If not provided, the new tab will be blank.
-
-<!-- NOTE: This has been generated via update-readme.js -->
-
-- **browser_tab_select**
-  - Description: Select a tab by index
-  - Parameters:
-    - `index` (number): The index of the tab to select
-
-<!-- NOTE: This has been generated via update-readme.js -->
-
-- **browser_tab_close**
-  - Description: Close a tab
-  - Parameters:
-    - `index` (number, optional): The index of the tab to close. Closes current tab if not provided.
-
-### Navigation
-
-<!-- NOTE: This has been generated via update-readme.js -->
-
-- **browser_navigate**
-  - Description: Navigate to a URL
-  - Parameters:
-    - `url` (string): The URL to navigate to
-
-<!-- NOTE: This has been generated via update-readme.js -->
-
-- **browser_navigate_back**
-  - Description: Go back to the previous page
-  - Parameters: None
-
-<!-- NOTE: This has been generated via update-readme.js -->
-
-- **browser_navigate_forward**
-  - Description: Go forward to the next page
-  - Parameters: None
-
-### Keyboard
-
-<!-- NOTE: This has been generated via update-readme.js -->
-
-- **browser_press_key**
-  - Description: Press a key on the keyboard
-  - Parameters:
-    - `key` (string): Name of the key to press or a character to generate, such as `ArrowLeft` or `a`
-
-### Console
-
-<!-- NOTE: This has been generated via update-readme.js -->
-
-- **browser_console_messages**
-  - Description: Returns all console messages
-  - Parameters: None
-
-### Files and Media
-
-<!-- NOTE: This has been generated via update-readme.js -->
-
-- **browser_file_upload**
-  - Description: Upload one or multiple files
-  - Parameters:
-    - `paths` (array): The absolute paths to the files to upload. Can be a single file or multiple files.
+<details>
+<summary><b>PDF generation (opt-in via --caps=pdf)</b></summary>
 
 <!-- NOTE: This has been generated via update-readme.js -->
 
 - **browser_pdf_save**
+  - Title: Save as PDF
   - Description: Save page as PDF
-  - Parameters: None
-
-### Utilities
-
-<!-- NOTE: This has been generated via update-readme.js -->
-
-- **browser_close**
-  - Description: Close the page
-  - Parameters: None
-
-<!-- NOTE: This has been generated via update-readme.js -->
-
-- **browser_wait**
-  - Description: Wait for a specified time in seconds
   - Parameters:
-    - `time` (number): The time to wait in seconds
+    - `filename` (string, optional): File name to save the pdf to. Defaults to `page-{timestamp}.pdf` if not specified.
+  - Read-only: **true**
 
-<!-- NOTE: This has been generated via update-readme.js -->
+</details>
 
-- **browser_resize**
-  - Description: Resize the browser window
-  - Parameters:
-    - `width` (number): Width of the browser window
-    - `height` (number): Height of the browser window
 
-<!-- NOTE: This has been generated via update-readme.js -->
-
-- **browser_install**
-  - Description: Install the browser specified in the config. Call this if you get an error about the browser not being installed.
-  - Parameters: None
-
-<!-- NOTE: This has been generated via update-readme.js -->
-
-- **browser_handle_dialog**
-  - Description: Handle a dialog
-  - Parameters:
-    - `accept` (boolean): Whether to accept the dialog.
-    - `promptText` (string, optional): The text of the prompt in case of a prompt dialog.
-
-### Testing
-
-<!-- NOTE: This has been generated via update-readme.js -->
-
-- **browser_generate_playwright_test**
-  - Description: Generate a Playwright test for given scenario
-  - Parameters:
-    - `name` (string): The name of the test
-    - `description` (string): The description of the test
-    - `steps` (array): The steps of the test
-
-<!--- End of generated section -->
+<!--- End of tools generated section -->

config.d.ts

@@ -16,7 +16,7 @@
 
 import type * as playwright from 'playwright';
 
-export type ToolCapability = 'core' | 'tabs' | 'pdf' | 'history' | 'wait' | 'files' | 'install' | 'testing';
+export type ToolCapability = 'core' | 'core-tabs' | 'core-install' | 'vision' | 'pdf';
 
 export type Config = {
   /**
@@ -28,6 +28,11 @@ export type Config = {
      */
     browserName?: 'chromium' | 'firefox' | 'webkit';
 
+    /**
+     * Keep the browser profile in memory, do not save it to disk.
+     */
+    isolated?: boolean;
+
     /**
      * Path to a user data directory for browser profile persistence.
      * Temporary directory is created by default.
@@ -40,7 +45,7 @@ export type Config = {
      *
      * This is useful for settings options like `channel`, `headless`, `executablePath`, etc.
      */
-    launchOptions?: playwright.BrowserLaunchOptions;
+    launchOptions?: playwright.LaunchOptions;
 
     /**
      * Context options for the browser context.
@@ -75,39 +80,40 @@ export type Config = {
   /**
    * List of enabled tool capabilities. Possible values:
    *   - 'core': Core browser automation features.
-   *   - 'tabs': Tab management features.
    *   - 'pdf': PDF generation and manipulation.
-   *   - 'history': Browser history access.
-   *   - 'wait': Wait and timing utilities.
-   *   - 'files': File upload/download support.
-   *   - 'install': Browser installation utilities.
+   *   - 'vision': Coordinate-based interactions.
    */
   capabilities?: ToolCapability[];
 
   /**
-   * Run server that uses screenshots (Aria snapshots are used by default).
+   * Whether to save the Playwright session into the output directory.
    */
-  vision?: boolean;
+  saveSession?: boolean;
+
+  /**
+   * Whether to save the Playwright trace of the session into the output directory.
+   */
+  saveTrace?: boolean;
 
   /**
    * The directory to save output files.
    */
   outputDir?: string;
 
-  /**
-   * Configuration for specific tools.
-   */
-  tools?: {
+  network?: {
     /**
-     * Configuration for the browser_take_screenshot tool.
+     * List of origins to allow the browser to request. Default is to allow all. Origins matching both `allowedOrigins` and `blockedOrigins` will be blocked.
      */
-    browser_take_screenshot?: {
+    allowedOrigins?: string[];
 
-      /**
-       * Whether to disable base64-encoded image responses to the clients that
-       * don't support binary data or prefer to save on tokens.
-      */
-      omitBase64?: boolean;
-    }
-  }
+    /**
+     * List of origins to block the browser to request. Origins matching both `allowedOrigins` and `blockedOrigins` will be blocked.
+     */
+    blockedOrigins?: string[];
+  };
+
+  /**
+   * Whether to send image responses to the client. Can be "allow", "omit", or "auto". Defaults to "auto", which sends images if the client can display them.
+   */
+  imageResponses?: 'allow' | 'omit';
 };

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,
+    },
   },
 ];

examples/generate-test.md

@@ -1,4 +1,4 @@
-Generate test for scenario:
+Use Playwright tools to generate test for scenario:
 
 ## GitHub PR Checks Navigation Checklist
 

extension/connect.html

@@ -0,0 +1,34 @@
+<!--
+  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.
+-->
+<!DOCTYPE html>
+<html>
+<head>
+  <title>Playwright MCP extension</title>
+</head>
+<body>
+  <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> 

extension/manifest.json

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

extension/src/background.ts

@@ -0,0 +1,124 @@
+/**
+ * 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 { RelayConnection, debugLog } from './relayConnection.js';
+
+type PageMessage = {
+  type: 'connectToMCPRelay';
+  mcpRelayUrl: string;
+  tabId: number;
+  windowId: number;
+} | {
+  type: 'getTabs';
+};
+
+class TabShareExtension {
+  private _activeConnection: RelayConnection | undefined;
+  private _connectedTabId: number | null = null;
+
+  constructor() {
+    chrome.tabs.onRemoved.addListener(this._onTabRemoved.bind(this));
+    chrome.tabs.onUpdated.addListener(this._onTabUpdated.bind(this));
+    chrome.runtime.onMessage.addListener(this._onMessage.bind(this));
+  }
+
+  // Promise-based message handling is not supported in Chrome: https://issues.chromium.org/issues/40753031
+  private _onMessage(message: PageMessage, sender: chrome.runtime.MessageSender, sendResponse: (response: any) => void) {
+    switch (message.type) {
+      case 'connectToMCPRelay':
+        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, windowId: number, mcpRelayUrl: string): Promise<void> {
+    try {
+      debugLog(`Connecting tab ${tabId} to bridge at ${mcpRelayUrl}`);
+      const socket = new WebSocket(mcpRelayUrl);
+      await new Promise<void>((resolve, reject) => {
+        socket.onopen = () => resolve();
+        socket.onerror = () => reject(new Error('WebSocket error'));
+        setTimeout(() => reject(new Error('Connection timeout')), 5000);
+      });
+
+      const connection = new RelayConnection(socket, tabId);
+      const connectionClosed = (m: string) => {
+        debugLog(m);
+        if (this._activeConnection === connection) {
+          this._activeConnection = undefined;
+          void this._setConnectedTabId(null);
+        }
+      };
+      socket.onclose = () => connectionClosed('WebSocket closed');
+      socket.onerror = error => connectionClosed(`WebSocket error: ${error}`);
+      this._activeConnection = connection;
+
+      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) {
+      await this._setConnectedTabId(null);
+      debugLog(`Failed to connect tab ${tabId}:`, error.message);
+      throw error;
+    }
+  }
+
+  private async _setConnectedTabId(tabId: number | null): Promise<void> {
+    const oldTabId = this._connectedTabId;
+    this._connectedTabId = tabId;
+    if (oldTabId && oldTabId !== tabId)
+      await this._updateBadge(oldTabId, { text: '', color: null });
+    if (tabId)
+      await this._updateBadge(tabId, { text: '●', color: '#4CAF50' });
+  }
+
+  private async _updateBadge(tabId: number, { text, color }: { text: string; color: string | null }): Promise<void> {
+    await chrome.action.setBadgeText({ tabId, text });
+    if (color)
+      await chrome.action.setBadgeBackgroundColor({ tabId, color });
+  }
+
+  private async _onTabRemoved(tabId: number): Promise<void> {
+    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();

extension/src/connect.ts

@@ -0,0 +1,172 @@
+/**
+ * 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.
+ */
+
+interface TabInfo {
+  id: number;
+  windowId: number;
+  title: string;
+  url: string;
+  favIconUrl?: 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;
+    this._statusContainer.replaceChildren(div);
+  }
+}
+
+new ConnectPage();

extension/src/relayConnection.ts

@@ -0,0 +1,166 @@
+/**
+ * Copyright (c) Microsoft Corporation.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+export function debugLog(...args: unknown[]): void {
+  const enabled = true;
+  if (enabled) {
+    // eslint-disable-next-line no-console
+    console.log('[Extension]', ...args);
+  }
+}
+
+type ProtocolCommand = {
+  id: number;
+  method: string;
+  params?: any;
+};
+
+type ProtocolResponse = {
+  id?: number;
+  method?: string;
+  params?: any;
+  result?: any;
+  error?: string;
+};
+
+export class RelayConnection {
+  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, tabId: number) {
+    this._debuggee = { tabId };
+    this._ws = ws;
+    this._ws.onmessage = this._onMessage.bind(this);
+    // Store listeners for cleanup
+    this._eventListener = this._onDebuggerEvent.bind(this);
+    this._detachListener = this._onDebuggerDetach.bind(this);
+    chrome.debugger.onEvent.addListener(this._eventListener);
+    chrome.debugger.onDetach.addListener(this._detachListener);
+  }
+
+  close(message: string): void {
+    chrome.debugger.onEvent.removeListener(this._eventListener);
+    chrome.debugger.onDetach.removeListener(this._detachListener);
+    this._ws.close(1000, message);
+  }
+
+  private async _detachDebugger(): Promise<void> {
+    await chrome.debugger.detach(this._debuggee);
+  }
+
+  private _onDebuggerEvent(source: chrome.debugger.DebuggerSession, method: string, params: any): void {
+    if (source.tabId !== this._debuggee.tabId)
+      return;
+    debugLog('Forwarding CDP event:', method, params);
+    const sessionId = source.sessionId;
+    this._sendMessage({
+      method: 'forwardCDPEvent',
+      params: {
+        sessionId,
+        method,
+        params,
+      },
+    });
+  }
+
+  private _onDebuggerDetach(source: chrome.debugger.Debuggee, reason: string): void {
+    if (source.tabId !== this._debuggee.tabId)
+      return;
+    this._sendMessage({
+      method: 'detachedFromTab',
+      params: {
+        tabId: this._debuggee.tabId,
+        reason,
+      },
+    });
+    this._debuggee = { };
+  }
+
+  private _onMessage(event: MessageEvent): void {
+    this._onMessageAsync(event).catch(e => debugLog('Error handling message:', e));
+  }
+
+  private async _onMessageAsync(event: MessageEvent): Promise<void> {
+    let message: ProtocolCommand;
+    try {
+      message = JSON.parse(event.data);
+    } catch (error: any) {
+      debugLog('Error parsing message:', error);
+      this._sendError(-32700, `Error parsing message: ${error.message}`);
+      return;
+    }
+
+    debugLog('Received message:', message);
+
+    const response: ProtocolResponse = {
+      id: message.id,
+    };
+    try {
+      response.result = await this._handleCommand(message);
+    } catch (error: any) {
+      debugLog('Error handling command:', error);
+      response.error = error.message;
+    }
+    debugLog('Sending response:', response);
+    this._sendMessage(response);
+  }
+
+  private async _handleCommand(message: ProtocolCommand): Promise<any> {
+    if (!this._debuggee.tabId)
+      throw new Error('No tab is connected. Please go to the Playwright MCP extension and select the tab you want to connect to.');
+    if (message.method === 'attachToTab') {
+      debugLog('Attaching debugger to tab:', this._debuggee);
+      await chrome.debugger.attach(this._debuggee, '1.3');
+      const result: any = await chrome.debugger.sendCommand(this._debuggee, 'Target.getTargetInfo');
+      return {
+        targetInfo: result?.targetInfo,
+      };
+    }
+    if (message.method === 'detachFromTab') {
+      debugLog('Detaching debugger from tab:', this._debuggee);
+      return await this._detachDebugger();
+    }
+    if (message.method === 'forwardCDPCommand') {
+      const { sessionId, method, params } = message.params;
+      debugLog('CDP command:', method, params);
+      const debuggerSession: chrome.debugger.DebuggerSession = {
+        ...this._debuggee,
+        sessionId,
+      };
+      // Forward CDP command to chrome.debugger
+      return await chrome.debugger.sendCommand(
+          debuggerSession,
+          method,
+          params
+      );
+    }
+  }
+
+  private _sendError(code: number, message: string): void {
+    this._sendMessage({
+      error: {
+        code,
+        message,
+      },
+    });
+  }
+
+  private _sendMessage(message: any): void {
+    this._ws.send(JSON.stringify(message));
+  }
+}

extension/tsconfig.json

@@ -0,0 +1,15 @@
+{
+  "compilerOptions": {
+    "target": "ESNext",
+    "esModuleInterop": true,
+    "moduleResolution": "node",
+    "strict": true,
+    "module": "ESNext",
+    "rootDir": "src",
+    "outDir": "./lib",
+    "resolveJsonModule": true,
+  },
+  "include": [
+    "src",
+  ],
+}

index.d.ts

@@ -16,8 +16,8 @@
  */
 
 import type { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import type { Config } from './config.js';
+import type { BrowserContext } from 'playwright';
 
-import type { Config } from './config';
-
-export declare function createServer(config?: Config): Promise<Server>;
+export declare function createConnection(config?: Config, contextGetter?: () => Promise<BrowserContext>): Promise<Server>;
 export {};

index.js

@@ -15,5 +15,5 @@
  * limitations under the License.
  */
 
-import { createServer } from './lib/index';
-export default { createServer };
+import { createConnection } from './lib/index.js';
+export { createConnection };

package-lock.json

@@ -1,41 +1,60 @@
 {
   "name": "@playwright/mcp",
-  "version": "0.0.19",
+  "version": "0.0.32",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "@playwright/mcp",
-      "version": "0.0.19",
+      "version": "0.0.32",
       "license": "Apache-2.0",
       "dependencies": {
-        "@modelcontextprotocol/sdk": "^1.10.1",
+        "@modelcontextprotocol/sdk": "^1.16.0",
         "commander": "^13.1.0",
-        "playwright": "1.53.0-alpha-1746218818000",
-        "yaml": "^2.7.1",
+        "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",
+        "ws": "^8.18.1",
         "zod-to-json-schema": "^3.24.4"
       },
       "bin": {
         "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.53.0-alpha-1746218818000",
+        "@playwright/test": "1.55.0-alpha-1752701791000",
         "@stylistic/eslint-plugin": "^3.0.1",
+        "@types/chrome": "^0.0.315",
+        "@types/debug": "^4.1.12",
         "@types/node": "^22.13.10",
+        "@types/ws": "^8.18.1",
         "@typescript-eslint/eslint-plugin": "^8.26.1",
         "@typescript-eslint/parser": "^8.26.1",
         "@typescript-eslint/utils": "^8.26.1",
         "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",
@@ -66,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": {
@@ -81,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": {
@@ -91,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": {
@@ -104,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": {
@@ -128,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": {
@@ -148,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": {
@@ -228,15 +250,17 @@
       }
     },
     "node_modules/@modelcontextprotocol/sdk": {
-      "version": "1.10.1",
-      "resolved": "https://registry.npmjs.org/@modelcontextprotocol/sdk/-/sdk-1.10.1.tgz",
-      "integrity": "sha512-xNYdFdkJqEfIaTVP1gPKoEvluACHZsHZegIoICX8DM1o6Qf3G5u2BQJHmgd0n4YgRPqqK/u1ujQvrgAxxSJT9w==",
+      "version": "1.16.0",
+      "resolved": "https://registry.npmjs.org/@modelcontextprotocol/sdk/-/sdk-1.16.0.tgz",
+      "integrity": "sha512-8ofX7gkZcLj9H9rSd50mCgm3SSF8C7XoclxJuLoV0Cz3rEQ1tv9MZRYYvJtm9n1BiEQQMzSmE/w2AEkNacLYfg==",
       "license": "MIT",
       "dependencies": {
+        "ajv": "^6.12.6",
         "content-type": "^1.0.5",
         "cors": "^2.8.5",
-        "cross-spawn": "^7.0.3",
+        "cross-spawn": "^7.0.5",
         "eventsource": "^3.0.2",
+        "eventsource-parser": "^3.0.0",
         "express": "^5.0.1",
         "express-rate-limit": "^7.5.0",
         "pkce-challenge": "^5.0.0",
@@ -287,13 +311,13 @@
       }
     },
     "node_modules/@playwright/test": {
-      "version": "1.53.0-alpha-1746218818000",
-      "resolved": "https://registry.npmjs.org/@playwright/test/-/test-1.53.0-alpha-1746218818000.tgz",
-      "integrity": "sha512-J05FD0oOCVbjbp4IjQi5tOPKywchi5EENS9jRjgkA5N9jd/+BaZ3jT8HlLMIgALdk/eLsprQa7vh9h45Q1FOPA==",
+      "version": "1.55.0-alpha-1752701791000",
+      "resolved": "https://registry.npmjs.org/@playwright/test/-/test-1.55.0-alpha-1752701791000.tgz",
+      "integrity": "sha512-mnitdsjXKPyKTjQQDJ78Or1xZSGcaoDzZVD/0BWFCvygn3nyNmGmiias/Mlfvzvgz9UWBbPeZYxU/bd2Lu+OrQ==",
       "dev": true,
       "license": "Apache-2.0",
       "dependencies": {
-        "playwright": "1.53.0-alpha-1746218818000"
+        "playwright": "1.55.0-alpha-1752701791000"
       },
       "bin": {
         "playwright": "cli.js"
@@ -355,6 +379,27 @@
         "url": "https://github.com/sponsors/jonschlinkert"
       }
     },
+    "node_modules/@types/chrome": {
+      "version": "0.0.315",
+      "resolved": "https://registry.npmjs.org/@types/chrome/-/chrome-0.0.315.tgz",
+      "integrity": "sha512-Oy1dYWkr6BCmgwBtOngLByCHstQ3whltZg7/7lubgIZEYvKobDneqplgc6LKERNRBwckFviV4UU5AZZNUFrJ4A==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "@types/filesystem": "*",
+        "@types/har-format": "*"
+      }
+    },
+    "node_modules/@types/debug": {
+      "version": "4.1.12",
+      "resolved": "https://registry.npmjs.org/@types/debug/-/debug-4.1.12.tgz",
+      "integrity": "sha512-vIChWdVG3LG1SMxEvI/AK+FWJthlrqlTu7fbrlywTkkaONwk/UAGaULXRlf8vkzFBLVm0zkMdCquhL5aOjhXPQ==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "@types/ms": "*"
+      }
+    },
     "node_modules/@types/estree": {
       "version": "1.0.6",
       "resolved": "https://registry.npmjs.org/@types/estree/-/estree-1.0.6.tgz",
@@ -362,6 +407,30 @@
       "dev": true,
       "license": "MIT"
     },
+    "node_modules/@types/filesystem": {
+      "version": "0.0.36",
+      "resolved": "https://registry.npmjs.org/@types/filesystem/-/filesystem-0.0.36.tgz",
+      "integrity": "sha512-vPDXOZuannb9FZdxgHnqSwAG/jvdGM8Wq+6N4D/d80z+D4HWH+bItqsZaVRQykAn6WEVeEkLm2oQigyHtgb0RA==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "@types/filewriter": "*"
+      }
+    },
+    "node_modules/@types/filewriter": {
+      "version": "0.0.33",
+      "resolved": "https://registry.npmjs.org/@types/filewriter/-/filewriter-0.0.33.tgz",
+      "integrity": "sha512-xFU8ZXTw4gd358lb2jw25nxY9QAgqn2+bKKjKOYfNCzN4DKCFetK7sPtrlpg66Ywe3vWY9FNxprZawAh9wfJ3g==",
+      "dev": true,
+      "license": "MIT"
+    },
+    "node_modules/@types/har-format": {
+      "version": "1.2.16",
+      "resolved": "https://registry.npmjs.org/@types/har-format/-/har-format-1.2.16.tgz",
+      "integrity": "sha512-fluxdy7ryD3MV6h8pTfTYpy/xQzCFC7m89nOH9y94cNqJ1mDIDPut7MnRHI3F6qRmh/cT2fUjG1MLdCNb4hE9A==",
+      "dev": true,
+      "license": "MIT"
+    },
     "node_modules/@types/json-schema": {
       "version": "7.0.15",
       "resolved": "https://registry.npmjs.org/@types/json-schema/-/json-schema-7.0.15.tgz",
@@ -376,6 +445,13 @@
       "dev": true,
       "license": "MIT"
     },
+    "node_modules/@types/ms": {
+      "version": "2.1.0",
+      "resolved": "https://registry.npmjs.org/@types/ms/-/ms-2.1.0.tgz",
+      "integrity": "sha512-GsCCIZDE/p3i96vtEqx+7dBUGXrc7zeSK3wwPHIaRThS+9OhWIXRqzs4d6k1SVU8g91DrNRWxWUGhp5KXQb2VA==",
+      "dev": true,
+      "license": "MIT"
+    },
     "node_modules/@types/node": {
       "version": "22.13.10",
       "resolved": "https://registry.npmjs.org/@types/node/-/node-22.13.10.tgz",
@@ -386,6 +462,16 @@
         "undici-types": "~6.20.0"
       }
     },
+    "node_modules/@types/ws": {
+      "version": "8.18.1",
+      "resolved": "https://registry.npmjs.org/@types/ws/-/ws-8.18.1.tgz",
+      "integrity": "sha512-ThVF6DCVhA8kUGy+aazFQ4kXQ7E1Ty7A3ypFOe0IcJV8O/M511G99AW24irKrW56Wt44yG9+ij8FaqoBGkuBXg==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "@types/node": "*"
+      }
+    },
     "node_modules/@typescript-eslint/eslint-plugin": {
       "version": "8.27.0",
       "resolved": "https://registry.npmjs.org/@typescript-eslint/eslint-plugin/-/eslint-plugin-8.27.0.tgz",
@@ -525,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": {
@@ -619,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": {
@@ -645,7 +731,6 @@
       "version": "6.12.6",
       "resolved": "https://registry.npmjs.org/ajv/-/ajv-6.12.6.tgz",
       "integrity": "sha512-j3fVLgvTo527anyYyJOGTYJbG+vnnQYvE0m5mmkc1TK+nxAppkCLMIL0aZ4dblVCNoGShhm+kzE4ZUykBoMg4g==",
-      "dev": true,
       "license": "MIT",
       "dependencies": {
         "fast-deep-equal": "^3.1.1",
@@ -835,16 +920,16 @@
       "license": "MIT"
     },
     "node_modules/body-parser": {
-      "version": "2.1.0",
-      "resolved": "https://registry.npmjs.org/body-parser/-/body-parser-2.1.0.tgz",
-      "integrity": "sha512-/hPxh61E+ll0Ujp24Ilm64cykicul1ypfwjVttduAiEdtnJFvLePSrIPk+HMImtNv5270wOGCb1Tns2rybMkoQ==",
+      "version": "2.2.0",
+      "resolved": "https://registry.npmjs.org/body-parser/-/body-parser-2.2.0.tgz",
+      "integrity": "sha512-02qvAaxv8tp7fBa/mw1ga98OGm+eCbqzJOKoRt70sLmfEEi+jyBYVTDGfCL/k06/4EMk/z01gCe7HoCH/f2LTg==",
       "license": "MIT",
       "dependencies": {
         "bytes": "^3.1.2",
         "content-type": "^1.0.5",
         "debug": "^4.4.0",
         "http-errors": "^2.0.0",
-        "iconv-lite": "^0.5.2",
+        "iconv-lite": "^0.6.3",
         "on-finished": "^2.4.1",
         "qs": "^6.14.0",
         "raw-body": "^3.0.0",
@@ -854,48 +939,10 @@
         "node": ">=18"
       }
     },
-    "node_modules/body-parser/node_modules/debug": {
-      "version": "4.4.0",
-      "resolved": "https://registry.npmjs.org/debug/-/debug-4.4.0.tgz",
-      "integrity": "sha512-6WTZ/IxCY/T6BALoZHaE4ctp9xm+Z5kY/pzYaCHRFeyVhojxlrm+46y68HA6hr0TcwEssoxNiDEUJQjfPZ/RYA==",
-      "license": "MIT",
-      "dependencies": {
-        "ms": "^2.1.3"
-      },
-      "engines": {
-        "node": ">=6.0"
-      },
-      "peerDependenciesMeta": {
-        "supports-color": {
-          "optional": true
-        }
-      }
-    },
-    "node_modules/body-parser/node_modules/ms": {
-      "version": "2.1.3",
-      "resolved": "https://registry.npmjs.org/ms/-/ms-2.1.3.tgz",
-      "integrity": "sha512-6FlzubTLZG3J2a/NVCAleEhjzq5oxgHyaCU9yYXvcLsvoVaHJq/s5xXI6/XXP6tz7R9xAOtHnSO/tXtF3WRTlA==",
-      "license": "MIT"
-    },
-    "node_modules/body-parser/node_modules/qs": {
-      "version": "6.14.0",
-      "resolved": "https://registry.npmjs.org/qs/-/qs-6.14.0.tgz",
-      "integrity": "sha512-YWWTjgABSKcvs/nWBi9PycY/JiPJqOD4JA6o9Sej2AtvSGarXxKC3OQSk4pAarbdQlKAh5D4FCQkJNkW+GAn3w==",
-      "license": "BSD-3-Clause",
-      "dependencies": {
-        "side-channel": "^1.1.0"
-      },
-      "engines": {
-        "node": ">=0.6"
-      },
-      "funding": {
-        "url": "https://github.com/sponsors/ljharb"
-      }
-    },
     "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": {
@@ -1157,12 +1204,12 @@
       }
     },
     "node_modules/debug": {
-      "version": "4.3.6",
-      "resolved": "https://registry.npmjs.org/debug/-/debug-4.3.6.tgz",
-      "integrity": "sha512-O/09Bd4Z1fBrU4VzkhFqVgpPzaGbw6Sm9FEkBT1A/YBXQFGuuSxa1dN2nxgxS34JmKXqYx8CZAwEVoJFImUXIg==",
+      "version": "4.4.1",
+      "resolved": "https://registry.npmjs.org/debug/-/debug-4.4.1.tgz",
+      "integrity": "sha512-KcKCqiftBJcZr++7ykoDIEwSa3XWowTfNPo92BYxjXiyYEVrUQh2aLyhxBCwww+heortUFxEJYcRzosstTEBYQ==",
       "license": "MIT",
       "dependencies": {
-        "ms": "2.1.2"
+        "ms": "^2.1.3"
       },
       "engines": {
         "node": ">=6.0"
@@ -1225,16 +1272,6 @@
         "node": ">= 0.8"
       }
     },
-    "node_modules/destroy": {
-      "version": "1.2.0",
-      "resolved": "https://registry.npmjs.org/destroy/-/destroy-1.2.0.tgz",
-      "integrity": "sha512-2sJGJTaXIIaR1w4iJSNoN0hnMY7Gpc/n8D4qSCJw8QqFWXf7cuAgnEHxBpweaVcPevC2l3KpjYCx3NypQQgaJg==",
-      "license": "MIT",
-      "engines": {
-        "node": ">= 0.8",
-        "npm": "1.2.8000 || >= 1.4.16"
-      }
-    },
     "node_modules/doctrine": {
       "version": "2.1.0",
       "resolved": "https://registry.npmjs.org/doctrine/-/doctrine-2.1.0.tgz",
@@ -1248,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",
@@ -1440,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",
@@ -1464,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",
@@ -1620,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": {
@@ -1650,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": {
@@ -1663,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"
@@ -1681,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": {
@@ -1770,46 +1819,45 @@
       }
     },
     "node_modules/express": {
-      "version": "5.0.1",
-      "resolved": "https://registry.npmjs.org/express/-/express-5.0.1.tgz",
-      "integrity": "sha512-ORF7g6qGnD+YtUG9yx4DFoqCShNMmUKiXuT5oWMHiOvt/4WFbHC6yCwQMTSBMno7AqntNCAzzcnnjowRkTL9eQ==",
+      "version": "5.1.0",
+      "resolved": "https://registry.npmjs.org/express/-/express-5.1.0.tgz",
+      "integrity": "sha512-DT9ck5YIRU+8GYzzU5kT3eHGA5iL+1Zd0EutOmTE9Dtk+Tvuzd23VBU+ec7HPNSTxXYO55gPV/hq4pSBJDjFpA==",
       "license": "MIT",
       "dependencies": {
         "accepts": "^2.0.0",
-        "body-parser": "^2.0.1",
+        "body-parser": "^2.2.0",
         "content-disposition": "^1.0.0",
-        "content-type": "~1.0.4",
-        "cookie": "0.7.1",
+        "content-type": "^1.0.5",
+        "cookie": "^0.7.1",
         "cookie-signature": "^1.2.1",
-        "debug": "4.3.6",
-        "depd": "2.0.0",
-        "encodeurl": "~2.0.0",
-        "escape-html": "~1.0.3",
-        "etag": "~1.8.1",
-        "finalhandler": "^2.0.0",
-        "fresh": "2.0.0",
-        "http-errors": "2.0.0",
+        "debug": "^4.4.0",
+        "encodeurl": "^2.0.0",
+        "escape-html": "^1.0.3",
+        "etag": "^1.8.1",
+        "finalhandler": "^2.1.0",
+        "fresh": "^2.0.0",
+        "http-errors": "^2.0.0",
         "merge-descriptors": "^2.0.0",
-        "methods": "~1.1.2",
         "mime-types": "^3.0.0",
-        "on-finished": "2.4.1",
-        "once": "1.4.0",
-        "parseurl": "~1.3.3",
-        "proxy-addr": "~2.0.7",
-        "qs": "6.13.0",
-        "range-parser": "~1.2.1",
-        "router": "^2.0.0",
-        "safe-buffer": "5.2.1",
+        "on-finished": "^2.4.1",
+        "once": "^1.4.0",
+        "parseurl": "^1.3.3",
+        "proxy-addr": "^2.0.7",
+        "qs": "^6.14.0",
+        "range-parser": "^1.2.1",
+        "router": "^2.2.0",
         "send": "^1.1.0",
-        "serve-static": "^2.1.0",
-        "setprototypeof": "1.2.0",
-        "statuses": "2.0.1",
-        "type-is": "^2.0.0",
-        "utils-merge": "1.0.1",
-        "vary": "~1.1.2"
+        "serve-static": "^2.2.0",
+        "statuses": "^2.0.1",
+        "type-is": "^2.0.1",
+        "vary": "^1.1.2"
       },
       "engines": {
         "node": ">= 18"
+      },
+      "funding": {
+        "type": "opencollective",
+        "url": "https://opencollective.com/express"
       }
     },
     "node_modules/express-rate-limit": {
@@ -1831,7 +1879,6 @@
       "version": "3.1.3",
       "resolved": "https://registry.npmjs.org/fast-deep-equal/-/fast-deep-equal-3.1.3.tgz",
       "integrity": "sha512-f3qQ9oQy9j2AhBe/H9VC91wLmKBCCU/gDOnKNAYG5hswO7BLKj09Hc5HYNz9cGI++xlpDCIgDaitVs03ATR84Q==",
-      "dev": true,
       "license": "MIT"
     },
     "node_modules/fast-glob": {
@@ -1868,7 +1915,6 @@
       "version": "2.1.0",
       "resolved": "https://registry.npmjs.org/fast-json-stable-stringify/-/fast-json-stable-stringify-2.1.0.tgz",
       "integrity": "sha512-lhd/wF+Lk98HZoTCtlVraHtfh5XYijIjalXck7saUtuanSDyLMxnHhSXEDJqHxD7msR8D0uCmqlkwjCV8xvwHw==",
-      "dev": true,
       "license": "MIT"
     },
     "node_modules/fast-levenshtein": {
@@ -1931,29 +1977,6 @@
         "node": ">= 0.8"
       }
     },
-    "node_modules/finalhandler/node_modules/debug": {
-      "version": "4.4.0",
-      "resolved": "https://registry.npmjs.org/debug/-/debug-4.4.0.tgz",
-      "integrity": "sha512-6WTZ/IxCY/T6BALoZHaE4ctp9xm+Z5kY/pzYaCHRFeyVhojxlrm+46y68HA6hr0TcwEssoxNiDEUJQjfPZ/RYA==",
-      "license": "MIT",
-      "dependencies": {
-        "ms": "^2.1.3"
-      },
-      "engines": {
-        "node": ">=6.0"
-      },
-      "peerDependenciesMeta": {
-        "supports-color": {
-          "optional": true
-        }
-      }
-    },
-    "node_modules/finalhandler/node_modules/ms": {
-      "version": "2.1.3",
-      "resolved": "https://registry.npmjs.org/ms/-/ms-2.1.3.tgz",
-      "integrity": "sha512-6FlzubTLZG3J2a/NVCAleEhjzq5oxgHyaCU9yYXvcLsvoVaHJq/s5xXI6/XXP6tz7R9xAOtHnSO/tXtF3WRTlA==",
-      "license": "MIT"
-    },
     "node_modules/find-root": {
       "version": "1.1.0",
       "resolved": "https://registry.npmjs.org/find-root/-/find-root-1.1.0.tgz",
@@ -2313,12 +2336,12 @@
       }
     },
     "node_modules/iconv-lite": {
-      "version": "0.5.2",
-      "resolved": "https://registry.npmjs.org/iconv-lite/-/iconv-lite-0.5.2.tgz",
-      "integrity": "sha512-kERHXvpSaB4aU3eANwidg79K8FlrN77m8G9V+0vOR3HYaRifrlwMEpT7ZBJqLSEIHnEgJTHcWK82wwLwwKwtag==",
+      "version": "0.6.3",
+      "resolved": "https://registry.npmjs.org/iconv-lite/-/iconv-lite-0.6.3.tgz",
+      "integrity": "sha512-4fCk79wshMdzMp2rH06qWrJE4iolqLhCUH+OiuIgU++RB0+94NlDL81atO7GX55uUKueo0txHNtvEyI6D7WdMw==",
       "license": "MIT",
       "dependencies": {
-        "safer-buffer": ">= 2.1.2 < 3"
+        "safer-buffer": ">= 2.1.2 < 3.0.0"
       },
       "engines": {
         "node": ">=0.10.0"
@@ -2812,7 +2835,6 @@
       "version": "0.4.1",
       "resolved": "https://registry.npmjs.org/json-schema-traverse/-/json-schema-traverse-0.4.1.tgz",
       "integrity": "sha512-xbbCH5dCYU5T8LcEhhuh7HJ88HXuW3qsI3Y0zOZFKfZEHcpWiHU/Jxzk629Brsab/mMiHQti9wMP+845RPe3Vg==",
-      "dev": true,
       "license": "MIT"
     },
     "node_modules/json-stable-stringify-without-jsonify": {
@@ -2929,15 +2951,6 @@
         "node": ">= 8"
       }
     },
-    "node_modules/methods": {
-      "version": "1.1.2",
-      "resolved": "https://registry.npmjs.org/methods/-/methods-1.1.2.tgz",
-      "integrity": "sha512-iclAHeNqNm68zFtnZ0e+1L2yUIdvzNoauKU4WBA3VvH/vPFieF7qfRlwUZU+DA9P9bPXIS90ulxoUoCH23sV2w==",
-      "license": "MIT",
-      "engines": {
-        "node": ">= 0.6"
-      }
-    },
     "node_modules/metric-lcs": {
       "version": "0.1.2",
       "resolved": "https://registry.npmjs.org/metric-lcs/-/metric-lcs-0.1.2.tgz",
@@ -2959,6 +2972,21 @@
         "node": ">=8.6"
       }
     },
+    "node_modules/mime": {
+      "version": "4.0.7",
+      "resolved": "https://registry.npmjs.org/mime/-/mime-4.0.7.tgz",
+      "integrity": "sha512-2OfDPL+e03E0LrXaGYOtTFIYhiuzep94NSsuhrNULq+stylcJedcHdzHtz0atMUuGwJfFYs0YL5xeC/Ca2x0eQ==",
+      "funding": [
+        "https://github.com/sponsors/broofa"
+      ],
+      "license": "MIT",
+      "bin": {
+        "mime": "bin/cli.js"
+      },
+      "engines": {
+        "node": ">=16"
+      }
+    },
     "node_modules/mime-db": {
       "version": "1.54.0",
       "resolved": "https://registry.npmjs.org/mime-db/-/mime-db-1.54.0.tgz",
@@ -2969,12 +2997,12 @@
       }
     },
     "node_modules/mime-types": {
-      "version": "3.0.0",
-      "resolved": "https://registry.npmjs.org/mime-types/-/mime-types-3.0.0.tgz",
-      "integrity": "sha512-XqoSHeCGjVClAmoGFG3lVFqQFRIrTVw2OH3axRqAcfaw+gHWIfnASS92AV+Rl/mk0MupgZTRHQOjxY6YVnzK5w==",
+      "version": "3.0.1",
+      "resolved": "https://registry.npmjs.org/mime-types/-/mime-types-3.0.1.tgz",
+      "integrity": "sha512-xRc4oEhT6eaBpU1XF7AjpOFD+xQmXNB5OVKwp4tqCuBpHLS/ZbBDrc07mYTDqVMg6PfxUjjNp85O6Cd2Z/5HWA==",
       "license": "MIT",
       "dependencies": {
-        "mime-db": "^1.53.0"
+        "mime-db": "^1.54.0"
       },
       "engines": {
         "node": ">= 0.6"
@@ -3004,9 +3032,9 @@
       }
     },
     "node_modules/ms": {
-      "version": "2.1.2",
-      "resolved": "https://registry.npmjs.org/ms/-/ms-2.1.2.tgz",
-      "integrity": "sha512-sGkPx+VjMtmA6MX27oA4FBFELFCZZ4S4XqeGOXCv68tT+jb3vk/RyaKWP0PTKyWtmLSM0b+adUTEvbs1PEaH2w==",
+      "version": "2.1.3",
+      "resolved": "https://registry.npmjs.org/ms/-/ms-2.1.3.tgz",
+      "integrity": "sha512-6FlzubTLZG3J2a/NVCAleEhjzq5oxgHyaCU9yYXvcLsvoVaHJq/s5xXI6/XXP6tz7R9xAOtHnSO/tXtF3WRTlA==",
       "license": "MIT"
     },
     "node_modules/natural-compare": {
@@ -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",
@@ -3299,12 +3349,12 @@
       }
     },
     "node_modules/playwright": {
-      "version": "1.53.0-alpha-1746218818000",
-      "resolved": "https://registry.npmjs.org/playwright/-/playwright-1.53.0-alpha-1746218818000.tgz",
-      "integrity": "sha512-mVIjtdqIawIqWVyvCaLmV6XTALCT4oWWrbMjoHyyWRln3jQjnm3RUO9LkaINz+Yh88O3FkuY6RfjGXPXeFeJ4Q==",
+      "version": "1.55.0-alpha-1752701791000",
+      "resolved": "https://registry.npmjs.org/playwright/-/playwright-1.55.0-alpha-1752701791000.tgz",
+      "integrity": "sha512-PA3TvDz7uQ+Pde0uaii5/WpU5vntRJsYFsaSPoBzywIqzYFO1ugk1ZZ0q6z4/xHq0ha1UClvsv3P77B+u1fi+w==",
       "license": "Apache-2.0",
       "dependencies": {
-        "playwright-core": "1.53.0-alpha-1746218818000"
+        "playwright-core": "1.55.0-alpha-1752701791000"
       },
       "bin": {
         "playwright": "cli.js"
@@ -3317,9 +3367,9 @@
       }
     },
     "node_modules/playwright-core": {
-      "version": "1.53.0-alpha-1746218818000",
-      "resolved": "https://registry.npmjs.org/playwright-core/-/playwright-core-1.53.0-alpha-1746218818000.tgz",
-      "integrity": "sha512-iaIZmhO/psGssWpxIprJkFrn2h4xFjgL0jZsKGtReAMZ/XhlqMUJxtSitwWM4BV+wxJIptsZD0s5Ml2KU62Z3w==",
+      "version": "1.55.0-alpha-1752701791000",
+      "resolved": "https://registry.npmjs.org/playwright-core/-/playwright-core-1.55.0-alpha-1752701791000.tgz",
+      "integrity": "sha512-mQhzhjJMiqnGNnYZv7M4yk1OcNTt1E72jrTLO7EqZuoeat4+qpcU0/mbK+RcTEass5a9YheoVFh6OIhruFMGVg==",
       "license": "Apache-2.0",
       "bin": {
         "playwright-core": "cli.js"
@@ -3365,19 +3415,18 @@
       "version": "2.3.1",
       "resolved": "https://registry.npmjs.org/punycode/-/punycode-2.3.1.tgz",
       "integrity": "sha512-vYt7UD1U9Wg6138shLtLOvdAu+8DsC/ilFtEVHcH+wydcSpNE20AfSOduf6MkRFahL5FY7X1oU7nKVZFtfq8Fg==",
-      "dev": true,
       "license": "MIT",
       "engines": {
         "node": ">=6"
       }
     },
     "node_modules/qs": {
-      "version": "6.13.0",
-      "resolved": "https://registry.npmjs.org/qs/-/qs-6.13.0.tgz",
-      "integrity": "sha512-+38qI9SOr8tfZ4QmJNplMUxqjbe7LKvvZgWdExBOmd+egZTtjLB67Gu0HRX3u/XOq7UU2Nx6nsjvS16Z9uwfpg==",
+      "version": "6.14.0",
+      "resolved": "https://registry.npmjs.org/qs/-/qs-6.14.0.tgz",
+      "integrity": "sha512-YWWTjgABSKcvs/nWBi9PycY/JiPJqOD4JA6o9Sej2AtvSGarXxKC3OQSk4pAarbdQlKAh5D4FCQkJNkW+GAn3w==",
       "license": "BSD-3-Clause",
       "dependencies": {
-        "side-channel": "^1.0.6"
+        "side-channel": "^1.1.0"
       },
       "engines": {
         "node": ">=0.6"
@@ -3431,18 +3480,6 @@
         "node": ">= 0.8"
       }
     },
-    "node_modules/raw-body/node_modules/iconv-lite": {
-      "version": "0.6.3",
-      "resolved": "https://registry.npmjs.org/iconv-lite/-/iconv-lite-0.6.3.tgz",
-      "integrity": "sha512-4fCk79wshMdzMp2rH06qWrJE4iolqLhCUH+OiuIgU++RB0+94NlDL81atO7GX55uUKueo0txHNtvEyI6D7WdMw==",
-      "license": "MIT",
-      "dependencies": {
-        "safer-buffer": ">= 2.1.2 < 3.0.0"
-      },
-      "engines": {
-        "node": ">=0.10.0"
-      }
-    },
     "node_modules/reflect.getprototypeof": {
       "version": "1.0.10",
       "resolved": "https://registry.npmjs.org/reflect.getprototypeof/-/reflect.getprototypeof-1.0.10.tgz",
@@ -3530,11 +3567,13 @@
       }
     },
     "node_modules/router": {
-      "version": "2.1.0",
-      "resolved": "https://registry.npmjs.org/router/-/router-2.1.0.tgz",
-      "integrity": "sha512-/m/NSLxeYEgWNtyC+WtNHCF7jbGxOibVWKnn+1Psff4dJGOfoXP+MuC/f2CwSmyiHdOIzYnYFp4W6GxWfekaLA==",
+      "version": "2.2.0",
+      "resolved": "https://registry.npmjs.org/router/-/router-2.2.0.tgz",
+      "integrity": "sha512-nLTrUKm2UyiL7rlhapu/Zl45FwNgkZGaCpZbIHajDYgwlJCOzLSk+cIPAnsEqV955GjILJnKbdQC1nVPz+gAYQ==",
       "license": "MIT",
       "dependencies": {
+        "debug": "^4.4.0",
+        "depd": "^2.0.0",
         "is-promise": "^4.0.0",
         "parseurl": "^1.3.3",
         "path-to-regexp": "^8.0.0"
@@ -3662,19 +3701,18 @@
       }
     },
     "node_modules/send": {
-      "version": "1.1.0",
-      "resolved": "https://registry.npmjs.org/send/-/send-1.1.0.tgz",
-      "integrity": "sha512-v67WcEouB5GxbTWL/4NeToqcZiAWEq90N888fczVArY8A79J0L4FD7vj5hm3eUMua5EpoQ59wa/oovY6TLvRUA==",
+      "version": "1.2.0",
+      "resolved": "https://registry.npmjs.org/send/-/send-1.2.0.tgz",
+      "integrity": "sha512-uaW0WwXKpL9blXE2o0bRhoL2EGXIrZxQ2ZQ4mgcfoBxdFmQold+qWsD2jLrfZ0trjKL6vOw0j//eAwcALFjKSw==",
       "license": "MIT",
       "dependencies": {
         "debug": "^4.3.5",
-        "destroy": "^1.2.0",
         "encodeurl": "^2.0.0",
         "escape-html": "^1.0.3",
         "etag": "^1.8.1",
-        "fresh": "^0.5.2",
+        "fresh": "^2.0.0",
         "http-errors": "^2.0.0",
-        "mime-types": "^2.1.35",
+        "mime-types": "^3.0.1",
         "ms": "^2.1.3",
         "on-finished": "^2.4.1",
         "range-parser": "^1.2.1",
@@ -3684,52 +3722,16 @@
         "node": ">= 18"
       }
     },
-    "node_modules/send/node_modules/fresh": {
-      "version": "0.5.2",
-      "resolved": "https://registry.npmjs.org/fresh/-/fresh-0.5.2.tgz",
-      "integrity": "sha512-zJ2mQYM18rEFOudeV4GShTGIQ7RbzA7ozbU9I/XBpm7kqgMywgmylMwXHxZJmkVoYkna9d2pVXVXPdYTP9ej8Q==",
-      "license": "MIT",
-      "engines": {
-        "node": ">= 0.6"
-      }
-    },
-    "node_modules/send/node_modules/mime-db": {
-      "version": "1.52.0",
-      "resolved": "https://registry.npmjs.org/mime-db/-/mime-db-1.52.0.tgz",
-      "integrity": "sha512-sPU4uV7dYlvtWJxwwxHD0PuihVNiE7TyAbQ5SWxDCB9mUYvOgroQOwYQQOKPJ8CIbE+1ETVlOoK1UC2nU3gYvg==",
-      "license": "MIT",
-      "engines": {
-        "node": ">= 0.6"
-      }
-    },
-    "node_modules/send/node_modules/mime-types": {
-      "version": "2.1.35",
-      "resolved": "https://registry.npmjs.org/mime-types/-/mime-types-2.1.35.tgz",
-      "integrity": "sha512-ZDY+bPm5zTTF+YpCrAU9nK0UgICYPT0QtT1NZWFv4s++TNkcgVaT0g6+4R2uI4MjQjzysHB1zxuWL50hzaeXiw==",
-      "license": "MIT",
-      "dependencies": {
-        "mime-db": "1.52.0"
-      },
-      "engines": {
-        "node": ">= 0.6"
-      }
-    },
-    "node_modules/send/node_modules/ms": {
-      "version": "2.1.3",
-      "resolved": "https://registry.npmjs.org/ms/-/ms-2.1.3.tgz",
-      "integrity": "sha512-6FlzubTLZG3J2a/NVCAleEhjzq5oxgHyaCU9yYXvcLsvoVaHJq/s5xXI6/XXP6tz7R9xAOtHnSO/tXtF3WRTlA==",
-      "license": "MIT"
-    },
     "node_modules/serve-static": {
-      "version": "2.1.0",
-      "resolved": "https://registry.npmjs.org/serve-static/-/serve-static-2.1.0.tgz",
-      "integrity": "sha512-A3We5UfEjG8Z7VkDv6uItWw6HY2bBSBJT1KtVESn6EOoOr2jAxNhxWCLY3jDE2WcuHXByWju74ck3ZgLwL8xmA==",
+      "version": "2.2.0",
+      "resolved": "https://registry.npmjs.org/serve-static/-/serve-static-2.2.0.tgz",
+      "integrity": "sha512-61g9pCh0Vnh7IutZjtLGGpTA355+OPn2TyDv/6ivP2h/AdAVX9azsoxmg2/M6nZeQZNYBEwIcsne1mJd9oQItQ==",
       "license": "MIT",
       "dependencies": {
         "encodeurl": "^2.0.0",
         "escape-html": "^1.0.3",
         "parseurl": "^1.3.3",
-        "send": "^1.0.0"
+        "send": "^1.2.0"
       },
       "engines": {
         "node": ">= 18"
@@ -4062,9 +4064,9 @@
       }
     },
     "node_modules/type-is": {
-      "version": "2.0.0",
-      "resolved": "https://registry.npmjs.org/type-is/-/type-is-2.0.0.tgz",
-      "integrity": "sha512-gd0sGezQYCbWSbkZr75mln4YBidWUN60+devscpLF5mtRDUpiaTvKpBNrdaCvel1NdR2k6vclXybU5fBd2i+nw==",
+      "version": "2.0.1",
+      "resolved": "https://registry.npmjs.org/type-is/-/type-is-2.0.1.tgz",
+      "integrity": "sha512-OZs6gsjF4vMp32qrCbiVSkrFmXtG/AZhY3t0iAMrMBiAZyV9oALtXO8hsrHbMXF9x6L3grlFuwW2oAz7cav+Gw==",
       "license": "MIT",
       "dependencies": {
         "content-type": "^1.0.5",
@@ -4206,21 +4208,11 @@
       "version": "4.4.1",
       "resolved": "https://registry.npmjs.org/uri-js/-/uri-js-4.4.1.tgz",
       "integrity": "sha512-7rKUyy33Q1yc98pQ1DAmLtwX109F7TIfWlW1Ydo8Wl1ii1SeHieeh0HHfPeL2fMXK6z0s8ecKs9frCuLJvndBg==",
-      "dev": true,
       "license": "BSD-2-Clause",
       "dependencies": {
         "punycode": "^2.1.0"
       }
     },
-    "node_modules/utils-merge": {
-      "version": "1.0.1",
-      "resolved": "https://registry.npmjs.org/utils-merge/-/utils-merge-1.0.1.tgz",
-      "integrity": "sha512-pMZTvIkT1d+TFGvDOqodOclx0QWkkgi6Tdoa8gC8ffGAAqz9pzPTZWAybbsHHoED/ztMtkv/VoYTYyShUn81hA==",
-      "license": "MIT",
-      "engines": {
-        "node": ">= 0.4.0"
-      }
-    },
     "node_modules/vary": {
       "version": "1.1.2",
       "resolved": "https://registry.npmjs.org/vary/-/vary-1.1.2.tgz",
@@ -4350,16 +4342,25 @@
       "integrity": "sha512-l4Sp/DRseor9wL6EvV2+TuQn63dMkPjZ/sp9XkghTEbV9KlPS1xUsZ3u7/IQO4wxtcFB4bgpQPRcR3QCvezPcQ==",
       "license": "ISC"
     },
-    "node_modules/yaml": {
-      "version": "2.7.1",
-      "resolved": "https://registry.npmjs.org/yaml/-/yaml-2.7.1.tgz",
-      "integrity": "sha512-10ULxpnOCQXxJvBgxsn9ptjq6uviG/htZKk9veJGhlqn3w/DxQ631zFF+nlQXLwmImeS5amR2dl2U8sg6U9jsQ==",
-      "license": "ISC",
-      "bin": {
-        "yaml": "bin.mjs"
-      },
+    "node_modules/ws": {
+      "version": "8.18.1",
+      "resolved": "https://registry.npmjs.org/ws/-/ws-8.18.1.tgz",
+      "integrity": "sha512-RKW2aJZMXeMxVpnZ6bck+RswznaxmzdULiBr6KY7XkTnW8uvt0iT9H5DkHUChXrc+uurzwa0rVI16n/Xzjdz1w==",
+      "license": "MIT",
       "engines": {
-        "node": ">= 14"
+        "node": ">=10.0.0"
+      },
+      "peerDependencies": {
+        "bufferutil": "^4.0.1",
+        "utf-8-validate": ">=5.0.2"
+      },
+      "peerDependenciesMeta": {
+        "bufferutil": {
+          "optional": true
+        },
+        "utf-8-validate": {
+          "optional": true
+        }
       }
     },
     "node_modules/yocto-queue": {

package.json

@@ -1,6 +1,6 @@
 {
   "name": "@playwright/mcp",
-  "version": "0.0.19",
+  "version": "0.0.32",
   "description": "Playwright Tools for MCP",
   "type": "module",
   "repository": {
@@ -17,14 +17,18 @@
   "license": "Apache-2.0",
   "scripts": {
     "build": "tsc",
-    "lint": "npm run update-readme && eslint .",
+    "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",
     "test": "playwright test",
     "ctest": "playwright test --project=chrome",
     "ftest": "playwright test --project=firefox",
     "wtest": "playwright test --project=webkit",
-    "clean": "rm -rf lib",
+    "run-server": "node lib/browserServer.js",
+    "clean": "rm -rf lib extension/lib",
     "npm-publish": "npm run clean && npm run build && npm run test && npm publish"
   },
   "exports": {
@@ -35,24 +39,33 @@
     }
   },
   "dependencies": {
-    "@modelcontextprotocol/sdk": "^1.10.1",
+    "@modelcontextprotocol/sdk": "^1.16.0",
     "commander": "^13.1.0",
-    "playwright": "1.53.0-alpha-1746218818000",
-    "yaml": "^2.7.1",
+    "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",
+    "ws": "^8.18.1",
     "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.53.0-alpha-1746218818000",
+    "@playwright/test": "1.55.0-alpha-1752701791000",
     "@stylistic/eslint-plugin": "^3.0.1",
+    "@types/chrome": "^0.0.315",
+    "@types/debug": "^4.1.12",
     "@types/node": "^22.13.10",
+    "@types/ws": "^8.18.1",
     "@typescript-eslint/eslint-plugin": "^8.26.1",
     "@typescript-eslint/parser": "^8.26.1",
     "@typescript-eslint/utils": "^8.26.1",
     "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": {

playwright.config.ts

@@ -29,6 +29,14 @@ export default defineConfig<TestOptions>({
     { name: 'chrome' },
     { name: 'msedge', use: { mcpBrowser: 'msedge' } },
     { name: 'chromium', use: { mcpBrowser: 'chromium' } },
+    ...process.env.MCP_IN_DOCKER ? [{
+      name: 'chromium-docker',
+      grep: /browser_navigate|browser_click/,
+      use: {
+        mcpBrowser: 'chromium',
+        mcpMode: 'docker' as const
+      }
+    }] : [],
     { name: 'firefox', use: { mcpBrowser: 'firefox' } },
     { name: 'webkit', use: { mcpBrowser: 'webkit' } },
   ],

src/browserContextFactory.ts

@@ -0,0 +1,229 @@
+/**
+ * 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 'node:fs';
+import net from 'node:net';
+import path from 'node:path';
+import os from 'node:os';
+
+import * as playwright from 'playwright';
+
+import { logUnhandledError, testDebug } from './log.js';
+
+import type { FullConfig } from './config.js';
+
+export function contextFactory(browserConfig: FullConfig['browser']): BrowserContextFactory {
+  if (browserConfig.remoteEndpoint)
+    return new RemoteContextFactory(browserConfig);
+  if (browserConfig.cdpEndpoint)
+    return new CdpContextFactory(browserConfig);
+  if (browserConfig.isolated)
+    return new IsolatedContextFactory(browserConfig);
+  return new PersistentContextFactory(browserConfig);
+}
+
+export interface BrowserContextFactory {
+  createContext(clientInfo: { name: string, version: string }): Promise<{ browserContext: playwright.BrowserContext, close: () => Promise<void> }>;
+}
+
+class BaseContextFactory implements BrowserContextFactory {
+  readonly browserConfig: FullConfig['browser'];
+  protected _browserPromise: Promise<playwright.Browser> | undefined;
+  readonly name: string;
+
+  constructor(name: string, browserConfig: FullConfig['browser']) {
+    this.name = name;
+    this.browserConfig = browserConfig;
+  }
+
+  protected async _obtainBrowser(): Promise<playwright.Browser> {
+    if (this._browserPromise)
+      return this._browserPromise;
+    testDebug(`obtain browser (${this.name})`);
+    this._browserPromise = this._doObtainBrowser();
+    void this._browserPromise.then(browser => {
+      browser.on('disconnected', () => {
+        this._browserPromise = undefined;
+      });
+    }).catch(() => {
+      this._browserPromise = undefined;
+    });
+    return this._browserPromise;
+  }
+
+  protected async _doObtainBrowser(): Promise<playwright.Browser> {
+    throw new Error('Not implemented');
+  }
+
+  async createContext(): Promise<{ browserContext: playwright.BrowserContext, close: () => Promise<void> }> {
+    testDebug(`create browser context (${this.name})`);
+    const browser = await this._obtainBrowser();
+    const browserContext = await this._doCreateContext(browser);
+    return { browserContext, close: () => this._closeBrowserContext(browserContext, browser) };
+  }
+
+  protected async _doCreateContext(browser: playwright.Browser): Promise<playwright.BrowserContext> {
+    throw new Error('Not implemented');
+  }
+
+  private async _closeBrowserContext(browserContext: playwright.BrowserContext, browser: playwright.Browser) {
+    testDebug(`close browser context (${this.name})`);
+    if (browser.contexts().length === 1)
+      this._browserPromise = undefined;
+    await browserContext.close().catch(logUnhandledError);
+    if (browser.contexts().length === 0) {
+      testDebug(`close browser (${this.name})`);
+      await browser.close().catch(logUnhandledError);
+    }
+  }
+}
+
+class IsolatedContextFactory extends BaseContextFactory {
+  constructor(browserConfig: FullConfig['browser']) {
+    super('isolated', browserConfig);
+  }
+
+  protected override async _doObtainBrowser(): Promise<playwright.Browser> {
+    await injectCdpPort(this.browserConfig);
+    const browserType = playwright[this.browserConfig.browserName];
+    return browserType.launch({
+      ...this.browserConfig.launchOptions,
+      handleSIGINT: false,
+      handleSIGTERM: false,
+    }).catch(error => {
+      if (error.message.includes('Executable doesn\'t exist'))
+        throw new Error(`Browser specified in your config is not installed. Either install it (likely) or change the config.`);
+      throw error;
+    });
+  }
+
+  protected override async _doCreateContext(browser: playwright.Browser): Promise<playwright.BrowserContext> {
+    return browser.newContext(this.browserConfig.contextOptions);
+  }
+}
+
+class CdpContextFactory extends BaseContextFactory {
+  constructor(browserConfig: FullConfig['browser']) {
+    super('cdp', browserConfig);
+  }
+
+  protected override async _doObtainBrowser(): Promise<playwright.Browser> {
+    return playwright.chromium.connectOverCDP(this.browserConfig.cdpEndpoint!);
+  }
+
+  protected override async _doCreateContext(browser: playwright.Browser): Promise<playwright.BrowserContext> {
+    return this.browserConfig.isolated ? await browser.newContext() : browser.contexts()[0];
+  }
+}
+
+class RemoteContextFactory extends BaseContextFactory {
+  constructor(browserConfig: FullConfig['browser']) {
+    super('remote', browserConfig);
+  }
+
+  protected override async _doObtainBrowser(): Promise<playwright.Browser> {
+    const url = new URL(this.browserConfig.remoteEndpoint!);
+    url.searchParams.set('browser', this.browserConfig.browserName);
+    if (this.browserConfig.launchOptions)
+      url.searchParams.set('launch-options', JSON.stringify(this.browserConfig.launchOptions));
+    return playwright[this.browserConfig.browserName].connect(String(url));
+  }
+
+  protected override async _doCreateContext(browser: playwright.Browser): Promise<playwright.BrowserContext> {
+    return browser.newContext();
+  }
+}
+
+class PersistentContextFactory implements BrowserContextFactory {
+  readonly browserConfig: FullConfig['browser'];
+  private _userDataDirs = new Set<string>();
+
+  constructor(browserConfig: FullConfig['browser']) {
+    this.browserConfig = browserConfig;
+  }
+
+  async createContext(): Promise<{ browserContext: playwright.BrowserContext, close: () => Promise<void> }> {
+    await injectCdpPort(this.browserConfig);
+    testDebug('create browser context (persistent)');
+    const userDataDir = this.browserConfig.userDataDir ?? await this._createUserDataDir();
+
+    this._userDataDirs.add(userDataDir);
+    testDebug('lock user data dir', userDataDir);
+
+    const browserType = playwright[this.browserConfig.browserName];
+    for (let i = 0; i < 5; i++) {
+      try {
+        const browserContext = await browserType.launchPersistentContext(userDataDir, {
+          ...this.browserConfig.launchOptions,
+          ...this.browserConfig.contextOptions,
+          handleSIGINT: false,
+          handleSIGTERM: false,
+        });
+        const close = () => this._closeBrowserContext(browserContext, userDataDir);
+        return { browserContext, close };
+      } catch (error: any) {
+        if (error.message.includes('Executable doesn\'t exist'))
+          throw new Error(`Browser specified in your config is not installed. Either install it (likely) or change the config.`);
+        if (error.message.includes('ProcessSingleton') || error.message.includes('Invalid URL')) {
+          // User data directory is already in use, try again.
+          await new Promise(resolve => setTimeout(resolve, 1000));
+          continue;
+        }
+        throw error;
+      }
+    }
+    throw new Error(`Browser is already in use for ${userDataDir}, use --isolated to run multiple instances of the same browser`);
+  }
+
+  private async _closeBrowserContext(browserContext: playwright.BrowserContext, userDataDir: string) {
+    testDebug('close browser context (persistent)');
+    testDebug('release user data dir', userDataDir);
+    await browserContext.close().catch(() => {});
+    this._userDataDirs.delete(userDataDir);
+    testDebug('close browser context complete (persistent)');
+  }
+
+  private async _createUserDataDir() {
+    let cacheDirectory: string;
+    if (process.platform === 'linux')
+      cacheDirectory = process.env.XDG_CACHE_HOME || path.join(os.homedir(), '.cache');
+    else if (process.platform === 'darwin')
+      cacheDirectory = path.join(os.homedir(), 'Library', 'Caches');
+    else if (process.platform === 'win32')
+      cacheDirectory = process.env.LOCALAPPDATA || path.join(os.homedir(), 'AppData', 'Local');
+    else
+      throw new Error('Unsupported platform: ' + process.platform);
+    const result = path.join(cacheDirectory, 'ms-playwright', `mcp-${this.browserConfig.launchOptions?.channel ?? this.browserConfig?.browserName}-profile`);
+    await fs.promises.mkdir(result, { recursive: true });
+    return result;
+  }
+}
+
+async function injectCdpPort(browserConfig: FullConfig['browser']) {
+  if (browserConfig.browserName === 'chromium')
+    (browserConfig.launchOptions as any).cdpPort = await findFreePort();
+}
+
+async function findFreePort(): Promise<number> {
+  return new Promise((resolve, reject) => {
+    const server = net.createServer();
+    server.listen(0, () => {
+      const { port } = server.address() as net.AddressInfo;
+      server.close(() => resolve(port));
+    });
+    server.on('error', reject);
+  });
+}

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);
+  }
+}

src/config.ts

@@ -15,51 +15,94 @@
  */
 
 import fs from 'fs';
-import net from 'net';
 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[];
+  blockedOrigins?: string[];
+  blockServiceWorkers?: boolean;
   browser?: string;
-  caps?: string;
+  caps?: string[];
   cdpEndpoint?: string;
+  config?: string;
+  device?: string;
   executablePath?: string;
   headless?: boolean;
-  device?: string;
-  userDataDir?: string;
-  port?: number;
   host?: string;
-  vision?: boolean;
-  config?: string;
+  ignoreHttpsErrors?: boolean;
+  isolated?: boolean;
+  imageResponses?: 'allow' | 'omit';
+  sandbox?: boolean;
+  outputDir?: string;
+  port?: number;
+  proxyBypass?: string;
+  proxyServer?: string;
+  saveSession?: boolean;
+  saveTrace?: boolean;
+  storageState?: string;
+  userAgent?: string;
+  userDataDir?: string;
+  viewportSize?: string;
 };
 
-const defaultConfig: Config = {
+const defaultConfig: FullConfig = {
   browser: {
     browserName: 'chromium',
-    userDataDir: os.tmpdir(),
     launchOptions: {
       channel: 'chrome',
       headless: os.platform() === 'linux' && !process.env.DISPLAY,
+      chromiumSandbox: true,
     },
     contextOptions: {
       viewport: null,
     },
   },
+  network: {
+    allowedOrigins: undefined,
+    blockedOrigins: undefined,
+  },
+  server: {},
+  outputDir: path.join(os.tmpdir(), 'playwright-mcp-output', sanitizeForFilePath(new Date().toISOString())),
 };
 
-export async function resolveConfig(cliOptions: CLIOptions): Promise<Config> {
-  const config = await loadConfig(cliOptions.config);
-  const cliOverrides = await configFromCLIOptions(cliOptions);
-  return mergeConfig(defaultConfig, mergeConfig(config, cliOverrides));
+type BrowserUserConfig = NonNullable<Config['browser']>;
+
+export type FullConfig = Config & {
+  browser: Omit<BrowserUserConfig, 'browserName'> & {
+    browserName: 'chromium' | 'firefox' | 'webkit';
+    launchOptions: NonNullable<BrowserUserConfig['launchOptions']>;
+    contextOptions: NonNullable<BrowserUserConfig['contextOptions']>;
+  },
+  network: NonNullable<Config['network']>,
+  outputDir: string;
+  server: NonNullable<Config['server']>,
+};
+
+export async function resolveConfig(config: Config): Promise<FullConfig> {
+  return mergeConfig(defaultConfig, config);
 }
 
-export async function configFromCLIOptions(cliOptions: CLIOptions): Promise<Config> {
-  let browserName: 'chromium' | 'firefox' | 'webkit';
+export async function resolveCLIConfig(cliOptions: CLIOptions): Promise<FullConfig> {
+  const configInFile = await loadConfig(cliOptions.config);
+  const envOverrides = configFromEnv();
+  const cliOverrides = configFromCLIOptions(cliOptions);
+  let result = defaultConfig;
+  result = mergeConfig(result, configInFile);
+  result = mergeConfig(result, envOverrides);
+  result = mergeConfig(result, cliOverrides);
+  // Derive artifact output directory from config.outputDir
+  if (result.saveTrace)
+    result.browser.launchOptions.tracesDir = path.join(result.outputDir, 'traces');
+  return result;
+}
+
+export function configFromCLIOptions(cliOptions: CLIOptions): Config {
+  let browserName: 'chromium' | 'firefox' | 'webkit' | undefined;
   let channel: string | undefined;
   switch (cliOptions.browser) {
     case 'chrome':
@@ -80,26 +123,60 @@ export async function configFromCLIOptions(cliOptions: CLIOptions): Promise<Conf
     case 'webkit':
       browserName = 'webkit';
       break;
-    default:
-      browserName = 'chromium';
-      channel = 'chrome';
   }
 
+  // Launch options
   const launchOptions: LaunchOptions = {
     channel,
     executablePath: cliOptions.executablePath,
     headless: cliOptions.headless,
   };
 
-  if (browserName === 'chromium')
-    (launchOptions as any).webSocketPort = await findFreePort();
+  // --no-sandbox was passed, disable the sandbox
+  if (cliOptions.sandbox === false)
+    launchOptions.chromiumSandbox = false;
 
-  const contextOptions: BrowserContextOptions | undefined = cliOptions.device ? devices[cliOptions.device] : undefined;
+  if (cliOptions.proxyServer) {
+    launchOptions.proxy = {
+      server: cliOptions.proxyServer
+    };
+    if (cliOptions.proxyBypass)
+      launchOptions.proxy.bypass = cliOptions.proxyBypass;
+  }
 
-  return {
+  if (cliOptions.device && cliOptions.cdpEndpoint)
+    throw new Error('Device emulation is not supported with cdpEndpoint.');
+
+  // Context options
+  const contextOptions: BrowserContextOptions = cliOptions.device ? devices[cliOptions.device] : {};
+  if (cliOptions.storageState)
+    contextOptions.storageState = cliOptions.storageState;
+
+  if (cliOptions.userAgent)
+    contextOptions.userAgent = cliOptions.userAgent;
+
+  if (cliOptions.viewportSize) {
+    try {
+      const [width, height] = cliOptions.viewportSize.split(',').map(n => +n);
+      if (isNaN(width) || isNaN(height))
+        throw new Error('bad values');
+      contextOptions.viewport = { width, height };
+    } catch (e) {
+      throw new Error('Invalid viewport size format: use "width,height", for example --viewport-size="800,600"');
+    }
+  }
+
+  if (cliOptions.ignoreHttpsErrors)
+    contextOptions.ignoreHTTPSErrors = true;
+
+  if (cliOptions.blockServiceWorkers)
+    contextOptions.serviceWorkers = 'block';
+
+  const result: Config = {
     browser: {
       browserName,
-      userDataDir: cliOptions.userDataDir ?? await createUserDataDir({ browserName, channel }),
+      isolated: cliOptions.isolated,
+      userDataDir: cliOptions.userDataDir,
       launchOptions,
       contextOptions,
       cdpEndpoint: cliOptions.cdpEndpoint,
@@ -108,20 +185,48 @@ export async function configFromCLIOptions(cliOptions: CLIOptions): Promise<Conf
       port: cliOptions.port,
       host: cliOptions.host,
     },
-    capabilities: cliOptions.caps?.split(',').map((c: string) => c.trim() as ToolCapability),
-    vision: !!cliOptions.vision,
+    capabilities: cliOptions.caps as ToolCapability[],
+    network: {
+      allowedOrigins: cliOptions.allowedOrigins,
+      blockedOrigins: cliOptions.blockedOrigins,
+    },
+    saveSession: cliOptions.saveSession,
+    saveTrace: cliOptions.saveTrace,
+    outputDir: cliOptions.outputDir,
+    imageResponses: cliOptions.imageResponses,
   };
+
+  return result;
 }
 
-async function findFreePort() {
-  return new Promise((resolve, reject) => {
-    const server = net.createServer();
-    server.listen(0, () => {
-      const { port } = server.address() as net.AddressInfo;
-      server.close(() => resolve(port));
-    });
-    server.on('error', reject);
-  });
+function configFromEnv(): Config {
+  const options: CLIOptions = {};
+  options.allowedOrigins = semicolonSeparatedList(process.env.PLAYWRIGHT_MCP_ALLOWED_ORIGINS);
+  options.blockedOrigins = semicolonSeparatedList(process.env.PLAYWRIGHT_MCP_BLOCKED_ORIGINS);
+  options.blockServiceWorkers = envToBoolean(process.env.PLAYWRIGHT_MCP_BLOCK_SERVICE_WORKERS);
+  options.browser = envToString(process.env.PLAYWRIGHT_MCP_BROWSER);
+  options.caps = commaSeparatedList(process.env.PLAYWRIGHT_MCP_CAPS);
+  options.cdpEndpoint = envToString(process.env.PLAYWRIGHT_MCP_CDP_ENDPOINT);
+  options.config = envToString(process.env.PLAYWRIGHT_MCP_CONFIG);
+  options.device = envToString(process.env.PLAYWRIGHT_MCP_DEVICE);
+  options.executablePath = envToString(process.env.PLAYWRIGHT_MCP_EXECUTABLE_PATH);
+  options.headless = envToBoolean(process.env.PLAYWRIGHT_MCP_HEADLESS);
+  options.host = envToString(process.env.PLAYWRIGHT_MCP_HOST);
+  options.ignoreHttpsErrors = envToBoolean(process.env.PLAYWRIGHT_MCP_IGNORE_HTTPS_ERRORS);
+  options.isolated = envToBoolean(process.env.PLAYWRIGHT_MCP_ISOLATED);
+  if (process.env.PLAYWRIGHT_MCP_IMAGE_RESPONSES === 'omit')
+    options.imageResponses = 'omit';
+  options.sandbox = envToBoolean(process.env.PLAYWRIGHT_MCP_SANDBOX);
+  options.outputDir = envToString(process.env.PLAYWRIGHT_MCP_OUTPUT_DIR);
+  options.port = envToNumber(process.env.PLAYWRIGHT_MCP_PORT);
+  options.proxyBypass = envToString(process.env.PLAYWRIGHT_MCP_PROXY_BYPASS);
+  options.proxyServer = envToString(process.env.PLAYWRIGHT_MCP_PROXY_SERVER);
+  options.saveTrace = envToBoolean(process.env.PLAYWRIGHT_MCP_SAVE_TRACE);
+  options.storageState = envToString(process.env.PLAYWRIGHT_MCP_STORAGE_STATE);
+  options.userAgent = envToString(process.env.PLAYWRIGHT_MCP_USER_AGENT);
+  options.userDataDir = envToString(process.env.PLAYWRIGHT_MCP_USER_DATA_DIR);
+  options.viewportSize = envToString(process.env.PLAYWRIGHT_MCP_VIEWPORT_SIZE);
+  return configFromCLIOptions(options);
 }
 
 async function loadConfig(configFile: string | undefined): Promise<Config> {
@@ -135,26 +240,10 @@ async function loadConfig(configFile: string | undefined): Promise<Config> {
   }
 }
 
-async function createUserDataDir(options: { browserName: 'chromium' | 'firefox' | 'webkit', channel: string | undefined }) {
-  let cacheDirectory: string;
-  if (process.platform === 'linux')
-    cacheDirectory = process.env.XDG_CACHE_HOME || path.join(os.homedir(), '.cache');
-  else if (process.platform === 'darwin')
-    cacheDirectory = path.join(os.homedir(), 'Library', 'Caches');
-  else if (process.platform === 'win32')
-    cacheDirectory = process.env.LOCALAPPDATA || path.join(os.homedir(), 'AppData', 'Local');
-  else
-    throw new Error('Unsupported platform: ' + process.platform);
-  const result = path.join(cacheDirectory, 'ms-playwright', `mcp-${options.channel ?? options.browserName}-profile`);
-  await fs.promises.mkdir(result, { recursive: true });
-  return result;
-}
-
-export async function outputFile(config: Config, name: string): Promise<string> {
-  const result = config.outputDir ?? os.tmpdir();
-  await fs.promises.mkdir(result, { recursive: true });
+export async function outputFile(config: FullConfig, name: string): Promise<string> {
+  await fs.promises.mkdir(config.outputDir, { recursive: true });
   const fileName = sanitizeForFilePath(name);
-  return path.join(result, fileName);
+  return path.join(config.outputDir, fileName);
 }
 
 function pickDefined<T extends object>(obj: T | undefined): Partial<T> {
@@ -163,10 +252,12 @@ function pickDefined<T extends object>(obj: T | undefined): Partial<T> {
   ) as Partial<T>;
 }
 
-function mergeConfig(base: Config, overrides: Config): Config {
-  const browser: Config['browser'] = {
+function mergeConfig(base: FullConfig, overrides: Config): FullConfig {
+  const browser: FullConfig['browser'] = {
     ...pickDefined(base.browser),
     ...pickDefined(overrides.browser),
+    browserName: overrides.browser?.browserName ?? base.browser?.browserName ?? 'chromium',
+    isolated: overrides.browser?.isolated ?? base.browser?.isolated ?? false,
     launchOptions: {
       ...pickDefined(base.browser?.launchOptions),
       ...pickDefined(overrides.browser?.launchOptions),
@@ -178,12 +269,50 @@ function mergeConfig(base: Config, overrides: Config): Config {
     },
   };
 
-  if (browser.browserName !== 'chromium')
+  if (browser.browserName !== 'chromium' && browser.launchOptions)
     delete browser.launchOptions.channel;
 
   return {
     ...pickDefined(base),
     ...pickDefined(overrides),
     browser,
-  };
+    network: {
+      ...pickDefined(base.network),
+      ...pickDefined(overrides.network),
+    },
+    server: {
+      ...pickDefined(base.server),
+      ...pickDefined(overrides.server),
+    },
+  } as FullConfig;
+}
+
+export function semicolonSeparatedList(value: string | undefined): string[] | undefined {
+  if (!value)
+    return undefined;
+  return value.split(';').map(v => v.trim());
+}
+
+export function commaSeparatedList(value: string | undefined): string[] | undefined {
+  if (!value)
+    return undefined;
+  return value.split(',').map(v => v.trim());
+}
+
+function envToNumber(value: string | undefined): number | undefined {
+  if (!value)
+    return undefined;
+  return +value;
+}
+
+function envToBoolean(value: string | undefined): boolean | undefined {
+  if (value === 'true' || value === '1')
+    return true;
+  if (value === 'false' || value === '0')
+    return false;
+  return undefined;
+}
+
+function envToString(value: string | undefined): string | undefined {
+  return value ? value.trim() : undefined;
 }

src/context.ts

@@ -14,242 +14,110 @@
  * limitations under the License.
  */
 
+import debug from 'debug';
 import * as playwright from 'playwright';
 
-import { waitForCompletion } from './tools/utils.js';
-import { ManualPromise } from './manualPromise.js';
+import { logUnhandledError } from './log.js';
 import { Tab } from './tab.js';
 
-import type { ImageContent, TextContent } from '@modelcontextprotocol/sdk/types.js';
-import type { ModalState, Tool, ToolActionResult } from './tools/tool.js';
-import type { Config } from '../config.js';
-import { outputFile } from './config.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 {
   readonly tools: Tool[];
-  readonly config: Config;
-  private _browser: playwright.Browser | undefined;
-  private _browserContext: playwright.BrowserContext | undefined;
-  private _createBrowserContextPromise: Promise<{ browser?: playwright.Browser, browserContext: playwright.BrowserContext }> | undefined;
+  readonly config: FullConfig;
+  private _browserContextPromise: Promise<{ browserContext: playwright.BrowserContext, close: () => Promise<void> }> | undefined;
+  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;
 
-  constructor(tools: Tool[], config: Config) {
+  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);
   }
 
-  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 of 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;
   }
 
   async newTab(): Promise<Tab> {
-    const browserContext = await this._ensureBrowserContext();
+    const { browserContext } = await this._ensureBrowserContext();
     const page = await browserContext.newPage();
     this._currentTab = this._tabs.find(t => t.page === page)!;
     return this._currentTab;
   }
 
   async selectTab(index: number) {
-    this._currentTab = this._tabs[index - 1];
-    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> {
-    const context = await this._ensureBrowserContext();
+    const { browserContext } = await this._ensureBrowserContext();
     if (!this._currentTab)
-      await context.newPage();
+      await browserContext.newPage();
     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];
-      const title = await tab.page.title();
+      const title = await tab.title();
       const url = tab.page.url();
       const current = tab === this._currentTab ? ' (current)' : '';
-      lines.push(`- ${i + 1}:${current} [${title}] (${url})`);
+      lines.push(`- ${i}:${current} [${title}] (${url})`);
     }
-    return lines.join('\n');
+    lines.push('');
+    return lines;
   }
 
-  async closeTab(index: number | undefined) {
-    const tab = index === undefined ? this._currentTab : this._tabs[index - 1];
-    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;
-    const racingAction = action ? () => this._raceAgainstModalDialogs(action) : undefined;
-
-    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.
-    let actionResult: { content?: (ImageContent | TextContent)[] } | undefined;
-    try {
-      if (waitForNetwork)
-        actionResult = await waitForCompletion(this, tab.page, async () => racingAction?.()) ?? undefined;
-      else
-        actionResult = await racingAction?.() ?? 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'),
-        }],
-      };
-    }
-
-    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()} ...`);
-      }
-      result.push('');
-    }
-
-    if (this.tabs().length > 1)
-      result.push(await this.listTabsMarkdown(), '');
-
-    if (this.tabs().length > 1)
-      result.push('### Current tab');
-
-    result.push(
-        `- Page URL: ${tab.page.url()}`,
-        `- Page Title: ${await tab.page.title()}`
-    );
-
-    if (captureSnapshot && tab.hasSnapshot())
-      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 this._currentTab.page.evaluate(() => new Promise(f => setTimeout(f, 1000)));
-    else
-      await new Promise(f => setTimeout(f, time));
-  }
-
-  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;
+  async closeTab(index: number | undefined): Promise<string> {
+    const tab = index === undefined ? this._currentTab : this._tabs[index];
+    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) {
@@ -260,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;
@@ -268,80 +135,80 @@ ${code.join('\n')}
 
     if (this._currentTab === tab)
       this._currentTab = this._tabs[Math.min(index, this._tabs.length - 1)];
-    if (this._browserContext && !this._tabs.length)
-      void this.close();
+    if (!this._tabs.length)
+      void this.closeBrowserContext();
   }
 
-  async close() {
-    if (!this._browserContext)
+  async closeBrowserContext() {
+    if (!this._closeBrowserContextPromise)
+      this._closeBrowserContextPromise = this._closeBrowserContextImpl().catch(logUnhandledError);
+    await this._closeBrowserContextPromise;
+    this._closeBrowserContextPromise = undefined;
+  }
+
+  private async _closeBrowserContextImpl() {
+    if (!this._browserContextPromise)
       return;
-    const browserContext = this._browserContext;
-    const browser = this._browser;
-    this._createBrowserContextPromise = undefined;
-    this._browserContext = undefined;
-    this._browser = undefined;
 
-    await browserContext?.close().then(async () => {
-      await browser?.close();
-    }).catch(() => {});
+    testDebug('close context');
+
+    const promise = this._browserContextPromise;
+    this._browserContextPromise = undefined;
+
+    await promise.then(async ({ browserContext, close }) => {
+      if (this.config.saveTrace)
+        await browserContext.tracing.stop();
+      await close();
+    });
   }
 
-  private async _ensureBrowserContext() {
-    if (!this._browserContext) {
-      const context = await this._createBrowserContext();
-      this._browser = context.browser;
-      this._browserContext = context.browserContext;
-      for (const page of this._browserContext.pages())
-        this._onPageCreated(page);
-      this._browserContext.on('page', page => this._onPageCreated(page));
+  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'));
+
+      for (const origin of this.config.network.allowedOrigins)
+        await context.route(`*://${origin}/**`, route => route.continue());
+    }
+
+    if (this.config.network?.blockedOrigins?.length) {
+      for (const origin of this.config.network.blockedOrigins)
+        await context.route(`*://${origin}/**`, route => route.abort('blockedbyclient'));
     }
-    return this._browserContext;
   }
 
-  private async _createBrowserContext(): Promise<{ browser?: playwright.Browser, browserContext: playwright.BrowserContext }> {
-    if (!this._createBrowserContextPromise) {
-      this._createBrowserContextPromise = this._innerCreateBrowserContext();
-      void this._createBrowserContextPromise.catch(() => {
-        this._createBrowserContextPromise = undefined;
+  private _ensureBrowserContext() {
+    if (!this._browserContextPromise) {
+      this._browserContextPromise = this._setupBrowserContext();
+      this._browserContextPromise.catch(() => {
+        this._browserContextPromise = undefined;
       });
     }
-    return this._createBrowserContextPromise;
+    return this._browserContextPromise;
   }
 
-  private async _innerCreateBrowserContext(): Promise<{ browser?: playwright.Browser, browserContext: playwright.BrowserContext }> {
-    if (this.config.browser?.remoteEndpoint) {
-      const url = new URL(this.config.browser?.remoteEndpoint);
-      if (this.config.browser.browserName)
-        url.searchParams.set('browser', this.config.browser.browserName);
-      if (this.config.browser.launchOptions)
-        url.searchParams.set('launch-options', JSON.stringify(this.config.browser.launchOptions));
-      const browser = await playwright[this.config.browser?.browserName ?? 'chromium'].connect(String(url));
-      const browserContext = await browser.newContext();
-      return { browser, browserContext };
+  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;
+    await this._setupRequestInterception(browserContext);
+    for (const page of browserContext.pages())
+      this._onPageCreated(page);
+    browserContext.on('page', page => this._onPageCreated(page));
+    if (this.config.saveTrace) {
+      await browserContext.tracing.start({
+        name: 'trace',
+        screenshots: false,
+        snapshots: true,
+        sources: false,
+      });
     }
-
-    if (this.config.browser?.cdpEndpoint) {
-      const browser = await playwright.chromium.connectOverCDP(this.config.browser.cdpEndpoint);
-      const browserContext = browser.contexts()[0];
-      return { browser, browserContext };
-    }
-
-    const browserContext = await launchPersistentContext(this.config.browser);
-    return { browserContext };
+    return result;
   }
 }
-
-async function launchPersistentContext(browserConfig: Config['browser']): Promise<playwright.BrowserContext> {
-  try {
-    const browserType = browserConfig?.browserName ? playwright[browserConfig.browserName] : playwright.chromium;
-    return await browserType.launchPersistentContext(browserConfig?.userDataDir || '', { ...browserConfig?.launchOptions, ...browserConfig?.contextOptions });
-  } catch (error: any) {
-    if (error.message.includes('Executable doesn\'t exist'))
-      throw new Error(`Browser specified in your config is not installed. Either install it (likely) or change the config.`);
-    throw error;
-  }
-}
-
-export async function generateLocator(locator: playwright.Locator): Promise<string> {
-  return (locator as any)._generateLocatorString();
-}

src/extension/cdpRelay.ts

@@ -0,0 +1,440 @@
+/**
+ * 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.
+ */
+
+/**
+ * WebSocket server that bridges Playwright MCP and Chrome Extension
+ *
+ * Endpoints:
+ * - /cdp/guid - Full CDP interface for Playwright MCP
+ * - /extension/guid - Extension connection for chrome.debugger forwarding
+ */
+
+import http from 'http';
+import { spawn } from 'child_process';
+import { WebSocket, WebSocketServer } from 'ws';
+import debug from 'debug';
+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');
+
+type CDPCommand = {
+  id: number;
+  sessionId?: string;
+  method: string;
+  params?: any;
+};
+
+type CDPResponse = {
+  id?: number;
+  sessionId?: string;
+  method?: string;
+  params?: any;
+  result?: any;
+  error?: { code?: number; message: string };
+};
+
+export class CDPRelayServer {
+  private _wsHost: string;
+  private _browserChannel: string;
+  private _cdpPath: string;
+  private _extensionPath: string;
+  private _wss: WebSocketServer;
+  private _playwrightConnection: WebSocket | null = null;
+  private _extensionConnection: ExtensionConnection | null = null;
+  private _connectedTabInfo: {
+    targetInfo: any;
+    // Page sessionId that should be used by this connection.
+    sessionId: string;
+  } | undefined;
+  private _nextSessionId: number = 1;
+  private _extensionConnectionPromise!: ManualPromise<void>;
+
+  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._resetExtensionConnection();
+    this._wss = new WebSocketServer({ server });
+    this._wss.on('connection', this._onConnection.bind(this));
+  }
+
+  cdpEndpoint() {
+    return `${this._wsHost}${this._cdpPath}`;
+  }
+
+  extensionEndpoint() {
+    return `${this._wsHost}${this._extensionPath}`;
+  }
+
+  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 }) {
+    const mcpRelayEndpoint = `${this._wsHost}${this._extensionPath}`;
+    // Need to specify "key" in the manifest.json to make the id stable when loading from file.
+    const url = new URL('chrome-extension://jakfalbnbhgkpmoaakfflhflbfpkailf/connect.html');
+    url.searchParams.set('mcpRelayUrl', mcpRelayEndpoint);
+    url.searchParams.set('client', JSON.stringify(clientInfo));
+    const href = url.toString();
+    const executableInfo = registry.findExecutable(this._browserChannel);
+    if (!executableInfo)
+      throw new Error(`Unsupported channel: "${this._browserChannel}"`);
+    const executablePath = executableInfo.executablePath();
+    if (!executablePath)
+      throw new Error(`"${this._browserChannel}" executable not found. Make sure it is installed at a standard location.`);
+
+    spawn(executablePath, [href], {
+      windowsHide: true,
+      detached: true,
+      shell: false,
+      stdio: 'ignore',
+    });
+  }
+
+  stop(): void {
+    this.closeConnections('Server stopped');
+    this._wss.close();
+  }
+
+  closeConnections(reason: string) {
+    this._closePlaywrightConnection(reason);
+    this._closeExtensionConnection(reason);
+  }
+
+  private _onConnection(ws: WebSocket, request: http.IncomingMessage): void {
+    const url = new URL(`http://localhost${request.url}`);
+    debugLogger(`New connection to ${url.pathname}`);
+    if (url.pathname === this._cdpPath) {
+      this._handlePlaywrightConnection(ws);
+    } else if (url.pathname === this._extensionPath) {
+      this._handleExtensionConnection(ws);
+    } else {
+      debugLogger(`Invalid path: ${url.pathname}`);
+      ws.close(4004, 'Invalid path');
+    }
+  }
+
+  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: any) {
+        debugLogger(`Error while handling Playwright message\n${data.toString()}\n`, error);
+      }
+    });
+    ws.on('close', () => {
+      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);
+    });
+    debugLogger('Playwright MCP connected');
+  }
+
+  private _closeExtensionConnection(reason: string) {
+    this._extensionConnection?.close(reason);
+    this._extensionConnectionPromise.reject(new Error(reason));
+    this._resetExtensionConnection();
+  }
+
+  private _resetExtensionConnection() {
+    this._connectedTabInfo = undefined;
+    this._extensionConnection = null;
+    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 {
+    if (this._extensionConnection) {
+      ws.close(1000, 'Another extension connection already established');
+      return;
+    }
+    this._extensionConnection = new ExtensionConnection(ws);
+    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._extensionConnectionPromise.resolve();
+  }
+
+  private _handleExtensionMessage(method: string, params: any) {
+    switch (method) {
+      case 'forwardCDPEvent':
+        const sessionId = params.sessionId || this._connectedTabInfo?.sessionId;
+        this._sendToPlaywright({
+          sessionId,
+          method: params.method,
+          params: params.params
+        });
+        break;
+      case 'detachedFromTab':
+        debugLogger('← Debugger detached from tab:', params);
+        this._connectedTabInfo = undefined;
+        break;
+    }
+  }
+
+  private async _handlePlaywrightMessage(message: CDPCommand): Promise<void> {
+    debugLogger('← Playwright:', `${message.method} (id=${message.id})`);
+    const { id, sessionId, method, params } = message;
+    try {
+      const result = await this._handleCDPCommand(method, params, sessionId);
+      this._sendToPlaywright({ id, sessionId, result });
+    } catch (e) {
+      debugLogger('Error in the extension:', e);
+      this._sendToPlaywright({
+        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));
+  }
+}
+
+class ExtensionContextFactory implements BrowserContextFactory {
+  private _relay: CDPRelayServer;
+  private _browserPromise: Promise<playwright.Browser> | undefined;
+
+  constructor(relay: CDPRelayServer) {
+    this._relay = relay;
+  }
+
+  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 () => {
+        debugLogger('close() called for browser context, ignoring');
+      }
+    };
+  }
+
+  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);
+    const browser = await playwright.chromium.connectOverCDP(this._relay.cdpEndpoint());
+    browser.on('disconnected', () => {
+      this._browserPromise = undefined;
+      debugLogger('Browser disconnected');
+    });
+    return browser;
+  }
+}
+
+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, error: Error }>();
+  private _lastId = 0;
+
+  onmessage?: (method: string, params: any) => void;
+  onclose?: (self: ExtensionConnection, reason: string) => void;
+
+  constructor(ws: WebSocket) {
+    this._ws = ws;
+    this._ws.on('message', this._onMessage.bind(this));
+    this._ws.on('close', this._onClose.bind(this));
+    this._ws.on('error', this._onError.bind(this));
+  }
+
+  async send(method: string, params?: any, sessionId?: string): Promise<any> {
+    if (this._ws.readyState !== WebSocket.OPEN)
+      throw new Error(`Unexpected WebSocket state: ${this._ws.readyState}`);
+    const id = ++this._lastId;
+    this._ws.send(JSON.stringify({ id, method, params, sessionId }));
+    const error = new Error(`Protocol error: ${method}`);
+    return new Promise((resolve, reject) => {
+      this._callbacks.set(id, { resolve, reject, error });
+    });
+  }
+
+  close(message: string) {
+    debugLogger('closing extension connection:', message);
+    if (this._ws.readyState === WebSocket.OPEN)
+      this._ws.close(1000, message);
+  }
+
+  private _onMessage(event: websocket.RawData) {
+    const eventData = event.toString();
+    let parsedJson;
+    try {
+      parsedJson = JSON.parse(eventData);
+    } catch (e: any) {
+      debugLogger(`<closing ws> Closing websocket due to malformed JSON. eventData=${eventData} e=${e?.message}`);
+      this._ws.close();
+      return;
+    }
+    try {
+      this._handleParsedMessage(parsedJson);
+    } catch (e: any) {
+      debugLogger(`<closing ws> Closing websocket due to failed onmessage callback. eventData=${eventData} e=${e?.message}`);
+      this._ws.close();
+    }
+  }
+
+  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) {
+        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);
+    }
+  }
+
+  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) {
+    debugLogger(`<ws error> message=${event.message} type=${event.type} target=${event.target}`);
+    this._dispose();
+  }
+
+  private _dispose() {
+    for (const callback of this._callbacks.values())
+      callback.reject(new Error('WebSocket closed'));
+    this._callbacks.clear();
+  }
+}

src/extension/main.ts

@@ -0,0 +1,39 @@
+/**
+ * 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 { startCDPRelayServer } from './cdpRelay.js';
+import { BrowserServerBackend } from '../browserServerBackend.js';
+import * as mcpTransport from '../mcp/transport.js';
+
+import type { FullConfig } from '../config.js';
+
+export async function runWithExtension(config: FullConfig, abortController: AbortController) {
+  const contextFactory = await startCDPRelayServer(config.browser.launchOptions.channel || 'chrome', abortController);
+
+  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);
+}

src/fileUtils.ts

@@ -0,0 +1,37 @@
+/**
+ * Copyright (c) Microsoft Corporation.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+import os from 'node:os';
+import path from 'node:path';
+
+import type { FullConfig } from './config.js';
+
+export function cacheDir() {
+  let cacheDirectory: string;
+  if (process.platform === 'linux')
+    cacheDirectory = process.env.XDG_CACHE_HOME || path.join(os.homedir(), '.cache');
+  else if (process.platform === 'darwin')
+    cacheDirectory = path.join(os.homedir(), 'Library', 'Caches');
+  else if (process.platform === 'win32')
+    cacheDirectory = process.env.LOCALAPPDATA || path.join(os.homedir(), 'AppData', 'Local');
+  else
+    throw new Error('Unsupported platform: ' + process.platform);
+  return path.join(cacheDirectory, 'ms-playwright');
+}
+
+export async function userDataDir(browserConfig: FullConfig['browser']) {
+  return path.join(cacheDir(), 'ms-playwright', `mcp-${browserConfig.launchOptions?.channel ?? browserConfig?.browserName}-profile`);
+}

src/httpServer.ts

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

src/index.ts

@@ -14,62 +14,34 @@
  * limitations under the License.
  */
 
-import { createServerWithTools } from './server.js';
-import common from './tools/common.js';
-import console from './tools/console.js';
-import dialogs from './tools/dialogs.js';
-import files from './tools/files.js';
-import install from './tools/install.js';
-import keyboard from './tools/keyboard.js';
-import navigate from './tools/navigate.js';
-import network from './tools/network.js';
-import pdf from './tools/pdf.js';
-import snapshot from './tools/snapshot.js';
-import tabs from './tools/tabs.js';
-import screen from './tools/screen.js';
-import testing from './tools/testing.js';
-import type { Tool } from './tools/tool.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';
 
-const snapshotTools: Tool<any>[] = [
-  ...common(true),
-  ...console,
-  ...dialogs(true),
-  ...files(true),
-  ...install,
-  ...keyboard(true),
-  ...navigate(true),
-  ...network,
-  ...pdf,
-  ...snapshot,
-  ...tabs(true),
-  ...testing,
-];
-
-const screenshotTools: Tool<any>[] = [
-  ...common(false),
-  ...console,
-  ...dialogs(false),
-  ...files(false),
-  ...install,
-  ...keyboard(false),
-  ...navigate(false),
-  ...network,
-  ...pdf,
-  ...screen,
-  ...tabs(false),
-  ...testing,
-];
-
-import packageJSON from '../package.json' with { type: 'json' };
-
-export async function createServer(config: Config = {}): Promise<Server> {
-  const allTools = config.vision ? screenshotTools : snapshotTools;
-  const tools = allTools.filter(tool => !config.capabilities || tool.capability === 'core' || config.capabilities.includes(tool.capability));
-  return createServerWithTools({
-    name: 'Playwright',
-    version: packageJSON.version,
-    tools,
-  }, config);
+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 mcpServer.createServer(new BrowserServerBackend(config, factory), false);
+}
+
+class SimpleBrowserContextFactory implements BrowserContextFactory {
+  private readonly _contextGetter: () => Promise<BrowserContext>;
+
+  constructor(contextGetter: () => Promise<BrowserContext>) {
+    this._contextGetter = contextGetter;
+  }
+
+  async createContext(): Promise<{ browserContext: BrowserContext, close: () => Promise<void> }> {
+    const browserContext = await this._contextGetter();
+    return {
+      browserContext,
+      close: () => browserContext.close()
+    };
+  }
 }

src/log.ts

@@ -14,23 +14,12 @@
  * limitations under the License.
  */
 
-import type { Context } from '../context.js';
+import debug from 'debug';
 
-export type ResourceSchema = {
-  uri: string;
-  name: string;
-  description?: string;
-  mimeType?: string;
-};
+const errorsDebug = debug('pw:mcp:errors');
 
-export type ResourceResult = {
-  uri: string;
-  mimeType?: string;
-  text?: string;
-  blob?: string;
-};
+export function logUnhandledError(error: unknown) {
+  errorsDebug(error);
+}
 
-export type Resource = {
-  schema: ResourceSchema;
-  read: (context: Context, uri: string) => Promise<ResourceResult[]>;
-};
+export const testDebug = debug('pw:mcp:test');

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');
+}

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;
+  }
+}

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;
+  }
+}

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);

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();
+  }
+}

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();
+  }
+}

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);
+  },
+});

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);
+  },
+});

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;
+}

src/mcp/README.md

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

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);
+  }
+}

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();
+  };
+}

src/mcp/transport.ts

@@ -0,0 +1,137 @@
+/**
+ * Copyright (c) Microsoft Corporation.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+import 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 type { ServerBackendFactory } from './server.js';
+
+export async function start(serverBackendFactory: ServerBackendFactory, options: { host?: string; port?: number }) {
+  if (options.port !== undefined) {
+    const httpServer = await startHttpServer(options);
+    startHttpTransport(httpServer, serverBackendFactory);
+  } else {
+    await startStdioTransport(serverBackendFactory);
+  }
+}
+
+async function startStdioTransport(serverBackendFactory: ServerBackendFactory) {
+  await mcpServer.connect(serverBackendFactory, new StdioServerTransport(), false);
+}
+
+const testDebug = debug('pw:mcp:test');
+
+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) {
+      res.statusCode = 400;
+      return res.end('Missing sessionId');
+    }
+
+    const transport = sessions.get(sessionId);
+    if (!transport) {
+      res.statusCode = 404;
+      return res.end('Session not found');
+    }
+
+    return await transport.handlePostMessage(req, res);
+  } else if (req.method === 'GET') {
+    const transport = new SSEServerTransport('/sse', res);
+    sessions.set(transport.sessionId, transport);
+    testDebug(`create SSE session: ${transport.sessionId}`);
+    await mcpServer.connect(serverBackendFactory, transport, false);
+    res.on('close', () => {
+      testDebug(`delete SSE session: ${transport.sessionId}`);
+      sessions.delete(transport.sessionId);
+    });
+    return;
+  }
+
+  res.statusCode = 405;
+  res.end('Method not allowed');
+}
+
+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);
+    if (!transport) {
+      res.statusCode = 404;
+      res.end('Session not found');
+      return;
+    }
+    return await transport.handleRequest(req, res);
+  }
+
+  if (req.method === 'POST') {
+    const transport = new StreamableHTTPServerTransport({
+      sessionIdGenerator: () => crypto.randomUUID(),
+      onsessioninitialized: async sessionId => {
+        testDebug(`create http session: ${transport.sessionId}`);
+        await mcpServer.connect(serverBackendFactory, transport, true);
+        sessions.set(sessionId, transport);
+      }
+    });
+
+    transport.onclose = () => {
+      if (!transport.sessionId)
+        return;
+      sessions.delete(transport.sessionId);
+      testDebug(`delete http session: ${transport.sessionId}`);
+    };
+
+    await transport.handleRequest(req, res);
+    return;
+  }
+
+  res.statusCode = 400;
+  res.end('Invalid request');
+}
+
+function startHttpTransport(httpServer: http.Server, serverBackendFactory: ServerBackendFactory) {
+  const sseSessions = new Map();
+  const streamableSessions = new Map();
+  httpServer.on('request', async (req, res) => {
+    const url = new URL(`http://localhost${req.url}`);
+    if (url.pathname.startsWith('/sse'))
+      await handleSSE(serverBackendFactory, req, res, url, sseSessions);
+    else
+      await handleStreamable(serverBackendFactory, req, res, streamableSessions);
+  });
+  const url = httpAddressToString(httpServer.address());
+  const message = [
+    `Listening on ${url}`,
+    'Put this in your client config:',
+    JSON.stringify({
+      'mcpServers': {
+        'playwright': {
+          'url': `${url}/mcp`
+        }
+      }
+    }, undefined, 2),
+    'For legacy SSE transport support, you can use the /sse endpoint instead.',
+  ].join('\n');
+    // eslint-disable-next-line no-console
+  console.error(message);
+}

src/package.ts

@@ -0,0 +1,22 @@
+/**
+ * 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 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'));

src/pageSnapshot.ts

@@ -1,101 +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 yaml from 'yaml';
-
-type PageOrFrameLocator = playwright.Page | playwright.FrameLocator;
-
-export class PageSnapshot {
-  private _frameLocators: PageOrFrameLocator[] = [];
-  private _text!: string;
-
-  constructor() {
-  }
-
-  static async create(page: playwright.Page): Promise<PageSnapshot> {
-    const snapshot = new PageSnapshot();
-    await snapshot._build(page);
-    return snapshot;
-  }
-
-  text(): string {
-    return this._text;
-  }
-
-  private async _build(page: playwright.Page) {
-    const yamlDocument = await this._snapshotFrame(page);
-    this._text = [
-      `- Page Snapshot`,
-      '```yaml',
-      yamlDocument.toString({ indentSeq: false }).trim(),
-      '```',
-    ].join('\n');
-  }
-
-  private async _snapshotFrame(frame: playwright.Page | playwright.FrameLocator) {
-    const frameIndex = this._frameLocators.push(frame) - 1;
-    const snapshotString = await frame.locator('body').ariaSnapshot({ ref: true, emitGeneric: true });
-    const snapshot = yaml.parseDocument(snapshotString);
-
-    const visit = async (node: any): Promise<unknown> => {
-      if (yaml.isPair(node)) {
-        await Promise.all([
-          visit(node.key).then(k => node.key = k),
-          visit(node.value).then(v => node.value = v)
-        ]);
-      } else if (yaml.isSeq(node) || yaml.isMap(node)) {
-        node.items = await Promise.all(node.items.map(visit));
-      } else if (yaml.isScalar(node)) {
-        if (typeof node.value === 'string') {
-          const value = node.value;
-          if (frameIndex > 0)
-            node.value = value.replace('[ref=', `[ref=f${frameIndex}`);
-          if (value.startsWith('iframe ')) {
-            const ref = value.match(/\[ref=(.*)\]/)?.[1];
-            if (ref) {
-              try {
-                const childSnapshot = await this._snapshotFrame(frame.frameLocator(`aria-ref=${ref}`));
-                return snapshot.createPair(node.value, childSnapshot);
-              } catch (error) {
-                return snapshot.createPair(node.value, '<could not take iframe snapshot>');
-              }
-            }
-          }
-        }
-      }
-
-      return node;
-    };
-    await visit(snapshot.contents);
-    return snapshot;
-  }
-
-  refLocator(ref: string): playwright.Locator {
-    let frame = this._frameLocators[0];
-    const match = ref.match(/^f(\d+)(.*)/);
-    if (match) {
-      const frameIndex = parseInt(match[1], 10);
-      frame = this._frameLocators[frameIndex];
-      ref = match[2];
-    }
-
-    if (!frame)
-      throw new Error(`Frame does not exist. Provide ref from the most current snapshot.`);
-
-    return frame.locator(`aria-ref=${ref}`);
-  }
-}

src/program.ts

@@ -14,52 +14,101 @@
  * limitations under the License.
  */
 
-import { program } from 'commander';
+import { program, Option } from 'commander';
+// @ts-ignore
+import { startTraceViewerServer } from 'playwright-core/lib/server';
 
-import { createServer } from './index.js';
-import { ServerList } from './server.js';
-
-import { startHttpTransport, startStdioTransport } from './transport.js';
-
-import { resolveConfig } from './config.js';
-
-import packageJSON from '../package.json' with { type: 'json' };
+import * as mcpTransport from './mcp/transport.js';
+import { commaSeparatedList, resolveCLIConfig, semicolonSeparatedList } from './config.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)
     .name(packageJSON.name)
-    .option('--browser <browser>', 'Browser or chrome channel to use, possible values: chrome, firefox, webkit, msedge.')
-    .option('--caps <caps>', 'Comma-separated list of capabilities to enable, possible values: tabs, pdf, history, wait, files, install. Default is all.')
+    .option('--allowed-origins <origins>', 'semicolon-separated list of origins to allow the browser to request. Default is to allow all.', semicolonSeparatedList)
+    .option('--blocked-origins <origins>', 'semicolon-separated list of origins to block the browser from requesting. Blocklist is evaluated before allowlist. If used without the allowlist, requests not matching the blocklist are still allowed.', semicolonSeparatedList)
+    .option('--block-service-workers', 'block service workers')
+    .option('--browser <browser>', 'browser or chrome channel to use, possible values: chrome, firefox, webkit, msedge.')
+    .option('--caps <caps>', 'comma-separated list of additional capabilities to enable, possible values: vision, pdf.', commaSeparatedList)
     .option('--cdp-endpoint <endpoint>', 'CDP endpoint to connect to.')
-    .option('--executable-path <path>', 'Path to the browser executable.')
-    .option('--headless', 'Run browser in headless mode, headed by default')
-    .option('--device <device>', 'Device to emulate, for example: "iPhone 15"')
-    .option('--user-data-dir <path>', 'Path to the user data directory')
-    .option('--port <port>', 'Port to listen on for SSE transport.')
-    .option('--host <host>', 'Host to bind server to. Default is localhost. Use 0.0.0.0 to bind to all interfaces.')
-    .option('--vision', 'Run server that uses screenshots (Aria snapshots are used by default)')
-    .option('--config <path>', 'Path to the configuration file.')
+    .option('--config <path>', 'path to the configuration file.')
+    .option('--device <device>', 'device to emulate, for example: "iPhone 15"')
+    .option('--executable-path <path>', 'path to the browser executable.')
+    .option('--headless', 'run browser in headless mode, headed by default')
+    .option('--host <host>', 'host to bind server to. Default is localhost. Use 0.0.0.0 to bind to all interfaces.')
+    .option('--ignore-https-errors', 'ignore https errors')
+    .option('--isolated', 'keep the browser profile in memory, do not save it to disk.')
+    .option('--image-responses <mode>', 'whether to send image responses to the client. Can be "allow" or "omit", Defaults to "allow".')
+    .option('--no-sandbox', 'disable the sandbox for all process types that are normally sandboxed.')
+    .option('--output-dir <path>', 'path to the directory for output files.')
+    .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 => {
-      const config = await resolveConfig(options);
-      const serverList = new ServerList(() => createServer(config));
-      setupExitWatchdog(serverList);
+      const abortController = setupExitWatchdog();
 
-      if (options.port)
-        startHttpTransport(+options.port, options.host, serverList);
-      else
-        await startStdioTransport(serverList);
+      if (options.vision) {
+        // eslint-disable-next-line no-console
+        console.error('The --vision option is deprecated, use --caps=vision instead');
+        options.caps = 'vision';
+      }
+      const config = await resolveCLIConfig(options);
+
+      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();
+        const urlPrefix = server.urlPrefix('human-readable');
+        const url = urlPrefix + '/trace/index.html?trace=' + config.browser.launchOptions.tracesDir + '/trace.json';
+        // eslint-disable-next-line no-console
+        console.error('\nTrace viewer listening on ' + url);
+      }
     });
 
-function setupExitWatchdog(serverList: ServerList) {
+function setupExitWatchdog() {
+  const abortController = new AbortController();
+
+  let isExiting = false;
   const handleExit = async () => {
+    if (isExiting)
+      return;
+    isExiting = true;
     setTimeout(() => process.exit(0), 15000);
-    await serverList.closeAll();
+    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;
 }
 
-program.parse(process.argv);
+void program.parseAsync(process.argv);

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 };
+  }
+}

src/server.ts

@@ -1,108 +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 } from '@modelcontextprotocol/sdk/server/index.js';
-import { CallToolRequestSchema, ListToolsRequestSchema } from '@modelcontextprotocol/sdk/types.js';
-import { zodToJsonSchema } from 'zod-to-json-schema';
-
-import { Context } from './context.js';
-
-import type { Tool } from './tools/tool.js';
-import type { Config } from '../config.js';
-
-type MCPServerOptions = {
-  name: string;
-  version: string;
-  tools: Tool[];
-};
-
-export function createServerWithTools(serverOptions: MCPServerOptions, config: Config): Server {
-  const { name, version, tools } = serverOptions;
-  const context = new Context(tools, config);
-  const server = new Server({ name, 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)
-      })),
-    };
-  });
-
-  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));
-    }
-  });
-
-  const oldClose = server.close.bind(server);
-
-  server.close = async () => {
-    await oldClose();
-    await context.close();
-  };
-
-  return server;
-}
-
-export class ServerList {
-  private _servers: Server[] = [];
-  private _serverFactory: () => Promise<Server>;
-
-  constructor(serverFactory: () => Promise<Server>) {
-    this._serverFactory = serverFactory;
-  }
-
-  async create() {
-    const server = await this._serverFactory();
-    this._servers.push(server);
-    return server;
-  }
-
-  async close(server: Server) {
-    const index = this._servers.indexOf(server);
-    if (index !== -1)
-      this._servers.splice(index, 1);
-    await server.close();
-  }
-
-  async closeAll() {
-    await Promise.all(this._servers.map(server => server.close()));
-  }
-}

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';
+}

src/tab.ts

@@ -14,82 +14,297 @@
  * limitations under the License.
  */
 
+import { EventEmitter } from 'events';
 import * as playwright from 'playwright';
-
-import { PageSnapshot } from './pageSnapshot.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 _console: playwright.ConsoleMessage[] = [];
+  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;
-    page.on('console', event => this._console.push(event));
+    page.on('console', event => this._handleConsoleMessage(messageToConsoleMessage(event)));
+    page.on('pageerror', error => this._handleConsoleMessage(pageErrorToConsoleMessage(error)));
     page.on('request', request => this._requests.set(request, null));
     page.on('response', response => this._requests.set(response.request(), response));
-    page.on('framenavigated', frame => {
-      if (!frame.parentFrame())
-        this._clearCollectedArtifacts();
-    });
     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._console.length = 0;
+    this._consoleMessages.length = 0;
+    this._recentConsoleMessages.length = 0;
     this._requests.clear();
   }
 
+  private _handleConsoleMessage(message: ConsoleMessage) {
+    this._consoleMessages.push(message);
+    this._recentConsoleMessages.push(message);
+  }
+
   private _onClose() {
     this._clearCollectedArtifacts();
     this._onPageClose(this);
   }
 
+  async title(): Promise<string> {
+    return await callOnPageNoTrace(this.page, page => page.title());
+  }
+
+  async waitForLoadState(state: 'load', options?: { timeout?: number }): Promise<void> {
+    await callOnPageNoTrace(this.page, page => page.waitForLoadState(state, options).catch(logUnhandledError));
+  }
+
   async navigate(url: string) {
-    await this.page.goto(url, { waitUntil: 'domcontentloaded' });
+    this._clearCollectedArtifacts();
+
+    const downloadEvent = callOnPageNoTrace(this.page, page => page.waitForEvent('download').catch(logUnhandledError));
+    try {
+      await this.page.goto(url, { waitUntil: 'domcontentloaded' });
+    } catch (_e: unknown) {
+      const e = _e as Error;
+      const mightBeDownload =
+        e.message.includes('net::ERR_ABORTED') // chromium
+        || e.message.includes('Download is starting'); // firefox + webkit
+      if (!mightBeDownload)
+        throw e;
+      // 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, 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.page.waitForLoadState('load', { timeout: 5000 }).catch(() => {});
+    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;
-  }
-
-  console(): playwright.ConsoleMessage[] {
-    return this._console;
+  consoleMessages(): ConsoleMessage[] {
+    return this._consoleMessages;
   }
 
   requests(): Map<playwright.Request, playwright.Response | null> {
     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, ''];
+  }
+
+  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 = {
+  type: ReturnType<playwright.ConsoleMessage['type']> | undefined;
+  text: string;
+  toString(): string;
+};
+
+function messageToConsoleMessage(message: playwright.ConsoleMessage): ConsoleMessage {
+  return {
+    type: message.type(),
+    text: message.text(),
+    toString: () => `[${message.type().toUpperCase()}] ${message.text()} @ ${message.location().url}:${message.location().lineNumber}`,
+  };
+}
+
+function pageErrorToConsoleMessage(errorOrValue: Error | any): ConsoleMessage {
+  if (errorOrValue instanceof Error) {
+    return {
+      type: undefined,
+      text: errorOrValue.message,
+      toString: () => errorOrValue.stack || errorOrValue.message,
+    };
+  }
+  return {
+    type: undefined,
+    text: String(errorOrValue),
+    toString: () => String(errorOrValue),
+  };
+}
+
+function trim(text: string, maxLength: number) {
+  if (text.length <= maxLength)
+    return text;
+  return text.slice(0, maxLength) + '...';
+}

src/tools.ts

@@ -0,0 +1,56 @@
+/**
+ * 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 common from './tools/common.js';
+import console from './tools/console.js';
+import dialogs from './tools/dialogs.js';
+import evaluate from './tools/evaluate.js';
+import files from './tools/files.js';
+import install from './tools/install.js';
+import keyboard from './tools/keyboard.js';
+import navigate from './tools/navigate.js';
+import network from './tools/network.js';
+import pdf from './tools/pdf.js';
+import snapshot from './tools/snapshot.js';
+import tabs from './tools/tabs.js';
+import screenshot from './tools/screenshot.js';
+import wait from './tools/wait.js';
+import mouse from './tools/mouse.js';
+
+import type { Tool } from './tools/tool.js';
+import type { FullConfig } from './config.js';
+
+export const allTools: Tool<any>[] = [
+  ...common,
+  ...console,
+  ...dialogs,
+  ...evaluate,
+  ...files,
+  ...install,
+  ...keyboard,
+  ...navigate,
+  ...network,
+  ...mouse,
+  ...pdf,
+  ...screenshot,
+  ...snapshot,
+  ...tabs,
+  ...wait,
+];
+
+export function filteredTools(config: FullConfig) {
+  return allTools.filter(tool => tool.capability.startsWith('core') || config.capabilities?.includes(tool.capability));
+}

src/tools/common.ts

@@ -15,82 +15,50 @@
  */
 
 import { z } from 'zod';
-import { defineTool, type ToolFactory } from './tool.js';
-
-const wait: ToolFactory = captureSnapshot => defineTool({
-  capability: 'wait',
-
-  schema: {
-    name: 'browser_wait',
-    description: 'Wait for a specified time in seconds',
-    inputSchema: z.object({
-      time: z.number().describe('The time to wait in seconds'),
-    }),
-  },
-
-  handle: async (context, params) => {
-    await new Promise(f => setTimeout(f, Math.min(10000, params.time * 1000)));
-    return {
-      code: [`// Waited for ${params.time} seconds`],
-      captureSnapshot,
-      waitForNetwork: false,
-    };
-  },
-});
+import { defineTabTool, defineTool } from './tool.js';
 
 const close = defineTool({
   capability: 'core',
 
   schema: {
     name: 'browser_close',
+    title: 'Close browser',
     description: 'Close the page',
     inputSchema: z.object({}),
+    type: 'readOnly',
   },
 
-  handle: async context => {
-    await context.close();
-    return {
-      code: [`// Internal to close the page`],
-      captureSnapshot: false,
-      waitForNetwork: false,
-    };
+  handle: async (context, params, response) => {
+    await context.closeBrowserContext();
+    response.setIncludeTabs();
+    response.addCode(`await page.close()`);
   },
 });
 
-const resize: ToolFactory = captureSnapshot => defineTool({
+const resize = defineTabTool({
   capability: 'core',
   schema: {
     name: 'browser_resize',
+    title: 'Resize browser window',
     description: 'Resize the browser window',
     inputSchema: z.object({
       width: z.number().describe('Width of the browser window'),
       height: z.number().describe('Height of the browser window'),
     }),
+    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,
-      waitForNetwork: true
-    };
+    });
   },
 });
 
-export default (captureSnapshot: boolean) => [
+export default [
   close,
-  wait(captureSnapshot),
-  resize(captureSnapshot)
+  resize
 ];

src/tools/console.ts

@@ -15,28 +15,19 @@
  */
 
 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',
+    title: 'Get console messages',
     description: 'Returns all console messages',
     inputSchema: z.object({}),
+    type: 'readOnly',
   },
-  handle: async context => {
-    const messages = context.currentTabOrDie().console();
-    const log = messages.map(message => `[${message.type().toUpperCase()}] ${message.text()}`).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()));
   },
 });
 

src/tools/dialogs.ts

@@ -15,46 +15,41 @@
  */
 
 import { z } from 'zod';
-import { defineTool, type ToolFactory } from './tool.js';
+import { defineTabTool } from './tool.js';
 
-const handleDialog: ToolFactory = captureSnapshot => defineTool({
+const handleDialog = defineTabTool({
   capability: 'core',
 
   schema: {
     name: 'browser_handle_dialog',
+    title: 'Handle a dialog',
     description: 'Handle a dialog',
     inputSchema: z.object({
       accept: z.boolean().describe('Whether to accept the dialog.'),
       promptText: z.string().optional().describe('The text of the prompt in case of a prompt dialog.'),
     }),
+    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,
-      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',
 });
 
-export default (captureSnapshot: boolean) => [
-  handleDialog(captureSnapshot),
+export default [
+  handleDialog,
 ];

src/tools/evaluate.ts

@@ -0,0 +1,62 @@
+/**
+ * Copyright (c) Microsoft Corporation.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+import { z } from 'zod';
+
+import { defineTabTool } from './tool.js';
+import * as javascript from '../javascript.js';
+import { generateLocator } from './utils.js';
+
+import type * as playwright from 'playwright';
+
+const evaluateSchema = z.object({
+  function: z.string().describe('() => { /* code */ } or (element) => { /* code */ } when element is provided'),
+  element: z.string().optional().describe('Human-readable element description used to obtain permission to interact with the element'),
+  ref: z.string().optional().describe('Exact target element reference from the page snapshot'),
+});
+
+const evaluate = defineTabTool({
+  capability: 'core',
+  schema: {
+    name: 'browser_evaluate',
+    title: 'Evaluate JavaScript',
+    description: 'Evaluate JavaScript expression on page or element',
+    inputSchema: evaluateSchema,
+    type: 'destructive',
+  },
+
+  handle: async (tab, params, response) => {
+    response.setIncludeSnapshot();
+
+    let locator: playwright.Locator | undefined;
+    if (params.ref && params.element) {
+      locator = await tab.refLocator({ ref: params.ref, element: params.element });
+      response.addCode(`await page.${await generateLocator(locator)}.evaluate(${javascript.quote(params.function)});`);
+    } else {
+      response.addCode(`await page.evaluate(${javascript.quote(params.function)});`);
+    }
+
+    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');
+    });
+  },
+});
+
+export default [
+  evaluate,
+];

src/tools/files.ts

@@ -15,43 +15,39 @@
  */
 
 import { z } from 'zod';
-import { defineTool, type ToolFactory } from './tool.js';
+import { defineTabTool } from './tool.js';
 
-const uploadFile: ToolFactory = captureSnapshot => defineTool({
-  capability: 'files',
+const uploadFile = defineTabTool({
+  capability: 'core',
 
   schema: {
     name: 'browser_file_upload',
+    title: 'Upload files',
     description: 'Upload one or multiple files',
     inputSchema: z.object({
       paths: z.array(z.string()).describe('The absolute paths to the files to upload. Can be a single file or multiple files.'),
     }),
+    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,
-      waitForNetwork: true,
-    };
+    });
   },
   clearsModalState: 'fileChooser',
 });
 
-export default (captureSnapshot: boolean) => [
-  uploadFile(captureSnapshot),
+export default [
+  uploadFile,
 ];

src/tools/install.ts

@@ -16,22 +16,26 @@
 
 import { fork } from 'child_process';
 import path from 'path';
-
+import { fileURLToPath } from 'url';
 import { z } from 'zod';
 import { defineTool } from './tool.js';
 
+
 const install = defineTool({
-  capability: 'install',
+  capability: 'core-install',
   schema: {
     name: 'browser_install',
+    title: 'Install the browser specified in the config',
     description: 'Install the browser specified in the config. Call this if you get an error about the browser not being installed.',
     inputSchema: z.object({}),
+    type: 'destructive',
   },
 
-  handle: async context => {
-    const channel = context.config.browser?.launchOptions?.channel ?? context.config.browser?.launchOptions.browserName ?? 'chrome';
-    const cli = path.join(require.resolve('playwright/package.json'), '..', 'cli.js');
-    const child = fork(cli, ['install', channel], {
+  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');
+    const child = fork(cliPath, ['install', channel], {
       stdio: 'pipe',
     });
     const output: string[] = [];
@@ -45,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();
   },
 });
 

src/tools/keyboard.ts

@@ -15,38 +15,77 @@
  */
 
 import { z } from 'zod';
-import { defineTool, type ToolFactory } from './tool.js';
 
-const pressKey: ToolFactory = captureSnapshot => defineTool({
+import { defineTabTool } from './tool.js';
+import { elementSchema } from './snapshot.js';
+import { generateLocator } from './utils.js';
+import * as javascript from '../javascript.js';
+
+const pressKey = defineTabTool({
   capability: 'core',
 
   schema: {
     name: 'browser_press_key',
+    title: 'Press a key',
     description: 'Press a key on the keyboard',
     inputSchema: z.object({
       key: z.string().describe('Name of the key to press or a character to generate, such as `ArrowLeft` or `a`'),
     }),
+    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,
-      waitForNetwork: true
-    };
+    await tab.waitForCompletion(async () => {
+      await tab.page.keyboard.press(params.key);
+    });
   },
 });
 
-export default (captureSnapshot: boolean) => [
-  pressKey(captureSnapshot),
+const typeSchema = elementSchema.extend({
+  text: z.string().describe('Text to type into the element'),
+  submit: z.boolean().optional().describe('Whether to submit entered text (press Enter after)'),
+  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 = defineTabTool({
+  capability: 'core',
+  schema: {
+    name: 'browser_type',
+    title: 'Type text',
+    description: 'Type text into editable element',
+    inputSchema: typeSchema,
+    type: 'destructive',
+  },
+
+  handle: async (tab, params, response) => {
+    const locator = await tab.refLocator(params);
+
+    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.submit) {
+        response.setIncludeSnapshot();
+        response.addCode(`await page.${await generateLocator(locator)}.press('Enter');`);
+        await locator.press('Enter');
+      }
+    });
+  },
+});
+
+export default [
+  pressKey,
+  type,
 ];

src/tools/mouse.ts

@@ -0,0 +1,113 @@
+/**
+ * Copyright (c) Microsoft Corporation.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+import { z } from 'zod';
+import { defineTabTool } from './tool.js';
+
+const elementSchema = z.object({
+  element: z.string().describe('Human-readable element description used to obtain permission to interact with the element'),
+});
+
+const mouseMove = defineTabTool({
+  capability: 'vision',
+  schema: {
+    name: 'browser_mouse_move_xy',
+    title: 'Move mouse',
+    description: 'Move mouse to a given position',
+    inputSchema: elementSchema.extend({
+      x: z.number().describe('X coordinate'),
+      y: z.number().describe('Y coordinate'),
+    }),
+    type: 'readOnly',
+  },
+
+  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 = defineTabTool({
+  capability: 'vision',
+  schema: {
+    name: 'browser_mouse_click_xy',
+    title: 'Click',
+    description: 'Click left mouse button at a given position',
+    inputSchema: elementSchema.extend({
+      x: z.number().describe('X coordinate'),
+      y: z.number().describe('Y coordinate'),
+    }),
+    type: 'destructive',
+  },
+
+  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();
+    });
+  },
+});
+
+const mouseDrag = defineTabTool({
+  capability: 'vision',
+  schema: {
+    name: 'browser_mouse_drag_xy',
+    title: 'Drag mouse',
+    description: 'Drag left mouse button to a given position',
+    inputSchema: elementSchema.extend({
+      startX: z.number().describe('Start X coordinate'),
+      startY: z.number().describe('Start Y coordinate'),
+      endX: z.number().describe('End X coordinate'),
+      endY: z.number().describe('End Y coordinate'),
+    }),
+    type: 'destructive',
+  },
+
+  handle: async (tab, params, response) => {
+    response.setIncludeSnapshot();
+
+    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();`);
+
+    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();
+    });
+  },
+});
+
+export default [
+  mouseMove,
+  mouseClick,
+  mouseDrag,
+];

src/tools/navigate.ts

@@ -15,84 +15,68 @@
  */
 
 import { z } from 'zod';
-import { defineTool, type ToolFactory } from './tool.js';
+import { defineTool, defineTabTool } from './tool.js';
 
-const navigate: ToolFactory = captureSnapshot => defineTool({
+const navigate = defineTool({
   capability: 'core',
 
   schema: {
     name: 'browser_navigate',
+    title: 'Navigate to a URL',
     description: 'Navigate to a URL',
     inputSchema: z.object({
       url: z.string().describe('The URL to navigate to'),
     }),
+    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,
-      waitForNetwork: false,
-    };
+    response.setIncludeSnapshot();
+    response.addCode(`// Navigate to ${params.url}`);
+    response.addCode(`await page.goto('${params.url}');`);
   },
 });
 
-const goBack: ToolFactory = captureSnapshot => defineTool({
-  capability: 'history',
+const goBack = defineTabTool({
+  capability: 'core',
   schema: {
     name: 'browser_navigate_back',
+    title: 'Go back',
     description: 'Go back to the previous page',
     inputSchema: z.object({}),
+    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,
-      waitForNetwork: false,
-    };
+    response.setIncludeSnapshot();
+    response.addCode(`// Navigate back`);
+    response.addCode(`await page.goBack();`);
   },
 });
 
-const goForward: ToolFactory = captureSnapshot => defineTool({
-  capability: 'history',
+const goForward = defineTabTool({
+  capability: 'core',
   schema: {
     name: 'browser_navigate_forward',
+    title: 'Go forward',
     description: 'Go forward to the next page',
     inputSchema: z.object({}),
+    type: 'readOnly',
   },
-  handle: async context => {
-    const tab = context.currentTabOrDie();
+  handle: async (tab, params, response) => {
     await tab.page.goForward();
-    const code = [
-      `// Navigate forward`,
-      `await page.goForward();`,
-    ];
-    return {
-      code,
-      captureSnapshot,
-      waitForNetwork: false,
-    };
+    response.setIncludeSnapshot();
+    response.addCode(`// Navigate forward`);
+    response.addCode(`await page.goForward();`);
   },
 });
 
-export default (captureSnapshot: boolean) => [
-  navigate(captureSnapshot),
-  goBack(captureSnapshot),
-  goForward(captureSnapshot),
+export default [
+  navigate,
+  goBack,
+  goForward,
 ];

src/tools/network.ts

@@ -15,32 +15,24 @@
  */
 
 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: {
     name: 'browser_network_requests',
+    title: 'List network requests',
     description: 'Returns all network requests since loading the page',
     inputSchema: z.object({}),
+    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)));
   },
 });
 

src/tools/pdf.ts

@@ -15,35 +15,32 @@
  */
 
 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';
 
-const pdf = defineTool({
+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 = defineTabTool({
   capability: 'pdf',
 
   schema: {
     name: 'browser_pdf_save',
+    title: 'Save as PDF',
     description: 'Save page as PDF',
-    inputSchema: z.object({}),
+    inputSchema: pdfSchema,
+    type: 'readOnly',
   },
 
-  handle: async context => {
-    const tab = context.currentTabOrDie();
-    const fileName = await outputFile(context.config, `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 });
   },
 });
 

src/tools/screen.ts

@@ -1,205 +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 { z } from 'zod';
-import { defineTool } from './tool.js';
-
-import * as javascript from '../javascript.js';
-
-const elementSchema = z.object({
-  element: z.string().describe('Human-readable element description used to obtain permission to interact with the element'),
-});
-
-const screenshot = defineTool({
-  capability: 'core',
-  schema: {
-    name: 'browser_screen_capture',
-    description: 'Take a screenshot of the current page',
-    inputSchema: z.object({}),
-  },
-
-  handle: async context => {
-    const tab = await context.ensureTab();
-    const options = { type: 'jpeg' as 'jpeg', quality: 50, scale: 'css' as 'css' };
-
-    const code = [
-      `// Take a screenshot of the current page`,
-      `await page.screenshot(${javascript.formatObject(options)});`,
-    ];
-
-    const action = () => tab.page.screenshot(options).then(buffer => {
-      return {
-        content: [{ type: 'image' as 'image', data: buffer.toString('base64'), mimeType: 'image/jpeg' }],
-      };
-    });
-
-    return {
-      code,
-      action,
-      captureSnapshot: false,
-      waitForNetwork: false
-    };
-  },
-});
-
-const moveMouse = defineTool({
-  capability: 'core',
-  schema: {
-    name: 'browser_screen_move_mouse',
-    description: 'Move mouse to a given position',
-    inputSchema: elementSchema.extend({
-      x: z.number().describe('X coordinate'),
-      y: z.number().describe('Y coordinate'),
-    }),
-  },
-
-  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
-    };
-  },
-});
-
-const click = defineTool({
-  capability: 'core',
-  schema: {
-    name: 'browser_screen_click',
-    description: 'Click left mouse button',
-    inputSchema: elementSchema.extend({
-      x: z.number().describe('X coordinate'),
-      y: z.number().describe('Y coordinate'),
-    }),
-  },
-
-  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 () => {
-      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 drag = defineTool({
-  capability: 'core',
-
-  schema: {
-    name: 'browser_screen_drag',
-    description: 'Drag left mouse button',
-    inputSchema: elementSchema.extend({
-      startX: z.number().describe('Start X coordinate'),
-      startY: z.number().describe('Start Y coordinate'),
-      endX: z.number().describe('End X coordinate'),
-      endY: z.number().describe('End Y coordinate'),
-    }),
-  },
-
-  handle: async (context, params) => {
-    const tab = context.currentTabOrDie();
-
-    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();`,
-    ];
-
-    const action = 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,
-    };
-  },
-});
-
-const type = defineTool({
-  capability: 'core',
-
-  schema: {
-    name: 'browser_screen_type',
-    description: 'Type text',
-    inputSchema: z.object({
-      text: z.string().describe('Text to type into the element'),
-      submit: z.boolean().optional().describe('Whether to submit entered text (press Enter after)'),
-    }),
-  },
-
-  handle: async (context, params) => {
-    const tab = context.currentTabOrDie();
-
-    const code = [
-      `// Type ${params.text}`,
-      `await page.keyboard.type('${params.text}');`,
-    ];
-
-    const action = async () => {
-      await tab.page.keyboard.type(params.text);
-      if (params.submit)
-        await tab.page.keyboard.press('Enter');
-    };
-
-    if (params.submit) {
-      code.push(`// Submit text`);
-      code.push(`await page.keyboard.press('Enter');`);
-    }
-
-    return {
-      code,
-      action,
-      captureSnapshot: false,
-      waitForNetwork: true,
-    };
-  },
-});
-
-export default [
-  screenshot,
-  moveMouse,
-  click,
-  drag,
-  type,
-];

src/tools/screenshot.ts

@@ -0,0 +1,88 @@
+/**
+ * Copyright (c) Microsoft Corporation.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+import { z } from 'zod';
+
+import { defineTabTool } from './tool.js';
+import * as javascript from '../javascript.js';
+import { outputFile } from '../config.js';
+import { generateLocator } from './utils.js';
+
+import type * as playwright from 'playwright';
+
+const screenshotSchema = z.object({
+  raw: z.boolean().optional().describe('Whether to return without compression (in PNG format). Default is false, which returns a JPEG image.'),
+  filename: z.string().optional().describe('File name to save the screenshot to. Defaults to `page-{timestamp}.{png|jpeg}` if not specified.'),
+  element: z.string().optional().describe('Human-readable element description used to obtain permission to screenshot the element. If not provided, the screenshot will be taken of viewport. If element is provided, ref must be provided too.'),
+  ref: z.string().optional().describe('Exact target element reference from the page snapshot. If not provided, the screenshot will be taken of viewport. If ref is provided, element must be provided too.'),
+  fullPage: z.boolean().optional().describe('When true, takes a screenshot of the full scrollable page, instead of the currently visible viewport. Cannot be used with element screenshots.'),
+}).refine(data => {
+  return !!data.element === !!data.ref;
+}, {
+  message: 'Both element and ref must be provided or neither.',
+  path: ['ref', 'element']
+}).refine(data => {
+  return !(data.fullPage && (data.element || data.ref));
+}, {
+  message: 'fullPage cannot be used with element screenshots.',
+  path: ['fullPage']
+});
+
+const screenshot = defineTabTool({
+  capability: 'core',
+  schema: {
+    name: 'browser_take_screenshot',
+    title: 'Take a screenshot',
+    description: `Take a screenshot of the current page. You can't perform actions based on the screenshot, use browser_snapshot for actions.`,
+    inputSchema: screenshotSchema,
+    type: 'readOnly',
+  },
+
+  handle: async (tab, params, response) => {
+    const fileType = params.raw ? 'png' : 'jpeg';
+    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,
+      scale: 'css',
+      path: fileName,
+      ...(params.fullPage !== undefined && { fullPage: params.fullPage })
+    };
+    const isElementScreenshot = params.element && params.ref;
+
+    const screenshotTarget = isElementScreenshot ? params.element : (params.fullPage ? 'full page' : 'viewport');
+    response.addCode(`// Screenshot ${screenshotTarget} and save it as ${fileName}`);
+
+    // Only get snapshot when element screenshot is needed
+    const locator = params.ref ? await tab.refLocator({ element: params.element || '', ref: params.ref }) : null;
+
+    if (locator)
+      response.addCode(`await page.${await generateLocator(locator)}.screenshot(${javascript.formatObject(options)});`);
+    else
+      response.addCode(`await page.screenshot(${javascript.formatObject(options)});`);
+
+    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
+    });
+  }
+});
+
+export default [
+  screenshot,
+];

src/tools/snapshot.ts

@@ -16,66 +16,75 @@
 
 import { z } from 'zod';
 
-import { defineTool } from './tool.js';
+import { defineTabTool, defineTool } from './tool.js';
 import * as javascript from '../javascript.js';
-import { outputFile } from '../config.js';
-
-import type * as playwright from 'playwright';
+import { generateLocator } from './utils.js';
 
 const snapshot = defineTool({
   capability: 'core',
   schema: {
     name: 'browser_snapshot',
+    title: 'Page snapshot',
     description: 'Capture accessibility snapshot of the current page, this is better than screenshot',
     inputSchema: z.object({}),
+    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();
   },
 });
 
-const elementSchema = z.object({
+export const elementSchema = z.object({
   element: z.string().describe('Human-readable element description used to obtain permission to interact with the element'),
   ref: z.string().describe('Exact target element reference from the page snapshot'),
 });
 
-const click = defineTool({
+const clickSchema = elementSchema.extend({
+  doubleClick: z.boolean().optional().describe('Whether to perform a double click instead of a single click'),
+  button: z.enum(['left', 'right', 'middle']).optional().describe('Button to click, defaults to left'),
+});
+
+const click = defineTabTool({
   capability: 'core',
   schema: {
     name: 'browser_click',
+    title: 'Click',
     description: 'Perform click on a web page',
-    inputSchema: elementSchema,
+    inputSchema: clickSchema,
+    type: 'destructive',
   },
 
-  handle: async (context, params) => {
-    const tab = context.currentTabOrDie();
-    const locator = tab.snapshotOrDie().refLocator(params.ref);
+  handle: async (tab, params, response) => {
+    response.setIncludeSnapshot();
 
-    const code = [
-      `// Click ${params.element}`,
-      `await page.${await generateLocator(locator)}.click();`
-    ];
+    const locator = await tab.refLocator(params);
+    const button = params.button;
+    const buttonAttr = button ? `{ button: '${button}' }` : '';
 
-    return {
-      code,
-      action: () => locator.click(),
-      captureSnapshot: true,
-      waitForNetwork: true,
-    };
+    if (params.doubleClick) {
+      response.addCode(`// Double click ${params.element}`);
+      response.addCode(`await page.${await generateLocator(locator)}.dblclick(${buttonAttr});`);
+    } else {
+      response.addCode(`// Click ${params.element}`);
+      response.addCode(`await page.${await generateLocator(locator)}.click(${buttonAttr});`);
+    }
+
+    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',
+    title: 'Drag mouse',
     description: 'Perform drag and drop between two elements',
     inputSchema: z.object({
       startElement: z.string().describe('Human-readable source element description used to obtain the permission to interact with the element'),
@@ -83,96 +92,44 @@ const drag = defineTool({
       endElement: z.string().describe('Human-readable target element description used to obtain the permission to interact with the element'),
       endRef: z.string().describe('Exact target element reference from the page snapshot'),
     }),
+    type: 'destructive',
   },
 
-  handle: async (context, params) => {
-    const snapshot = context.currentTabOrDie().snapshotOrDie();
-    const startLocator = snapshot.refLocator(params.startRef);
-    const endLocator = snapshot.refLocator(params.endRef);
+  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',
+    title: 'Hover mouse',
     description: 'Hover over element on page',
     inputSchema: elementSchema,
+    type: 'readOnly',
   },
 
-  handle: async (context, params) => {
-    const snapshot = context.currentTabOrDie().snapshotOrDie();
-    const locator = snapshot.refLocator(params.ref);
+  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,
-    };
-  },
-});
-
-const typeSchema = elementSchema.extend({
-  text: z.string().describe('Text to type into the element'),
-  submit: z.boolean().optional().describe('Whether to submit entered text (press Enter after)'),
-  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({
-  capability: 'core',
-  schema: {
-    name: 'browser_type',
-    description: 'Type text into editable element',
-    inputSchema: typeSchema,
-  },
-
-  handle: async (context, params) => {
-    const snapshot = context.currentTabOrDie().snapshotOrDie();
-    const locator = snapshot.refLocator(params.ref);
-
-    const code: string[] = [];
-    const steps: (() => Promise<void>)[] = [];
-
-    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,
-    };
+    await tab.waitForCompletion(async () => {
+      await locator.hover();
+    });
   },
 });
 
@@ -180,101 +137,33 @@ 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',
+    title: 'Select option',
     description: 'Select an option in a dropdown',
     inputSchema: selectOptionSchema,
+    type: 'destructive',
   },
 
-  handle: async (context, params) => {
-    const snapshot = context.currentTabOrDie().snapshotOrDie();
-    const locator = snapshot.refLocator(params.ref);
+  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);
+    });
   },
 });
 
-const screenshotSchema = z.object({
-  raw: z.boolean().optional().describe('Whether to return without compression (in PNG format). Default is false, which returns a JPEG image.'),
-  element: z.string().optional().describe('Human-readable element description used to obtain permission to screenshot the element. If not provided, the screenshot will be taken of viewport. If element is provided, ref must be provided too.'),
-  ref: z.string().optional().describe('Exact target element reference from the page snapshot. If not provided, the screenshot will be taken of viewport. If ref is provided, element must be provided too.'),
-}).refine(data => {
-  return !!data.element === !!data.ref;
-}, {
-  message: 'Both element and ref must be provided or neither.',
-  path: ['ref', 'element']
-});
-
-const screenshot = defineTool({
-  capability: 'core',
-  schema: {
-    name: 'browser_take_screenshot',
-    description: `Take a screenshot of the current page. You can't perform actions based on the screenshot, use browser_snapshot for actions.`,
-    inputSchema: screenshotSchema,
-  },
-
-  handle: async (context, params) => {
-    const tab = context.currentTabOrDie();
-    const snapshot = tab.snapshotOrDie();
-    const fileType = params.raw ? 'png' : 'jpeg';
-    const fileName = await outputFile(context.config, `page-${new Date().toISOString()}.${fileType}`);
-    const options: playwright.PageScreenshotOptions = { type: fileType, quality: fileType === 'png' ? undefined : 50, scale: 'css', path: fileName };
-    const isElementScreenshot = params.element && params.ref;
-
-    const code = [
-      `// Screenshot ${isElementScreenshot ? params.element : 'viewport'} and save it as ${fileName}`,
-    ];
-
-    const locator = params.ref ? snapshot.refLocator(params.ref) : null;
-
-    if (locator)
-      code.push(`await page.${await generateLocator(locator)}.screenshot(${javascript.formatObject(options)});`);
-    else
-      code.push(`await page.screenshot(${javascript.formatObject(options)});`);
-
-    const includeBase64 = !context.config.tools?.browser_take_screenshot?.omitBase64;
-    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: true,
-      waitForNetwork: false,
-    };
-  }
-});
-
-export async function generateLocator(locator: playwright.Locator): Promise<string> {
-  return (locator as any)._generateLocatorString();
-}
-
 export default [
   snapshot,
   click,
   drag,
   hover,
-  type,
   selectOption,
-  screenshot,
 ];

src/tools/tabs.ts

@@ -15,112 +15,87 @@
  */
 
 import { z } from 'zod';
-import { defineTool, type ToolFactory } from './tool.js';
+import { defineTool } from './tool.js';
 
 const listTabs = defineTool({
-  capability: 'tabs',
+  capability: 'core-tabs',
 
   schema: {
     name: 'browser_tab_list',
+    title: 'List tabs',
     description: 'List browser tabs',
     inputSchema: z.object({}),
+    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();
   },
 });
 
-const selectTab: ToolFactory = captureSnapshot => defineTool({
-  capability: 'tabs',
+const selectTab = defineTool({
+  capability: 'core-tabs',
 
   schema: {
     name: 'browser_tab_select',
+    title: 'Select a tab',
     description: 'Select a tab by index',
     inputSchema: z.object({
       index: z.number().describe('The index of the tab to select'),
     }),
+    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,
-      waitForNetwork: false
-    };
+    response.setIncludeSnapshot();
   },
 });
 
-const newTab: ToolFactory = captureSnapshot => defineTool({
-  capability: 'tabs',
+const newTab = defineTool({
+  capability: 'core-tabs',
 
   schema: {
     name: 'browser_tab_new',
+    title: 'Open a new tab',
     description: 'Open a new tab',
     inputSchema: z.object({
       url: z.string().optional().describe('The URL to navigate to in the new tab. If not provided, the new tab will be blank.'),
     }),
+    type: 'readOnly',
   },
 
-  handle: async (context, params) => {
-    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,
-      waitForNetwork: false
-    };
+      await tab.navigate(params.url);
+    response.setIncludeSnapshot();
   },
 });
 
-const closeTab: ToolFactory = captureSnapshot => defineTool({
-  capability: 'tabs',
+const closeTab = defineTool({
+  capability: 'core-tabs',
 
   schema: {
     name: 'browser_tab_close',
+    title: 'Close a tab',
     description: 'Close a tab',
     inputSchema: z.object({
       index: z.number().optional().describe('The index of the tab to close. Closes current tab if not provided.'),
     }),
+    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,
-      waitForNetwork: false
-    };
+    response.setIncludeSnapshot();
   },
 });
 
-export default (captureSnapshot: boolean) => [
+export default [
   listTabs,
-  newTab(captureSnapshot),
-  selectTab(captureSnapshot),
-  closeTab(captureSnapshot),
+  newTab,
+  selectTab,
+  closeTab,
 ];

src/tools/testing.ts

@@ -1,65 +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 { z } from 'zod';
-import { defineTool } from './tool.js';
-
-const generateTestSchema = z.object({
-  name: z.string().describe('The name of the test'),
-  description: z.string().describe('The description of the test'),
-  steps: z.array(z.string()).describe('The steps of the test'),
-});
-
-const generateTest = defineTool({
-  capability: 'testing',
-
-  schema: {
-    name: 'browser_generate_playwright_test',
-    description: 'Generate a Playwright test for given scenario',
-    inputSchema: generateTestSchema,
-  },
-
-  handle: async (context, params) => {
-    return {
-      resultOverride: {
-        content: [{
-          type: 'text',
-          text: instructions(params),
-        }],
-      },
-      code: [],
-      captureSnapshot: false,
-      waitForNetwork: false,
-    };
-  },
-});
-
-const instructions = (params: { name: string, description: string, steps: string[] }) => [
-  `## Instructions`,
-  `- You are a playwright test generator.`,
-  `- You are given a scenario and you need to generate a playwright test for it.`,
-  '- DO NOT generate test code based on the scenario alone. DO run steps one by one using the tools provided instead.',
-  '- Only after all steps are completed, emit a Playwright TypeScript test that uses @playwright/test based on message history',
-  '- Save generated test file in the tests directory',
-  `Test name: ${params.name}`,
-  `Description: ${params.description}`,
-  `Steps:`,
-  ...params.steps.map((step, index) => `- ${index + 1}. ${step}`),
-].join('\n');
-
-export default [
-  generateTest,
-];

src/tools/tool.ts

@@ -14,19 +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;
-  description: string;
-  inputSchema: Input;
-};
-
-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';
@@ -42,25 +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 type ToolFactory = (snapshot: boolean) => Tool<any>;
-
-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);
+    },
+  };
 }

src/tools/utils.ts

@@ -14,10 +14,13 @@
  * limitations under the License.
  */
 
-import type * as playwright from 'playwright';
-import type { Context } from '../context.js';
+// @ts-ignore
+import { asLocator } from 'playwright-core/lib/utils';
 
-export async function waitForCompletion<R>(context: Context, page: playwright.Page, callback: () => Promise<R>): Promise<R> {
+import type * as playwright from 'playwright';
+import type { Tab } from '../tab.js';
+
+export async function waitForCompletion<R>(tab: Tab, callback: () => Promise<R>): Promise<R> {
   const requests = new Set<playwright.Request>();
   let frameNavigated = false;
   let waitCallback: () => void = () => {};
@@ -36,9 +39,7 @@ export async function waitForCompletion<R>(context: Context, page: playwright.Pa
     frameNavigated = true;
     dispose();
     clearTimeout(timeout);
-    void frame.waitForLoadState('load').then(() => {
-      waitCallback();
-    });
+    void tab.waitForLoadState('load').then(waitCallback);
   };
 
   const onTimeout = () => {
@@ -46,15 +47,15 @@ export async function waitForCompletion<R>(context: Context, page: playwright.Pa
     waitCallback();
   };
 
-  page.on('request', requestListener);
-  page.on('requestfinished', requestFinishedListener);
-  page.on('framenavigated', frameNavigateListener);
+  tab.page.on('request', requestListener);
+  tab.page.on('requestfinished', requestFinishedListener);
+  tab.page.on('framenavigated', frameNavigateListener);
   const timeout = setTimeout(onTimeout, 10000);
 
   const dispose = () => {
-    page.off('request', requestListener);
-    page.off('requestfinished', requestFinishedListener);
-    page.off('framenavigated', frameNavigateListener);
+    tab.page.off('request', requestListener);
+    tab.page.off('requestfinished', requestFinishedListener);
+    tab.page.off('framenavigated', frameNavigateListener);
     clearTimeout(timeout);
   };
 
@@ -63,7 +64,7 @@ export async function waitForCompletion<R>(context: Context, page: playwright.Pa
     if (!requests.size && !frameNavigated)
       waitCallback();
     await waitBarrier;
-    await context.waitForTimeout(1000);
+    await tab.waitForTimeout(1000);
     return result;
   } finally {
     dispose();
@@ -77,3 +78,16 @@ export function sanitizeForFilePath(s: string) {
     return sanitize(s);
   return sanitize(s.substring(0, separator)) + '.' + sanitize(s.substring(separator + 1));
 }
+
+export async function generateLocator(locator: playwright.Locator): Promise<string> {
+  try {
+    const { resolvedSelector } = await (locator as any)._resolveSelector();
+    return asLocator('javascript', resolvedSelector);
+  } catch (e) {
+    throw new Error('Ref not found, likely because element was removed. Use browser_snapshot to see what elements are currently on the page.');
+  }
+}
+
+export async function callOnPageNoTrace<T>(page: playwright.Page, callback: (page: playwright.Page) => Promise<T>): Promise<T> {
+  return await (page as any)._wrapApiCall(() => callback(page), { internal: true });
+}

src/tools/wait.ts

@@ -0,0 +1,67 @@
+/**
+ * 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 wait = defineTool({
+  capability: 'core',
+
+  schema: {
+    name: 'browser_wait_for',
+    title: 'Wait for',
+    description: 'Wait for text to appear or disappear or a specified time to pass',
+    inputSchema: z.object({
+      time: z.number().optional().describe('The time to wait in seconds'),
+      text: z.string().optional().describe('The text to wait for'),
+      textGone: z.string().optional().describe('The text to wait for to disappear'),
+    }),
+    type: 'readOnly',
+  },
+
+  handle: async (context, params, response) => {
+    if (!params.text && !params.textGone && !params.time)
+      throw new Error('Either time, text or textGone must be provided');
+
+    const code: string[] = [];
+
+    if (params.time) {
+      code.push(`await new Promise(f => setTimeout(f, ${params.time!} * 1000));`);
+      await new Promise(f => setTimeout(f, Math.min(30000, params.time! * 1000)));
+    }
+
+    const tab = context.currentTabOrDie();
+    const locator = params.text ? tab.page.getByText(params.text).first() : undefined;
+    const goneLocator = params.textGone ? tab.page.getByText(params.textGone).first() : undefined;
+
+    if (goneLocator) {
+      code.push(`await page.getByText(${JSON.stringify(params.textGone)}).first().waitFor({ state: 'hidden' });`);
+      await goneLocator.waitFor({ state: 'hidden' });
+    }
+
+    if (locator) {
+      code.push(`await page.getByText(${JSON.stringify(params.text)}).first().waitFor({ state: 'visible' });`);
+      await locator.waitFor({ state: 'visible' });
+    }
+
+    response.addResult(`Waited for ${params.text || params.textGone || params.time}`);
+    response.setIncludeSnapshot();
+  },
+});
+
+export default [
+  wait,
+];

src/transport.ts

@@ -1,134 +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 http from 'node:http';
-import assert from 'node:assert';
-import crypto from 'node:crypto';
-
-import { ServerList } from './server.js';
-import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
-import { SSEServerTransport } from '@modelcontextprotocol/sdk/server/sse.js';
-import { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/streamableHttp.js';
-
-export async function startStdioTransport(serverList: ServerList) {
-  const server = await serverList.create();
-  await server.connect(new StdioServerTransport());
-}
-
-async function handleSSE(req: http.IncomingMessage, res: http.ServerResponse, url: URL, serverList: ServerList, sessions: Map<string, SSEServerTransport>) {
-  if (req.method === 'POST') {
-    const sessionId = url.searchParams.get('sessionId');
-    if (!sessionId) {
-      res.statusCode = 400;
-      return res.end('Missing sessionId');
-    }
-
-    const transport = sessions.get(sessionId);
-    if (!transport) {
-      res.statusCode = 404;
-      return res.end('Session not found');
-    }
-
-    return await transport.handlePostMessage(req, res);
-  } else if (req.method === 'GET') {
-    const transport = new SSEServerTransport('/sse', res);
-    sessions.set(transport.sessionId, transport);
-    const server = await serverList.create();
-    res.on('close', () => {
-      sessions.delete(transport.sessionId);
-      serverList.close(server).catch(e => {
-        // eslint-disable-next-line no-console
-        console.error(e);
-      });
-    });
-    return await server.connect(transport);
-  }
-
-  res.statusCode = 405;
-  res.end('Method not allowed');
-}
-
-async function handleStreamable(req: http.IncomingMessage, res: http.ServerResponse, serverList: ServerList, sessions: Map<string, StreamableHTTPServerTransport>) {
-  const sessionId = req.headers['mcp-session-id'] as string | undefined;
-  if (sessionId) {
-    const transport = sessions.get(sessionId);
-    if (!transport) {
-      res.statusCode = 404;
-      res.end('Session not found');
-      return;
-    }
-    return await transport.handleRequest(req, res);
-  }
-
-  if (req.method === 'POST') {
-    const transport = new StreamableHTTPServerTransport({
-      sessionIdGenerator: () => crypto.randomUUID(),
-      onsessioninitialized: sessionId => {
-        sessions.set(sessionId, transport);
-      }
-    });
-    transport.onclose = () => {
-      if (transport.sessionId)
-        sessions.delete(transport.sessionId);
-    };
-    const server = await serverList.create();
-    await server.connect(transport);
-    return await transport.handleRequest(req, res);
-  }
-
-  res.statusCode = 400;
-  res.end('Invalid request');
-}
-
-export function startHttpTransport(port: number, hostname: string | undefined, serverList: ServerList) {
-  const sseSessions = new Map<string, SSEServerTransport>();
-  const streamableSessions = new Map<string, StreamableHTTPServerTransport>();
-  const httpServer = http.createServer(async (req, res) => {
-    const url = new URL(`http://localhost${req.url}`);
-    if (url.pathname.startsWith('/mcp'))
-      await handleStreamable(req, res, serverList, streamableSessions);
-    else
-      await handleSSE(req, res, url, serverList, sseSessions);
-  });
-  httpServer.listen(port, hostname, () => {
-    const address = httpServer.address();
-    assert(address, 'Could not bind server socket');
-    let url: string;
-    if (typeof address === 'string') {
-      url = address;
-    } else {
-      const resolvedPort = address.port;
-      let resolvedHost = address.family === 'IPv4' ? address.address : `[${address.address}]`;
-      if (resolvedHost === '0.0.0.0' || resolvedHost === '[::]')
-        resolvedHost = 'localhost';
-      url = `http://${resolvedHost}:${resolvedPort}`;
-    }
-    const message = [
-      `Listening on ${url}`,
-      'Put this in your client config:',
-      JSON.stringify({
-        'mcpServers': {
-          'playwright': {
-            'url': `${url}/sse`
-          }
-        }
-      }, undefined, 2),
-      'If your client supports streamable HTTP, you can use the /mcp endpoint instead.',
-    ].join('\n');
-    // eslint-disable-next-line no-console
-    console.log(message);
-  });
-}

tests/capabilities.spec.ts

@@ -22,8 +22,8 @@ test('test snapshot tool list', async ({ client }) => {
     'browser_click',
     'browser_console_messages',
     'browser_drag',
+    'browser_evaluate',
     'browser_file_upload',
-    'browser_generate_playwright_test',
     'browser_handle_dialog',
     'browser_hover',
     'browser_select_option',
@@ -34,7 +34,6 @@ test('test snapshot tool list', async ({ client }) => {
     'browser_navigate_forward',
     'browser_navigate',
     'browser_network_requests',
-    'browser_pdf_save',
     'browser_press_key',
     'browser_resize',
     'browser_snapshot',
@@ -43,50 +42,37 @@ test('test snapshot tool list', async ({ client }) => {
     'browser_tab_new',
     'browser_tab_select',
     'browser_take_screenshot',
-    'browser_wait',
+    'browser_wait_for',
   ]));
 });
 
-test('test vision tool list', async ({ visionClient }) => {
-  const { tools: visionTools } = await visionClient.listTools();
-  expect(new Set(visionTools.map(t => t.name))).toEqual(new Set([
-    'browser_close',
-    'browser_console_messages',
-    'browser_file_upload',
-    'browser_generate_playwright_test',
-    'browser_handle_dialog',
-    'browser_install',
-    'browser_navigate_back',
-    'browser_navigate_forward',
-    'browser_navigate',
-    'browser_network_requests',
-    'browser_pdf_save',
-    'browser_press_key',
-    'browser_resize',
-    'browser_screen_capture',
-    'browser_screen_click',
-    'browser_screen_drag',
-    'browser_screen_move_mouse',
-    'browser_screen_type',
-    'browser_tab_close',
-    'browser_tab_list',
-    'browser_tab_new',
-    'browser_tab_select',
-    'browser_wait',
-  ]));
-});
-
-test('test capabilities', async ({ startClient }) => {
-  const client = await startClient({
-    args: ['--caps="core"'],
+test('test capabilities (pdf)', async ({ startClient }) => {
+  const { client } = await startClient({
+    args: ['--caps=pdf'],
   });
   const { tools } = await client.listTools();
   const toolNames = tools.map(t => t.name);
-  expect(toolNames).not.toContain('browser_file_upload');
-  expect(toolNames).not.toContain('browser_pdf_save');
-  expect(toolNames).not.toContain('browser_screen_capture');
-  expect(toolNames).not.toContain('browser_screen_click');
-  expect(toolNames).not.toContain('browser_screen_drag');
-  expect(toolNames).not.toContain('browser_screen_move_mouse');
-  expect(toolNames).not.toContain('browser_screen_type');
+  expect(toolNames).toContain('browser_pdf_save');
+});
+
+test('test capabilities (vision)', async ({ startClient }) => {
+  const { client } = await startClient({
+    args: ['--caps=vision'],
+  });
+  const { tools } = await client.listTools();
+  const toolNames = tools.map(t => t.name);
+  expect(toolNames).toContain('browser_mouse_move_xy');
+  expect(toolNames).toContain('browser_mouse_click_xy');
+  expect(toolNames).toContain('browser_mouse_drag_xy');
+});
+
+test('support for legacy --vision option', async ({ startClient }) => {
+  const { client } = await startClient({
+    args: ['--vision'],
+  });
+  const { tools } = await client.listTools();
+  const toolNames = tools.map(t => t.name);
+  expect(toolNames).toContain('browser_mouse_move_xy');
+  expect(toolNames).toContain('browser_mouse_click_xy');
+  expect(toolNames).toContain('browser_mouse_drag_xy');
 });

tests/cdp.spec.ts

@@ -14,20 +14,26 @@
  * limitations under the License.
  */
 
+import url from 'node:url';
+import path from 'node:path';
+import { spawnSync } from 'node:child_process';
 import { test, expect } from './fixtures.js';
 
-test('cdp server', async ({ cdpEndpoint, startClient }) => {
-  const client = await startClient({ args: [`--cdp-endpoint=${await cdpEndpoint()}`] });
+test('cdp server', async ({ cdpServer, startClient, server }) => {
+  await cdpServer.start();
+  const { client } = await startClient({ args: [`--cdp-endpoint=${cdpServer.endpoint}`] });
   expect(await client.callTool({
     name: 'browser_navigate',
-    arguments: {
-      url: 'data:text/html,<html><title>Title</title><body>Hello, world!</body></html>',
-    },
-  })).toContainTextContent(`- generic [ref=s1e2]: Hello, world!`);
+    arguments: { url: server.HELLO_WORLD },
+  })).toContainTextContent(`- generic [active] [ref=e1]: Hello, world!`);
 });
 
-test('cdp server reuse tab', async ({ cdpEndpoint, startClient }) => {
-  const client = await startClient({ args: [`--cdp-endpoint=${await cdpEndpoint()}`] });
+test('cdp server reuse tab', async ({ cdpServer, startClient, server }) => {
+  const browserContext = await cdpServer.start();
+  const { client } = await startClient({ args: [`--cdp-endpoint=${cdpServer.endpoint}`] });
+
+  const [page] = browserContext.pages();
+  await page.goto(server.HELLO_WORLD);
 
   expect(await client.callTool({
     name: 'browser_click',
@@ -35,40 +41,47 @@ test('cdp server reuse tab', async ({ cdpEndpoint, startClient }) => {
       element: 'Hello, world!',
       ref: 'f0',
     },
-  })).toHaveTextContent(`Error: No current snapshot available. Capture a snapshot of 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',
-    arguments: {},
-  })).toHaveTextContent(`
-- Ran Playwright code:
-\`\`\`js
-// <internal code to capture accessibility snapshot>
-\`\`\`
-
-- Page URL: data:text/html,hello world
-- Page Title: 
-- Page Snapshot
+  })).toHaveTextContent(`### Page state
+- Page URL: ${server.HELLO_WORLD}
+- Page Title: Title
+- Page Snapshot:
 \`\`\`yaml
-- generic [ref=s1e2]: hello world
+- generic [active] [ref=e1]: Hello, world!
 \`\`\`
 `);
 });
 
-test('should throw connection error and allow re-connecting', async ({ cdpEndpoint, startClient }) => {
-  const port = 3200 + test.info().parallelIndex;
-  const client = await startClient({ args: [`--cdp-endpoint=http://localhost:${port}`] });
+test('should throw connection error and allow re-connecting', async ({ cdpServer, startClient, server }) => {
+  const { client } = await startClient({ args: [`--cdp-endpoint=${cdpServer.endpoint}`] });
+
+  server.setContent('/', `
+    <title>Title</title>
+    <body>Hello, world!</body>
+  `, 'text/html');
+
   expect(await client.callTool({
     name: 'browser_navigate',
-    arguments: {
-      url: 'data:text/html,<html><title>Title</title><body>Hello, world!</body></html>',
-    },
+    arguments: { url: server.PREFIX },
   })).toContainTextContent(`Error: browserType.connectOverCDP: connect ECONNREFUSED`);
-  await cdpEndpoint(port);
+  await cdpServer.start();
   expect(await client.callTool({
     name: 'browser_navigate',
-    arguments: {
-      url: 'data:text/html,<html><title>Title</title><body>Hello, world!</body></html>',
-    },
-  })).toContainTextContent(`- generic [ref=s1e2]: Hello, world!`);
+    arguments: { url: server.PREFIX },
+  })).toContainTextContent(`- generic [active] [ref=e1]: Hello, world!`);
+});
+
+// NOTE: Can be removed when we drop Node.js 18 support and changed to import.meta.filename.
+const __filename = url.fileURLToPath(import.meta.url);
+
+test('does not support --device', async () => {
+  const result = spawnSync('node', [
+    path.join(__filename, '../../cli.js'), '--device=Pixel 5', '--cdp-endpoint=http://localhost:1234',
+  ]);
+  expect(result.error).toBeUndefined();
+  expect(result.status).toBe(1);
+  expect(result.stderr.toString()).toContain('Device emulation is not supported with cdpEndpoint.');
 });

tests/click.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_click', async ({ client, server, mcpBrowser }) => {
+  server.setContent('/', `
+    <title>Title</title>
+    <button>Submit</button>
+  `, 'text/html');
+
+  await client.callTool({
+    name: 'browser_navigate',
+    arguments: { url: server.PREFIX },
+  });
+
+  expect(await client.callTool({
+    name: 'browser_click',
+    arguments: {
+      element: 'Submit button',
+      ref: 'e2',
+    },
+  })).toHaveTextContent(`
+### Ran Playwright code
+\`\`\`js
+// Click Submit button
+await page.getByRole('button', { name: 'Submit' }).click();
+\`\`\`
+
+### Page state
+- Page URL: ${server.PREFIX}
+- Page Title: Title
+- Page Snapshot:
+\`\`\`yaml
+- button "Submit" ${mcpBrowser !== 'webkit' || process.platform === 'linux' ? '[active] ' : ''}[ref=e2]
+\`\`\`
+`);
+});
+
+test('browser_click (double)', async ({ client, server }) => {
+  server.setContent('/', `
+    <title>Title</title>
+    <script>
+      function handle() {
+        document.querySelector('h1').textContent = 'Double clicked';
+      }
+    </script>
+    <h1 ondblclick="handle()">Click me</h1>
+  `, 'text/html');
+
+  await client.callTool({
+    name: 'browser_navigate',
+    arguments: { url: server.PREFIX },
+  });
+
+  expect(await client.callTool({
+    name: 'browser_click',
+    arguments: {
+      element: 'Click me',
+      ref: 'e2',
+      doubleClick: true,
+    },
+  })).toHaveTextContent(`
+### Ran Playwright code
+\`\`\`js
+// Double click Click me
+await page.getByRole('heading', { name: 'Click me' }).dblclick();
+\`\`\`
+
+### Page state
+- Page URL: ${server.PREFIX}
+- Page Title: Title
+- Page Snapshot:
+\`\`\`yaml
+- heading "Double clicked" [level=1] [ref=e3]
+\`\`\`
+`);
+});
+
+test('browser_click (right)', async ({ client, server }) => {
+  server.setContent('/', `
+    <button oncontextmenu="handle">Menu</button>
+    <script>
+      document.addEventListener('contextmenu', event => {
+        event.preventDefault();
+        document.querySelector('button').textContent = 'Right clicked';
+      });
+    </script>
+  `, 'text/html');
+
+  await client.callTool({
+    name: 'browser_navigate',
+    arguments: { url: server.PREFIX },
+  });
+
+  const result = await client.callTool({
+    name: 'browser_click',
+    arguments: {
+      element: 'Menu',
+      ref: 'e2',
+      button: 'right',
+    },
+  });
+  expect(result).toContainTextContent(`await page.getByRole('button', { name: 'Menu' }).click({ button: 'right' });`);
+  expect(result).toContainTextContent(`- button "Right clicked"`);
+});

tests/config.spec.ts

@@ -0,0 +1,80 @@
+/**
+ * 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 'node:fs';
+
+import { Config } from '../config.js';
+import { test, expect } from './fixtures.js';
+
+test('config user data dir', async ({ startClient, server, mcpMode }, testInfo) => {
+  server.setContent('/', `
+    <title>Title</title>
+    <body>Hello, world!</body>
+  `, 'text/html');
+
+  const config: Config = {
+    browser: {
+      userDataDir: testInfo.outputPath('user-data-dir'),
+    },
+  };
+  const configPath = testInfo.outputPath('config.json');
+  await fs.promises.writeFile(configPath, JSON.stringify(config, null, 2));
+
+  const { client } = await startClient({ args: ['--config', configPath] });
+  expect(await client.callTool({
+    name: 'browser_navigate',
+    arguments: { url: server.PREFIX },
+  })).toContainTextContent(`Hello, world!`);
+
+  const files = await fs.promises.readdir(config.browser!.userDataDir!);
+  expect(files.length).toBeGreaterThan(0);
+});
+
+test.describe(() => {
+  test.use({ mcpBrowser: '' });
+  test('browserName', { annotation: { type: 'issue', description: 'https://github.com/microsoft/playwright-mcp/issues/458' } }, async ({ startClient, mcpMode }, testInfo) => {
+    const config: Config = {
+      browser: {
+        browserName: 'firefox',
+      },
+    };
+    const configPath = testInfo.outputPath('config.json');
+    await fs.promises.writeFile(configPath, JSON.stringify(config, null, 2));
+
+    const { client } = await startClient({ args: ['--config', configPath] });
+    expect(await client.callTool({
+      name: 'browser_navigate',
+      arguments: { url: 'data:text/html,<script>document.title = navigator.userAgent</script>' },
+    })).toContainTextContent(`Firefox`);
+  });
+});
+
+test.describe('sandbox configuration', () => {
+  test('should enable sandbox by default (no --no-sandbox flag)', async () => {
+    const { configFromCLIOptions } = await import('../lib/config.js');
+    const config = configFromCLIOptions({ sandbox: undefined });
+    // When --no-sandbox is not passed, chromiumSandbox should not be set to false
+    // This allows the default (true) to be used
+    expect(config.browser?.launchOptions?.chromiumSandbox).toBeUndefined();
+  });
+
+  test('should disable sandbox when --no-sandbox flag is passed', async () => {
+    const { configFromCLIOptions } = await import('../lib/config.js');
+    const config = configFromCLIOptions({ sandbox: false });
+    // When --no-sandbox is passed, chromiumSandbox should be explicitly set to false
+    expect(config.browser?.launchOptions?.chromiumSandbox).toBe(false);
+  });
+});

tests/console.spec.ts

@@ -16,20 +16,82 @@
 
 import { test, expect } from './fixtures.js';
 
-test('browser_console_messages', async ({ client }) => {
+test('browser_console_messages', async ({ client, server }) => {
+  server.setContent('/', `
+    <!DOCTYPE html>
+    <html>
+      <script>
+        console.log("Hello, world!");
+        console.error("Error");
+      </script>
+    </html>
+  `, 'text/html');
+
   await client.callTool({
     name: 'browser_navigate',
     arguments: {
-      url: 'data:text/html,<html><script>console.log("Hello, world!");console.error("Error"); </script></html>',
+      url: server.PREFIX,
     },
   });
 
   const resource = await client.callTool({
     name: 'browser_console_messages',
-    arguments: {},
   });
   expect(resource).toHaveTextContent([
-    '[LOG] Hello, world!',
-    '[ERROR] Error',
+    '### Result',
+    `[LOG] Hello, world! @ ${server.PREFIX}:4`,
+    `[ERROR] Error @ ${server.PREFIX}:5`,
   ].join('\n'));
 });
+
+test('browser_console_messages (page error)', async ({ client, server }) => {
+  server.setContent('/', `
+    <!DOCTYPE html>
+    <html>
+      <script>
+        throw new Error("Error in script");
+      </script>
+    </html>
+  `, 'text/html');
+
+  await client.callTool({
+    name: 'browser_navigate',
+    arguments: {
+      url: server.PREFIX,
+    },
+  });
+
+  const resource = await client.callTool({
+    name: 'browser_console_messages',
+  });
+  expect(resource).toHaveTextContent(/Error: Error in script/);
+  expect(resource).toHaveTextContent(new RegExp(server.PREFIX));
+});
+
+test('recent console messages', async ({ client, server }) => {
+  server.setContent('/', `
+    <!DOCTYPE html>
+    <html>
+      <button onclick="console.log('Hello, world!');">Click me</button>
+    </html>
+  `, 'text/html');
+
+  await client.callTool({
+    name: 'browser_navigate',
+    arguments: {
+      url: server.PREFIX,
+    },
+  });
+
+  const response = await client.callTool({
+    name: 'browser_click',
+    arguments: {
+      element: 'Click me',
+      ref: 'e2',
+    },
+  });
+
+  expect(response).toContainTextContent(`
+### New console messages
+- [LOG] Hello, world! @`);
+});

tests/core.spec.ts

@@ -16,182 +16,122 @@
 
 import { test, expect } from './fixtures.js';
 
-test('browser_navigate', async ({ client }) => {
+test('browser_navigate', async ({ client, server }) => {
   expect(await client.callTool({
     name: 'browser_navigate',
-    arguments: {
-      url: 'data:text/html,<html><title>Title</title><body>Hello, world!</body></html>',
-    },
+    arguments: { url: server.HELLO_WORLD },
   })).toHaveTextContent(`
-- Ran Playwright code:
+### Ran Playwright code
 \`\`\`js
-// Navigate to data:text/html,<html><title>Title</title><body>Hello, world!</body></html>
-await page.goto('data:text/html,<html><title>Title</title><body>Hello, world!</body></html>');
+// Navigate to ${server.HELLO_WORLD}
+await page.goto('${server.HELLO_WORLD}');
 \`\`\`
 
-- Page URL: data:text/html,<html><title>Title</title><body>Hello, world!</body></html>
+### Page state
+- Page URL: ${server.HELLO_WORLD}
 - Page Title: Title
-- Page Snapshot
+- Page Snapshot:
 \`\`\`yaml
-- generic [ref=s1e2]: Hello, world!
+- generic [active] [ref=e1]: Hello, world!
 \`\`\`
 `
   );
 });
 
-test('browser_click', async ({ client }) => {
+test('browser_select_option', async ({ client, server }) => {
+  server.setContent('/', `
+    <title>Title</title>
+    <select>
+      <option value="foo">Foo</option>
+      <option value="bar">Bar</option>
+    </select>
+  `, 'text/html');
+
   await client.callTool({
     name: 'browser_navigate',
-    arguments: {
-      url: 'data:text/html,<html><title>Title</title><button>Submit</button></html>',
-    },
-  });
-
-  expect(await client.callTool({
-    name: 'browser_click',
-    arguments: {
-      element: 'Submit button',
-      ref: 's1e3',
-    },
-  })).toHaveTextContent(`
-- Ran Playwright code:
-\`\`\`js
-// Click Submit button
-await page.getByRole('button', { name: 'Submit' }).click();
-\`\`\`
-
-- Page URL: data:text/html,<html><title>Title</title><button>Submit</button></html>
-- Page Title: Title
-- Page Snapshot
-\`\`\`yaml
-- button "Submit" [ref=s2e3]
-\`\`\`
-`);
-});
-
-test('browser_select_option', async ({ client }) => {
-  await client.callTool({
-    name: 'browser_navigate',
-    arguments: {
-      url: 'data:text/html,<html><title>Title</title><select><option value="foo">Foo</option><option value="bar">Bar</option></select></html>',
-    },
+    arguments: { url: server.PREFIX },
   });
 
   expect(await client.callTool({
     name: 'browser_select_option',
     arguments: {
       element: 'Select',
-      ref: 's1e3',
+      ref: 'e2',
       values: ['bar'],
     },
   })).toHaveTextContent(`
-- Ran Playwright code:
+### Ran Playwright code
 \`\`\`js
 // Select options [bar] in Select
 await page.getByRole('combobox').selectOption(['bar']);
 \`\`\`
 
-- Page URL: data:text/html,<html><title>Title</title><select><option value="foo">Foo</option><option value="bar">Bar</option></select></html>
+### Page state
+- Page URL: ${server.PREFIX}
 - Page Title: Title
-- Page Snapshot
+- Page Snapshot:
 \`\`\`yaml
-- combobox [ref=s2e3]:
+- combobox [ref=e2]:
   - option "Foo"
   - option "Bar" [selected]
 \`\`\`
 `);
 });
 
-test('browser_select_option (multiple)', async ({ client }) => {
+test('browser_select_option (multiple)', async ({ client, server }) => {
+  server.setContent('/', `
+    <title>Title</title>
+    <select multiple>
+      <option value="foo">Foo</option>
+      <option value="bar">Bar</option>
+      <option value="baz">Baz</option>
+    </select>
+  `, 'text/html');
+
   await client.callTool({
     name: 'browser_navigate',
-    arguments: {
-      url: 'data:text/html,<html><title>Title</title><select multiple><option value="foo">Foo</option><option value="bar">Bar</option><option value="baz">Baz</option></select></html>',
-    },
+    arguments: { url: server.PREFIX },
   });
 
   expect(await client.callTool({
     name: 'browser_select_option',
     arguments: {
       element: 'Select',
-      ref: 's1e3',
+      ref: 'e2',
       values: ['bar', 'baz'],
     },
   })).toHaveTextContent(`
-- Ran Playwright code:
+### Ran Playwright code
 \`\`\`js
 // Select options [bar, baz] in Select
 await page.getByRole('listbox').selectOption(['bar', 'baz']);
 \`\`\`
 
-- Page URL: data:text/html,<html><title>Title</title><select multiple><option value="foo">Foo</option><option value="bar">Bar</option><option value="baz">Baz</option></select></html>
+### Page state
+- Page URL: ${server.PREFIX}
 - Page Title: Title
-- Page Snapshot
+- Page Snapshot:
 \`\`\`yaml
-- listbox [ref=s2e3]:
-  - option "Foo" [ref=s2e4]
-  - option "Bar" [selected] [ref=s2e5]
-  - option "Baz" [selected] [ref=s2e6]
+- listbox [ref=e2]:
+  - option "Foo" [ref=e3]
+  - option "Bar" [selected] [ref=e4]
+  - option "Baz" [selected] [ref=e5]
 \`\`\`
 `);
 });
 
-test('browser_type', async ({ client }) => {
+test('browser_resize', async ({ client, server }) => {
+  server.setContent('/', `
+    <title>Resize Test</title>
+    <body>
+      <div id="size">Waiting for resize...</div>
+      <script>new ResizeObserver(() => { document.getElementById("size").textContent = \`Window size: \${window.innerWidth}x\${window.innerHeight}\`; }).observe(document.body);
+      </script>
+    </body>
+  `, 'text/html');
   await client.callTool({
     name: 'browser_navigate',
-    arguments: {
-      url: `data:text/html,<input type='keypress' onkeypress="console.log('Key pressed:', event.key, ', Text:', event.target.value)"></input>`,
-    },
-  });
-  await client.callTool({
-    name: 'browser_type',
-    arguments: {
-      element: 'textbox',
-      ref: 's1e3',
-      text: 'Hi!',
-      submit: true,
-    },
-  });
-  expect(await client.callTool({
-    name: 'browser_console_messages',
-    arguments: {},
-  })).toHaveTextContent('[LOG] Key pressed: Enter , Text: Hi!');
-});
-
-test('browser_type (slowly)', async ({ client }) => {
-  await client.callTool({
-    name: 'browser_navigate',
-    arguments: {
-      url: `data:text/html,<input type='text' onkeydown="console.log('Key pressed:', event.key, 'Text:', event.target.value)"></input>`,
-    },
-  });
-  await client.callTool({
-    name: 'browser_type',
-    arguments: {
-      element: 'textbox',
-      ref: 's1e3',
-      text: 'Hi!',
-      submit: true,
-      slowly: true,
-    },
-  });
-  expect(await client.callTool({
-    name: 'browser_console_messages',
-    arguments: {},
-  })).toHaveTextContent([
-    '[LOG] Key pressed: H Text: ',
-    '[LOG] Key pressed: i Text: H',
-    '[LOG] Key pressed: ! Text: Hi',
-    '[LOG] Key pressed: Enter Text: Hi!',
-  ].join('\n'));
-});
-
-test('browser_resize', async ({ client }) => {
-  await client.callTool({
-    name: 'browser_navigate',
-    arguments: {
-      url: 'data:text/html,<html><title>Resize Test</title><body><div id="size">Waiting for resize...</div><script>new ResizeObserver(() => { document.getElementById("size").textContent = `Window size: ${window.innerWidth}x${window.innerHeight}`; }).observe(document.body);</script></body></html>',
-    },
+    arguments: { url: server.PREFIX },
   });
 
   const response = await client.callTool({
@@ -201,10 +141,67 @@ test('browser_resize', async ({ client }) => {
       height: 780,
     },
   });
-  expect(response).toContainTextContent(`- Ran Playwright code:
+  expect(response).toContainTextContent(`### Ran Playwright code
 \`\`\`js
 // Resize browser window to 390x780
 await page.setViewportSize({ width: 390, height: 780 });
 \`\`\``);
-  await expect.poll(() => client.callTool({ name: 'browser_snapshot', arguments: {} })).toContainTextContent('Window size: 390x780');
+  await expect.poll(() => client.callTool({ name: 'browser_snapshot' })).toContainTextContent('Window size: 390x780');
+});
+
+test('old locator error message', async ({ client, server }) => {
+  server.setContent('/', `
+    <button>Button 1</button>
+    <button>Button 2</button>
+    <script>
+      document.querySelector('button').addEventListener('click', () => {
+        document.querySelectorAll('button')[1].remove();
+      });
+    </script>
+  `, 'text/html');
+
+  expect(await client.callTool({
+    name: 'browser_navigate',
+    arguments: {
+      url: server.PREFIX,
+    },
+  })).toContainTextContent(`
+  - button "Button 1" [ref=e2]
+  - button "Button 2" [ref=e3]
+  `.trim());
+
+  await client.callTool({
+    name: 'browser_click',
+    arguments: {
+      element: 'Button 1',
+      ref: 'e2',
+    },
+  });
+
+  expect(await client.callTool({
+    name: 'browser_click',
+    arguments: {
+      element: 'Button 2',
+      ref: 'e3',
+    },
+  })).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 }) => {
+  server.setContent('/', `
+    <div style="visibility: hidden;">
+      <div style="visibility: visible;">
+        <button>Button</button>
+      </div>
+    </div>
+  `, 'text/html');
+
+  await client.callTool({
+    name: 'browser_navigate',
+    arguments: { url: server.PREFIX },
+  });
+
+  expect(await client.callTool({
+    name: 'browser_snapshot'
+  })).toContainTextContent('- button "Button"');
 });

tests/device.spec.ts

@@ -16,8 +16,8 @@
 
 import { test, expect } from './fixtures.js';
 
-test('--device should work', async ({ startClient, server }) => {
-  const client = await startClient({
+test('--device should work', async ({ startClient, server, mcpMode }) => {
+  const { client } = await startClient({
     args: ['--device', 'iPhone 15'],
   });
 

tests/dialogs.spec.ts

@@ -16,77 +16,28 @@
 
 import { test, expect } from './fixtures.js';
 
-// https://github.com/microsoft/playwright/issues/35663
-test.skip(({ mcpBrowser, mcpHeadless }) => mcpBrowser === 'webkit' && mcpHeadless);
-
-test('alert dialog', async ({ client }) => {
+test('alert dialog', async ({ client, server }) => {
+  server.setContent('/', `<button onclick="alert('Alert')">Button</button>`, 'text/html');
   expect(await client.callTool({
     name: 'browser_navigate',
-    arguments: {
-      url: 'data:text/html,<html><title>Title</title><button onclick="alert(\'Alert\')">Button</button></html>',
-    },
-  })).toContainTextContent('- button "Button" [ref=s1e3]');
+    arguments: { url: server.PREFIX },
+  })).toContainTextContent('- button "Button" [ref=e2]');
 
   expect(await client.callTool({
     name: 'browser_click',
     arguments: {
       element: 'Button',
-      ref: 's1e3',
+      ref: 'e2',
     },
-  })).toHaveTextContent(`- Ran Playwright code:
+  })).toHaveTextContent(`### Ran Playwright code
 \`\`\`js
 // Click Button
 await page.getByRole('button', { name: 'Button' }).click();
 \`\`\`
 
 ### Modal state
-- ["alert" dialog with message "Alert"]: can be handled by the "browser_handle_dialog" tool`);
-
-  const result = await client.callTool({
-    name: 'browser_handle_dialog',
-    arguments: {
-      accept: true,
-    },
-  });
-
-  expect(result).not.toContainTextContent('### Modal state');
-  expect(result).toHaveTextContent(`- Ran Playwright code:
-\`\`\`js
-// <internal code to handle "alert" dialog>
-\`\`\`
-
-- Page URL: data:text/html,<html><title>Title</title><button onclick="alert('Alert')">Button</button></html>
-- Page Title: Title
-- Page Snapshot
-\`\`\`yaml
-- button "Button" [ref=s2e3]
-\`\`\`
+- ["alert" dialog with message "Alert"]: can be handled by the "browser_handle_dialog" tool
 `);
-});
-
-test('two alert dialogs', async ({ client }) => {
-  test.fixme(true, 'Race between the dialog and ariaSnapshot');
-  expect(await client.callTool({
-    name: 'browser_navigate',
-    arguments: {
-      url: 'data:text/html,<html><title>Title</title><button onclick="alert(\'Alert 1\');alert(\'Alert 2\');">Button</button></html>',
-    },
-  })).toContainTextContent('- button "Button" [ref=s1e3]');
-
-  expect(await client.callTool({
-    name: 'browser_click',
-    arguments: {
-      element: 'Button',
-      ref: 's1e3',
-    },
-  })).toHaveTextContent(`- Ran Playwright code:
-\`\`\`js
-// Click Button
-await page.getByRole('button', { name: 'Button' }).click();
-\`\`\`
-
-### Modal state
-- ["alert" dialog with message "Alert 1"]: can be handled by the "browser_handle_dialog" tool`);
 
   const result = await client.callTool({
     name: 'browser_handle_dialog',
@@ -96,21 +47,77 @@ await page.getByRole('button', { name: 'Button' }).click();
   });
 
   expect(result).not.toContainTextContent('### Modal state');
+  expect(result).toContainTextContent(`Page Snapshot:`);
 });
 
-test('confirm dialog (true)', async ({ client }) => {
+test('two alert dialogs', async ({ client, server }) => {
+  server.setContent('/', `
+    <title>Title</title>
+    <body>
+      <button onclick="alert('Alert 1');alert('Alert 2');">Button</button>
+    </body>
+  `, 'text/html');
+
   expect(await client.callTool({
     name: 'browser_navigate',
-    arguments: {
-      url: 'data:text/html,<html><title>Title</title><button onclick="document.body.textContent = confirm(\'Confirm\')">Button</button></html>',
-    },
-  })).toContainTextContent('- button "Button" [ref=s1e3]');
+    arguments: { url: server.PREFIX },
+  })).toContainTextContent('- button "Button" [ref=e2]');
 
   expect(await client.callTool({
     name: 'browser_click',
     arguments: {
       element: 'Button',
-      ref: 's1e3',
+      ref: 'e2',
+    },
+  })).toHaveTextContent(`### Ran Playwright code
+\`\`\`js
+// Click Button
+await page.getByRole('button', { name: 'Button' }).click();
+\`\`\`
+
+### Modal state
+- ["alert" dialog with message "Alert 1"]: can be handled by the "browser_handle_dialog" tool
+`);
+
+  const result = await client.callTool({
+    name: 'browser_handle_dialog',
+    arguments: {
+      accept: true,
+    },
+  });
+
+  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',
+    arguments: {
+      accept: true,
+    },
+  });
+
+  expect(result2).not.toContainTextContent('### Modal state');
+});
+
+test('confirm dialog (true)', async ({ client, server }) => {
+  server.setContent('/', `
+    <title>Title</title>
+    <body>
+      <button onclick="document.body.textContent = confirm('Confirm')">Button</button>
+    </body>
+  `, 'text/html');
+
+  expect(await client.callTool({
+    name: 'browser_navigate',
+    arguments: { url: server.PREFIX },
+  })).toContainTextContent('- button "Button" [ref=e2]');
+
+  expect(await client.callTool({
+    name: 'browser_click',
+    arguments: {
+      element: 'Button',
+      ref: 'e2',
     },
   })).toContainTextContent(`### Modal state
 - ["confirm" dialog with message "Confirm"]: can be handled by the "browser_handle_dialog" tool`);
@@ -123,29 +130,34 @@ test('confirm dialog (true)', async ({ client }) => {
   });
 
   expect(result).not.toContainTextContent('### Modal state');
-  expect(result).toContainTextContent('// <internal code to handle "confirm" dialog>');
-  expect(result).toContainTextContent(`- Page Snapshot
+  expect(result).toContainTextContent(`- Page Snapshot:
 \`\`\`yaml
-- generic [ref=s2e2]: "true"
+- generic [active] [ref=e1]: "true"
 \`\`\``);
 });
 
-test('confirm dialog (false)', async ({ client }) => {
+test('confirm dialog (false)', async ({ client, server }) => {
+  server.setContent('/', `
+    <title>Title</title>
+    <body>
+      <button onclick="document.body.textContent = confirm('Confirm')">Button</button>
+    </body>
+  `, 'text/html');
+
   expect(await client.callTool({
     name: 'browser_navigate',
-    arguments: {
-      url: 'data:text/html,<html><title>Title</title><button onclick="document.body.textContent = confirm(\'Confirm\')">Button</button></html>',
-    },
-  })).toContainTextContent('- button "Button" [ref=s1e3]');
+    arguments: { url: server.PREFIX },
+  })).toContainTextContent('- button "Button" [ref=e2]');
 
   expect(await client.callTool({
     name: 'browser_click',
     arguments: {
       element: 'Button',
-      ref: 's1e3',
+      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',
@@ -154,28 +166,34 @@ test('confirm dialog (false)', async ({ client }) => {
     },
   });
 
-  expect(result).toContainTextContent(`- Page Snapshot
+  expect(result).toContainTextContent(`- Page Snapshot:
 \`\`\`yaml
-- generic [ref=s2e2]: "false"
+- generic [active] [ref=e1]: "false"
 \`\`\``);
 });
 
-test('prompt dialog', async ({ client }) => {
+test('prompt dialog', async ({ client, server }) => {
+  server.setContent('/', `
+    <title>Title</title>
+    <body>
+      <button onclick="document.body.textContent = prompt('Prompt')">Button</button>
+    </body>
+  `, 'text/html');
+
   expect(await client.callTool({
     name: 'browser_navigate',
-    arguments: {
-      url: 'data:text/html,<html><title>Title</title><button onclick="document.body.textContent = prompt(\'Prompt\')">Button</button></html>',
-    },
-  })).toContainTextContent('- button "Button" [ref=s1e3]');
+    arguments: { url: server.PREFIX },
+  })).toContainTextContent('- button "Button" [ref=e2]');
 
   expect(await client.callTool({
     name: 'browser_click',
     arguments: {
       element: 'Button',
-      ref: 's1e3',
+      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',
@@ -185,8 +203,47 @@ test('prompt dialog', async ({ client }) => {
     },
   });
 
-  expect(result).toContainTextContent(`- Page Snapshot
+  expect(result).toContainTextContent(`- Page Snapshot:
 \`\`\`yaml
-- generic [ref=s2e2]: Answer
+- generic [active] [ref=e1]: Answer
 \`\`\``);
 });
+
+test('alert dialog w/ race', async ({ client, server }) => {
+  server.setContent('/', `<button onclick="setTimeout(() => alert('Alert'), 100)">Button</button>`, 'text/html');
+  expect(await client.callTool({
+    name: 'browser_navigate',
+    arguments: { url: server.PREFIX },
+  })).toContainTextContent('- button "Button" [ref=e2]');
+
+  expect(await client.callTool({
+    name: 'browser_click',
+    arguments: {
+      element: 'Button',
+      ref: 'e2',
+    },
+  })).toHaveTextContent(`### Ran Playwright code
+\`\`\`js
+// Click Button
+await page.getByRole('button', { name: 'Button' }).click();
+\`\`\`
+
+### Modal state
+- ["alert" dialog with message "Alert"]: can be handled by the "browser_handle_dialog" tool
+`);
+
+  const result = await client.callTool({
+    name: 'browser_handle_dialog',
+    arguments: {
+      accept: true,
+    },
+  });
+
+  expect(result).not.toContainTextContent('### Modal state');
+  expect(result).toContainTextContent(`### Page state
+- Page URL: ${server.PREFIX}
+- Page Title: 
+- Page Snapshot:
+\`\`\`yaml
+- button "Button"`);
+});

tests/evaluate.spec.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.
+ */
+
+import { test, expect } from './fixtures.js';
+
+test('browser_evaluate', async ({ client, server }) => {
+  expect(await client.callTool({
+    name: 'browser_navigate',
+    arguments: { url: server.HELLO_WORLD },
+  })).toContainTextContent(`- Page Title: Title`);
+
+  const result = await client.callTool({
+    name: 'browser_evaluate',
+    arguments: {
+      function: '() => document.title',
+    },
+  });
+  expect(result).toContainTextContent(`"Title"`);
+});
+
+test('browser_evaluate (element)', async ({ client, server }) => {
+  server.setContent('/', `
+    <body style="background-color: red">Hello, world!</body>
+  `, 'text/html');
+  await client.callTool({
+    name: 'browser_navigate',
+    arguments: { url: server.PREFIX },
+  });
+
+  expect(await client.callTool({
+    name: 'browser_evaluate',
+    arguments: {
+      function: 'element => element.style.backgroundColor',
+      element: 'body',
+      ref: 'e1',
+    },
+  })).toContainTextContent(`### Result
+"red"`);
+});
+
+test('browser_evaluate (error)', async ({ client, server }) => {
+  expect(await client.callTool({
+    name: 'browser_navigate',
+    arguments: { url: server.HELLO_WORLD },
+  })).toContainTextContent(`- Page Title: Title`);
+
+  const result = await client.callTool({
+    name: 'browser_evaluate',
+    arguments: {
+      function: '() => nonExistentVariable',
+    },
+  });
+
+  expect(result.isError).toBe(true);
+  expect(result.content?.[0]?.text).toContain('nonExistentVariable');
+  // Check for common error patterns across browsers
+  const errorText = result.content?.[0]?.text || '';
+  expect(errorText).toMatch(/not defined|Can't find variable/);
+});

tests/files.spec.ts

@@ -14,20 +14,23 @@
  * limitations under the License.
  */
 
-import { test, expect } from './fixtures.js';
 import fs from 'fs/promises';
-import path from 'path';
+import { test, expect } from './fixtures.js';
+
+test('browser_file_upload', async ({ client, server }, testInfo) => {
+  server.setContent('/', `
+    <input type="file" />
+    <button>Button</button>
+  `, 'text/html');
 
-test('browser_file_upload', async ({ client }) => {
   expect(await client.callTool({
     name: 'browser_navigate',
-    arguments: {
-      url: 'data:text/html,<html><title>Title</title><input type="file" /><button>Button</button></html>',
-    },
+    arguments: { url: server.PREFIX },
   })).toContainTextContent(`
 \`\`\`yaml
-- button "Choose File" [ref=s1e3]
-- button "Button" [ref=s1e4]
+- generic [active] [ref=e1]:
+  - button "Choose File" [ref=e2]
+  - button "Button" [ref=e3]
 \`\`\``);
 
   {
@@ -35,7 +38,7 @@ test('browser_file_upload', async ({ client }) => {
       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());
@@ -45,12 +48,12 @@ The tool "browser_file_upload" can only be used when there is related modal stat
     name: 'browser_click',
     arguments: {
       element: 'Textbox',
-      ref: 's1e3',
+      ref: 'e2',
     },
   })).toContainTextContent(`### Modal state
 - [File chooser]: can be handled by the "browser_file_upload" tool`);
 
-  const filePath = test.info().outputPath('test.txt');
+  const filePath = testInfo.outputPath('test.txt');
   await fs.writeFile(filePath, 'Hello, world!');
 
   {
@@ -62,11 +65,6 @@ The tool "browser_file_upload" can only be used when there is related modal stat
     });
 
     expect(response).not.toContainTextContent('### Modal state');
-    expect(response).toContainTextContent(`
-\`\`\`yaml
-- button "Choose File" [ref=s3e3]
-- button "Button" [ref=s3e4]
-\`\`\``);
   }
 
   {
@@ -74,7 +72,7 @@ The tool "browser_file_upload" can only be used when there is related modal stat
       name: 'browser_click',
       arguments: {
         element: 'Textbox',
-        ref: 's3e3',
+        ref: 'e2',
       },
     });
 
@@ -86,36 +84,57 @@ The tool "browser_file_upload" can only be used when there is related modal stat
       name: 'browser_click',
       arguments: {
         element: 'Button',
-        ref: 's4e4',
+        ref: 'e3',
       },
     });
 
-    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`);
   }
 });
 
-test('clicking on download link emits download', async ({ startClient }, testInfo) => {
-  const outputDir = testInfo.outputPath('output');
-  const client = await startClient({
-    config: { outputDir },
+test('clicking on download link emits download', async ({ startClient, server, mcpMode }, testInfo) => {
+  const { client } = await startClient({
+    config: { outputDir: testInfo.outputPath('output') },
+  });
+
+  server.setContent('/', `<a href="/download" download="test.txt">Download</a>`, 'text/html');
+  server.setContent('/download', 'Data', 'text/plain');
+
+  expect(await client.callTool({
+    name: 'browser_navigate',
+    arguments: { url: server.PREFIX },
+  })).toContainTextContent('- link "Download" [ref=e2]');
+  await client.callTool({
+    name: 'browser_click',
+    arguments: {
+      element: 'Download link',
+      ref: 'e2',
+    },
+  });
+  await expect.poll(() => client.callTool({ name: 'browser_snapshot' })).toContainTextContent(`### Downloads
+- Downloaded file test.txt to ${testInfo.outputPath('output', 'test.txt')}`);
+});
+
+test('navigating to download link emits download', async ({ startClient, server, mcpBrowser, mcpMode }, testInfo) => {
+  const { client } = await startClient({
+    config: { outputDir: testInfo.outputPath('output') },
+  });
+
+  test.skip(mcpBrowser !== 'chromium', 'This test is racy');
+  server.route('/download', (req, res) => {
+    res.writeHead(200, {
+      'Content-Type': 'text/plain',
+      'Content-Disposition': 'attachment; filename=test.txt',
+    });
+    res.end('Hello world!');
   });
 
   expect(await client.callTool({
     name: 'browser_navigate',
     arguments: {
-      url: 'data:text/html,<a href="data:text/plain,Hello world!" download="test.txt">Download</a>',
+      url: server.PREFIX + 'download',
     },
-  })).toContainTextContent('- link "Download" [ref=s1e3]');
-  await client.callTool({
-    name: 'browser_click',
-    arguments: {
-      element: 'Download link',
-      ref: 's1e3',
-    },
-  });
-  await expect.poll(() => client.callTool({ name: 'browser_snapshot', arguments: {} })).toContainTextContent(`
-### Downloads
-- Downloaded file test.txt to ${path.join(outputDir, 'test.txt')}`);
+  })).toContainTextContent('### Downloads');
 });

tests/fixtures.ts

@@ -22,21 +22,28 @@ import { chromium } from 'playwright';
 import { test as baseTest, expect as baseExpect } from '@playwright/test';
 import { StdioClientTransport } from '@modelcontextprotocol/sdk/client/stdio.js';
 import { Client } from '@modelcontextprotocol/sdk/client/index.js';
-import { ChildProcessWithoutNullStreams, spawn } from 'child_process';
 import { TestServer } from './testserver/index.ts';
 
 import type { Config } from '../config';
+import type { BrowserContext } from 'playwright';
+import type { Transport } from '@modelcontextprotocol/sdk/shared/transport.js';
+import type { Stream } from 'stream';
 
 export type TestOptions = {
   mcpBrowser: string | undefined;
+  mcpMode: 'docker' | undefined;
+};
+
+type CDPServer = {
+  endpoint: string;
+  start: () => Promise<BrowserContext>;
 };
 
 type TestFixtures = {
   client: Client;
-  visionClient: Client;
-  startClient: (options?: { args?: string[], config?: Config }) => Promise<Client>;
+  startClient: (options?: { clientName?: string, args?: string[], config?: Config }) => Promise<{ client: Client, stderr: () => string }>;
   wsEndpoint: string;
-  cdpEndpoint: (port?: number) => Promise<string>;
+  cdpServer: CDPServer;
   server: TestServer;
   httpsServer: TestServer;
   mcpHeadless: boolean;
@@ -49,19 +56,21 @@ type WorkerFixtures = {
 export const test = baseTest.extend<TestFixtures & TestOptions, WorkerFixtures>({
 
   client: async ({ startClient }, use) => {
-    await use(await startClient());
+    const { client } = await startClient();
+    await use(client);
   },
 
-  visionClient: async ({ startClient }, use) => {
-    await use(await startClient({ args: ['--vision'] }));
-  },
-
-  startClient: async ({ mcpHeadless, mcpBrowser }, use, testInfo) => {
-    const userDataDir = testInfo.outputPath('user-data-dir');
+  startClient: async ({ mcpHeadless, mcpBrowser, mcpMode }, use, testInfo) => {
+    const userDataDir = mcpMode !== 'docker' ? testInfo.outputPath('user-data-dir') : undefined;
+    const configDir = path.dirname(test.info().config.configFile!);
     let client: Client | undefined;
 
     await use(async options => {
-      const args = ['--user-data-dir', userDataDir];
+      const args: string[] = [];
+      if (userDataDir)
+        args.push('--user-data-dir', userDataDir);
+      if (process.env.CI && process.platform === 'linux')
+        args.push('--no-sandbox');
       if (mcpHeadless)
         args.push('--headless');
       if (mcpBrowser)
@@ -71,18 +80,20 @@ export const test = baseTest.extend<TestFixtures & TestOptions, WorkerFixtures>(
       if (options?.config) {
         const configFile = testInfo.outputPath('config.json');
         await fs.promises.writeFile(configFile, JSON.stringify(options.config, null, 2));
-        args.push(`--config=${configFile}`);
+        args.push(`--config=${path.relative(configDir, configFile)}`);
       }
-      // NOTE: Can be removed when we drop Node.js 18 support and changed to import.meta.filename.
-      const __filename = url.fileURLToPath(import.meta.url);
-      const transport = new StdioClientTransport({
-        command: 'node',
-        args: [path.join(path.dirname(__filename), '../cli.js'), ...args],
+
+      client = new Client({ name: options?.clientName ?? 'test', version: '1.0.0' });
+      const { transport, stderr } = await createTransport(args, mcpMode);
+      let stderrBuffer = '';
+      stderr?.on('data', data => {
+        if (process.env.PWMCP_DEBUG)
+          process.stderr.write(data);
+        stderrBuffer += data.toString();
       });
-      client = new Client({ name: 'test', version: '1.0.0' });
       await client.connect(transport);
       await client.ping();
-      return client;
+      return { client, stderr: () => stderrBuffer };
     });
 
     await client?.close();
@@ -94,34 +105,25 @@ export const test = baseTest.extend<TestFixtures & TestOptions, WorkerFixtures>(
     await browserServer.close();
   },
 
-  cdpEndpoint: async ({ }, use, testInfo) => {
-    let browserProcess: ChildProcessWithoutNullStreams | undefined;
+  cdpServer: async ({ mcpBrowser }, use, testInfo) => {
+    test.skip(!['chrome', 'msedge', 'chromium'].includes(mcpBrowser!), 'CDP is not supported for non-Chromium browsers');
 
-    await use(async port => {
-      if (!port)
-        port = 3200 + test.info().parallelIndex;
-      if (browserProcess)
-        return `http://localhost:${port}`;
-      browserProcess = spawn(chromium.executablePath(), [
-        `--user-data-dir=${testInfo.outputPath('user-data-dir')}`,
-        `--remote-debugging-port=${port}`,
-        `--no-first-run`,
-        `--no-sandbox`,
-        `--headless`,
-        '--use-mock-keychain',
-        `data:text/html,hello world`,
-      ], {
-        stdio: 'pipe',
-      });
-      await new Promise<void>(resolve => {
-        browserProcess!.stderr.on('data', data => {
-          if (data.toString().includes('DevTools listening on '))
-            resolve();
+    let browserContext: BrowserContext | undefined;
+    const port = 3200 + test.info().parallelIndex;
+    await use({
+      endpoint: `http://localhost:${port}`,
+      start: async () => {
+        browserContext = await chromium.launchPersistentContext(testInfo.outputPath('cdp-user-data-dir'), {
+          channel: mcpBrowser,
+          headless: true,
+          args: [
+            `--remote-debugging-port=${port}`,
+          ],
         });
-      });
-      return `http://localhost:${port}`;
+        return browserContext;
+      }
     });
-    browserProcess?.kill();
+    await browserContext?.close();
   },
 
   mcpHeadless: async ({ headless }, use) => {
@@ -130,7 +132,9 @@ export const test = baseTest.extend<TestFixtures & TestOptions, WorkerFixtures>(
 
   mcpBrowser: ['chrome', { option: true }],
 
-  _workerServers: [async ({}, use, workerInfo) => {
+  mcpMode: [undefined, { option: true }],
+
+  _workerServers: [async ({ }, use, workerInfo) => {
     const port = 8907 + workerInfo.workerIndex * 4;
     const server = await TestServer.create(port);
 
@@ -156,6 +160,42 @@ export const test = baseTest.extend<TestFixtures & TestOptions, WorkerFixtures>(
   },
 });
 
+async function createTransport(args: string[], mcpMode: TestOptions['mcpMode']): Promise<{
+  transport: Transport,
+  stderr: Stream | null,
+}> {
+  // NOTE: Can be removed when we drop Node.js 18 support and changed to import.meta.filename.
+  const __filename = url.fileURLToPath(import.meta.url);
+  if (mcpMode === 'docker') {
+    const dockerArgs = ['run', '--rm', '-i', '--network=host', '-v', `${test.info().project.outputDir}:/app/test-results`];
+    const transport = new StdioClientTransport({
+      command: 'docker',
+      args: [...dockerArgs, 'playwright-mcp-dev:latest', ...args],
+    });
+    return {
+      transport,
+      stderr: transport.stderr,
+    };
+  }
+
+  const transport = new StdioClientTransport({
+    command: 'node',
+    args: [path.join(path.dirname(__filename), '../cli.js'), ...args],
+    cwd: path.join(path.dirname(__filename), '..'),
+    stderr: 'pipe',
+    env: {
+      ...process.env,
+      DEBUG: 'pw:mcp:test',
+      DEBUG_COLORS: '0',
+      DEBUG_HIDE_DATE: '1',
+    },
+  });
+  return {
+    transport,
+    stderr: transport.stderr!,
+  };
+}
+
 type Response = Awaited<ReturnType<Client['callTool']>>;
 
 export const expect = baseExpect.extend({
@@ -186,17 +226,14 @@ export const expect = baseExpect.extend({
     };
   },
 
-  toContainTextContent(response: Response, content: string | string[]) {
+  toContainTextContent(response: Response, content: string) {
     const isNot = this.isNot;
     try {
-      content = Array.isArray(content) ? content : [content];
-      const texts = (response.content as any).map(c => c.text);
-      for (let i = 0; i < texts.length; i++) {
-        if (isNot)
-          expect(texts[i]).not.toContain(content[i]);
-        else
-          expect(texts[i]).toContain(content[i]);
-      }
+      const texts = (response.content as any).map(c => c.text).join('\n');
+      if (isNot)
+        expect(texts).not.toContain(content);
+      else
+        expect(texts).toContain(content);
     } catch (e) {
       return {
         pass: isNot,
@@ -209,3 +246,7 @@ export const expect = baseExpect.extend({
     };
   },
 });
+
+export function formatOutput(output: string): string[] {
+  return output.split('\n').map(line => line.replace(/^pw:mcp:test /, '').replace(/user data dir.*/, 'user data dir').trim()).filter(Boolean);
+}

tests/headed.spec.ts

@@ -20,6 +20,7 @@ for (const mcpHeadless of [false, true]) {
   test.describe(`mcpHeadless: ${mcpHeadless}`, () => {
     test.use({ mcpHeadless });
     test.skip(process.platform === 'linux', 'Auto-detection wont let this test run on linux');
+    test.skip(({ mcpMode, mcpHeadless }) => mcpMode === 'docker' && !mcpHeadless, 'Headed mode is not supported in docker');
     test('browser', async ({ client, server, mcpBrowser }) => {
       test.skip(!['chrome', 'msedge', 'chromium'].includes(mcpBrowser ?? ''), 'Only chrome is supported for this test');
       server.route('/', (req, res) => {

tests/http.spec.ts

@@ -0,0 +1,259 @@
+/**
+ * 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 'node:fs';
+import url from 'node:url';
+
+import { ChildProcess, spawn } from 'node:child_process';
+import path from 'node:path';
+import { StreamableHTTPClientTransport } from '@modelcontextprotocol/sdk/client/streamableHttp.js';
+import { Client } from '@modelcontextprotocol/sdk/client/index.js';
+
+import { test as baseTest, expect } from './fixtures.js';
+import type { Config } from '../config.d.ts';
+
+// NOTE: Can be removed when we drop Node.js 18 support and changed to import.meta.filename.
+const __filename = url.fileURLToPath(import.meta.url);
+
+const test = baseTest.extend<{ serverEndpoint: (options?: { args?: string[], noPort?: boolean }) => Promise<{ url: URL, stderr: () => string }> }>({
+  serverEndpoint: async ({ mcpHeadless }, use, testInfo) => {
+    let cp: ChildProcess | undefined;
+    const userDataDir = testInfo.outputPath('user-data-dir');
+    await use(async (options?: { args?: string[], noPort?: boolean }) => {
+      if (cp)
+        throw new Error('Process already running');
+
+      cp = spawn('node', [
+        path.join(path.dirname(__filename), '../cli.js'),
+        ...(options?.noPort ? [] : ['--port=0']),
+        '--user-data-dir=' + userDataDir,
+        ...(mcpHeadless ? ['--headless'] : []),
+        ...(options?.args || []),
+      ], {
+        stdio: 'pipe',
+        env: {
+          ...process.env,
+          DEBUG: 'pw:mcp:test',
+          DEBUG_COLORS: '0',
+          DEBUG_HIDE_DATE: '1',
+        },
+      });
+      let stderr = '';
+      const url = await new Promise<string>(resolve => cp!.stderr?.on('data', data => {
+        stderr += data.toString();
+        const match = stderr.match(/Listening on (http:\/\/.*)/);
+        if (match)
+          resolve(match[1]);
+      }));
+
+      return { url: new URL(url), stderr: () => stderr };
+    });
+    cp?.kill('SIGTERM');
+  },
+});
+
+test('http transport', async ({ serverEndpoint }) => {
+  const { url } = await serverEndpoint();
+  const transport = new StreamableHTTPClientTransport(new URL('/mcp', url));
+  const client = new Client({ name: 'test', version: '1.0.0' });
+  await client.connect(transport);
+  await client.ping();
+});
+
+test('http transport (config)', async ({ serverEndpoint }) => {
+  const config: Config = {
+    server: {
+      port: 0,
+    }
+  };
+  const configFile = test.info().outputPath('config.json');
+  await fs.promises.writeFile(configFile, JSON.stringify(config, null, 2));
+
+  const { url } = await serverEndpoint({ noPort: true, args: ['--config=' + configFile] });
+  const transport = new StreamableHTTPClientTransport(new URL('/mcp', url));
+  const client = new Client({ name: 'test', version: '1.0.0' });
+  await client.connect(transport);
+  await client.ping();
+});
+
+test('http transport browser lifecycle (isolated)', async ({ serverEndpoint, server }) => {
+  const { url, stderr } = await serverEndpoint({ args: ['--isolated'] });
+
+  const transport1 = new StreamableHTTPClientTransport(new URL('/mcp', url));
+  const client1 = new Client({ name: 'test', version: '1.0.0' });
+  await client1.connect(transport1);
+  await client1.callTool({
+    name: 'browser_navigate',
+    arguments: { url: server.HELLO_WORLD },
+  });
+  /**
+   * src/client/streamableHttp.ts
+   * Clients that no longer need a particular session
+   * (e.g., because the user is leaving the client application) SHOULD send an
+   * HTTP DELETE to the MCP endpoint with the Mcp-Session-Id header to explicitly
+   * terminate the session.
+   */
+  await transport1.terminateSession();
+  await client1.close();
+
+  const transport2 = new StreamableHTTPClientTransport(new URL('/mcp', url));
+  const client2 = new Client({ name: 'test', version: '1.0.0' });
+  await client2.connect(transport2);
+  await client2.callTool({
+    name: 'browser_navigate',
+    arguments: { url: server.HELLO_WORLD },
+  });
+  await transport2.terminateSession();
+  await client2.close();
+
+  await expect(async () => {
+    const lines = stderr().split('\n');
+    expect(lines.filter(line => line.match(/create http session/)).length).toBe(2);
+    expect(lines.filter(line => line.match(/delete http session/)).length).toBe(2);
+
+    expect(lines.filter(line => line.match(/create context/)).length).toBe(2);
+    expect(lines.filter(line => line.match(/close context/)).length).toBe(2);
+
+    expect(lines.filter(line => line.match(/create browser context \(isolated\)/)).length).toBe(2);
+    expect(lines.filter(line => line.match(/close browser context \(isolated\)/)).length).toBe(2);
+
+    expect(lines.filter(line => line.match(/obtain browser \(isolated\)/)).length).toBe(2);
+    expect(lines.filter(line => line.match(/close browser \(isolated\)/)).length).toBe(2);
+  }).toPass();
+});
+
+test('http transport browser lifecycle (isolated, multiclient)', async ({ serverEndpoint, server }) => {
+  const { url, stderr } = await serverEndpoint({ args: ['--isolated'] });
+
+  const transport1 = new StreamableHTTPClientTransport(new URL('/mcp', url));
+  const client1 = new Client({ name: 'test', version: '1.0.0' });
+  await client1.connect(transport1);
+  await client1.callTool({
+    name: 'browser_navigate',
+    arguments: { url: server.HELLO_WORLD },
+  });
+
+  const transport2 = new StreamableHTTPClientTransport(new URL('/mcp', url));
+  const client2 = new Client({ name: 'test', version: '1.0.0' });
+  await client2.connect(transport2);
+  await client2.callTool({
+    name: 'browser_navigate',
+    arguments: { url: server.HELLO_WORLD },
+  });
+  await transport1.terminateSession();
+  await client1.close();
+
+  const transport3 = new StreamableHTTPClientTransport(new URL('/mcp', url));
+  const client3 = new Client({ name: 'test', version: '1.0.0' });
+  await client3.connect(transport3);
+  await client3.callTool({
+    name: 'browser_navigate',
+    arguments: { url: server.HELLO_WORLD },
+  });
+
+  await transport2.terminateSession();
+  await client2.close();
+  await transport3.terminateSession();
+  await client3.close();
+
+  await expect(async () => {
+    const lines = stderr().split('\n');
+    expect(lines.filter(line => line.match(/create http session/)).length).toBe(3);
+    expect(lines.filter(line => line.match(/delete http session/)).length).toBe(3);
+
+    expect(lines.filter(line => line.match(/create context/)).length).toBe(3);
+    expect(lines.filter(line => line.match(/close context/)).length).toBe(3);
+
+    expect(lines.filter(line => line.match(/create browser context \(isolated\)/)).length).toBe(3);
+    expect(lines.filter(line => line.match(/close browser context \(isolated\)/)).length).toBe(3);
+
+    expect(lines.filter(line => line.match(/obtain browser \(isolated\)/)).length).toBe(1);
+    expect(lines.filter(line => line.match(/close browser \(isolated\)/)).length).toBe(1);
+  }).toPass();
+});
+
+test('http transport browser lifecycle (persistent)', async ({ serverEndpoint, server }) => {
+  const { url, stderr } = await serverEndpoint();
+
+  const transport1 = new StreamableHTTPClientTransport(new URL('/mcp', url));
+  const client1 = new Client({ name: 'test', version: '1.0.0' });
+  await client1.connect(transport1);
+  await client1.callTool({
+    name: 'browser_navigate',
+    arguments: { url: server.HELLO_WORLD },
+  });
+  await transport1.terminateSession();
+  await client1.close();
+
+  const transport2 = new StreamableHTTPClientTransport(new URL('/mcp', url));
+  const client2 = new Client({ name: 'test', version: '1.0.0' });
+  await client2.connect(transport2);
+  await client2.callTool({
+    name: 'browser_navigate',
+    arguments: { url: server.HELLO_WORLD },
+  });
+  await transport2.terminateSession();
+  await client2.close();
+
+  await expect(async () => {
+    const lines = stderr().split('\n');
+    expect(lines.filter(line => line.match(/create http session/)).length).toBe(2);
+    expect(lines.filter(line => line.match(/delete http session/)).length).toBe(2);
+
+    expect(lines.filter(line => line.match(/create context/)).length).toBe(2);
+    expect(lines.filter(line => line.match(/close context/)).length).toBe(2);
+
+    expect(lines.filter(line => line.match(/create browser context \(persistent\)/)).length).toBe(2);
+    expect(lines.filter(line => line.match(/close browser context \(persistent\)/)).length).toBe(2);
+
+    expect(lines.filter(line => line.match(/lock user data dir/)).length).toBe(2);
+    expect(lines.filter(line => line.match(/release user data dir/)).length).toBe(2);
+  }).toPass();
+});
+
+test('http transport browser lifecycle (persistent, multiclient)', async ({ serverEndpoint, server }) => {
+  const { url } = await serverEndpoint();
+
+  const transport1 = new StreamableHTTPClientTransport(new URL('/mcp', url));
+  const client1 = new Client({ name: 'test', version: '1.0.0' });
+  await client1.connect(transport1);
+  await client1.callTool({
+    name: 'browser_navigate',
+    arguments: { url: server.HELLO_WORLD },
+  });
+
+  const transport2 = new StreamableHTTPClientTransport(new URL('/mcp', url));
+  const client2 = new Client({ name: 'test', version: '1.0.0' });
+  await client2.connect(transport2);
+  const response = await client2.callTool({
+    name: 'browser_navigate',
+    arguments: { url: server.HELLO_WORLD },
+  });
+  expect(response.isError).toBe(true);
+  expect(response.content?.[0].text).toContain('use --isolated to run multiple instances of the same browser');
+
+  await client1.close();
+  await client2.close();
+});
+
+test('http transport (default)', async ({ serverEndpoint }) => {
+  const { url } = await serverEndpoint();
+  const transport = new StreamableHTTPClientTransport(url);
+  const client = new Client({ name: 'test', version: '1.0.0' });
+  await client.connect(transport);
+  await client.ping();
+  expect(transport.sessionId, 'has session support').toBeDefined();
+});

tests/iframes.spec.ts

@@ -24,19 +24,21 @@ test('stitched aria frames', async ({ client }) => {
     },
   })).toContainTextContent(`
 \`\`\`yaml
-- heading "Hello" [level=1] [ref=s1e3]
-- iframe [ref=s1e4]:
-  - button "World" [ref=f1s1e3]
-  - main [ref=f1s1e4]:
-    - iframe [ref=f1s1e5]:
-      - paragraph [ref=f2s1e3]: Nested
+- generic [active] [ref=e1]:
+  - heading "Hello" [level=1] [ref=e2]
+  - iframe [ref=e3]:
+    - generic [active] [ref=f1e1]:
+      - button "World" [ref=f1e2]
+      - main [ref=f1e3]:
+        - iframe [ref=f1e4]:
+          - paragraph [ref=f2e2]: Nested
 \`\`\``);
 
   expect(await client.callTool({
     name: 'browser_click',
     arguments: {
       element: 'World',
-      ref: 'f1s1e3',
+      ref: 'f1e2',
     },
   })).toContainTextContent(`// Click World`);
 });

tests/install.spec.ts

@@ -0,0 +1,24 @@
+/**
+ * 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_install', async ({ client, mcpBrowser }) => {
+  test.skip(mcpBrowser !== 'chromium', 'Test only chromium');
+  expect(await client.callTool({
+    name: 'browser_install',
+  })).toContainTextContent(`### No open tabs`);
+});

tests/launch.spec.ts

@@ -14,36 +14,150 @@
  * limitations under the License.
  */
 
-import { test, expect } from './fixtures.js';
+import fs from 'fs';
 
-test('test reopen browser', async ({ client }) => {
+import { test, expect, formatOutput } from './fixtures.js';
+
+test('test reopen browser', async ({ startClient, server, mcpMode }) => {
+  const { client, stderr } = await startClient();
   await client.callTool({
     name: 'browser_navigate',
-    arguments: {
-      url: 'data:text/html,<html><title>Title</title><body>Hello, world!</body></html>',
-    },
+    arguments: { url: server.HELLO_WORLD },
   });
 
   expect(await client.callTool({
     name: 'browser_close',
-    arguments: {},
-  })).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',
-    arguments: {
-      url: 'data:text/html,<html><title>Title</title><body>Hello, world!</body></html>',
-    },
-  })).toContainTextContent(`- generic [ref=s1e2]: Hello, world!`);
+    arguments: { url: server.HELLO_WORLD },
+  })).toContainTextContent(`- generic [active] [ref=e1]: Hello, world!`);
+
+  await client.close();
+
+  if (process.platform === 'win32')
+    return;
+
+  await expect.poll(() => formatOutput(stderr()), { timeout: 0 }).toEqual([
+    'create context',
+    'create browser context (persistent)',
+    'lock user data dir',
+    'close context',
+    'close browser context (persistent)',
+    'release user data dir',
+    'close browser context complete (persistent)',
+    'create browser context (persistent)',
+    'lock user data dir',
+    'close context',
+    'close browser context (persistent)',
+    'release user data dir',
+    'close browser context complete (persistent)',
+  ]);
 });
 
-test('executable path', async ({ startClient }) => {
-  const client = await startClient({ args: [`--executable-path=bogus`] });
+test('executable path', async ({ startClient, server }) => {
+  const { client } = await startClient({ args: [`--executable-path=bogus`] });
   const response = await client.callTool({
     name: 'browser_navigate',
-    arguments: {
-      url: 'data:text/html,<html><title>Title</title><body>Hello, world!</body></html>',
-    },
+    arguments: { url: server.HELLO_WORLD },
   });
   expect(response).toContainTextContent(`executable doesn't exist`);
 });
+
+test('persistent context', async ({ startClient, server }) => {
+  server.setContent('/', `
+    <body>
+    </body>
+    <script>
+      document.body.textContent = localStorage.getItem('test') ? 'Storage: YES' : 'Storage: NO';
+      localStorage.setItem('test', 'test');
+    </script>
+  `, 'text/html');
+
+  const { client } = await startClient();
+  const response = await client.callTool({
+    name: 'browser_navigate',
+    arguments: { url: server.PREFIX },
+  });
+  expect(response).toContainTextContent(`Storage: NO`);
+
+  await new Promise(resolve => setTimeout(resolve, 3000));
+
+  await client.callTool({
+    name: 'browser_close',
+  });
+
+  const { client: client2 } = await startClient();
+  const response2 = await client2.callTool({
+    name: 'browser_navigate',
+    arguments: { url: server.PREFIX },
+  });
+
+  expect(response2).toContainTextContent(`Storage: YES`);
+});
+
+test('isolated context', async ({ startClient, server }) => {
+  server.setContent('/', `
+    <body>
+    </body>
+    <script>
+      document.body.textContent = localStorage.getItem('test') ? 'Storage: YES' : 'Storage: NO';
+      localStorage.setItem('test', 'test');
+    </script>
+  `, 'text/html');
+
+  const { client: client1 } = await startClient({ args: [`--isolated`] });
+  const response = await client1.callTool({
+    name: 'browser_navigate',
+    arguments: { url: server.PREFIX },
+  });
+  expect(response).toContainTextContent(`Storage: NO`);
+
+  await client1.callTool({
+    name: 'browser_close',
+  });
+
+  const { client: client2 } = await startClient({ args: [`--isolated`] });
+  const response2 = await client2.callTool({
+    name: 'browser_navigate',
+    arguments: { url: server.PREFIX },
+  });
+  expect(response2).toContainTextContent(`Storage: NO`);
+});
+
+test('isolated context with storage state', async ({ startClient, server }, testInfo) => {
+  const storageStatePath = testInfo.outputPath('storage-state.json');
+  await fs.promises.writeFile(storageStatePath, JSON.stringify({
+    origins: [
+      {
+        origin: server.PREFIX,
+        localStorage: [{ name: 'test', value: 'session-value' }],
+      },
+    ],
+  }));
+
+  server.setContent('/', `
+    <body>
+    </body>
+    <script>
+      document.body.textContent = 'Storage: ' + localStorage.getItem('test');
+    </script>
+  `, 'text/html');
+
+  const { client } = await startClient({ args: [
+    `--isolated`,
+    `--storage-state=${storageStatePath}`,
+  ] });
+  const response = await client.callTool({
+    name: 'browser_navigate',
+    arguments: { url: server.PREFIX },
+  });
+  expect(response).toContainTextContent(`Storage: session-value`);
+});

tests/library.spec.ts

@@ -0,0 +1,28 @@
+/**
+ * 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 child_process from 'child_process';
+import fs from 'fs/promises';
+import { test, expect } from './fixtures.js';
+
+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');
+  await fs.writeFile(file, `
+    import('@playwright/mcp')
+      .then(playwrightMCP => playwrightMCP.createConnection())
+      .then(() => console.log('OK'));
+ `);
+  expect(child_process.execSync(`node ${file}`, { encoding: 'utf-8' })).toContain('OK');
+});

tests/network.spec.ts

@@ -17,15 +17,11 @@
 import { test, expect } from './fixtures.js';
 
 test('browser_network_requests', async ({ client, server }) => {
-  server.route('/', (req, res) => {
-    res.writeHead(200, { 'Content-Type': 'text/html' });
-    res.end(`<button onclick="fetch('/json')">Click me</button>`);
-  });
+  server.setContent('/', `
+    <button onclick="fetch('/json')">Click me</button>
+  `, 'text/html');
 
-  server.route('/json', (req, res) => {
-    res.writeHead(200, { 'Content-Type': 'application/json' });
-    res.end(JSON.stringify({ name: 'John Doe' }));
-  });
+  server.setContent('/json', JSON.stringify({ name: 'John Doe' }), 'application/json');
 
   await client.callTool({
     name: 'browser_navigate',
@@ -38,12 +34,13 @@ test('browser_network_requests', async ({ client, server }) => {
     name: 'browser_click',
     arguments: {
       element: 'Click me button',
-      ref: 's1e3',
+      ref: 'e2',
     },
   });
 
   await expect.poll(() => client.callTool({
     name: 'browser_network_requests',
-    arguments: {},
-  })).toHaveTextContent(`[GET] http://localhost:${server.PORT}/json => [200] OK`);
+  })).toHaveTextContent(`### Result
+[GET] ${`${server.PREFIX}`} => [200] OK
+[GET] ${`${server.PREFIX}json`} => [200] OK`);
 });

tests/pdf.spec.ts

@@ -14,15 +14,15 @@
  * limitations under the License.
  */
 
+import fs from 'fs';
+
 import { test, expect } from './fixtures.js';
 
-test('save as pdf unavailable', async ({ startClient }) => {
-  const client = await startClient({ args: ['--caps="no-pdf"'] });
+test('save as pdf unavailable', async ({ startClient, server }) => {
+  const { client } = await startClient();
   await client.callTool({
     name: 'browser_navigate',
-    arguments: {
-      url: 'data:text/html,<html><title>Title</title><body>Hello, world!</body></html>',
-    },
+    arguments: { url: server.HELLO_WORLD },
   });
 
   expect(await client.callTool({
@@ -30,18 +30,47 @@ test('save as pdf unavailable', async ({ startClient }) => {
   })).toHaveTextContent(/Tool \"browser_pdf_save\" not found/);
 });
 
-test('save as pdf', async ({ client, mcpBrowser }) => {
+test('save as pdf', async ({ startClient, mcpBrowser, server }, testInfo) => {
+  const { client } = await startClient({
+    config: { outputDir: testInfo.outputPath('output'), capabilities: ['pdf'] },
+  });
+
   test.skip(!!mcpBrowser && !['chromium', 'chrome', 'msedge'].includes(mcpBrowser), 'Save as PDF is only supported in Chromium.');
+
   expect(await client.callTool({
     name: 'browser_navigate',
-    arguments: {
-      url: 'data:text/html,<html><title>Title</title><body>Hello, world!</body></html>',
-    },
-  })).toContainTextContent(`- generic [ref=s1e2]: Hello, world!`);
+    arguments: { url: server.HELLO_WORLD },
+  })).toContainTextContent(`- generic [active] [ref=e1]: Hello, world!`);
 
   const response = await client.callTool({
     name: 'browser_pdf_save',
-    arguments: {},
   });
   expect(response).toHaveTextContent(/Save page as.*page-[^:]+.pdf/);
 });
+
+test('save as pdf (filename: output.pdf)', async ({ startClient, mcpBrowser, server }, testInfo) => {
+  const outputDir = testInfo.outputPath('output');
+  test.skip(!!mcpBrowser && !['chromium', 'chrome', 'msedge'].includes(mcpBrowser), 'Save as PDF is only supported in Chromium.');
+  const { client } = await startClient({
+    config: { outputDir, capabilities: ['pdf'] },
+  });
+
+  expect(await client.callTool({
+    name: 'browser_navigate',
+    arguments: { url: server.HELLO_WORLD },
+  })).toContainTextContent(`- generic [active] [ref=e1]: Hello, world!`);
+
+  expect(await client.callTool({
+    name: 'browser_pdf_save',
+    arguments: {
+      filename: 'output.pdf',
+    },
+  })).toContainTextContent(`output.pdf`);
+
+  const files = [...fs.readdirSync(outputDir)];
+
+  expect(fs.existsSync(outputDir)).toBeTruthy();
+  const pdfFiles = files.filter(f => f.endsWith('.pdf'));
+  expect(pdfFiles).toHaveLength(1);
+  expect(pdfFiles[0]).toMatch(/^output.pdf$/);
+});

tests/request-blocking.spec.ts

@@ -0,0 +1,82 @@
+/**
+ * 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 { test, expect } from './fixtures.ts';
+
+const BLOCK_MESSAGE = /Blocked by Web Inspector|NS_ERROR_FAILURE|net::ERR_BLOCKED_BY_CLIENT/g;
+
+const fetchPage = async (client: Client, url: string) => {
+  const result = await client.callTool({
+    name: 'browser_navigate',
+    arguments: {
+      url,
+    },
+  });
+
+  return JSON.stringify(result, null, 2);
+};
+
+test('default to allow all', async ({ server, client }) => {
+  server.setContent('/ppp', 'content:PPP', 'text/html');
+  const result = await fetchPage(client, server.PREFIX + 'ppp');
+  expect(result).toContain('content:PPP');
+});
+
+test('blocked works', async ({ startClient }) => {
+  const { client } = await startClient({
+    args: ['--blocked-origins', 'microsoft.com;example.com;playwright.dev']
+  });
+  const result = await fetchPage(client, 'https://example.com/');
+  expect(result).toMatch(BLOCK_MESSAGE);
+});
+
+test('allowed works', async ({ server, startClient }) => {
+  server.setContent('/ppp', 'content:PPP', 'text/html');
+  const { client } = await startClient({
+    args: ['--allowed-origins', `microsoft.com;${new URL(server.PREFIX).host};playwright.dev`]
+  });
+  const result = await fetchPage(client, server.PREFIX + 'ppp');
+  expect(result).toContain('content:PPP');
+});
+
+test('blocked takes precedence', async ({ startClient }) => {
+  const { client } = await startClient({
+    args: [
+      '--blocked-origins', 'example.com',
+      '--allowed-origins', 'example.com',
+    ],
+  });
+  const result = await fetchPage(client, 'https://example.com/');
+  expect(result).toMatch(BLOCK_MESSAGE);
+});
+
+test('allowed without blocked blocks all non-explicitly specified origins', async ({ startClient }) => {
+  const { client } = await startClient({
+    args: ['--allowed-origins', 'playwright.dev'],
+  });
+  const result = await fetchPage(client, 'https://example.com/');
+  expect(result).toMatch(BLOCK_MESSAGE);
+});
+
+test('blocked without allowed allows non-explicitly specified origins', async ({ server, startClient }) => {
+  server.setContent('/ppp', 'content:PPP', 'text/html');
+  const { client } = await startClient({
+    args: ['--blocked-origins', 'example.com'],
+  });
+  const result = await fetchPage(client, server.PREFIX + 'ppp');
+  expect(result).toContain('content:PPP');
+});

tests/screenshot.spec.ts

@@ -18,108 +18,180 @@ import fs from 'fs';
 
 import { test, expect } from './fixtures.js';
 
-test('browser_take_screenshot (viewport)', async ({ client }) => {
+test('browser_take_screenshot (viewport)', async ({ startClient, server }, testInfo) => {
+  const { client } = await startClient({
+    config: { outputDir: testInfo.outputPath('output') },
+  });
   expect(await client.callTool({
     name: 'browser_navigate',
-    arguments: {
-      url: 'data:text/html,<html><title>Title</title><body>Hello, world!</body></html>',
-    },
-  })).toContainTextContent(`Navigate to data:text/html`);
+    arguments: { url: server.HELLO_WORLD },
+  })).toContainTextContent(`Navigate to http://localhost`);
 
   expect(await client.callTool({
     name: 'browser_take_screenshot',
-    arguments: {},
   })).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',
-      },
     ],
   });
 });
 
-test('browser_take_screenshot (element)', async ({ client }) => {
+test('browser_take_screenshot (element)', async ({ startClient, server }, testInfo) => {
+  const { client } = await startClient({
+    config: { outputDir: testInfo.outputPath('output') },
+  });
   expect(await client.callTool({
     name: 'browser_navigate',
-    arguments: {
-      url: 'data:text/html,<html><title>Title</title><button>Hello, world!</button></html>',
-    },
-  })).toContainTextContent(`[ref=s1e3]`);
+    arguments: { url: server.HELLO_WORLD },
+  })).toContainTextContent(`[ref=e1]`);
 
   expect(await client.callTool({
     name: 'browser_take_screenshot',
     arguments: {
       element: 'hello button',
-      ref: 's1e3',
+      ref: 'e1',
     },
   })).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.getByRole('button', { name: 'Hello, world!' }).screenshot`),
-        type: 'text',
-      },
     ],
   });
 });
 
-test('browser_take_screenshot (outputDir)', async ({ startClient }, testInfo) => {
+test('--output-dir should work', async ({ startClient, server }, testInfo) => {
   const outputDir = testInfo.outputPath('output');
-  const client = await startClient({
+  const { client } = await startClient({
     config: { outputDir },
   });
   expect(await client.callTool({
     name: 'browser_navigate',
-    arguments: {
-      url: 'data:text/html,<html><title>Title</title><body>Hello, world!</body></html>',
-    },
-  })).toContainTextContent(`Navigate to data:text/html`);
+    arguments: { url: server.HELLO_WORLD },
+  })).toContainTextContent(`Navigate to http://localhost`);
 
   await client.callTool({
     name: 'browser_take_screenshot',
-    arguments: {},
   });
 
   expect(fs.existsSync(outputDir)).toBeTruthy();
-  expect([...fs.readdirSync(outputDir)]).toHaveLength(1);
+  const files = [...fs.readdirSync(outputDir)].filter(f => f.endsWith('.jpeg'));
+  expect(files).toHaveLength(1);
+  expect(files[0]).toMatch(/^page-\d{4}-\d{2}-\d{2}T\d{2}-\d{2}-\d{2}-\d{3}Z\.jpeg$/);
 });
 
-test('browser_take_screenshot (omitBase64)', async ({ startClient }) => {
-  const client = await startClient({
-    config: {
-      tools: {
-        browser_take_screenshot: {
-          omitBase64: true,
+for (const raw of [undefined, true]) {
+  test(`browser_take_screenshot (raw: ${raw})`, async ({ startClient, server }, testInfo) => {
+    const outputDir = testInfo.outputPath('output');
+    const ext = raw ? 'png' : 'jpeg';
+    const { client } = await startClient({
+      config: { outputDir },
+    });
+    expect(await client.callTool({
+      name: 'browser_navigate',
+      arguments: { url: server.PREFIX },
+    })).toContainTextContent(`Navigate to http://localhost`);
+
+    expect(await client.callTool({
+      name: 'browser_take_screenshot',
+      arguments: { raw },
+    })).toEqual({
+      content: [
+        {
+          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',
+        },
+      ],
+    });
+
+    const files = [...fs.readdirSync(outputDir)].filter(f => f.endsWith(`.${ext}`));
+
+    expect(fs.existsSync(outputDir)).toBeTruthy();
+    expect(files).toHaveLength(1);
+    expect(files[0]).toMatch(
+        new RegExp(`^page-\\d{4}-\\d{2}-\\d{2}T\\d{2}-\\d{2}-\\d{2}-\\d{3}Z\\.${ext}$`)
+    );
+  });
+
+}
+
+test('browser_take_screenshot (filename: "output.jpeg")', async ({ startClient, server }, testInfo) => {
+  const outputDir = testInfo.outputPath('output');
+  const { client } = await startClient({
+    config: { outputDir },
+  });
+  expect(await client.callTool({
+    name: 'browser_navigate',
+    arguments: { url: server.HELLO_WORLD },
+  })).toContainTextContent(`Navigate to http://localhost`);
+
+  expect(await client.callTool({
+    name: 'browser_take_screenshot',
+    arguments: {
+      filename: 'output.jpeg',
+    },
+  })).toEqual({
+    content: [
+      {
+        text: expect.stringContaining(`output.jpeg`),
+        type: 'text',
       },
+      {
+        data: expect.any(String),
+        mimeType: 'image/jpeg',
+        type: 'image',
+      },
+    ],
+  });
+
+  const files = [...fs.readdirSync(outputDir)].filter(f => f.endsWith('.jpeg'));
+
+  expect(fs.existsSync(outputDir)).toBeTruthy();
+  expect(files).toHaveLength(1);
+  expect(files[0]).toMatch(/^output\.jpeg$/);
+});
+
+test('browser_take_screenshot (imageResponses=omit)', async ({ startClient, server }, testInfo) => {
+  const outputDir = testInfo.outputPath('output');
+  const { client } = await startClient({
+    config: {
+      outputDir,
+      imageResponses: 'omit',
     },
   });
 
   expect(await client.callTool({
     name: 'browser_navigate',
-    arguments: {
-      url: 'data:text/html,<html><title>Title</title><body>Hello, world!</body></html>',
-    },
-  })).toContainTextContent(`Navigate to data:text/html`);
+    arguments: { url: server.HELLO_WORLD },
+  })).toContainTextContent(`Navigate to http://localhost`);
 
   await client.callTool({
     name: 'browser_take_screenshot',
-    arguments: {},
   });
 
   expect(await client.callTool({
     name: 'browser_take_screenshot',
-    arguments: {},
   })).toEqual({
     content: [
       {
@@ -129,3 +201,80 @@ test('browser_take_screenshot (omitBase64)', async ({ startClient }) => {
     ],
   });
 });
+
+test('browser_take_screenshot (fullPage: true)', async ({ startClient, server }, testInfo) => {
+  const { client } = await startClient({
+    config: { outputDir: testInfo.outputPath('output') },
+  });
+  expect(await client.callTool({
+    name: 'browser_navigate',
+    arguments: { url: server.HELLO_WORLD },
+  })).toContainTextContent(`Navigate to http://localhost`);
+
+  expect(await client.callTool({
+    name: 'browser_take_screenshot',
+    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',
+      },
+    ],
+  });
+});
+
+test('browser_take_screenshot (fullPage with element should error)', async ({ startClient, server }, testInfo) => {
+  const { client } = await startClient({
+    config: { outputDir: testInfo.outputPath('output') },
+  });
+  expect(await client.callTool({
+    name: 'browser_navigate',
+    arguments: { url: server.HELLO_WORLD },
+  })).toContainTextContent(`[ref=e1]`);
+
+  const result = await client.callTool({
+    name: 'browser_take_screenshot',
+    arguments: {
+      fullPage: true,
+      element: 'hello button',
+      ref: 'e1',
+    },
+  });
+
+  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',
+      },
+    ],
+  });
+});

tests/sse.spec.ts

@@ -14,51 +14,223 @@
  * limitations under the License.
  */
 
+import fs from 'node:fs';
 import url from 'node:url';
-import { spawn } from 'node:child_process';
+
+import { ChildProcess, spawn } from 'node:child_process';
 import path from 'node:path';
-import { test as baseTest } from './fixtures.js';
-import { expect } from 'playwright/test';
+import { SSEClientTransport } from '@modelcontextprotocol/sdk/client/sse.js';
+import { Client } from '@modelcontextprotocol/sdk/client/index.js';
+
+import { test as baseTest, expect } from './fixtures.js';
+import type { Config } from '../config.d.ts';
 
 // NOTE: Can be removed when we drop Node.js 18 support and changed to import.meta.filename.
 const __filename = url.fileURLToPath(import.meta.url);
 
-const test = baseTest.extend<{ serverEndpoint: string }>({
-  serverEndpoint: async ({}, use) => {
-    const cp = spawn('node', [path.join(path.dirname(__filename), '../cli.js'), '--port', '0'], { stdio: 'pipe' });
-    try {
-      let stdout = '';
-      const url = await new Promise<string>(resolve => cp.stdout?.on('data', data => {
-        stdout += data.toString();
-        const match = stdout.match(/Listening on (http:\/\/.*)/);
+const test = baseTest.extend<{ serverEndpoint: (options?: { args?: string[], noPort?: boolean }) => Promise<{ url: URL, stderr: () => string }> }>({
+  serverEndpoint: async ({ mcpHeadless }, use, testInfo) => {
+    let cp: ChildProcess | undefined;
+    const userDataDir = testInfo.outputPath('user-data-dir');
+    await use(async (options?: { args?: string[], noPort?: boolean }) => {
+      if (cp)
+        throw new Error('Process already running');
+
+      cp = spawn('node', [
+        path.join(path.dirname(__filename), '../cli.js'),
+        ...(options?.noPort ? [] : ['--port=0']),
+        '--user-data-dir=' + userDataDir,
+        ...(mcpHeadless ? ['--headless'] : []),
+        ...(options?.args || []),
+      ], {
+        stdio: 'pipe',
+        env: {
+          ...process.env,
+          DEBUG: 'pw:mcp:test',
+          DEBUG_COLORS: '0',
+          DEBUG_HIDE_DATE: '1',
+        },
+      });
+      let stderr = '';
+      const url = await new Promise<string>(resolve => cp!.stderr?.on('data', data => {
+        stderr += data.toString();
+        const match = stderr.match(/Listening on (http:\/\/.*)/);
         if (match)
           resolve(match[1]);
       }));
 
-      await use(url);
-    } finally {
-      cp.kill();
-    }
+      return { url: new URL(url), stderr: () => stderr };
+    });
+    cp?.kill('SIGTERM');
   },
 });
 
 test('sse transport', async ({ serverEndpoint }) => {
-  // need dynamic import b/c of some ESM nonsense
-  const { SSEClientTransport } = await import('@modelcontextprotocol/sdk/client/sse.js');
-  const { Client } = await import('@modelcontextprotocol/sdk/client/index.js');
-  const transport = new SSEClientTransport(new URL(serverEndpoint));
+  const { url } = await serverEndpoint();
+  const transport = new SSEClientTransport(new URL('/sse', url));
   const client = new Client({ name: 'test', version: '1.0.0' });
   await client.connect(transport);
   await client.ping();
 });
 
-test('streamable http transport', async ({ serverEndpoint }) => {
-  // need dynamic import b/c of some ESM nonsense
-  const { StreamableHTTPClientTransport } = await import('@modelcontextprotocol/sdk/client/streamableHttp.js');
-  const { Client } = await import('@modelcontextprotocol/sdk/client/index.js');
-  const transport = new StreamableHTTPClientTransport(new URL('/mcp', serverEndpoint));
+test('sse transport (config)', async ({ serverEndpoint }) => {
+  const config: Config = {
+    server: {
+      port: 0,
+    }
+  };
+  const configFile = test.info().outputPath('config.json');
+  await fs.promises.writeFile(configFile, JSON.stringify(config, null, 2));
+
+  const { url } = await serverEndpoint({ noPort: true, args: ['--config=' + configFile] });
+  const transport = new SSEClientTransport(new URL('/sse', url));
   const client = new Client({ name: 'test', version: '1.0.0' });
   await client.connect(transport);
   await client.ping();
-  expect(transport.sessionId, 'has session support').toBeDefined();
+});
+
+test('sse transport browser lifecycle (isolated)', async ({ serverEndpoint, server }) => {
+  const { url, stderr } = await serverEndpoint({ args: ['--isolated'] });
+
+  const transport1 = new SSEClientTransport(new URL('/sse', url));
+  const client1 = new Client({ name: 'test', version: '1.0.0' });
+  await client1.connect(transport1);
+  await client1.callTool({
+    name: 'browser_navigate',
+    arguments: { url: server.HELLO_WORLD },
+  });
+  await client1.close();
+
+  const transport2 = new SSEClientTransport(new URL('/sse', url));
+  const client2 = new Client({ name: 'test', version: '1.0.0' });
+  await client2.connect(transport2);
+  await client2.callTool({
+    name: 'browser_navigate',
+    arguments: { url: server.HELLO_WORLD },
+  });
+  await client2.close();
+
+  await expect(async () => {
+    const lines = stderr().split('\n');
+    expect(lines.filter(line => line.match(/create SSE session/)).length).toBe(2);
+    expect(lines.filter(line => line.match(/delete SSE session/)).length).toBe(2);
+
+    expect(lines.filter(line => line.match(/create context/)).length).toBe(2);
+    expect(lines.filter(line => line.match(/close context/)).length).toBe(2);
+
+    expect(lines.filter(line => line.match(/create browser context \(isolated\)/)).length).toBe(2);
+    expect(lines.filter(line => line.match(/close browser context \(isolated\)/)).length).toBe(2);
+
+    expect(lines.filter(line => line.match(/obtain browser \(isolated\)/)).length).toBe(2);
+    expect(lines.filter(line => line.match(/close browser \(isolated\)/)).length).toBe(2);
+  }).toPass();
+});
+
+test('sse transport browser lifecycle (isolated, multiclient)', async ({ serverEndpoint, server }) => {
+  const { url, stderr } = await serverEndpoint({ args: ['--isolated'] });
+
+  const transport1 = new SSEClientTransport(new URL('/sse', url));
+  const client1 = new Client({ name: 'test', version: '1.0.0' });
+  await client1.connect(transport1);
+  await client1.callTool({
+    name: 'browser_navigate',
+    arguments: { url: server.HELLO_WORLD },
+  });
+
+  const transport2 = new SSEClientTransport(new URL('/sse', url));
+  const client2 = new Client({ name: 'test', version: '1.0.0' });
+  await client2.connect(transport2);
+  await client2.callTool({
+    name: 'browser_navigate',
+    arguments: { url: server.HELLO_WORLD },
+  });
+  await client1.close();
+
+  const transport3 = new SSEClientTransport(new URL('/sse', url));
+  const client3 = new Client({ name: 'test', version: '1.0.0' });
+  await client3.connect(transport3);
+  await client3.callTool({
+    name: 'browser_navigate',
+    arguments: { url: server.HELLO_WORLD },
+  });
+
+  await client2.close();
+  await client3.close();
+
+  await expect(async () => {
+    const lines = stderr().split('\n');
+    expect(lines.filter(line => line.match(/create SSE session/)).length).toBe(3);
+    expect(lines.filter(line => line.match(/delete SSE session/)).length).toBe(3);
+
+    expect(lines.filter(line => line.match(/create context/)).length).toBe(3);
+    expect(lines.filter(line => line.match(/close context/)).length).toBe(3);
+
+    expect(lines.filter(line => line.match(/create browser context \(isolated\)/)).length).toBe(3);
+    expect(lines.filter(line => line.match(/close browser context \(isolated\)/)).length).toBe(3);
+
+    expect(lines.filter(line => line.match(/obtain browser \(isolated\)/)).length).toBe(1);
+    expect(lines.filter(line => line.match(/close browser \(isolated\)/)).length).toBe(1);
+  }).toPass();
+});
+
+test('sse transport browser lifecycle (persistent)', async ({ serverEndpoint, server }) => {
+  const { url, stderr } = await serverEndpoint();
+
+  const transport1 = new SSEClientTransport(new URL('/sse', url));
+  const client1 = new Client({ name: 'test', version: '1.0.0' });
+  await client1.connect(transport1);
+  await client1.callTool({
+    name: 'browser_navigate',
+    arguments: { url: server.HELLO_WORLD },
+  });
+  await client1.close();
+
+  const transport2 = new SSEClientTransport(new URL('/sse', url));
+  const client2 = new Client({ name: 'test', version: '1.0.0' });
+  await client2.connect(transport2);
+  await client2.callTool({
+    name: 'browser_navigate',
+    arguments: { url: server.HELLO_WORLD },
+  });
+  await client2.close();
+
+  await expect(async () => {
+    const lines = stderr().split('\n');
+    expect(lines.filter(line => line.match(/create SSE session/)).length).toBe(2);
+    expect(lines.filter(line => line.match(/delete SSE session/)).length).toBe(2);
+
+    expect(lines.filter(line => line.match(/create context/)).length).toBe(2);
+    expect(lines.filter(line => line.match(/close context/)).length).toBe(2);
+
+    expect(lines.filter(line => line.match(/create browser context \(persistent\)/)).length).toBe(2);
+    expect(lines.filter(line => line.match(/close browser context \(persistent\)/)).length).toBe(2);
+
+    expect(lines.filter(line => line.match(/lock user data dir/)).length).toBe(2);
+    expect(lines.filter(line => line.match(/release user data dir/)).length).toBe(2);
+  }).toPass();
+});
+
+test('sse transport browser lifecycle (persistent, multiclient)', async ({ serverEndpoint, server }) => {
+  const { url } = await serverEndpoint();
+
+  const transport1 = new SSEClientTransport(new URL('/sse', url));
+  const client1 = new Client({ name: 'test', version: '1.0.0' });
+  await client1.connect(transport1);
+  await client1.callTool({
+    name: 'browser_navigate',
+    arguments: { url: server.HELLO_WORLD },
+  });
+
+  const transport2 = new SSEClientTransport(new URL('/sse', url));
+  const client2 = new Client({ name: 'test', version: '1.0.0' });
+  await client2.connect(transport2);
+  const response = await client2.callTool({
+    name: 'browser_navigate',
+    arguments: { url: server.HELLO_WORLD },
+  });
+  expect(response.isError).toBe(true);
+  expect(response.content?.[0].text).toContain('use --isolated to run multiple instances of the same browser');
+
+  await client1.close();
+  await client2.close();
 });

tests/tabs.spec.ts

@@ -14,8 +14,6 @@
  * limitations under the License.
  */
 
-import { chromium } from 'playwright';
-
 import { test, expect } from './fixtures.js';
 
 import type { Client } from '@modelcontextprotocol/sdk/client/index.js';
@@ -32,126 +30,109 @@ async function createTab(client: Client, title: string, body: string) {
 test('list initial tabs', async ({ client }) => {
   expect(await client.callTool({
     name: 'browser_tab_list',
-    arguments: {},
   })).toHaveTextContent(`### Open tabs
-- 1: (current) [] (about:blank)`);
+- 0: (current) [] (about:blank)`);
 });
 
 test('list first tab', async ({ client }) => {
   await createTab(client, 'Tab one', 'Body one');
   expect(await client.callTool({
     name: 'browser_tab_list',
-    arguments: {},
   })).toHaveTextContent(`### Open tabs
-- 1: [] (about:blank)
-- 2: (current) [Tab one] (data:text/html,<title>Tab one</title><body>Body one</body>)`);
+- 0: [] (about:blank)
+- 1: (current) [Tab one] (data:text/html,<title>Tab one</title><body>Body one</body>)`);
 });
 
 test('create new tab', async ({ client }) => {
-  expect(await createTab(client, 'Tab one', 'Body one')).toHaveTextContent(`
-- Ran Playwright code:
-\`\`\`js
-// <internal code to open a new tab>
-\`\`\`
+  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>)
+`);
 
-### Open tabs
-- 1: [] (about:blank)
-- 2: (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
+- Page Snapshot:
 \`\`\`yaml
-- generic [ref=s1e2]: Body one
+- generic [active] [ref=e1]: Body one
 \`\`\``);
 
-  expect(await createTab(client, 'Tab two', 'Body two')).toHaveTextContent(`
-- Ran Playwright code:
-\`\`\`js
-// <internal code to open a new tab>
-\`\`\`
+  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>)
+`);
 
-### Open tabs
-- 1: [] (about:blank)
-- 2: [Tab one] (data:text/html,<title>Tab one</title><body>Body one</body>)
-- 3: (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
+- Page Snapshot:
 \`\`\`yaml
-- generic [ref=s1e2]: Body two
+- generic [active] [ref=e1]: Body two
 \`\`\``);
 });
 
 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: 2,
+      index: 1,
     },
-  })).toHaveTextContent(`
-- Ran Playwright code:
-\`\`\`js
-// <internal code to select tab 2>
-\`\`\`
+  });
+  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>)`);
 
-### Open tabs
-- 1: [] (about:blank)
-- 2: (current) [Tab one] (data:text/html,<title>Tab one</title><body>Body one</body>)
-- 3: [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
+- Page Snapshot:
 \`\`\`yaml
-- generic [ref=s2e2]: Body one
+- generic [active] [ref=e1]: Body one
 \`\`\``);
 });
 
 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: 3,
+      index: 2,
     },
-  })).toHaveTextContent(`
-- Ran Playwright code:
-\`\`\`js
-// <internal code to close tab 3>
-\`\`\`
+  });
+  expect(result).toContainTextContent(`### Open tabs
+- 0: [] (about:blank)
+- 1: (current) [Tab one] (data:text/html,<title>Tab one</title><body>Body one</body>)`);
 
-### Open tabs
-- 1: [] (about:blank)
-- 2: (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
+- Page Snapshot:
 \`\`\`yaml
-- generic [ref=s2e2]: Body one
+- generic [active] [ref=e1]: Body one
 \`\`\``);
 });
 
-test('reuse first tab when navigating', async ({ startClient, cdpEndpoint }) => {
-  const browser = await chromium.connectOverCDP(await cdpEndpoint());
-  const [context] = browser.contexts();
-  const pages = context.pages();
+test('reuse first tab when navigating', async ({ startClient, cdpServer, server }) => {
+  const browserContext = await cdpServer.start();
+  const pages = browserContext.pages();
 
-  const client = await startClient({ args: [`--cdp-endpoint=${await cdpEndpoint()}`] });
+  const { client } = await startClient({ args: [`--cdp-endpoint=${cdpServer.endpoint}`] });
   await client.callTool({
     name: 'browser_navigate',
-    arguments: {
-      url: 'data:text/html,<title>Title</title><body>Body</body>',
-    },
+    arguments: { url: server.HELLO_WORLD },
   });
 
   expect(pages.length).toBe(1);

tests/testserver/index.ts

@@ -38,6 +38,7 @@ export class TestServer {
   readonly PORT: number;
   readonly PREFIX: string;
   readonly CROSS_PROCESS_PREFIX: string;
+  readonly HELLO_WORLD: string;
 
   static async create(port: number): Promise<TestServer> {
     const server = new TestServer(port);
@@ -67,8 +68,9 @@ export class TestServer {
     const same_origin = 'localhost';
     const protocol = sslOptions ? 'https' : 'http';
     this.PORT = port;
-    this.PREFIX = `${protocol}://${same_origin}:${port}`;
-    this.CROSS_PROCESS_PREFIX = `${protocol}://${cross_origin}:${port}`;
+    this.PREFIX = `${protocol}://${same_origin}:${port}/`;
+    this.CROSS_PROCESS_PREFIX = `${protocol}://${cross_origin}:${port}/`;
+    this.HELLO_WORLD = `${this.PREFIX}hello-world`;
   }
 
   setCSP(path: string, csp: string) {
@@ -88,6 +90,13 @@ export class TestServer {
     this._routes.set(path, handler);
   }
 
+  setContent(path: string, content: string, mimeType: string) {
+    this.route(path, (req, res) => {
+      res.writeHead(200, { 'Content-Type': mimeType });
+      res.end(mimeType === 'text/html' ? `<!DOCTYPE html>${content}` : content);
+    });
+  }
+
   redirect(from: string, to: string) {
     this.route(from, (req, res) => {
       const headers = this._extraHeaders.get(req.url!) || {};
@@ -120,6 +129,15 @@ export class TestServer {
     for (const subscriber of this._requestSubscribers.values())
       subscriber[rejectSymbol].call(null, error);
     this._requestSubscribers.clear();
+
+    this.setContent('/favicon.ico', '', 'image/x-icon');
+
+    this.setContent('/', ``, 'text/html');
+
+    this.setContent('/hello-world', `
+      <title>Title</title>
+      <body>Hello, world!</body>
+    `, 'text/html');
   }
 
   _onRequest(request: http.IncomingMessage, response: http.ServerResponse) {
@@ -144,7 +162,11 @@ export class TestServer {
       this._requestSubscribers.delete(path);
     }
     const handler = this._routes.get(path);
-    if (handler)
+    if (handler) {
       handler.call(null, request, response);
+    } else {
+      response.writeHead(404);
+      response.end();
+    }
   }
 }

tests/trace.spec.ts

@@ -0,0 +1,35 @@
+/**
+ * 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 { test, expect } from './fixtures.js';
+
+test('check that trace is saved', async ({ startClient, server, mcpMode }, testInfo) => {
+  const outputDir = testInfo.outputPath('output');
+
+  const { client } = await startClient({
+    args: ['--save-trace', `--output-dir=${outputDir}`],
+  });
+
+  expect(await client.callTool({
+    name: 'browser_navigate',
+    arguments: { url: server.HELLO_WORLD },
+  })).toContainTextContent(`Navigate to http://localhost`);
+
+  expect(fs.existsSync(path.join(outputDir, 'traces', 'trace.trace'))).toBeTruthy();
+});