Fix misleading browser_close message by adding resultOverride

Co-authored-by: Skn0tt <14912729+Skn0tt@users.noreply.github.com>

.github/workflows/ci.yml

@@ -7,32 +7,79 @@ on:
     branches: [ main ]
 
 jobs:
-  build-and-test:
+  lint:
     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
+    - run: npm run build
+    - name: Run ESLint
+      run: npm run lint
+    - name: Ensure no changes
+      run: git diff --exit-code
 
+  test:
+    strategy:
+      fail-fast: false
+      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: Run linting
-      run: npm run lint
-
+    - 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: Install Playwright browsers
-      run: npx playwright install --with-deps
-
     - 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 chromium
+    - name: Build
+      run: npm run build
+    - 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
+      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/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
@@ -15,9 +15,41 @@ jobs:
           node-version: 18
           registry-url: https://registry.npmjs.org/
       - run: npm ci
+      - run: npx playwright install --with-deps
       - run: npm run build
       - run: npm run lint
-      - run: npm run test
+      - 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
+        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

.gitignore

@@ -1,3 +1,8 @@
 lib/
 node_modules/
 test-results/
+playwright-report/
+.vscode/mcp.json
+
+.idea
+.DS_Store

.npmignore

@@ -4,3 +4,4 @@ LICENSE
 !lib/**/*.js
 !cli.js
 !index.*
+!config.d.ts

Dockerfile

@@ -0,0 +1,69 @@
+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
+
+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
+
+# ------------------------------
+# Builder
+# ------------------------------
+FROM base AS builder
+
+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 *.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", "--no-sandbox"]

README.md

@@ -4,18 +4,22 @@ 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
+### Requirements
+- Node.js 18 or newer
+- VS Code, Cursor, Windsurf, Claude Desktop or any other MCP client
 
-- Web navigation and form-filling
-- Data extraction from structured content
-- Automated testing driven by LLMs
-- General-purpose browser interaction for agents
+<!--
+// Generate using:
+node utils/generate-links.js
+-->
 
-### Example config
+### Getting started
+
+First, install the Playwright MCP server with your client. A typical configuration looks like this:
 
 ```js
 {
@@ -30,68 +34,200 @@ A Model Context Protocol (MCP) server that provides browser automation capabilit
 }
 ```
 
+[<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
 
-Install the Playwright MCP server in VS Code using one of these buttons:
+<details><summary><b>Install in VS Code</b></summary>
 
-<!--
-// Generate using?:
-const config = JSON.stringify({ name: 'playwright', command: 'npx', args: ["-y", "@playwright/mcp@latest"] });
-const urlForWebsites = `vscode:mcp/install?${encodeURIComponent(config)}`;
-// Github markdown does not allow linking to `vscode:` directly, so you can use our redirect:
-const urlForGithub = `https://insiders.vscode.dev/redirect?url=${encodeURIComponent(urlForWebsites)}`;
--->
-
-[<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-y%2522%252C%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-y%2522%252C%2522%2540playwright%252Fmcp%2540latest%2522%255D%257D)
-
-Alternatively, you can install the Playwright MCP server using the VS Code CLI:
+You can also install the Playwright MCP server using the VS Code CLI:
 
 ```bash
 # For VS Code
 code --add-mcp '{"name":"playwright","command":"npx","args":["@playwright/mcp@latest"]}'
 ```
 
-```bash
-# For VS Code Insiders
-code-insiders --add-mcp '{"name":"playwright","command":"npx","args":["@playwright/mcp@latest"]}'
-```
-
 After installation, the Playwright MCP server will be available for use with your GitHub Copilot agent in VS Code.
+</details>
 
-### CLI Options
+<details>
+<summary><b>Install in Cursor</b></summary>
 
-The Playwright MCP server supports the following command-line options:
+#### Click the button to install:
 
-- `--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)
-- `--port <port>`: Port to listen on for SSE transport
-- `--user-data-dir <path>`: Path to the user data directory
-- `--vision`: Run server that uses screenshots (Aria snapshots are used by default)
+[![Install MCP Server](https://cursor.com/deeplink/mcp-install-dark.svg)](https://cursor.com/install-mcp?name=playwright&config=eyJjb21tYW5kIjoibnB4IEBwbGF5d3JpZ2h0L21jcEBsYXRlc3QifQ%3D%3D)
 
-### User data directory
+#### Or install manually:
 
-Playwright MCP will launch the browser with the new profile, located at
+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`.
 
+```js
+{
+  "mcpServers": {
+    "playwright": {
+      "command": "npx",
+      "args": [
+        "@playwright/mcp@latest"
+      ]
+    }
+  }
+}
 ```
-- `%USERPROFILE%\AppData\Local\ms-playwright\mcp-chrome-profile` on Windows
-- `~/Library/Caches/ms-playwright/mcp-chrome-profile` on macOS
-- `~/.cache/ms-playwright/mcp-chrome-profile` on Linux
+</details>
+
+<details>
+<summary><b>Install in Windsurf</b></summary>
+
+Follow Windsuff MCP [documentation](https://docs.windsurf.com/windsurf/cascade/mcp). Use following configuration:
+
+```js
+{
+  "mcpServers": {
+    "playwright": {
+      "command": "npx",
+      "args": [
+        "@playwright/mcp@latest"
+      ]
+    }
+  }
+}
+```
+</details>
+
+<details>
+<summary><b>Install in Claude Desktop</b></summary>
+
+Follow the MCP install [guide](https://modelcontextprotocol.io/quickstart/user), use following configuration:
+
+```js
+{
+  "mcpServers": {
+    "playwright": {
+      "command": "npx",
+      "args": [
+        "@playwright/mcp@latest"
+      ]
+    }
+  }
+}
+```
+</details>
+
+<details>
+<summary><b>Install in Claude Code</b></summary>
+
+Use the Claude Code CLI to add the Playwright MCP server:
+
+```bash
+claude mcp add playwright npx @playwright/mcp@latest
+```
+</details>
+
+<details>
+<summary><b>Install in Qodo Gen</b></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 following configuration:
+
+```js
+{
+  "mcpServers": {
+    "playwright": {
+      "command": "npx",
+      "args": [
+        "@playwright/mcp@latest"
+      ]
+    }
+  }
+}
 ```
 
-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.
+Click <code>Save</code>.
+</details>
 
+### Configuration
 
-### Running headless browser (Browser without GUI).
+Playwright MCP server supports following arguments. They can be provided in the JSON configuration above, as a part of the `"args"` list:
 
-This mode is useful for background or batch operations.
+<!--- 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.
+  --browser-agent <endpoint>   Use browser agent (experimental).
+  --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.
+  --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", "omit", or "auto". Defaults to
+                               "auto", which sends images if the client can
+                               display them.
+  --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-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"
+  --vision                     Run server that uses screenshots (Aria snapshots
+                               are used by default)
+```
+
+<!--- End of options generated section -->
+
+### User profile
+
+You can run Playwright MCP with persistent profile like a regular browser (default), or in the isolated contexts for the testing sessions.
+
+**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
+```
+
+**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
 {
@@ -100,14 +236,104 @@ This mode is useful for background or batch operations.
       "command": "npx",
       "args": [
         "@playwright/mcp@latest",
-        "--headless"
+        "--isolated",
+        "--storage-state={path/to/storage.json}"
       ]
     }
   }
 }
 ```
 
-### Running headed browser on Linux w/o DISPLAY
+### Configuration file
+
+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
+{
+  // Browser configuration
+  browser?: {
+    // 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;
+
+    // Browser launch options (see Playwright docs)
+    // @see https://playwright.dev/docs/api/class-browsertype#browser-type-launch
+    launchOptions?: {
+      channel?: string;        // Browser channel (e.g. 'chrome')
+      headless?: boolean;      // Run in headless mode
+      executablePath?: string; // Path to browser executable
+      // ... other Playwright launch options
+    };
+
+    // Browser context options
+    // @see https://playwright.dev/docs/api/class-browser#browser-new-context
+    contextOptions?: {
+      viewport?: { width: number, height: number };
+      // ... other Playwright context options
+    };
+
+    // CDP endpoint for connecting to existing browser
+    cdpEndpoint?: string;
+
+    // Remote Playwright server endpoint
+    remoteEndpoint?: string;
+  },
+
+  // Server configuration
+  server?: {
+    port?: number;  // Port to listen on
+    host?: string;  // Host to bind to (default: localhost)
+  },
+
+  // List of enabled 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
+  >;
+
+  // Enable vision mode (screenshots instead of accessibility snapshots)
+  vision?: boolean;
+
+  // Directory for output files
+  outputDir?: string;
+
+  // 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[];
+  };
+ 
+  /**
+   * Do not send image responses to the client.
+   */
+  noImageResponses?: boolean;
+}
+```
+</details>
+
+### 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.
@@ -128,7 +354,52 @@ And then in MCP client config, set the `url` to the SSE endpoint:
 }
 ```
 
-### Tool Modes
+<details>
+<summary><b>Docker</b></summary>
+
+**NOTE:** The Docker implementation only supports headless chromium at the moment.
+
+```js
+{
+  "mcpServers": {
+    "playwright": {
+      "command": "docker",
+      "args": ["run", "-i", "--rm", "--init", "--pull=always", "mcr.microsoft.com/playwright/mcp"]
+    }
+  }
+}
+```
+
+You can build the Docker image yourself.
+
+```
+docker build -t mcr.microsoft.com/playwright/mcp .
+```
+</details>
+
+<details>
+<summary><b>Programmatic usage</b></summary>
+
+```js
+import http from 'http';
+
+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 connection = await createConnection({ browser: { launchOptions: { headless: true } } });
+  const transport = new SSEServerTransport('/messages', res);
+  await connection.sever.connect(transport);
+
+  // ...
+});
+```
+</details>
+
+### Tools
 
 The tools are available in two modes:
 
@@ -154,43 +425,55 @@ To use Vision Mode, add the `--vision` flag when starting the server:
 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.
 
-### Programmatic usage with custom transports
+<!--- Tools generated by update-readme.js -->
 
-```js
-import { createServer } from '@playwright/mcp';
+<details>
+<summary><b>Interactions</b></summary>
 
-// ...
+<!-- NOTE: This has been generated via update-readme.js -->
 
-const server = createServer({
-  launchOptions: { headless: true }
-});
-transport = new SSEServerTransport("/messages", res);
-server.connect(transport);
-```
+- **browser_snapshot**
+  - Title: Page snapshot
+  - Description: Capture accessibility snapshot of the current page, this is better than screenshot
+  - Parameters: None
+  - Read-only: **true**
 
-### Snapshot-based Interactions
+<!-- 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
+  - Read-only: **false**
+
+<!-- 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_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**
 
-- **browser_drag**
-  - Description: Perform drag and drop between two elements
-  - Parameters:
-    - `startElement` (string): Human-readable source element description used to obtain 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 permission to interact with the element
-    - `endRef` (string): Exact target element reference from the page snapshot
+<!-- 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
@@ -198,44 +481,256 @@ server.connect(transport);
     - `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**
+  - 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**
 
-- **browser_snapshot**
-  - Description: Capture accessibility snapshot of the current page, this is better than screenshot
+<!-- 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_wait_for**
+  - Title: Wait for
+  - Description: Wait for text to appear or disappear or a specified time to pass
+  - Parameters:
+    - `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**
+
+<!-- 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**
+
+</details>
+
+<details>
+<summary><b>Navigation</b></summary>
+
+<!-- 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**
+
+</details>
+
+<details>
+<summary><b>Resources</b></summary>
+
+<!-- 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.
+  - Read-only: **true**
 
-### Vision-based Interactions
+<!-- NOTE: This has been generated via update-readme.js -->
+
+- **browser_pdf_save**
+  - Title: Save as PDF
+  - Description: Save page as PDF
+  - Parameters:
+    - `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 -->
+
+- **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_console_messages**
+  - Title: Get console messages
+  - Description: Returns all console messages
+  - Parameters: None
+  - Read-only: **true**
+
+</details>
+
+<details>
+<summary><b>Utilities</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**
+
+<!-- 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_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**
+
+</details>
+
+<details>
+<summary><b>Tabs</b></summary>
+
+<!-- NOTE: This has been generated via update-readme.js -->
+
+- **browser_tab_list**
+  - Title: List tabs
+  - Description: List browser tabs
+  - Parameters: None
+  - Read-only: **true**
+
+<!-- NOTE: This has been generated via update-readme.js -->
+
+- **browser_tab_new**
+  - Title: Open a new tab
+  - Description: Open a new tab
+  - Parameters:
+    - `url` (string, optional): The URL to navigate to in the new tab. If not provided, the new tab will be blank.
+  - Read-only: **true**
+
+<!-- NOTE: This has been generated via update-readme.js -->
+
+- **browser_tab_select**
+  - Title: Select a tab
+  - Description: Select a tab by index
+  - Parameters:
+    - `index` (number): The index of the tab to select
+  - Read-only: **true**
+
+<!-- NOTE: This has been generated via update-readme.js -->
+
+- **browser_tab_close**
+  - Title: Close a tab
+  - Description: Close a tab
+  - Parameters:
+    - `index` (number, optional): The index of the tab to close. Closes current tab if not provided.
+  - Read-only: **false**
+
+</details>
+
+<details>
+<summary><b>Testing</b></summary>
+
+<!-- NOTE: This has been generated via update-readme.js -->
+
+- **browser_generate_playwright_test**
+  - Title: Generate a 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
+  - Read-only: **true**
+
+</details>
+
+<details>
+<summary><b>Vision mode</b></summary>
+
+<!-- NOTE: This has been generated via update-readme.js -->
+
+- **browser_screen_capture**
+  - Title: Take a screenshot
+  - Description: Take a screenshot of the current page
+  - Parameters: None
+  - Read-only: **true**
+
+<!-- NOTE: This has been generated via update-readme.js -->
 
 - **browser_screen_move_mouse**
+  - Title: Move mouse
   - Description: Move mouse to 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: **true**
 
-- **browser_screen_capture**
-  - Description: Take a screenshot of the current page
-  - Parameters: None
+<!-- NOTE: This has been generated via update-readme.js -->
 
 - **browser_screen_click**
+  - Title: 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
+  - Read-only: **false**
+
+<!-- NOTE: This has been generated via update-readme.js -->
 
 - **browser_screen_drag**
+  - Title: Drag mouse
   - Description: Drag left mouse button
   - Parameters:
     - `element` (string): Human-readable element description used to obtain permission to interact with the element
@@ -243,83 +738,58 @@ server.connect(transport);
     - `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**
+  - Title: Type text
   - Description: Type text
   - Parameters:
-    - `text` (string): Text to type
+    - `text` (string): Text to type into the element
     - `submit` (boolean, optional): Whether to submit entered text (press Enter after)
+  - Read-only: **false**
+
+<!-- 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**
 
-### Tab Management
+<!-- NOTE: This has been generated via update-readme.js -->
 
-- **browser_tab_list**
-  - Description: List browser tabs
-  - Parameters: None
-
-- **browser_tab_new**
-  - Description: Open a new tab
+- **browser_wait_for**
+  - Title: Wait for
+  - Description: Wait for text to appear or disappear or a specified time to pass
   - Parameters:
-    - `url` (string, optional): The URL to navigate to in the new tab. If not provided, the new tab will be blank.
+    - `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**
 
-- **browser_tab_select**
-  - Description: Select a tab by index
-  - Parameters:
-    - `index` (number): The index of the tab to select
-
-- **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
-
-- **browser_navigate**
-  - Description: Navigate to a URL
-  - Parameters:
-    - `url` (string): The URL to navigate to
-
-- **browser_navigate_back**
-  - Description: Go back to the previous page
-  - Parameters: None
-
-- **browser_navigate_forward**
-  - Description: Go forward to the next page
-  - Parameters: None
-
-### Keyboard
-
-- **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`
-
-### Files and Media
+<!-- NOTE: This has been generated via update-readme.js -->
 
 - **browser_file_upload**
-  - Description: Choose one or multiple files to 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**
 
-- **browser_pdf_save**
-  - Description: Save page as PDF
-  - Parameters: None
+<!-- NOTE: This has been generated via update-readme.js -->
 
-### Utilities
-
-- **browser_wait**
-  - Description: Wait for a specified time in seconds
+- **browser_handle_dialog**
+  - Title: Handle a dialog
+  - Description: Handle a dialog
   - Parameters:
-    - `time` (number): The time to wait in seconds (capped at 10 seconds)
+    - `accept` (boolean): Whether to accept the dialog.
+    - `promptText` (string, optional): The text of the prompt in case of a prompt dialog.
+  - Read-only: **false**
 
-- **browser_close**
-  - Description: Close the page
-  - Parameters: None
+</details>
 
-- **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
+
+<!--- End of tools generated section -->

cli.js

@@ -15,4 +15,4 @@
  * limitations under the License.
  */
 
-require('./lib/program');
+import './lib/program.js';

config.d.ts

@@ -0,0 +1,128 @@
+/**
+ * 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 * as playwright from 'playwright';
+
+export type ToolCapability = 'core' | 'tabs' | 'pdf' | 'history' | 'wait' | 'files' | 'install' | 'testing';
+
+export type Config = {
+  /**
+   * The browser to use.
+   */
+  browser?: {
+    /**
+     * Use browser agent (experimental).
+     */
+    browserAgent?: string;
+
+    /**
+     * The type of browser to use.
+     */
+    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.
+     */
+    userDataDir?: string;
+
+    /**
+     * Launch options passed to
+     * @see https://playwright.dev/docs/api/class-browsertype#browser-type-launch-persistent-context
+     *
+     * This is useful for settings options like `channel`, `headless`, `executablePath`, etc.
+     */
+    launchOptions?: playwright.LaunchOptions;
+
+    /**
+     * Context options for the browser context.
+     *
+     * This is useful for settings options like `viewport`.
+     */
+    contextOptions?: playwright.BrowserContextOptions;
+
+    /**
+     * Chrome DevTools Protocol endpoint to connect to an existing browser instance in case of Chromium family browsers.
+     */
+    cdpEndpoint?: string;
+
+    /**
+     * Remote endpoint to connect to an existing Playwright server.
+     */
+    remoteEndpoint?: string;
+  },
+
+  server?: {
+    /**
+     * The port to listen on for SSE or MCP transport.
+     */
+    port?: number;
+
+    /**
+     * The host to bind the server to. Default is localhost. Use 0.0.0.0 to bind to all interfaces.
+     */
+    host?: string;
+  },
+
+  /**
+   * 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.
+   */
+  capabilities?: ToolCapability[];
+
+  /**
+   * Run server that uses screenshots (Aria snapshots are used by default).
+   */
+  vision?: boolean;
+
+  /**
+   * Whether to save the Playwright trace of the session into the output directory.
+   */
+  saveTrace?: boolean;
+
+  /**
+   * The directory to save output files.
+   */
+  outputDir?: string;
+
+  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", "omit", or "auto". Defaults to "auto", which sends images if the client can display them.
+   */
+  imageResponses?: 'allow' | 'omit' | 'auto';
+};

eslint.config.mjs

@@ -33,6 +33,8 @@ const plugins = {
 };
 
 export const baseRules = {
+  "import/extensions": ["error", "ignorePackages", {ts: "always"}],
+  "@typescript-eslint/no-floating-promises": "error",
   "@typescript-eslint/no-unused-vars": [
     2,
     { args: "none", caughtErrors: "none" },
@@ -178,12 +180,16 @@ export const baseRules = {
 
   // react
   "react/react-in-jsx-scope": 0,
+  "no-console": 2,
 };
 
 const languageOptions = {
   parser: tsParser,
   ecmaVersion: 9,
   sourceType: "module",
+  parserOptions: {
+    project: path.join(fileURLToPath(import.meta.url), "..", "tsconfig.all.json"),
+  }
 };
 
 export default [

examples/generate-test.md

@@ -0,0 +1,10 @@
+Use Playwright tools to generate test for scenario:
+
+## GitHub PR Checks Navigation Checklist
+
+1. Open the [Microsoft Playwright GitHub repository](https://github.com/microsoft/playwright).
+2. Click on the **Pull requests** tab.
+3. Find and open the pull request titled **"chore: make noWaitAfter a default"**.
+4. Switch to the **Checks** tab for that pull request.
+5. Expand the **infra** check suite to view its jobs.
+6. Click on the **docs & lint** job to view its details.

extension/background.js

@@ -0,0 +1,344 @@
+/**
+ * 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.
+ */
+
+/**
+ * Simple Chrome Extension that pumps CDP messages between chrome.debugger and WebSocket
+ */
+
+// @ts-check
+
+function debugLog(...args) {
+  const enabled = false;
+  if (enabled) {
+    console.log('[Extension]', ...args);
+  }
+}
+
+class TabShareExtension {
+  constructor() {
+    this.activeConnections = new Map(); // tabId -> connection info
+
+    // Remove page action click handler since we now use popup
+    chrome.tabs.onRemoved.addListener(this.onTabRemoved.bind(this));
+
+    // Handle messages from popup
+    chrome.runtime.onMessage.addListener(this.onMessage.bind(this));
+  }
+
+  /**
+   * Handle messages from popup
+   * @param {any} message
+   * @param {chrome.runtime.MessageSender} sender
+   * @param {Function} sendResponse
+   */
+  onMessage(message, sender, sendResponse) {
+    switch (message.type) {
+      case 'getStatus':
+        this.getStatus(message.tabId, sendResponse);
+        return true; // Will respond asynchronously
+
+      case 'connect':
+        this.connectTab(message.tabId, message.bridgeUrl).then(
+          () => sendResponse({ success: true }),
+          (error) => sendResponse({ success: false, error: error.message })
+        );
+        return true; // Will respond asynchronously
+
+      case 'disconnect':
+        this.disconnectTab(message.tabId).then(
+          () => sendResponse({ success: true }),
+          (error) => sendResponse({ success: false, error: error.message })
+        );
+        return true; // Will respond asynchronously
+    }
+    return false;
+  }
+
+  /**
+   * Get connection status for popup
+   * @param {number} requestedTabId
+   * @param {Function} sendResponse
+   */
+  getStatus(requestedTabId, sendResponse) {
+    const isConnected = this.activeConnections.size > 0;
+    let activeTabId = null;
+    let activeTabInfo = null;
+
+    if (isConnected) {
+      const [tabId, connection] = this.activeConnections.entries().next().value;
+      activeTabId = tabId;
+
+      // Get tab info
+      chrome.tabs.get(tabId, (tab) => {
+        if (chrome.runtime.lastError) {
+          sendResponse({
+            isConnected: false,
+            error: 'Active tab not found'
+          });
+        } else {
+          sendResponse({
+            isConnected: true,
+            activeTabId,
+            activeTabInfo: {
+              title: tab.title,
+              url: tab.url
+            }
+          });
+        }
+      });
+    } else {
+      sendResponse({
+        isConnected: false,
+        activeTabId: null,
+        activeTabInfo: null
+      });
+    }
+  }
+
+  /**
+   * Connect a tab to the bridge server
+   * @param {number} tabId
+   * @param {string} bridgeUrl
+   */
+  async connectTab(tabId, bridgeUrl) {
+    try {
+      debugLog(`Connecting tab ${tabId} to bridge at ${bridgeUrl}`);
+
+      // Attach chrome debugger
+      const debuggee = { tabId };
+      await chrome.debugger.attach(debuggee, '1.3');
+
+      if (chrome.runtime.lastError)
+        throw new Error(chrome.runtime.lastError.message);
+      const targetInfo = /** @type {any} */ (await chrome.debugger.sendCommand(debuggee, 'Target.getTargetInfo'));
+      debugLog('Target info:', targetInfo);
+
+      // Connect to bridge server
+      const socket = new WebSocket(bridgeUrl);
+
+      const connection = {
+        debuggee,
+        socket,
+        tabId,
+        sessionId: `pw-tab-${tabId}`
+      };
+
+      await new Promise((resolve, reject) => {
+        socket.onopen = () => {
+          debugLog(`WebSocket connected for tab ${tabId}`);
+          // Send initial connection info to bridge
+          socket.send(JSON.stringify({
+            type: 'connection_info',
+            sessionId: connection.sessionId,
+            targetInfo: targetInfo?.targetInfo
+          }));
+          resolve(undefined);
+        };
+        socket.onerror = reject;
+        setTimeout(() => reject(new Error('Connection timeout')), 5000);
+      });
+
+      // Set up message handling
+      this.setupMessageHandling(connection);
+
+      // Store connection
+      this.activeConnections.set(tabId, connection);
+
+      // Update UI
+      chrome.action.setBadgeText({ tabId, text: '●' });
+      chrome.action.setBadgeBackgroundColor({ tabId, color: '#4CAF50' });
+      chrome.action.setTitle({ tabId, title: 'Disconnect from Playwright MCP' });
+
+      debugLog(`Tab ${tabId} connected successfully`);
+
+    } catch (error) {
+      debugLog(`Failed to connect tab ${tabId}:`, error.message);
+      await this.cleanupConnection(tabId);
+
+      // Show error to user
+      chrome.action.setBadgeText({ tabId, text: '!' });
+      chrome.action.setBadgeBackgroundColor({ tabId, color: '#F44336' });
+      chrome.action.setTitle({ tabId, title: `Connection failed: ${error.message}` });
+
+      throw error; // Re-throw for popup to handle
+    }
+  }
+
+  /**
+   * Set up bidirectional message handling between debugger and WebSocket
+   * @param {Object} connection
+   */
+  setupMessageHandling(connection) {
+    const { debuggee, socket, tabId, sessionId: rootSessionId } = connection;
+
+    // WebSocket -> chrome.debugger
+    socket.onmessage = async (event) => {
+      let message;
+      try {
+        message = JSON.parse(event.data);
+      } catch (error) {
+        debugLog('Error parsing message:', error);
+        socket.send(JSON.stringify({
+          error: {
+            code: -32700,
+            message: `Error parsing message: ${error.message}`
+          }
+        }));
+        return;
+      }
+
+      try {
+        debugLog('Received from bridge:', message);
+
+        const debuggerSession = { ...debuggee };
+        const sessionId = message.sessionId;
+        // Pass session id, unless it's the root session.
+        if (sessionId && sessionId !== rootSessionId)
+          debuggerSession.sessionId = sessionId;
+
+        // Forward CDP command to chrome.debugger
+        const result = await chrome.debugger.sendCommand(
+          debuggerSession,
+          message.method,
+          message.params || {}
+        );
+
+        // Send response back to bridge
+        const response = {
+          id: message.id,
+          sessionId,
+          result
+        };
+
+        if (chrome.runtime.lastError) {
+          response.error = {
+            code: -32000,
+            message: chrome.runtime.lastError.message,
+          };
+        }
+
+        socket.send(JSON.stringify(response));
+      } catch (error) {
+        debugLog('Error processing WebSocket message:', error);
+        const response = {
+          id: message.id,
+          sessionId: message.sessionId,
+          error: {
+            code: -32000,
+            message: error.message,
+          },
+        };
+        socket.send(JSON.stringify(response));
+      }
+    };
+
+    // chrome.debugger events -> WebSocket
+    const eventListener = (source, method, params) => {
+      if (source.tabId === tabId && socket.readyState === WebSocket.OPEN) {
+        // If the sessionId is not provided, use the root sessionId.
+        const event = {
+          sessionId: source.sessionId || rootSessionId,
+          method,
+          params,
+        };
+        debugLog('Forwarding CDP event:', event);
+        socket.send(JSON.stringify(event));
+      }
+    };
+
+    const detachListener = (source, reason) => {
+      if (source.tabId === tabId) {
+        debugLog(`Debugger detached from tab ${tabId}, reason: ${reason}`);
+        this.disconnectTab(tabId);
+      }
+    };
+
+    // Store listeners for cleanup
+    connection.eventListener = eventListener;
+    connection.detachListener = detachListener;
+
+    chrome.debugger.onEvent.addListener(eventListener);
+    chrome.debugger.onDetach.addListener(detachListener);
+
+    // Handle WebSocket close
+    socket.onclose = () => {
+      debugLog(`WebSocket closed for tab ${tabId}`);
+      this.disconnectTab(tabId);
+    };
+
+    socket.onerror = (error) => {
+      debugLog(`WebSocket error for tab ${tabId}:`, error);
+      this.disconnectTab(tabId);
+    };
+  }
+
+  /**
+   * Disconnect a tab from the bridge
+   * @param {number} tabId
+   */
+  async disconnectTab(tabId) {
+    await this.cleanupConnection(tabId);
+
+    // Update UI
+    chrome.action.setBadgeText({ tabId, text: '' });
+    chrome.action.setTitle({ tabId, title: 'Share tab with Playwright MCP' });
+
+    debugLog(`Tab ${tabId} disconnected`);
+  }
+
+  /**
+   * Clean up connection resources
+   * @param {number} tabId
+   */
+  async cleanupConnection(tabId) {
+    const connection = this.activeConnections.get(tabId);
+    if (!connection) return;
+
+    // Remove listeners
+    if (connection.eventListener) {
+      chrome.debugger.onEvent.removeListener(connection.eventListener);
+    }
+    if (connection.detachListener) {
+      chrome.debugger.onDetach.removeListener(connection.detachListener);
+    }
+
+    // Close WebSocket
+    if (connection.socket && connection.socket.readyState === WebSocket.OPEN) {
+      connection.socket.close();
+    }
+
+    // Detach debugger
+    try {
+      await chrome.debugger.detach(connection.debuggee);
+    } catch (error) {
+      // Ignore detach errors - might already be detached
+    }
+
+    this.activeConnections.delete(tabId);
+  }
+
+  /**
+   * Handle tab removal
+   * @param {number} tabId
+   */
+  async onTabRemoved(tabId) {
+    if (this.activeConnections.has(tabId)) {
+      await this.cleanupConnection(tabId);
+    }
+  }
+}
+
+new TabShareExtension();

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 through CDP bridge",
+
+  "permissions": [
+    "debugger",
+    "activeTab",
+    "tabs",
+    "storage"
+  ],
+
+  "host_permissions": [
+    "<all_urls>"
+  ],
+
+  "background": {
+    "service_worker": "background.js",
+    "type": "module"
+  },
+
+  "action": {
+    "default_title": "Share tab with Playwright MCP",
+    "default_popup": "popup.html",
+    "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/popup.html

@@ -0,0 +1,173 @@
+<!--
+  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>
+  <meta charset="utf-8">
+  <style>
+    body {
+      width: 320px;
+      padding: 16px;
+      font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif;
+      font-size: 14px;
+      margin: 0;
+    }
+
+    .header {
+      margin-bottom: 16px;
+      text-align: center;
+    }
+
+    .header h3 {
+      margin: 0 0 8px 0;
+      color: #333;
+    }
+
+    .section {
+      margin-bottom: 16px;
+    }
+
+    label {
+      display: block;
+      margin-bottom: 4px;
+      font-weight: 500;
+      color: #555;
+    }
+
+    input[type="url"] {
+      width: 100%;
+      padding: 8px;
+      border: 1px solid #ddd;
+      border-radius: 4px;
+      font-size: 14px;
+      box-sizing: border-box;
+    }
+
+    input[type="url"]:focus {
+      outline: none;
+      border-color: #4CAF50;
+      box-shadow: 0 0 0 2px rgba(76, 175, 80, 0.2);
+    }
+
+    .button {
+      background: #4CAF50;
+      color: white;
+      border: none;
+      padding: 10px 16px;
+      border-radius: 4px;
+      cursor: pointer;
+      font-size: 14px;
+      width: 100%;
+      margin-top: 8px;
+    }
+
+    .button:hover {
+      background: #45a049;
+    }
+
+    .button:disabled {
+      background: #cccccc;
+      cursor: not-allowed;
+    }
+
+    .button.disconnect {
+      background: #f44336;
+    }
+
+    .button.disconnect:hover {
+      background: #da190b;
+    }
+
+    .status {
+      padding: 12px;
+      border-radius: 4px;
+      margin-bottom: 16px;
+      text-align: center;
+    }
+
+    .status.connected {
+      background: #e8f5e8;
+      color: #2e7d32;
+      border: 1px solid #4caf50;
+    }
+
+    .status.error {
+      background: #ffebee;
+      color: #c62828;
+      border: 1px solid #f44336;
+    }
+
+    .status.warning {
+      background: #fff3e0;
+      color: #ef6c00;
+      border: 1px solid #ff9800;
+    }
+
+    .tab-info {
+      background: #f5f5f5;
+      padding: 12px;
+      border-radius: 4px;
+      margin-bottom: 16px;
+    }
+
+    .tab-title {
+      font-weight: 500;
+      margin-bottom: 4px;
+      color: #333;
+    }
+
+    .tab-url {
+      font-size: 12px;
+      color: #666;
+      word-break: break-all;
+    }
+
+    .focus-button {
+      background: #2196F3;
+      margin-top: 8px;
+    }
+
+    .focus-button:hover {
+      background: #1976D2;
+    }
+
+    .small-text {
+      font-size: 12px;
+      color: #666;
+      margin-top: 8px;
+    }
+  </style>
+</head>
+<body>
+  <div class="header">
+    <h3>Playwright MCP Bridge</h3>
+  </div>
+
+  <div id="status-container"></div>
+
+  <div class="section">
+    <label for="bridge-url">Bridge Server URL:</label>
+    <input type="url" id="bridge-url" disabled placeholder="ws://localhost:9223/extension" />
+    <div class="small-text">Enter the WebSocket URL of your MCP bridge server</div>
+  </div>
+
+  <div id="action-container">
+    <button id="connect-btn" class="button">Share This Tab</button>
+  </div>
+
+  <script src="popup.js"></script>
+</body>
+</html>

extension/popup.js

@@ -0,0 +1,228 @@
+/**
+ * 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.
+ */
+
+// @ts-check
+
+/**
+ * Popup script for Playwright MCP Bridge extension
+ */
+
+class PopupController {
+  constructor() {
+    this.currentTab = null;
+    this.bridgeUrlInput = /** @type {HTMLInputElement} */ (document.getElementById('bridge-url'));
+    this.connectBtn = /** @type {HTMLButtonElement} */ (document.getElementById('connect-btn'));
+    this.statusContainer = /** @type {HTMLElement} */ (document.getElementById('status-container'));
+    this.actionContainer = /** @type {HTMLElement} */ (document.getElementById('action-container'));
+
+    this.init();
+  }
+
+  async init() {
+    // Get current tab
+    const [tab] = await chrome.tabs.query({ active: true, currentWindow: true });
+    this.currentTab = tab;
+
+    // Load saved bridge URL
+    const result = await chrome.storage.sync.get(['bridgeUrl']);
+    const savedUrl = result.bridgeUrl || 'ws://localhost:9223/extension';
+    this.bridgeUrlInput.value = savedUrl;
+    this.bridgeUrlInput.disabled = false;
+
+    // Set up event listeners
+    this.bridgeUrlInput.addEventListener('input', this.onUrlChange.bind(this));
+    this.connectBtn.addEventListener('click', this.onConnectClick.bind(this));
+
+    // Update UI based on current state
+    await this.updateUI();
+  }
+
+  async updateUI() {
+    if (!this.currentTab?.id) return;
+
+    // Get connection status from background script
+    const response = await chrome.runtime.sendMessage({
+      type: 'getStatus',
+      tabId: this.currentTab.id
+    });
+
+    const { isConnected, activeTabId, activeTabInfo, error } = response;
+
+    if (!this.statusContainer || !this.actionContainer) return;
+
+    this.statusContainer.innerHTML = '';
+    this.actionContainer.innerHTML = '';
+
+    if (error) {
+      this.showStatus('error', `Error: ${error}`);
+      this.showConnectButton();
+    } else if (isConnected && activeTabId === this.currentTab.id) {
+      // Current tab is connected
+      this.showStatus('connected', 'This tab is currently shared with MCP server');
+      this.showDisconnectButton();
+    } else if (isConnected && activeTabId !== this.currentTab.id) {
+      // Another tab is connected
+      this.showStatus('warning', 'Another tab is already sharing the CDP session');
+      this.showActiveTabInfo(activeTabInfo);
+      this.showFocusButton(activeTabId);
+    } else {
+      // No connection
+      this.showConnectButton();
+    }
+  }
+
+  showStatus(type, message) {
+    const statusDiv = document.createElement('div');
+    statusDiv.className = `status ${type}`;
+    statusDiv.textContent = message;
+    this.statusContainer.appendChild(statusDiv);
+  }
+
+  showConnectButton() {
+    if (!this.actionContainer) return;
+
+    this.actionContainer.innerHTML = `
+      <button id="connect-btn" class="button">Share This Tab</button>
+    `;
+
+    const connectBtn = /** @type {HTMLButtonElement} */ (document.getElementById('connect-btn'));
+    if (connectBtn) {
+      connectBtn.addEventListener('click', this.onConnectClick.bind(this));
+
+      // Disable if URL is invalid
+      const isValidUrl = this.bridgeUrlInput ? this.isValidWebSocketUrl(this.bridgeUrlInput.value) : false;
+      connectBtn.disabled = !isValidUrl;
+    }
+  }
+
+  showDisconnectButton() {
+    if (!this.actionContainer) return;
+
+    this.actionContainer.innerHTML = `
+      <button id="disconnect-btn" class="button disconnect">Stop Sharing</button>
+    `;
+
+    const disconnectBtn = /** @type {HTMLButtonElement} */ (document.getElementById('disconnect-btn'));
+    if (disconnectBtn) {
+      disconnectBtn.addEventListener('click', this.onDisconnectClick.bind(this));
+    }
+  }
+
+  showActiveTabInfo(tabInfo) {
+    if (!tabInfo) return;
+
+    const tabDiv = document.createElement('div');
+    tabDiv.className = 'tab-info';
+    tabDiv.innerHTML = `
+      <div class="tab-title">${tabInfo.title || 'Unknown Tab'}</div>
+      <div class="tab-url">${tabInfo.url || ''}</div>
+    `;
+    this.statusContainer.appendChild(tabDiv);
+  }
+
+  showFocusButton(activeTabId) {
+    if (!this.actionContainer) return;
+
+    this.actionContainer.innerHTML = `
+      <button id="focus-btn" class="button focus-button">Switch to Shared Tab</button>
+    `;
+
+    const focusBtn = /** @type {HTMLButtonElement} */ (document.getElementById('focus-btn'));
+    if (focusBtn) {
+      focusBtn.addEventListener('click', () => this.onFocusClick(activeTabId));
+    }
+  }
+
+  onUrlChange() {
+    if (!this.bridgeUrlInput) return;
+
+    const isValid = this.isValidWebSocketUrl(this.bridgeUrlInput.value);
+    const connectBtn = /** @type {HTMLButtonElement} */ (document.getElementById('connect-btn'));
+    if (connectBtn) {
+      connectBtn.disabled = !isValid;
+    }
+
+    // Save URL to storage
+    if (isValid) {
+      chrome.storage.sync.set({ bridgeUrl: this.bridgeUrlInput.value });
+    }
+  }
+
+  async onConnectClick() {
+    if (!this.bridgeUrlInput || !this.currentTab?.id) return;
+
+    const url = this.bridgeUrlInput.value.trim();
+    if (!this.isValidWebSocketUrl(url)) {
+      this.showStatus('error', 'Please enter a valid WebSocket URL');
+      return;
+    }
+
+    // Save URL to storage
+    await chrome.storage.sync.set({ bridgeUrl: url });
+
+    // Send connect message to background script
+    const response = await chrome.runtime.sendMessage({
+      type: 'connect',
+      tabId: this.currentTab.id,
+      bridgeUrl: url
+    });
+
+    if (response.success) {
+      await this.updateUI();
+    } else {
+      this.showStatus('error', response.error || 'Failed to connect');
+    }
+  }
+
+  async onDisconnectClick() {
+    if (!this.currentTab?.id) return;
+
+    const response = await chrome.runtime.sendMessage({
+      type: 'disconnect',
+      tabId: this.currentTab.id
+    });
+
+    if (response.success) {
+      await this.updateUI();
+    } else {
+      this.showStatus('error', response.error || 'Failed to disconnect');
+    }
+  }
+
+  async onFocusClick(activeTabId) {
+    try {
+      await chrome.tabs.update(activeTabId, { active: true });
+      window.close(); // Close popup after switching
+    } catch (error) {
+      this.showStatus('error', 'Failed to switch to tab');
+    }
+  }
+
+  isValidWebSocketUrl(url) {
+    if (!url) return false;
+    try {
+      const parsed = new URL(url);
+      return parsed.protocol === 'ws:' || parsed.protocol === 'wss:';
+    } catch {
+      return false;
+    }
+  }
+}
+
+// Initialize popup when DOM is loaded
+document.addEventListener('DOMContentLoaded', () => {
+  new PopupController();
+});

index.d.ts

@@ -15,33 +15,14 @@
  * limitations under the License.
  */
 
-import type { LaunchOptions } from 'playwright';
 import type { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import type { Config } from './config.js';
+import type { BrowserContext } from 'playwright';
 
-type ToolCapability = 'core' | 'tabs' | 'pdf' | 'history' | 'wait' | 'files' | 'install';
-
-type Options = {
-  /**
-   * Path to the user data directory.
-   */
-  userDataDir?: string;
-
-  /**
-   * Launch options for the browser.
-   */
-  launchOptions?: LaunchOptions;
-
-  /**
-   * Use screenshots instead of snapshots. Less accurate, reliable and overall
-   * slower, but contains visual representation of the page.
-   * @default false
-   */
-  vision?: boolean;
-
-  /**
-   * Capabilities to enable.
-   */
-  capabilities?: ToolCapability[];
+export type Connection = {
+  server: Server;
+  close(): Promise<void>;
 };
 
-export function createServer(options?: Options): Server;
+export declare function createConnection(config?: Config, contextGetter?: () => Promise<BrowserContext>): Promise<Connection>;
+export {};

index.js

@@ -15,5 +15,5 @@
  * limitations under the License.
  */
 
-const { createServer } = require('./lib/index');
-module.exports = { createServer };
+import { createConnection } from './lib/index.js';
+export { createConnection };

package-lock.json

@@ -1,18 +1,20 @@
 {
   "name": "@playwright/mcp",
-  "version": "0.0.11",
+  "version": "0.0.29",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "@playwright/mcp",
-      "version": "0.0.11",
+      "version": "0.0.29",
       "license": "Apache-2.0",
       "dependencies": {
-        "@modelcontextprotocol/sdk": "^1.6.1",
+        "@modelcontextprotocol/sdk": "^1.11.0",
         "commander": "^13.1.0",
-        "playwright": "^1.52.0-alpha-1743163434000",
-        "yaml": "^2.7.1",
+        "debug": "^4.4.1",
+        "mime": "^4.0.7",
+        "playwright": "1.53.0",
+        "ws": "^8.18.1",
         "zod-to-json-schema": "^3.24.4"
       },
       "bin": {
@@ -21,9 +23,12 @@
       "devDependencies": {
         "@eslint/eslintrc": "^3.2.0",
         "@eslint/js": "^9.19.0",
-        "@playwright/test": "^1.52.0-alpha-1743163434000",
+        "@playwright/test": "1.53.0",
         "@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",
@@ -228,17 +233,18 @@
       }
     },
     "node_modules/@modelcontextprotocol/sdk": {
-      "version": "1.7.0",
-      "resolved": "https://registry.npmjs.org/@modelcontextprotocol/sdk/-/sdk-1.7.0.tgz",
-      "integrity": "sha512-IYPe/FLpvF3IZrd/f5p5ffmWhMc3aEMuM2wGJASDqC2Ge7qatVCdbfPx3n/5xFeb19xN0j/911M2AaFuircsWA==",
+      "version": "1.11.0",
+      "resolved": "https://registry.npmjs.org/@modelcontextprotocol/sdk/-/sdk-1.11.0.tgz",
+      "integrity": "sha512-k/1pb70eD638anoi0e8wUGAlbMJXyvdV4p62Ko+EZ7eBe1xMx8Uhak1R5DgfoofsK5IBBnRwsYGTaLZl+6/+RQ==",
       "license": "MIT",
       "dependencies": {
         "content-type": "^1.0.5",
         "cors": "^2.8.5",
+        "cross-spawn": "^7.0.3",
         "eventsource": "^3.0.2",
         "express": "^5.0.1",
         "express-rate-limit": "^7.5.0",
-        "pkce-challenge": "^4.1.0",
+        "pkce-challenge": "^5.0.0",
         "raw-body": "^3.0.0",
         "zod": "^3.23.8",
         "zod-to-json-schema": "^3.24.1"
@@ -286,13 +292,12 @@
       }
     },
     "node_modules/@playwright/test": {
-      "version": "1.52.0-alpha-1743163434000",
-      "resolved": "https://registry.npmjs.org/@playwright/test/-/test-1.52.0-alpha-1743163434000.tgz",
-      "integrity": "sha512-4uBgNlJ6hgPtB8DrwQsgoKuVoe7j+nPqudna7CLXWCmmT3LYPMD5aOjGoBkszr+R9NejtKashq/bOi/ny9hsIA==",
+      "version": "1.53.0",
+      "resolved": "https://registry.npmjs.org/@playwright/test/-/test-1.53.0.tgz",
+      "integrity": "sha512-15hjKreZDcp7t6TL/7jkAo6Df5STZN09jGiv5dbP9A6vMVncXRqE7/B2SncsyOwrkZRBH2i6/TPOL8BVmm3c7w==",
       "dev": true,
-      "license": "Apache-2.0",
       "dependencies": {
-        "playwright": "1.52.0-alpha-1743163434000"
+        "playwright": "1.53.0"
       },
       "bin": {
         "playwright": "cli.js"
@@ -354,6 +359,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",
@@ -361,6 +387,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",
@@ -375,6 +425,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",
@@ -385,6 +442,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",
@@ -834,16 +901,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",
@@ -853,44 +920,6 @@
         "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",
@@ -1091,7 +1120,6 @@
       "version": "7.0.6",
       "resolved": "https://registry.npmjs.org/cross-spawn/-/cross-spawn-7.0.6.tgz",
       "integrity": "sha512-uV2QOWP2nWzsy2aMp8aRibhi9dlzF5Hgh5SHaB9OiTGEyDTiJJyx0uy51QXdyWbtAHNua4XJzUKca3OzKUd3vA==",
-      "dev": true,
       "license": "MIT",
       "dependencies": {
         "path-key": "^3.1.0",
@@ -1157,12 +1185,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 +1253,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",
@@ -1770,46 +1788,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": {
@@ -1931,29 +1948,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",
@@ -2038,7 +2032,6 @@
       "resolved": "https://registry.npmjs.org/fsevents/-/fsevents-2.3.2.tgz",
       "integrity": "sha512-xiqMQR4xAeHTuB9uWm+fFRcIOgKBMiOBP+eXiyT7jsgVCq1bkVygt00oASowB7EdtpOHaaPgKt812P9ab+DDKA==",
       "hasInstallScript": true,
-      "license": "MIT",
       "optional": true,
       "os": [
         "darwin"
@@ -2313,12 +2306,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"
@@ -2786,7 +2779,6 @@
       "version": "2.0.0",
       "resolved": "https://registry.npmjs.org/isexe/-/isexe-2.0.0.tgz",
       "integrity": "sha512-RHxMLp9lnKHGHRng9QFhRCMbYAcVpn69smSGcq3f36xjgVVWThj4qqLbTLlq7Ssj8B+fIQ1EuCEGI2lKsyQeIw==",
-      "dev": true,
       "license": "ISC"
     },
     "node_modules/js-yaml": {
@@ -2930,15 +2922,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",
@@ -2960,6 +2943,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",
@@ -2970,12 +2968,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"
@@ -3005,9 +3003,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": {
@@ -3256,7 +3254,6 @@
       "version": "3.1.1",
       "resolved": "https://registry.npmjs.org/path-key/-/path-key-3.1.1.tgz",
       "integrity": "sha512-ojmeN0qd+y0jszEtoY48r0Peq5dwMEkIlCOu6Q5f41lfkswXuKtYrhgoTpLnyIcHm24Uhqx+5Tqm2InSwLhE6Q==",
-      "dev": true,
       "license": "MIT",
       "engines": {
         "node": ">=8"
@@ -3292,21 +3289,20 @@
       }
     },
     "node_modules/pkce-challenge": {
-      "version": "4.1.0",
-      "resolved": "https://registry.npmjs.org/pkce-challenge/-/pkce-challenge-4.1.0.tgz",
-      "integrity": "sha512-ZBmhE1C9LcPoH9XZSdwiPtbPHZROwAnMy+kIFQVrnMCxY4Cudlz3gBOpzilgc0jOgRaiT3sIWfpMomW2ar2orQ==",
+      "version": "5.0.0",
+      "resolved": "https://registry.npmjs.org/pkce-challenge/-/pkce-challenge-5.0.0.tgz",
+      "integrity": "sha512-ueGLflrrnvwB3xuo/uGob5pd5FN7l0MsLf0Z87o/UQmRtwjvfylfc9MurIxRAWywCYTgrvpXBcqjV4OfCYGCIQ==",
       "license": "MIT",
       "engines": {
         "node": ">=16.20.0"
       }
     },
     "node_modules/playwright": {
-      "version": "1.52.0-alpha-1743163434000",
-      "resolved": "https://registry.npmjs.org/playwright/-/playwright-1.52.0-alpha-1743163434000.tgz",
-      "integrity": "sha512-4uYv49ekPjolydfFfTfFQ2z4URF9UZMVUXLy7aXam/tPxEQ5O7+jQC+yzrDMGmhcj5QkMnxjlyk7N2V9a0QLdQ==",
-      "license": "Apache-2.0",
+      "version": "1.53.0",
+      "resolved": "https://registry.npmjs.org/playwright/-/playwright-1.53.0.tgz",
+      "integrity": "sha512-ghGNnIEYZC4E+YtclRn4/p6oYbdPiASELBIYkBXfaTVKreQUYbMUYQDwS12a8F0/HtIjr/CkGjtwABeFPGcS4Q==",
       "dependencies": {
-        "playwright-core": "1.52.0-alpha-1743163434000"
+        "playwright-core": "1.53.0"
       },
       "bin": {
         "playwright": "cli.js"
@@ -3319,10 +3315,9 @@
       }
     },
     "node_modules/playwright-core": {
-      "version": "1.52.0-alpha-1743163434000",
-      "resolved": "https://registry.npmjs.org/playwright-core/-/playwright-core-1.52.0-alpha-1743163434000.tgz",
-      "integrity": "sha512-Tn4u3Ywwjkh847/bYWlXIrNxv5DRJRDgtb+VYMXHvNCKkrxL6yfZ1ApIAYD7IAkkKH/KLTXszGWl3a/Z/KDfQA==",
-      "license": "Apache-2.0",
+      "version": "1.53.0",
+      "resolved": "https://registry.npmjs.org/playwright-core/-/playwright-core-1.53.0.tgz",
+      "integrity": "sha512-mGLg8m0pm4+mmtB7M89Xw/GSqoNC+twivl8ITteqvAndachozYe2ZA7srU6uleV1vEdAHYqjq+SV8SNxRRFYBw==",
       "bin": {
         "playwright-core": "cli.js"
       },
@@ -3374,12 +3369,12 @@
       }
     },
     "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"
@@ -3433,18 +3428,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",
@@ -3532,11 +3515,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"
@@ -3664,19 +3649,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",
@@ -3686,52 +3670,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"
@@ -3796,7 +3744,6 @@
       "version": "2.0.0",
       "resolved": "https://registry.npmjs.org/shebang-command/-/shebang-command-2.0.0.tgz",
       "integrity": "sha512-kHxr2zZpYtdmrN1qDjrrX/Z1rR1kG8Dx+gkpK1G4eXmvXswmcE1hTWBWYUzlraYw1/yZp6YuDY77YtvbN0dmDA==",
-      "dev": true,
       "license": "MIT",
       "dependencies": {
         "shebang-regex": "^3.0.0"
@@ -3809,7 +3756,6 @@
       "version": "3.0.0",
       "resolved": "https://registry.npmjs.org/shebang-regex/-/shebang-regex-3.0.0.tgz",
       "integrity": "sha512-7++dFhtcx3353uBaq8DDR4NuxBetBzC7ZQOhmTQInHEd6bSrXdiEyzCvG07Z44UYdLShWUyXt5M/yhz8ekcb1A==",
-      "dev": true,
       "license": "MIT",
       "engines": {
         "node": ">=8"
@@ -4066,9 +4012,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",
@@ -4216,15 +4162,6 @@
         "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",
@@ -4238,7 +4175,6 @@
       "version": "2.0.2",
       "resolved": "https://registry.npmjs.org/which/-/which-2.0.2.tgz",
       "integrity": "sha512-BLI3Tl1TW3Pvl70l3yq3Y64i+awpwXqsGBYWkkqMtnbXgrMD+yj7rhW0kuEDxzJaYXGjEW5ogapKNMEKNMjibA==",
-      "dev": true,
       "license": "ISC",
       "dependencies": {
         "isexe": "^2.0.0"
@@ -4355,16 +4291,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,7 +1,8 @@
 {
   "name": "@playwright/mcp",
-  "version": "0.0.11",
+  "version": "0.0.29",
   "description": "Playwright Tools for MCP",
+  "type": "module",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/microsoft/playwright-mcp.git"
@@ -16,9 +17,15 @@
   "license": "Apache-2.0",
   "scripts": {
     "build": "tsc",
-    "lint": "eslint .",
+    "lint": "npm run update-readme && eslint . && tsc --noEmit",
+    "update-readme": "node utils/update-readme.js",
     "watch": "tsc --watch",
     "test": "playwright test",
+    "ctest": "playwright test --project=chrome",
+    "ftest": "playwright test --project=firefox",
+    "wtest": "playwright test --project=webkit",
+    "etest": "playwright test --project=chromium-extension",
+    "run-server": "node lib/browserServer.js",
     "clean": "rm -rf lib",
     "npm-publish": "npm run clean && npm run build && npm run test && npm publish"
   },
@@ -30,18 +37,23 @@
     }
   },
   "dependencies": {
-    "@modelcontextprotocol/sdk": "^1.6.1",
+    "@modelcontextprotocol/sdk": "^1.11.0",
     "commander": "^13.1.0",
-    "playwright": "^1.52.0-alpha-1743163434000",
-    "yaml": "^2.7.1",
+    "debug": "^4.4.1",
+    "mime": "^4.0.7",
+    "playwright": "1.53.0",
+    "ws": "^8.18.1",
     "zod-to-json-schema": "^3.24.4"
   },
   "devDependencies": {
     "@eslint/eslintrc": "^3.2.0",
     "@eslint/js": "^9.19.0",
-    "@playwright/test": "^1.52.0-alpha-1743163434000",
+    "@playwright/test": "1.53.0",
     "@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",

playwright.config.ts

@@ -16,12 +16,29 @@
 
 import { defineConfig } from '@playwright/test';
 
-export default defineConfig({
+import type { TestOptions } from './tests/fixtures.js';
+
+export default defineConfig<TestOptions>({
   testDir: './tests',
   fullyParallel: true,
   forbidOnly: !!process.env.CI,
   retries: process.env.CI ? 2 : 0,
   workers: process.env.CI ? 1 : undefined,
   reporter: 'list',
-  projects: [{ name: 'default' }],
+  projects: [
+    { 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' } },
+    { name: 'chromium-extension', use: { mcpBrowser: 'chromium', mcpMode: 'extension' } },
+  ],
 });

src/browserContextFactory.ts

@@ -0,0 +1,266 @@
+/**
+ * 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 debug from 'debug';
+import * as playwright from 'playwright';
+import { userDataDir } from './fileUtils.js';
+
+import type { FullConfig } from './config.js';
+import type { BrowserInfo, LaunchBrowserRequest } from './browserServer.js';
+
+const testDebug = debug('pw:mcp:test');
+
+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);
+  if (browserConfig.browserAgent)
+    return new BrowserServerContextFactory(browserConfig);
+  return new PersistentContextFactory(browserConfig);
+}
+
+export interface BrowserContextFactory {
+  createContext(): 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(() => {});
+    if (browser.contexts().length === 0) {
+      testDebug(`close browser (${this.name})`);
+      await browser.close().catch(() => {});
+    }
+  }
+}
+
+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;
+  }
+}
+
+export class BrowserServerContextFactory extends BaseContextFactory {
+  constructor(browserConfig: FullConfig['browser']) {
+    super('persistent', browserConfig);
+  }
+
+  protected override async _doObtainBrowser(): Promise<playwright.Browser> {
+    const response = await fetch(new URL(`/json/launch`, this.browserConfig.browserAgent), {
+      method: 'POST',
+      body: JSON.stringify({
+        browserType: this.browserConfig.browserName,
+        userDataDir: this.browserConfig.userDataDir ?? await this._createUserDataDir(),
+        launchOptions: this.browserConfig.launchOptions,
+        contextOptions: this.browserConfig.contextOptions,
+      } as LaunchBrowserRequest),
+    });
+    const info = await response.json() as BrowserInfo;
+    if (info.error)
+      throw new Error(info.error);
+    return await playwright.chromium.connectOverCDP(`http://localhost:${info.cdpPort}/`);
+  }
+
+  protected override async _doCreateContext(browser: playwright.Browser): Promise<playwright.BrowserContext> {
+    return this.browserConfig.isolated ? await browser.newContext() : browser.contexts()[0];
+  }
+
+  private async _createUserDataDir() {
+    const dir = await userDataDir(this.browserConfig);
+    await fs.promises.mkdir(dir, { recursive: true });
+    return dir;
+  }
+}
+
+async function injectCdpPort(browserConfig: FullConfig['browser']) {
+  if (browserConfig.browserName === 'chromium')
+    (browserConfig.launchOptions as any).cdpPort = await findFreePort();
+}
+
+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);
+  });
+}

src/browserServer.ts

@@ -0,0 +1,197 @@
+/**
+ * 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 net from 'net';
+
+import { program } from 'commander';
+import playwright from 'playwright';
+
+import { HttpServer } from './httpServer.js';
+import { packageJSON } from './package.js';
+
+import type http from 'http';
+
+export type LaunchBrowserRequest = {
+  browserType: string;
+  userDataDir: string;
+  launchOptions: playwright.LaunchOptions;
+  contextOptions: playwright.BrowserContextOptions;
+};
+
+export type BrowserInfo = {
+  browserType: string;
+  userDataDir: string;
+  cdpPort: number;
+  launchOptions: playwright.LaunchOptions;
+  contextOptions: playwright.BrowserContextOptions;
+  error?: string;
+};
+
+type BrowserEntry = {
+  browser?: playwright.Browser;
+  info: BrowserInfo;
+};
+
+class BrowserServer {
+  private _server = new HttpServer();
+  private _entries: BrowserEntry[] = [];
+
+  constructor() {
+    this._setupExitHandler();
+  }
+
+  async start(port: number) {
+    await this._server.start({ port });
+    this._server.routePath('/json/list', (req, res) => {
+      this._handleJsonList(res);
+    });
+    this._server.routePath('/json/launch', async (req, res) => {
+      void this._handleLaunchBrowser(req, res).catch(e => console.error(e));
+    });
+    this._setEntries([]);
+  }
+
+  private _handleJsonList(res: http.ServerResponse) {
+    const list = this._entries.map(browser => browser.info);
+    res.end(JSON.stringify(list));
+  }
+
+  private async _handleLaunchBrowser(req: http.IncomingMessage, res: http.ServerResponse) {
+    const request = await readBody<LaunchBrowserRequest>(req);
+    let info = this._entries.map(entry => entry.info).find(info => info.userDataDir === request.userDataDir);
+    if (!info || info.error)
+      info = await this._newBrowser(request);
+    res.end(JSON.stringify(info));
+  }
+
+  private async _newBrowser(request: LaunchBrowserRequest): Promise<BrowserInfo> {
+    const cdpPort = await findFreePort();
+    (request.launchOptions as any).cdpPort = cdpPort;
+    const info: BrowserInfo = {
+      browserType: request.browserType,
+      userDataDir: request.userDataDir,
+      cdpPort,
+      launchOptions: request.launchOptions,
+      contextOptions: request.contextOptions,
+    };
+
+    const browserType = playwright[request.browserType as 'chromium' | 'firefox' | 'webkit'];
+    const { browser, error } = await browserType.launchPersistentContext(request.userDataDir, {
+      ...request.launchOptions,
+      ...request.contextOptions,
+      handleSIGINT: false,
+      handleSIGTERM: false,
+    }).then(context => {
+      return { browser: context.browser()!, error: undefined };
+    }).catch(error => {
+      return { browser: undefined, error: error.message };
+    });
+    this._setEntries([...this._entries, {
+      browser,
+      info: {
+        browserType: request.browserType,
+        userDataDir: request.userDataDir,
+        cdpPort,
+        launchOptions: request.launchOptions,
+        contextOptions: request.contextOptions,
+        error,
+      },
+    }]);
+    browser?.on('disconnected', () => {
+      this._setEntries(this._entries.filter(entry => entry.browser !== browser));
+    });
+    return info;
+  }
+
+  private _updateReport() {
+    // Clear the current line and move cursor to top of screen
+    process.stdout.write('\x1b[2J\x1b[H');
+    process.stdout.write(`Playwright Browser Server v${packageJSON.version}\n`);
+    process.stdout.write(`Listening on ${this._server.urlPrefix('human-readable')}\n\n`);
+
+    if (this._entries.length === 0) {
+      process.stdout.write('No browsers currently running\n');
+      return;
+    }
+
+    process.stdout.write('Running browsers:\n');
+    for (const entry of this._entries) {
+      const status = entry.browser ? 'running' : 'error';
+      const statusColor = entry.browser ? '\x1b[32m' : '\x1b[31m'; // green for running, red for error
+      process.stdout.write(`${statusColor}${entry.info.browserType}\x1b[0m (${entry.info.userDataDir}) - ${statusColor}${status}\x1b[0m\n`);
+      if (entry.info.error)
+        process.stdout.write(`  Error: ${entry.info.error}\n`);
+    }
+
+  }
+
+  private _setEntries(entries: BrowserEntry[]) {
+    this._entries = entries;
+    this._updateReport();
+  }
+
+  private _setupExitHandler() {
+    let isExiting = false;
+    const handleExit = async () => {
+      if (isExiting)
+        return;
+      isExiting = true;
+      setTimeout(() => process.exit(0), 15000);
+      for (const entry of this._entries)
+        await entry.browser?.close().catch(() => {});
+      process.exit(0);
+    };
+
+    process.stdin.on('close', handleExit);
+    process.on('SIGINT', handleExit);
+    process.on('SIGTERM', handleExit);
+  }
+}
+
+program
+    .name('browser-agent')
+    .option('-p, --port <port>', 'Port to listen on', '9224')
+    .action(async options => {
+      await main(options);
+    });
+
+void program.parseAsync(process.argv);
+
+async function main(options: { port: string }) {
+  const server = new BrowserServer();
+  await server.start(+options.port);
+}
+
+function readBody<T>(req: http.IncomingMessage): Promise<T> {
+  return new Promise((resolve, reject) => {
+    const chunks: Buffer[] = [];
+    req.on('data', (chunk: Buffer) => chunks.push(chunk));
+    req.on('end', () => resolve(JSON.parse(Buffer.concat(chunks).toString())));
+  });
+}
+
+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/cdpRelay.ts

@@ -0,0 +1,317 @@
+/**
+ * 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.
+ */
+
+/**
+ * Bridge Server - Standalone WebSocket server that bridges Playwright MCP and Chrome Extension
+ *
+ * Endpoints:
+ * - /cdp - Full CDP interface for Playwright MCP
+ * - /extension - Extension connection for chrome.debugger forwarding
+ */
+
+/* eslint-disable no-console */
+
+import { WebSocket, WebSocketServer } from 'ws';
+import http from 'node:http';
+import { EventEmitter } from 'node:events';
+import debug from 'debug';
+import { httpAddressToString } from './transport.js';
+
+const debugLogger = debug('pw:mcp:relay');
+
+const CDP_PATH = '/cdp';
+const EXTENSION_PATH = '/extension';
+
+export class CDPRelayServer extends EventEmitter {
+  private _wss: WebSocketServer;
+  private _playwrightSocket: WebSocket | null = null;
+  private _extensionSocket: WebSocket | null = null;
+  private _connectionInfo: {
+    targetInfo: any;
+    sessionId: string;
+  } | undefined;
+
+  constructor(server: http.Server) {
+    super();
+    this._wss = new WebSocketServer({ server });
+    this._wss.on('connection', this._onConnection.bind(this));
+  }
+
+  stop(): void {
+    this._playwrightSocket?.close();
+    this._extensionSocket?.close();
+  }
+
+  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 === CDP_PATH) {
+      this._handlePlaywrightConnection(ws);
+    } else if (url.pathname === EXTENSION_PATH) {
+      this._handleExtensionConnection(ws);
+    } else {
+      debugLogger(`Invalid path: ${url.pathname}`);
+      ws.close(4004, 'Invalid path');
+    }
+  }
+
+  /**
+   * Handle Playwright MCP connection - provides full CDP interface
+   */
+  private _handlePlaywrightConnection(ws: WebSocket): void {
+    if (this._playwrightSocket?.readyState === WebSocket.OPEN) {
+      debugLogger('Closing previous Playwright connection');
+      this._playwrightSocket.close(1000, 'New connection established');
+    }
+
+    this._playwrightSocket = ws;
+    debugLogger('Playwright MCP connected');
+
+    ws.on('message', data => {
+      try {
+        const message = JSON.parse(data.toString());
+        this._handlePlaywrightMessage(message);
+      } catch (error) {
+        debugLogger('Error parsing Playwright message:', error);
+      }
+    });
+
+    ws.on('close', () => {
+      if (this._playwrightSocket === ws)
+        this._playwrightSocket = null;
+
+      debugLogger('Playwright MCP disconnected');
+    });
+
+    ws.on('error', error => {
+      debugLogger('Playwright WebSocket error:', error);
+    });
+  }
+
+  /**
+   * Handle Extension connection - forwards to chrome.debugger
+   */
+  private _handleExtensionConnection(ws: WebSocket): void {
+    if (this._extensionSocket?.readyState === WebSocket.OPEN) {
+      debugLogger('Closing previous extension connection');
+      this._extensionSocket.close(1000, 'New connection established');
+    }
+
+    this._extensionSocket = ws;
+    debugLogger('Extension connected');
+
+    ws.on('message', data => {
+      try {
+        const message = JSON.parse(data.toString());
+        this._handleExtensionMessage(message);
+      } catch (error) {
+        debugLogger('Error parsing extension message:', error);
+      }
+    });
+
+    ws.on('close', () => {
+      if (this._extensionSocket === ws)
+        this._extensionSocket = null;
+
+      debugLogger('Extension disconnected');
+    });
+
+    ws.on('error', error => {
+      debugLogger('Extension WebSocket error:', error);
+    });
+  }
+
+  /**
+   * Handle messages from Playwright MCP
+   */
+  private _handlePlaywrightMessage(message: any): void {
+    debugLogger('← Playwright:', message.method || `response(${message.id})`);
+
+    // Handle Browser domain methods locally
+    if (message.method?.startsWith('Browser.')) {
+      this._handleBrowserDomainMethod(message);
+      return;
+    }
+
+    // Handle Target domain methods
+    if (message.method?.startsWith('Target.')) {
+      this._handleTargetDomainMethod(message);
+      return;
+    }
+
+    // Forward other commands to extension
+    if (message.method)
+      this._forwardToExtension(message);
+
+  }
+
+  /**
+   * Handle messages from Extension
+   */
+  private _handleExtensionMessage(message: any): void {
+    // Handle connection info from extension
+    if (message.type === 'connection_info') {
+      debugLogger('← Extension connected to tab:', message);
+      this._connectionInfo = {
+        targetInfo: message.targetInfo,
+        // Page sessionId that should be used by this connection.
+        sessionId: message.sessionId
+      };
+      return;
+    }
+
+    // CDP event from extension
+    debugLogger(`← Extension message: ${message.method ?? (message.id && `response(id=${message.id})`) ?? 'unknown'}`);
+    this._sendToPlaywright(message);
+  }
+
+  /**
+   * Handle Browser domain methods locally
+   */
+  private _handleBrowserDomainMethod(message: any): void {
+    switch (message.method) {
+      case 'Browser.getVersion':
+        this._sendToPlaywright({
+          id: message.id,
+          result: {
+            protocolVersion: '1.3',
+            product: 'Chrome/Extension-Bridge',
+            userAgent: 'CDP-Bridge-Server/1.0.0',
+          }
+        });
+        break;
+
+      case 'Browser.setDownloadBehavior':
+        this._sendToPlaywright({
+          id: message.id,
+          result: {}
+        });
+        break;
+
+      default:
+        // Forward unknown Browser methods to extension
+        this._forwardToExtension(message);
+    }
+  }
+
+  /**
+   * Handle Target domain methods
+   */
+  private _handleTargetDomainMethod(message: any): void {
+    switch (message.method) {
+      case 'Target.setAutoAttach':
+        // Simulate auto-attach behavior with real target info
+        if (this._connectionInfo && !message.sessionId) {
+          debugLogger('Simulating auto-attach for target:', JSON.stringify(message));
+          this._sendToPlaywright({
+            method: 'Target.attachedToTarget',
+            params: {
+              sessionId: this._connectionInfo.sessionId,
+              targetInfo: {
+                ...this._connectionInfo.targetInfo,
+                attached: true,
+              },
+              waitingForDebugger: false
+            }
+          });
+          this._sendToPlaywright({
+            id: message.id,
+            result: {}
+          });
+        } else {
+          this._forwardToExtension(message);
+        }
+        break;
+
+      case 'Target.getTargets':
+        const targetInfos = [];
+
+        if (this._connectionInfo) {
+          targetInfos.push({
+            ...this._connectionInfo.targetInfo,
+            attached: true,
+          });
+        }
+
+        this._sendToPlaywright({
+          id: message.id,
+          result: { targetInfos }
+        });
+        break;
+
+      default:
+        this._forwardToExtension(message);
+    }
+  }
+
+  /**
+   * Forward message to extension
+   */
+  private _forwardToExtension(message: any): void {
+    if (this._extensionSocket?.readyState === WebSocket.OPEN) {
+      debugLogger('→ Extension:', message.method || `command(${message.id})`);
+      this._extensionSocket.send(JSON.stringify(message));
+    } else {
+      debugLogger('Extension not connected, cannot forward message');
+      if (message.id) {
+        this._sendToPlaywright({
+          id: message.id,
+          error: { message: 'Extension not connected' }
+        });
+      }
+    }
+  }
+
+  /**
+   * Forward message to Playwright
+   */
+  private _sendToPlaywright(message: any): void {
+    if (this._playwrightSocket?.readyState === WebSocket.OPEN) {
+      debugLogger('→ Playwright:', JSON.stringify(message));
+      this._playwrightSocket.send(JSON.stringify(message));
+    }
+  }
+}
+
+export async function startCDPRelayServer(httpServer: http.Server) {
+  const wsAddress = httpAddressToString(httpServer.address()).replace(/^http/, 'ws');
+  const cdpRelayServer = new CDPRelayServer(httpServer);
+  process.on('exit', () => cdpRelayServer.stop());
+  // eslint-disable-next-line no-console
+  console.error(`CDP relay server started on ${wsAddress}${EXTENSION_PATH} - Connect to it using the browser extension.`);
+  const cdpEndpoint = `${wsAddress}${CDP_PATH}`;
+  return cdpEndpoint;
+}
+
+// CLI usage
+if (import.meta.url === `file://${process.argv[1]}`) {
+  const port = parseInt(process.argv[2], 10) || 9223;
+  const httpServer = http.createServer();
+  await new Promise<void>(resolve => httpServer.listen(port, resolve));
+  const server = new CDPRelayServer(httpServer);
+
+  console.error(`CDP Bridge Server listening on ws://localhost:${port}`);
+  console.error(`- Playwright MCP: ws://localhost:${port}${CDP_PATH}`);
+  console.error(`- Extension: ws://localhost:${port}${EXTENSION_PATH}`);
+
+  process.on('SIGINT', () => {
+    debugLogger('\nShutting down bridge server...');
+    server.stop();
+    process.exit(0);
+  });
+}

src/config.ts

@@ -0,0 +1,276 @@
+/**
+ * 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 os from 'os';
+import path from 'path';
+import { devices } from 'playwright';
+
+import type { Config as PublicConfig, ToolCapability } from '../config.js';
+import type { BrowserContextOptions, LaunchOptions } from 'playwright';
+import { sanitizeForFilePath } from './tools/utils.js';
+
+type Config = PublicConfig & {
+  /**
+   * TODO: Move to PublicConfig once we are ready to release this feature.
+   * Run server that is able to connect to the 'Playwright MCP' Chrome extension.
+   */
+  extension?: boolean;
+};
+
+export type CLIOptions = {
+  allowedOrigins?: string[];
+  blockedOrigins?: string[];
+  blockServiceWorkers?: boolean;
+  browser?: string;
+  browserAgent?: string;
+  caps?: string;
+  cdpEndpoint?: string;
+  config?: string;
+  device?: string;
+  executablePath?: string;
+  headless?: boolean;
+  host?: string;
+  ignoreHttpsErrors?: boolean;
+  isolated?: boolean;
+  imageResponses?: 'allow' | 'omit' | 'auto';
+  sandbox: boolean;
+  outputDir?: string;
+  port?: number;
+  proxyBypass?: string;
+  proxyServer?: string;
+  saveTrace?: boolean;
+  storageState?: string;
+  userAgent?: string;
+  userDataDir?: string;
+  viewportSize?: string;
+  vision?: boolean;
+  extension?: boolean;
+};
+
+const defaultConfig: FullConfig = {
+  browser: {
+    browserName: 'chromium',
+    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())),
+};
+
+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 resolveCLIConfig(cliOptions: CLIOptions): Promise<FullConfig> {
+  const configInFile = await loadConfig(cliOptions.config);
+  const cliOverrides = await configFromCLIOptions(cliOptions);
+  const result = mergeConfig(mergeConfig(defaultConfig, configInFile), cliOverrides);
+  // Derive artifact output directory from config.outputDir
+  if (result.saveTrace)
+    result.browser.launchOptions.tracesDir = path.join(result.outputDir, 'traces');
+  return result;
+}
+
+export function validateConfig(config: Config) {
+  if (config.extension) {
+    if (config.browser?.browserName !== 'chromium')
+      throw new Error('Extension mode is only supported for Chromium browsers.');
+  }
+}
+
+export async function configFromCLIOptions(cliOptions: CLIOptions): Promise<Config> {
+  let browserName: 'chromium' | 'firefox' | 'webkit' | undefined;
+  let channel: string | undefined;
+  switch (cliOptions.browser) {
+    case 'chrome':
+    case 'chrome-beta':
+    case 'chrome-canary':
+    case 'chrome-dev':
+    case 'chromium':
+    case 'msedge':
+    case 'msedge-beta':
+    case 'msedge-canary':
+    case 'msedge-dev':
+      browserName = 'chromium';
+      channel = cliOptions.browser;
+      break;
+    case 'firefox':
+      browserName = 'firefox';
+      break;
+    case 'webkit':
+      browserName = 'webkit';
+      break;
+  }
+
+  // Launch options
+  const launchOptions: LaunchOptions = {
+    channel,
+    executablePath: cliOptions.executablePath,
+    headless: cliOptions.headless,
+  };
+
+  // --no-sandbox was passed, disable the sandbox
+  if (!cliOptions.sandbox)
+    launchOptions.chromiumSandbox = false;
+
+  if (cliOptions.proxyServer) {
+    launchOptions.proxy = {
+      server: cliOptions.proxyServer
+    };
+    if (cliOptions.proxyBypass)
+      launchOptions.proxy.bypass = cliOptions.proxyBypass;
+  }
+
+  if (cliOptions.device && cliOptions.cdpEndpoint)
+    throw new Error('Device emulation is not supported with cdpEndpoint.');
+  if (cliOptions.device && cliOptions.extension)
+    throw new Error('Device emulation is not supported with extension mode.');
+
+  // 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: {
+      browserAgent: cliOptions.browserAgent ?? process.env.PW_BROWSER_AGENT,
+      browserName,
+      isolated: cliOptions.isolated,
+      userDataDir: cliOptions.userDataDir,
+      launchOptions,
+      contextOptions,
+      cdpEndpoint: cliOptions.cdpEndpoint,
+    },
+    server: {
+      port: cliOptions.port,
+      host: cliOptions.host,
+    },
+    capabilities: cliOptions.caps?.split(',').map((c: string) => c.trim() as ToolCapability),
+    vision: !!cliOptions.vision,
+    extension: !!cliOptions.extension,
+    network: {
+      allowedOrigins: cliOptions.allowedOrigins,
+      blockedOrigins: cliOptions.blockedOrigins,
+    },
+    saveTrace: cliOptions.saveTrace,
+    outputDir: cliOptions.outputDir,
+    imageResponses: cliOptions.imageResponses,
+  };
+
+  return result;
+}
+
+async function loadConfig(configFile: string | undefined): Promise<Config> {
+  if (!configFile)
+    return {};
+
+  try {
+    return JSON.parse(await fs.promises.readFile(configFile, 'utf8'));
+  } catch (error) {
+    throw new Error(`Failed to load config file: ${configFile}, ${error}`);
+  }
+}
+
+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(config.outputDir, fileName);
+}
+
+function pickDefined<T extends object>(obj: T | undefined): Partial<T> {
+  return Object.fromEntries(
+      Object.entries(obj ?? {}).filter(([_, v]) => v !== undefined)
+  ) as Partial<T>;
+}
+
+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),
+      ...{ assistantMode: true },
+    },
+    contextOptions: {
+      ...pickDefined(base.browser?.contextOptions),
+      ...pickDefined(overrides.browser?.contextOptions),
+    },
+  };
+
+  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;
+}

src/connection.ts

@@ -0,0 +1,98 @@
+/**
+ * Copyright (c) Microsoft Corporation.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+import { Server as McpServer } from '@modelcontextprotocol/sdk/server/index.js';
+import { CallToolRequestSchema, ListToolsRequestSchema, Tool as McpTool } from '@modelcontextprotocol/sdk/types.js';
+import { zodToJsonSchema } from 'zod-to-json-schema';
+
+import { Context } from './context.js';
+import { snapshotTools, visionTools } from './tools.js';
+import { packageJSON } from './package.js';
+
+import { FullConfig, validateConfig } from './config.js';
+
+import type { BrowserContextFactory } from './browserContextFactory.js';
+
+export function createConnection(config: FullConfig, browserContextFactory: BrowserContextFactory): Connection {
+  const allTools = config.vision ? visionTools : snapshotTools;
+  const tools = allTools.filter(tool => !config.capabilities || tool.capability === 'core' || config.capabilities.includes(tool.capability));
+  validateConfig(config);
+  const context = new Context(tools, config, browserContextFactory);
+  const server = new McpServer({ name: 'Playwright', version: packageJSON.version }, {
+    capabilities: {
+      tools: {},
+    }
+  });
+
+  server.setRequestHandler(ListToolsRequestSchema, async () => {
+    return {
+      tools: tools.map(tool => ({
+        name: tool.schema.name,
+        description: tool.schema.description,
+        inputSchema: zodToJsonSchema(tool.schema.inputSchema),
+        annotations: {
+          title: tool.schema.title,
+          readOnlyHint: tool.schema.type === 'readOnly',
+          destructiveHint: tool.schema.type === 'destructive',
+          openWorldHint: true,
+        },
+      })) as McpTool[],
+    };
+  });
+
+  server.setRequestHandler(CallToolRequestSchema, async request => {
+    const errorResult = (...messages: string[]) => ({
+      content: [{ type: 'text', text: messages.join('\n') }],
+      isError: true,
+    });
+    const tool = tools.find(tool => tool.schema.name === request.params.name);
+    if (!tool)
+      return errorResult(`Tool "${request.params.name}" not found`);
+
+
+    const modalStates = context.modalStates().map(state => state.type);
+    if (tool.clearsModalState && !modalStates.includes(tool.clearsModalState))
+      return errorResult(`The tool "${request.params.name}" can only be used when there is related modal state present.`, ...context.modalStatesMarkdown());
+    if (!tool.clearsModalState && modalStates.length)
+      return errorResult(`Tool "${request.params.name}" does not handle the modal state.`, ...context.modalStatesMarkdown());
+
+    try {
+      return await context.run(tool, request.params.arguments);
+    } catch (error) {
+      return errorResult(String(error));
+    }
+  });
+
+  return new Connection(server, context);
+}
+
+export class Connection {
+  readonly server: McpServer;
+  readonly context: Context;
+
+  constructor(server: McpServer, context: Context) {
+    this.server = server;
+    this.context = context;
+    this.server.oninitialized = () => {
+      this.context.clientVersion = this.server.getClientVersion();
+    };
+  }
+
+  async close() {
+    await this.server.close();
+    await this.context.close();
+  }
+}

src/context.ts

@@ -14,52 +14,87 @@
  * limitations under the License.
  */
 
+import debug from 'debug';
 import * as playwright from 'playwright';
-import yaml from 'yaml';
 
-import { waitForCompletion } from './tools/utils';
-import { ToolResult } from './tools/tool';
+import { callOnPageNoTrace, waitForCompletion } from './tools/utils.js';
+import { ManualPromise } from './manualPromise.js';
+import { Tab } from './tab.js';
+import { outputFile } from './config.js';
 
-export type ContextOptions = {
-  browserName?: 'chromium' | 'firefox' | 'webkit';
-  userDataDir: string;
-  launchOptions?: playwright.LaunchOptions;
-  cdpEndpoint?: string;
-  remoteEndpoint?: string;
+import type { ImageContent, TextContent } from '@modelcontextprotocol/sdk/types.js';
+import type { ModalState, Tool, ToolActionResult } from './tools/tool.js';
+import type { FullConfig } from './config.js';
+import type { BrowserContextFactory } from './browserContextFactory.js';
+
+type PendingAction = {
+  dialogShown: ManualPromise<void>;
 };
 
-type PageOrFrameLocator = playwright.Page | playwright.FrameLocator;
-
-type RunOptions = {
-  captureSnapshot?: boolean;
-  waitForCompletion?: boolean;
-  status?: string;
-  noClearFileChooser?: boolean;
-};
+const testDebug = debug('pw:mcp:test');
 
 export class Context {
-  readonly options: ContextOptions;
-  private _browser: playwright.Browser | undefined;
-  private _browserContext: playwright.BrowserContext | undefined;
+  readonly tools: Tool[];
+  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(options: ContextOptions) {
-    this.options = options;
+  constructor(tools: Tool[], config: FullConfig, browserContextFactory: BrowserContextFactory) {
+    this.tools = tools;
+    this.config = config;
+    this._browserContextFactory = browserContextFactory;
+    testDebug('create context');
+  }
+
+  clientSupportsImages(): boolean {
+    if (this.config.imageResponses === 'allow')
+      return true;
+    if (this.config.imageResponses === 'omit')
+      return false;
+    return !this.clientVersion?.name.includes('cursor');
+  }
+
+  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;
   }
 
   tabs(): Tab[] {
     return this._tabs;
   }
 
-  currentTab(): Tab {
+  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 current snapshot available. Capture a snapshot or navigate to a new location 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;
@@ -71,19 +106,19 @@ export class Context {
   }
 
   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 listTabs(): Promise<string> {
+  async listTabsMarkdown(): Promise<string> {
     if (!this._tabs.length)
-      return 'No tabs open';
-    const lines: string[] = ['Open tabs:'];
+      return '### No tabs open';
+    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})`);
@@ -92,9 +127,147 @@ export class Context {
   }
 
   async closeTab(index: number | undefined) {
-    const tab = index === undefined ? this.currentTab() : this._tabs[index - 1];
-    await tab.page.close();
-    return await this.listTabs();
+    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, 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.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 new Promise(f => setTimeout(f, time));
+      return;
+    }
+
+    await callOnPageNoTrace(this._currentTab.page, page => {
+      return page.evaluate(() => new Promise(f => setTimeout(f, 1000)));
+    });
+  }
+
+  private async _raceAgainstModalDialogs(action: () => Promise<ToolActionResult>): Promise<ToolActionResult> {
+    this._pendingAction = {
+      dialogShown: new ManualPromise(),
+    };
+
+    let result: ToolActionResult | undefined;
+    try {
+      await Promise.race([
+        action().then(r => result = r),
+        this._pendingAction.dialogShown,
+      ]);
+    } finally {
+      this._pendingAction = undefined;
+    }
+    return result;
+  }
+
+  private _javaScriptBlocked(): boolean {
+    return this._modalStates.some(state => state.type === 'dialog');
+  }
+
+  dialogShown(tab: Tab, dialog: playwright.Dialog) {
+    this.setModalState({
+      type: 'dialog',
+      description: `"${dialog.type()}" dialog with message "${dialog.message()}"`,
+      dialog,
+    }, tab);
+    this._pendingAction?.dialogShown.resolve();
+  }
+
+  async downloadStarted(tab: Tab, download: playwright.Download) {
+    const entry = {
+      download,
+      finished: false,
+      outputFile: await outputFile(this.config, download.suggestedFilename())
+    };
+    this._downloads.push(entry);
+    await download.saveAs(entry.outputFile);
+    entry.finished = true;
   }
 
   private _onPageCreated(page: playwright.Page) {
@@ -105,6 +278,7 @@ export class Context {
   }
 
   private _onPageClosed(tab: Tab) {
+    this._modalStates = this._modalStates.filter(state => state.tab !== tab);
     const index = this._tabs.indexOf(tab);
     if (index === -1)
       return;
@@ -112,250 +286,66 @@ export class Context {
 
     if (this._currentTab === tab)
       this._currentTab = this._tabs[Math.min(index, this._tabs.length - 1)];
-    const browser = this._browser;
-    if (this._browserContext && !this._tabs.length) {
-      void this._browserContext.close().then(() => browser?.close()).catch(() => {});
-      this._browser = undefined;
-      this._browserContext = undefined;
-    }
+    if (!this._tabs.length)
+      void this.close();
   }
 
   async close() {
-    if (!this._browserContext)
+    if (!this._browserContextPromise)
       return;
-    await this._browserContext.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));
-    }
-    return this._browserContext;
-  }
+    testDebug('close context');
 
-  private async _createBrowserContext(): Promise<{ browser?: playwright.Browser, browserContext: playwright.BrowserContext }> {
-    if (this.options.remoteEndpoint) {
-      const url = new URL(this.options.remoteEndpoint);
-      if (this.options.browserName)
-        url.searchParams.set('browser', this.options.browserName);
-      if (this.options.launchOptions)
-        url.searchParams.set('launch-options', JSON.stringify(this.options.launchOptions));
-      const browser = await playwright[this.options.browserName ?? 'chromium'].connect(String(url));
-      const browserContext = await browser.newContext();
-      return { browser, browserContext };
-    }
+    const promise = this._browserContextPromise;
+    this._browserContextPromise = undefined;
 
-    if (this.options.cdpEndpoint) {
-      const browser = await playwright.chromium.connectOverCDP(this.options.cdpEndpoint);
-      const browserContext = browser.contexts()[0];
-      return { browser, browserContext };
-    }
-
-    const browserContext = await this._launchPersistentContext();
-    return { browserContext };
-  }
-
-  private async _launchPersistentContext(): Promise<playwright.BrowserContext> {
-    try {
-      const browserType = this.options.browserName ? playwright[this.options.browserName] : playwright.chromium;
-      return await browserType.launchPersistentContext(this.options.userDataDir, this.options.launchOptions);
-    } 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;
-    }
-  }
-}
-
-class Tab {
-  readonly context: Context;
-  readonly page: playwright.Page;
-  private _console: playwright.ConsoleMessage[] = [];
-  private _fileChooser: playwright.FileChooser | undefined;
-  private _snapshot: PageSnapshot | undefined;
-  private _onPageClose: (tab: Tab) => void;
-
-  constructor(context: Context, page: playwright.Page, onPageClose: (tab: Tab) => void) {
-    this.context = context;
-    this.page = page;
-    this._onPageClose = onPageClose;
-    page.on('console', event => this._console.push(event));
-    page.on('framenavigated', frame => {
-      if (!frame.parentFrame())
-        this._console.length = 0;
-    });
-    page.on('close', () => this._onClose());
-    page.on('filechooser', chooser => this._fileChooser = chooser);
-    page.setDefaultNavigationTimeout(60000);
-    page.setDefaultTimeout(5000);
-  }
-
-  private _onClose() {
-    this._fileChooser = undefined;
-    this._console.length = 0;
-    this._onPageClose(this);
-  }
-
-  async navigate(url: string) {
-    await this.page.goto(url, { waitUntil: 'domcontentloaded' });
-    // Cap load event to 5 seconds, the page is operational at this point.
-    await this.page.waitForLoadState('load', { timeout: 5000 }).catch(() => {});
-  }
-
-  async run(callback: (tab: Tab) => Promise<void>, options?: RunOptions): Promise<ToolResult> {
-    try {
-      if (!options?.noClearFileChooser)
-        this._fileChooser = undefined;
-      if (options?.waitForCompletion)
-        await waitForCompletion(this.page, () => callback(this));
-      else
-        await callback(this);
-    } finally {
-      if (options?.captureSnapshot)
-        this._snapshot = await PageSnapshot.create(this.page);
-    }
-    const tabList = this.context.tabs().length > 1 ? await this.context.listTabs() + '\n\nCurrent tab:' + '\n' : '';
-    const snapshot = this._snapshot?.text({ status: options?.status, hasFileChooser: !!this._fileChooser }) ?? options?.status ?? '';
-    return {
-      content: [{
-        type: 'text',
-        text: tabList + snapshot,
-      }],
-    };
-  }
-
-  async runAndWait(callback: (tab: Tab) => Promise<void>, options?: RunOptions): Promise<ToolResult> {
-    return await this.run(callback, {
-      waitForCompletion: true,
-      ...options,
+    await promise.then(async ({ browserContext, close }) => {
+      if (this.config.saveTrace)
+        await browserContext.tracing.stop();
+      await close();
     });
   }
 
-  async runAndWaitWithSnapshot(callback: (snapshot: PageSnapshot) => Promise<void>, options?: RunOptions): Promise<ToolResult> {
-    return await this.run(tab => callback(tab.lastSnapshot()), {
-      captureSnapshot: true,
-      waitForCompletion: true,
-      ...options,
-    });
+  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'));
+    }
   }
 
-  lastSnapshot(): PageSnapshot {
-    if (!this._snapshot)
-      throw new Error('No snapshot available');
-    return this._snapshot;
+  private _ensureBrowserContext() {
+    if (!this._browserContextPromise) {
+      this._browserContextPromise = this._setupBrowserContext();
+      this._browserContextPromise.catch(() => {
+        this._browserContextPromise = undefined;
+      });
+    }
+    return this._browserContextPromise;
   }
 
-  async console(): Promise<playwright.ConsoleMessage[]> {
-    return this._console;
-  }
-
-  async submitFileChooser(paths: string[]) {
-    if (!this._fileChooser)
-      throw new Error('No file chooser visible');
-    await this._fileChooser.setFiles(paths);
-    this._fileChooser = undefined;
-  }
-}
-
-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(options?: { status?: string, hasFileChooser?: boolean }): string {
-    const results: string[] = [];
-    if (options?.status) {
-      results.push(options.status);
-      results.push('');
-    }
-    if (options?.hasFileChooser) {
-      results.push('- There is a file chooser visible that requires browser_file_upload to be called');
-      results.push('');
-    }
-    results.push(this._text);
-    return results.join('\n');
-  }
-
-  private async _build(page: playwright.Page) {
-    const yamlDocument = await this._snapshotFrame(page);
-    const lines = [];
-    lines.push(
-        `- Page URL: ${page.url()}`,
-        `- Page Title: ${await page.title()}`
-    );
-    lines.push(
-        `- Page Snapshot`,
-        '```yaml',
-        yamlDocument.toString().trim(),
-        '```',
-        ''
-    );
-    this._text = lines.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 });
-    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}`);
+  private async _setupBrowserContext(): Promise<{ browserContext: playwright.BrowserContext, close: () => Promise<void> }> {
+    // TODO: move to the browser context factory to make it based on isolation mode.
+    const result = await this._browserContextFactory.createContext();
+    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,
+      });
+    }
+    return result;
   }
 }

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

src/index.ts

@@ -14,71 +14,33 @@
  * limitations under the License.
  */
 
-import { createServerWithTools } from './server';
-import common from './tools/common';
-import files from './tools/files';
-import install from './tools/install';
-import keyboard from './tools/keyboard';
-import navigate from './tools/navigate';
-import pdf from './tools/pdf';
-import snapshot from './tools/snapshot';
-import tabs from './tools/tabs';
-import screen from './tools/screen';
-import { console as consoleResource } from './resources/console';
+import { createConnection as createConnectionImpl } from './connection.js';
+import type { Connection } from '../index.js';
+import { resolveConfig } from './config.js';
+import { contextFactory } from './browserContextFactory.js';
 
-import type { Tool, ToolCapability } from './tools/tool';
-import type { Resource } from './resources/resource';
-import type { Server } from '@modelcontextprotocol/sdk/server/index.js';
-import type { LaunchOptions } from 'playwright';
+import type { Config } from '../config.js';
+import type { BrowserContext } from 'playwright';
+import type { BrowserContextFactory } from './browserContextFactory.js';
 
-const snapshotTools: Tool[] = [
-  ...common(true),
-  ...files(true),
-  ...install,
-  ...keyboard(true),
-  ...navigate(true),
-  ...pdf,
-  ...snapshot,
-  ...tabs(true),
-];
-
-const screenshotTools: Tool[] = [
-  ...common(false),
-  ...files(false),
-  ...install,
-  ...keyboard(false),
-  ...navigate(false),
-  ...pdf,
-  ...screen,
-  ...tabs(false),
-];
-
-const resources: Resource[] = [
-  consoleResource,
-];
-
-type Options = {
-  browserName?: 'chromium' | 'firefox' | 'webkit';
-  userDataDir?: string;
-  launchOptions?: LaunchOptions;
-  cdpEndpoint?: string;
-  vision?: boolean;
-  capabilities?: ToolCapability[];
-};
-
-const packageJSON = require('../package.json');
-
-export function createServer(options?: Options): Server {
-  const allTools = options?.vision ? screenshotTools : snapshotTools;
-  const tools = allTools.filter(tool => !options?.capabilities || tool.capability === 'core' || options.capabilities.includes(tool.capability));
-  return createServerWithTools({
-    name: 'Playwright',
-    version: packageJSON.version,
-    tools,
-    resources,
-    browserName: options?.browserName,
-    userDataDir: options?.userDataDir ?? '',
-    launchOptions: options?.launchOptions,
-    cdpEndpoint: options?.cdpEndpoint,
-  });
+export async function createConnection(userConfig: Config = {}, contextGetter?: () => Promise<BrowserContext>): Promise<Connection> {
+  const config = await resolveConfig(userConfig);
+  const factory = contextGetter ? new SimpleBrowserContextFactory(contextGetter) : contextFactory(config.browser);
+  return createConnectionImpl(config, factory);
+}
+
+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/javascript.ts

@@ -0,0 +1,53 @@
+/**
+ * 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.
+ */
+
+// adapted from:
+// - https://github.com/microsoft/playwright/blob/76ee48dc9d4034536e3ec5b2c7ce8be3b79418a8/packages/playwright-core/src/utils/isomorphic/stringUtils.ts
+// - https://github.com/microsoft/playwright/blob/76ee48dc9d4034536e3ec5b2c7ce8be3b79418a8/packages/playwright-core/src/server/codegen/javascript.ts
+
+// NOTE: this function should not be used to escape any selectors.
+export function escapeWithQuotes(text: string, char: string = '\'') {
+  const stringified = JSON.stringify(text);
+  const escapedText = stringified.substring(1, stringified.length - 1).replace(/\\"/g, '"');
+  if (char === '\'')
+    return char + escapedText.replace(/[']/g, '\\\'') + char;
+  if (char === '"')
+    return char + escapedText.replace(/["]/g, '\\"') + char;
+  if (char === '`')
+    return char + escapedText.replace(/[`]/g, '`') + char;
+  throw new Error('Invalid escape char');
+}
+
+export function quote(text: string) {
+  return escapeWithQuotes(text, '\'');
+}
+
+export function formatObject(value: any, indent = '  '): string {
+  if (typeof value === 'string')
+    return quote(value);
+  if (Array.isArray(value))
+    return `[${value.map(o => formatObject(o)).join(', ')}]`;
+  if (typeof value === 'object') {
+    const keys = Object.keys(value).filter(key => value[key] !== undefined).sort();
+    if (!keys.length)
+      return '{}';
+    const tokens: string[] = [];
+    for (const key of keys)
+      tokens.push(`${key}: ${formatObject(value[key])}`);
+    return `{\n${indent}${tokens.join(`,\n${indent}`)}\n}`;
+  }
+  return String(value);
+}

src/manualPromise.ts

@@ -0,0 +1,127 @@
+/**
+ * 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 class ManualPromise<T = void> extends Promise<T> {
+  private _resolve!: (t: T) => void;
+  private _reject!: (e: Error) => void;
+  private _isDone: boolean;
+
+  constructor() {
+    let resolve: (t: T) => void;
+    let reject: (e: Error) => void;
+    super((f, r) => {
+      resolve = f;
+      reject = r;
+    });
+    this._isDone = false;
+    this._resolve = resolve!;
+    this._reject = reject!;
+  }
+
+  isDone() {
+    return this._isDone;
+  }
+
+  resolve(t: T) {
+    this._isDone = true;
+    this._resolve(t);
+  }
+
+  reject(e: Error) {
+    this._isDone = true;
+    this._reject(e);
+  }
+
+  static override get [Symbol.species]() {
+    return Promise;
+  }
+
+  override get [Symbol.toStringTag]() {
+    return 'ManualPromise';
+  }
+}
+
+export class LongStandingScope {
+  private _terminateError: Error | undefined;
+  private _closeError: Error | undefined;
+  private _terminatePromises = new Map<ManualPromise<Error>, string[]>();
+  private _isClosed = false;
+
+  reject(error: Error) {
+    this._isClosed = true;
+    this._terminateError = error;
+    for (const p of this._terminatePromises.keys())
+      p.resolve(error);
+  }
+
+  close(error: Error) {
+    this._isClosed = true;
+    this._closeError = error;
+    for (const [p, frames] of this._terminatePromises)
+      p.resolve(cloneError(error, frames));
+  }
+
+  isClosed() {
+    return this._isClosed;
+  }
+
+  static async raceMultiple<T>(scopes: LongStandingScope[], promise: Promise<T>): Promise<T> {
+    return Promise.race(scopes.map(s => s.race(promise)));
+  }
+
+  async race<T>(promise: Promise<T> | Promise<T>[]): Promise<T> {
+    return this._race(Array.isArray(promise) ? promise : [promise], false) as Promise<T>;
+  }
+
+  async safeRace<T>(promise: Promise<T>, defaultValue?: T): Promise<T> {
+    return this._race([promise], true, defaultValue);
+  }
+
+  private async _race(promises: Promise<any>[], safe: boolean, defaultValue?: any): Promise<any> {
+    const terminatePromise = new ManualPromise<Error>();
+    const frames = captureRawStack();
+    if (this._terminateError)
+      terminatePromise.resolve(this._terminateError);
+    if (this._closeError)
+      terminatePromise.resolve(cloneError(this._closeError, frames));
+    this._terminatePromises.set(terminatePromise, frames);
+    try {
+      return await Promise.race([
+        terminatePromise.then(e => safe ? defaultValue : Promise.reject(e)),
+        ...promises
+      ]);
+    } finally {
+      this._terminatePromises.delete(terminatePromise);
+    }
+  }
+}
+
+function cloneError(error: Error, frames: string[]) {
+  const clone = new Error();
+  clone.name = error.name;
+  clone.message = error.message;
+  clone.stack = [error.name + ':' + error.message, ...frames].join('\n');
+  return clone;
+}
+
+function captureRawStack(): string[] {
+  const stackTraceLimit = Error.stackTraceLimit;
+  Error.stackTraceLimit = 50;
+  const error = new Error();
+  const stack = error.stack || '';
+  Error.stackTraceLimit = stackTraceLimit;
+  return stack.split('\n');
+}

src/package.ts

@@ -14,22 +14,9 @@
  * limitations under the License.
  */
 
-import type { Resource } from './resource';
+import fs from 'node:fs';
+import url from 'node:url';
+import path from 'node:path';
 
-export const console: Resource = {
-  schema: {
-    uri: 'browser://console',
-    name: 'Page console',
-    mimeType: 'text/plain',
-  },
-
-  read: async (context, uri) => {
-    const messages = await context.currentTab().console();
-    const log = messages.map(message => `[${message.type().toUpperCase()}] ${message.text()}`).join('\n');
-    return [{
-      uri,
-      mimeType: 'text/plain',
-      text: log
-    }];
-  },
-};
+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

@@ -0,0 +1,55 @@
+/**
+ * Copyright (c) Microsoft Corporation.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+import * as playwright from 'playwright';
+import { callOnPageNoTrace } from './tools/utils.js';
+
+type PageEx = playwright.Page & {
+  _snapshotForAI: () => Promise<string>;
+};
+
+export class PageSnapshot {
+  private _page: playwright.Page;
+  private _text!: string;
+
+  constructor(page: playwright.Page) {
+    this._page = page;
+  }
+
+  static async create(page: playwright.Page): Promise<PageSnapshot> {
+    const snapshot = new PageSnapshot(page);
+    await snapshot._build();
+    return snapshot;
+  }
+
+  text(): string {
+    return this._text;
+  }
+
+  private async _build() {
+    const snapshot = await callOnPageNoTrace(this._page, page => (page as PageEx)._snapshotForAI());
+    this._text = [
+      `- Page Snapshot`,
+      '```yaml',
+      snapshot,
+      '```',
+    ].join('\n');
+  }
+
+  refLocator(params: { element: string, ref: string }): playwright.Locator {
+    return this._page.locator(`aria-ref=${params.ref}`).describe(params.element);
+  }
+}

src/program.ts

@@ -14,177 +14,75 @@
  * limitations under the License.
  */
 
-import http from 'http';
-import fs from 'fs';
-import os from 'os';
-import path from 'path';
+import { Option, program } from 'commander';
+// @ts-ignore
+import { startTraceViewerServer } from 'playwright-core/lib/server';
 
-import { program } from 'commander';
-import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
-import { SSEServerTransport } from '@modelcontextprotocol/sdk/server/sse.js';
-
-
-import { createServer } from './index';
-import { ServerList } from './server';
-
-import type { LaunchOptions } from 'playwright';
-import assert from 'assert';
-import { ToolCapability } from './tools/tool';
-
-const packageJSON = require('../package.json');
+import { startHttpServer, startHttpTransport, startStdioTransport } from './transport.js';
+import { resolveCLIConfig } from './config.js';
+import { Server } from './server.js';
+import { packageJSON } from './package.js';
+import { startCDPRelayServer } from './cdpRelay.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('--browser-agent <endpoint>', 'Use browser agent (experimental).')
+    .option('--caps <caps>', 'comma-separated list of capabilities to enable, possible values: tabs, pdf, history, wait, files, install. Default is all.')
     .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('--port <port>', 'Port to listen on for SSE transport.')
-    .option('--user-data-dir <path>', 'Path to the user data directory')
+    .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", "omit", or "auto". Defaults to "auto", which sends images if the client can display them.')
+    .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-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"')
     .option('--vision', 'Run server that uses screenshots (Aria snapshots are used by default)')
+    .addOption(new Option('--extension', 'Allow connecting to a running browser instance (Edge/Chrome only). Requires the \'Playwright MCP\' browser extension to be installed.').hideHelp())
     .action(async options => {
-      let browserName: 'chromium' | 'firefox' | 'webkit';
-      let channel: string | undefined;
-      switch (options.browser) {
-        case 'chrome':
-        case 'chrome-beta':
-        case 'chrome-canary':
-        case 'chrome-dev':
-        case 'msedge':
-        case 'msedge-beta':
-        case 'msedge-canary':
-        case 'msedge-dev':
-          browserName = 'chromium';
-          channel = options.browser;
-          break;
-        case 'chromium':
-          browserName = 'chromium';
-          break;
-        case 'firefox':
-          browserName = 'firefox';
-          break;
-        case 'webkit':
-          browserName = 'webkit';
-          break;
-        default:
-          browserName = 'chromium';
-          channel = 'chrome';
+      const config = await resolveCLIConfig(options);
+      const httpServer = config.server.port !== undefined ? await startHttpServer(config.server) : undefined;
+      if (config.extension) {
+        if (!httpServer)
+          throw new Error('--port parameter is required for extension mode');
+        // Point CDP endpoint to the relay server.
+        config.browser.cdpEndpoint = await startCDPRelayServer(httpServer);
       }
 
-      const launchOptions: LaunchOptions = {
-        headless: options.headless ?? !process.env.DISPLAY,
-        channel,
-        executablePath: options.executablePath,
-      };
+      const server = new Server(config);
+      server.setupExitWatchdog();
 
-      const userDataDir = options.userDataDir ?? await createUserDataDir(browserName);
+      if (httpServer)
+        await startHttpTransport(httpServer, server);
+      else
+        await startStdioTransport(server);
 
-      const serverList = new ServerList(() => createServer({
-        browserName,
-        userDataDir,
-        launchOptions,
-        vision: !!options.vision,
-        cdpEndpoint: options.cdpEndpoint,
-        capabilities: options.caps?.split(',').map((c: string) => c.trim() as ToolCapability),
-      }));
-      setupExitWatchdog(serverList);
-
-      if (options.port) {
-        startSSEServer(+options.port, serverList);
-      } else {
-        const server = await serverList.create();
-        await server.connect(new StdioServerTransport());
+      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) {
-  const handleExit = async () => {
-    setTimeout(() => process.exit(0), 15000);
-    await serverList.closeAll();
-    process.exit(0);
-  };
-
-  process.stdin.on('close', handleExit);
-  process.on('SIGINT', handleExit);
-  process.on('SIGTERM', handleExit);
+function semicolonSeparatedList(value: string): string[] {
+  return value.split(';').map(v => v.trim());
 }
 
-program.parse(process.argv);
-
-async function createUserDataDir(browserName: 'chromium' | 'firefox' | 'webkit') {
-  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-${browserName}-profile`);
-  await fs.promises.mkdir(result, { recursive: true });
-  return result;
-}
-
-async function startSSEServer(port: number, serverList: ServerList) {
-  const sessions = new Map<string, SSEServerTransport>();
-  const httpServer = http.createServer(async (req, res) => {
-    if (req.method === 'POST') {
-      const searchParams = new URL(`http://localhost${req.url}`).searchParams;
-      const sessionId = searchParams.get('sessionId');
-      if (!sessionId) {
-        res.statusCode = 400;
-        res.end('Missing sessionId');
-        return;
-      }
-      const transport = sessions.get(sessionId);
-      if (!transport) {
-        res.statusCode = 404;
-        res.end('Session not found');
-        return;
-      }
-
-      await transport.handlePostMessage(req, res);
-      return;
-    } 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 => console.error(e));
-      });
-      await server.connect(transport);
-      return;
-    } else {
-      res.statusCode = 405;
-      res.end('Method not allowed');
-    }
-  });
-
-  httpServer.listen(port, () => {
-    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}`;
-    }
-    console.log(`Listening on ${url}`);
-    console.log('Put this in your client config:');
-    console.log(JSON.stringify({
-      'mcpServers': {
-        'playwright': {
-          'url': `${url}/sse`
-        }
-      }
-    }, undefined, 2));
-  });
-}
+void program.parseAsync(process.argv);

src/resources/resource.ts

@@ -14,7 +14,7 @@
  * limitations under the License.
  */
 
-import type { Context } from '../context';
+import type { Context } from '../context.js';
 
 export type ResourceSchema = {
   uri: string;

src/server.ts

@@ -14,101 +14,46 @@
  * limitations under the License.
  */
 
-import { Server } from '@modelcontextprotocol/sdk/server/index.js';
-import { CallToolRequestSchema, ListResourcesRequestSchema, ListToolsRequestSchema, ReadResourceRequestSchema } from '@modelcontextprotocol/sdk/types.js';
+import { createConnection } from './connection.js';
+import { contextFactory } from './browserContextFactory.js';
 
-import { Context } from './context';
+import type { FullConfig } from './config.js';
+import type { Connection } from './connection.js';
+import type { Transport } from '@modelcontextprotocol/sdk/shared/transport.js';
+import type { BrowserContextFactory } from './browserContextFactory.js';
 
-import type { Tool } from './tools/tool';
-import type { Resource } from './resources/resource';
-import type { ContextOptions } from './context';
+export class Server {
+  readonly config: FullConfig;
+  private _connectionList: Connection[] = [];
+  private _browserConfig: FullConfig['browser'];
+  private _contextFactory: BrowserContextFactory;
 
-type Options = ContextOptions & {
-  name: string;
-  version: string;
-  tools: Tool[];
-  resources: Resource[],
-};
-
-export function createServerWithTools(options: Options): Server {
-  const { name, version, tools, resources } = options;
-  const context = new Context(options);
-  const server = new Server({ name, version }, {
-    capabilities: {
-      tools: {},
-      resources: {},
-    }
-  });
-
-  server.setRequestHandler(ListToolsRequestSchema, async () => {
-    return { tools: tools.map(tool => tool.schema) };
-  });
-
-  server.setRequestHandler(ListResourcesRequestSchema, async () => {
-    return { resources: resources.map(resource => resource.schema) };
-  });
-
-  server.setRequestHandler(CallToolRequestSchema, async request => {
-    const tool = tools.find(tool => tool.schema.name === request.params.name);
-    if (!tool) {
-      return {
-        content: [{ type: 'text', text: `Tool "${request.params.name}" not found` }],
-        isError: true,
-      };
-    }
-
-    try {
-      const result = await tool.handle(context, request.params.arguments);
-      return result;
-    } catch (error) {
-      return {
-        content: [{ type: 'text', text: String(error) }],
-        isError: true,
-      };
-    }
-  });
-
-  server.setRequestHandler(ReadResourceRequestSchema, async request => {
-    const resource = resources.find(resource => resource.schema.uri === request.params.uri);
-    if (!resource)
-      return { contents: [] };
-
-    const contents = await resource.read(context, request.params.uri);
-    return { contents };
-  });
-
-  const oldClose = server.close.bind(server);
-
-  server.close = async () => {
-    await oldClose();
-    await context.close();
-  };
-
-  return server;
-}
-
-export class ServerList {
-  private _servers: Server[] = [];
-  private _serverFactory: () => Server;
-
-  constructor(serverFactory: () => Server) {
-    this._serverFactory = serverFactory;
+  constructor(config: FullConfig) {
+    this.config = config;
+    this._browserConfig = config.browser;
+    this._contextFactory = contextFactory(this._browserConfig);
   }
 
-  async create() {
-    const server = this._serverFactory();
-    this._servers.push(server);
-    return server;
+  async createConnection(transport: Transport): Promise<Connection> {
+    const connection = createConnection(this.config, this._contextFactory);
+    this._connectionList.push(connection);
+    await connection.server.connect(transport);
+    return connection;
   }
 
-  async close(server: Server) {
-    const index = this._servers.indexOf(server);
-    if (index !== -1)
-      this._servers.splice(index, 1);
-    await server.close();
-  }
+  setupExitWatchdog() {
+    let isExiting = false;
+    const handleExit = async () => {
+      if (isExiting)
+        return;
+      isExiting = true;
+      setTimeout(() => process.exit(0), 15000);
+      await Promise.all(this._connectionList.map(connection => connection.close()));
+      process.exit(0);
+    };
 
-  async closeAll() {
-    await Promise.all(this._servers.map(server => server.close()));
+    process.stdin.on('close', handleExit);
+    process.on('SIGINT', handleExit);
+    process.on('SIGTERM', handleExit);
   }
 }

src/tab.ts

@@ -0,0 +1,120 @@
+/**
+ * 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 { PageSnapshot } from './pageSnapshot.js';
+
+import type { Context } from './context.js';
+import { callOnPageNoTrace } from './tools/utils.js';
+
+export class Tab {
+  readonly context: Context;
+  readonly page: playwright.Page;
+  private _consoleMessages: playwright.ConsoleMessage[] = [];
+  private _requests: Map<playwright.Request, playwright.Response | null> = new Map();
+  private _snapshot: PageSnapshot | undefined;
+  private _onPageClose: (tab: Tab) => void;
+
+  constructor(context: Context, page: playwright.Page, onPageClose: (tab: Tab) => void) {
+    this.context = context;
+    this.page = page;
+    this._onPageClose = onPageClose;
+    page.on('console', event => this._consoleMessages.push(event));
+    page.on('request', request => this._requests.set(request, null));
+    page.on('response', response => this._requests.set(response.request(), response));
+    page.on('close', () => this._onClose());
+    page.on('filechooser', chooser => {
+      this.context.setModalState({
+        type: 'fileChooser',
+        description: 'File chooser',
+        fileChooser: chooser,
+      }, this);
+    });
+    page.on('dialog', dialog => this.context.dialogShown(this, dialog));
+    page.on('download', download => {
+      void this.context.downloadStarted(this, download);
+    });
+    page.setDefaultNavigationTimeout(60000);
+    page.setDefaultTimeout(5000);
+  }
+
+  private _clearCollectedArtifacts() {
+    this._consoleMessages.length = 0;
+    this._requests.clear();
+  }
+
+  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(() => {}));
+  }
+
+  async navigate(url: string) {
+    this._clearCollectedArtifacts();
+
+    const downloadEvent = callOnPageNoTrace(this.page, page => page.waitForEvent('download').catch(() => {}));
+    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, 1000)),
+      ]);
+      if (!download)
+        throw e;
+    }
+
+    // Cap load event to 5 seconds, the page is operational at this point.
+    await this.waitForLoadState('load', { timeout: 5000 });
+  }
+
+  hasSnapshot(): boolean {
+    return !!this._snapshot;
+  }
+
+  snapshotOrDie(): PageSnapshot {
+    if (!this._snapshot)
+      throw new Error('No snapshot available');
+    return this._snapshot;
+  }
+
+  consoleMessages(): playwright.ConsoleMessage[] {
+    return this._consoleMessages;
+  }
+
+  requests(): Map<playwright.Request, playwright.Response | null> {
+    return this._requests;
+  }
+
+  async captureSnapshot() {
+    this._snapshot = await PageSnapshot.create(this.page);
+  }
+}

src/tools.ts

@@ -0,0 +1,66 @@
+/**
+ * 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 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 testing from './tools/testing.js';
+import vision from './tools/vision.js';
+import wait from './tools/wait.js';
+
+import type { Tool } from './tools/tool.js';
+
+export const snapshotTools: Tool<any>[] = [
+  ...common(true),
+  ...console,
+  ...dialogs(true),
+  ...files(true),
+  ...install,
+  ...keyboard(true),
+  ...navigate(true),
+  ...network,
+  ...pdf,
+  ...screenshot,
+  ...snapshot,
+  ...tabs(true),
+  ...testing,
+  ...wait(true),
+];
+
+export const visionTools: Tool<any>[] = [
+  ...common(false),
+  ...console,
+  ...dialogs(false),
+  ...files(false),
+  ...install,
+  ...keyboard(false),
+  ...navigate(false),
+  ...network,
+  ...pdf,
+  ...tabs(false),
+  ...testing,
+  ...vision,
+  ...wait(false),
+];

src/tools/common.ts

@@ -15,81 +15,70 @@
  */
 
 import { z } from 'zod';
-import { zodToJsonSchema } from 'zod-to-json-schema';
+import { defineTool, type ToolFactory } from './tool.js';
 
-import type { Tool, ToolFactory } from './tool';
-
-const waitSchema = z.object({
-  time: z.number().describe('The time to wait in seconds'),
-});
-
-const wait: Tool = {
-  capability: 'wait',
-  schema: {
-    name: 'browser_wait',
-    description: 'Wait for a specified time in seconds',
-    inputSchema: zodToJsonSchema(waitSchema),
-  },
-  handle: async (context, params) => {
-    const validatedParams = waitSchema.parse(params);
-    await new Promise(f => setTimeout(f, Math.min(10000, validatedParams.time * 1000)));
-    return {
-      content: [{
-        type: 'text',
-        text: `Waited for ${validatedParams.time} seconds`,
-      }],
-    };
-  },
-};
-
-const closeSchema = z.object({});
-
-const close: Tool = {
+const close = defineTool({
   capability: 'core',
+
   schema: {
     name: 'browser_close',
+    title: 'Close browser',
     description: 'Close the page',
-    inputSchema: zodToJsonSchema(closeSchema),
+    inputSchema: z.object({}),
+    type: 'readOnly',
   },
+
   handle: async context => {
     await context.close();
     return {
-      content: [{
-        type: 'text',
-        text: `Page closed`,
-      }],
+      code: [`await page.close()`],
+      captureSnapshot: false,
+      waitForNetwork: false,
+      resultOverride: {
+        content: [{
+          type: 'text',
+          text: 'Browser closed successfully.',
+        }],
+      },
     };
   },
-};
-
-const resizeSchema = z.object({
-  width: z.number().describe('Width of the browser window'),
-  height: z.number().describe('Height of the browser window'),
 });
 
-const resize: ToolFactory = captureSnapshot => ({
+const resize: ToolFactory = captureSnapshot => defineTool({
   capability: 'core',
   schema: {
     name: 'browser_resize',
+    title: 'Resize browser window',
     description: 'Resize the browser window',
-    inputSchema: zodToJsonSchema(resizeSchema),
+    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 validatedParams = resizeSchema.parse(params);
 
-    const tab = context.currentTab();
-    return await tab.run(
-        tab => tab.page.setViewportSize({ width: validatedParams.width, height: validatedParams.height }),
-        {
-          status: `Resized browser window`,
-          captureSnapshot,
-        }
-    );
+  handle: async (context, params) => {
+    const tab = context.currentTabOrDie();
+
+    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.page.setViewportSize({ width: params.width, height: params.height });
+    };
+
+    return {
+      code,
+      action,
+      captureSnapshot,
+      waitForNetwork: true
+    };
   },
 });
 
 export default (captureSnapshot: boolean) => [
   close,
-  wait,
   resize(captureSnapshot)
 ];

src/tools/console.ts

@@ -0,0 +1,47 @@
+/**
+ * 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 console = defineTool({
+  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().consoleMessages();
+    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,
+    };
+  },
+});
+
+export default [
+  console,
+];

src/tools/dialogs.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 { defineTool, type ToolFactory } from './tool.js';
+
+const handleDialog: ToolFactory = captureSnapshot => defineTool({
+  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');
+    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,
+    };
+  },
+
+  clearsModalState: 'dialog',
+});
+
+export default (captureSnapshot: boolean) => [
+  handleDialog(captureSnapshot),
+];

src/tools/files.ts

@@ -15,32 +15,43 @@
  */
 
 import { z } from 'zod';
-import { zodToJsonSchema } from 'zod-to-json-schema';
+import { defineTool, type ToolFactory } from './tool.js';
 
-import type { ToolFactory } from './tool';
-
-const uploadFileSchema = z.object({
-  paths: z.array(z.string()).describe('The absolute paths to the files to upload. Can be a single file or multiple files.'),
-});
-
-const uploadFile: ToolFactory = captureSnapshot => ({
+const uploadFile: ToolFactory = captureSnapshot => defineTool({
   capability: 'files',
+
   schema: {
     name: 'browser_file_upload',
+    title: 'Upload files',
     description: 'Upload one or multiple files',
-    inputSchema: zodToJsonSchema(uploadFileSchema),
+    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 validatedParams = uploadFileSchema.parse(params);
-    const tab = context.currentTab();
-    return await tab.runAndWait(async () => {
-      await tab.submitFileChooser(validatedParams.paths);
-    }, {
-      status: `Chose files ${validatedParams.paths.join(', ')}`,
+    const modalState = context.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(', ')}`,
+    ];
+
+    const action = async () => {
+      await modalState.fileChooser.setFiles(params.paths);
+      context.clearModalState(modalState);
+    };
+
+    return {
+      code,
+      action,
       captureSnapshot,
-      noClearFileChooser: true,
-    });
+      waitForNetwork: true,
+    };
   },
+  clearsModalState: 'fileChooser',
 });
 
 export default (captureSnapshot: boolean) => [

src/tools/install.ts

@@ -18,22 +18,25 @@ import { fork } from 'child_process';
 import path from 'path';
 
 import { z } from 'zod';
-import { zodToJsonSchema } from 'zod-to-json-schema';
+import { defineTool } from './tool.js';
 
-import type { Tool } from './tool';
+import { fileURLToPath } from 'node:url';
 
-const install: Tool = {
+const install = defineTool({
   capability: '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: zodToJsonSchema(z.object({})),
+    inputSchema: z.object({}),
+    type: 'destructive',
   },
 
   handle: async context => {
-    const channel = context.options.launchOptions?.channel ?? context.options.browserName ?? 'chrome';
-    const cli = path.join(require.resolve('playwright/package.json'), '..', 'cli.js');
-    const child = fork(cli, ['install', channel], {
+    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[] = [];
@@ -48,13 +51,12 @@ const install: Tool = {
       });
     });
     return {
-      content: [{
-        type: 'text',
-        text: `Browser ${channel} installed`,
-      }],
+      code: [`// Browser ${channel} installed`],
+      captureSnapshot: false,
+      waitForNetwork: false,
     };
   },
-};
+});
 
 export default [
   install,

src/tools/keyboard.ts

@@ -15,29 +15,37 @@
  */
 
 import { z } from 'zod';
-import zodToJsonSchema from 'zod-to-json-schema';
+import { defineTool, type ToolFactory } from './tool.js';
 
-import type { ToolFactory } from './tool';
-
-const pressKeySchema = z.object({
-  key: z.string().describe('Name of the key to press or a character to generate, such as `ArrowLeft` or `a`'),
-});
-
-const pressKey: ToolFactory = captureSnapshot => ({
+const pressKey: ToolFactory = captureSnapshot => defineTool({
   capability: 'core',
+
   schema: {
     name: 'browser_press_key',
+    title: 'Press a key',
     description: 'Press a key on the keyboard',
-    inputSchema: zodToJsonSchema(pressKeySchema),
+    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 validatedParams = pressKeySchema.parse(params);
-    return await context.currentTab().runAndWait(async tab => {
-      await tab.page.keyboard.press(validatedParams.key);
-    }, {
-      status: `Pressed key ${validatedParams.key}`,
+    const tab = context.currentTabOrDie();
+
+    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
+    };
   },
 });
 

src/tools/navigate.ts

@@ -15,68 +15,85 @@
  */
 
 import { z } from 'zod';
-import { zodToJsonSchema } from 'zod-to-json-schema';
+import { defineTool, type ToolFactory } from './tool.js';
 
-import type { ToolFactory } from './tool';
-
-const navigateSchema = z.object({
-  url: z.string().describe('The URL to navigate to'),
-});
-
-const navigate: ToolFactory = captureSnapshot => ({
+const navigate: ToolFactory = captureSnapshot => defineTool({
   capability: 'core',
+
   schema: {
     name: 'browser_navigate',
+    title: 'Navigate to a URL',
     description: 'Navigate to a URL',
-    inputSchema: zodToJsonSchema(navigateSchema),
+    inputSchema: z.object({
+      url: z.string().describe('The URL to navigate to'),
+    }),
+    type: 'destructive',
   },
+
   handle: async (context, params) => {
-    const validatedParams = navigateSchema.parse(params);
-    const currentTab = await context.ensureTab();
-    return await currentTab.run(async tab => {
-      await tab.navigate(validatedParams.url);
-    }, {
-      status: `Navigated to ${validatedParams.url}`,
+    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,
+    };
   },
 });
 
-const goBackSchema = z.object({});
-
-const goBack: ToolFactory = snapshot => ({
+const goBack: ToolFactory = captureSnapshot => defineTool({
   capability: 'history',
   schema: {
     name: 'browser_navigate_back',
+    title: 'Go back',
     description: 'Go back to the previous page',
-    inputSchema: zodToJsonSchema(goBackSchema),
+    inputSchema: z.object({}),
+    type: 'readOnly',
   },
+
   handle: async context => {
-    return await context.currentTab().runAndWait(async tab => {
-      await tab.page.goBack();
-    }, {
-      status: 'Navigated back',
-      captureSnapshot: snapshot,
-    });
+    const tab = await context.ensureTab();
+    await tab.page.goBack();
+    const code = [
+      `// Navigate back`,
+      `await page.goBack();`,
+    ];
+
+    return {
+      code,
+      captureSnapshot,
+      waitForNetwork: false,
+    };
   },
 });
 
-const goForwardSchema = z.object({});
-
-const goForward: ToolFactory = snapshot => ({
+const goForward: ToolFactory = captureSnapshot => defineTool({
   capability: 'history',
   schema: {
     name: 'browser_navigate_forward',
+    title: 'Go forward',
     description: 'Go forward to the next page',
-    inputSchema: zodToJsonSchema(goForwardSchema),
+    inputSchema: z.object({}),
+    type: 'readOnly',
   },
   handle: async context => {
-    return await context.currentTab().runAndWait(async tab => {
-      await tab.page.goForward();
-    }, {
-      status: 'Navigated forward',
-      captureSnapshot: snapshot,
-    });
+    const tab = context.currentTabOrDie();
+    await tab.page.goForward();
+    const code = [
+      `// Navigate forward`,
+      `await page.goForward();`,
+    ];
+    return {
+      code,
+      captureSnapshot,
+      waitForNetwork: false,
+    };
   },
 });
 

src/tools/network.ts

@@ -0,0 +1,59 @@
+/**
+ * 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 type * as playwright from 'playwright';
+
+const requests = defineTool({
+  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,
+    };
+  },
+});
+
+function renderRequest(request: playwright.Request, response: playwright.Response | null) {
+  const result: string[] = [];
+  result.push(`[${request.method().toUpperCase()}] ${request.url()}`);
+  if (response)
+    result.push(`=> [${response.status()}] ${response.statusText()}`);
+  return result.join(' ');
+}
+
+export default [
+  requests,
+];

src/tools/pdf.ts

@@ -14,37 +14,44 @@
  * limitations under the License.
  */
 
-import os from 'os';
-import path from 'path';
-
 import { z } from 'zod';
-import { zodToJsonSchema } from 'zod-to-json-schema';
+import { defineTool } from './tool.js';
 
-import { sanitizeForFilePath } from './utils';
+import * as javascript from '../javascript.js';
+import { outputFile } from '../config.js';
 
-import type { Tool } from './tool';
+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 pdfSchema = z.object({});
-
-const pdf: Tool = {
+const pdf = defineTool({
   capability: 'pdf',
+
   schema: {
     name: 'browser_pdf_save',
+    title: 'Save as PDF',
     description: 'Save page as PDF',
-    inputSchema: zodToJsonSchema(pdfSchema),
+    inputSchema: pdfSchema,
+    type: 'readOnly',
   },
-  handle: async context => {
-    const tab = context.currentTab();
-    const fileName = path.join(os.tmpdir(), sanitizeForFilePath(`page-${new Date().toISOString()}`)) + '.pdf';
-    await tab.page.pdf({ path: fileName });
+
+  handle: async (context, params) => {
+    const tab = context.currentTabOrDie();
+    const fileName = await outputFile(context.config, params.filename ?? `page-${new Date().toISOString()}.pdf`);
+
+    const code = [
+      `// Save page as ${fileName}`,
+      `await page.pdf(${javascript.formatObject({ path: fileName })});`,
+    ];
+
     return {
-      content: [{
-        type: 'text',
-        text: `Saved as ${fileName}`,
-      }],
+      code,
+      action: async () => tab.page.pdf({ path: fileName }).then(() => {}),
+      captureSnapshot: false,
+      waitForNetwork: false,
     };
   },
-};
+});
 
 export default [
   pdf,

src/tools/screen.ts

@@ -1,150 +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 { zodToJsonSchema } from 'zod-to-json-schema';
-
-import type { Tool } from './tool';
-
-const screenshot: Tool = {
-  capability: 'core',
-  schema: {
-    name: 'browser_screen_capture',
-    description: 'Take a screenshot of the current page',
-    inputSchema: zodToJsonSchema(z.object({})),
-  },
-
-  handle: async context => {
-    const tab = await context.ensureTab();
-    const screenshot = await tab.page.screenshot({ type: 'jpeg', quality: 50, scale: 'css' });
-    return {
-      content: [{ type: 'image', data: screenshot.toString('base64'), mimeType: 'image/jpeg' }],
-    };
-  },
-};
-
-const elementSchema = z.object({
-  element: z.string().describe('Human-readable element description used to obtain permission to interact with the element'),
-});
-
-const moveMouseSchema = elementSchema.extend({
-  x: z.number().describe('X coordinate'),
-  y: z.number().describe('Y coordinate'),
-});
-
-const moveMouse: Tool = {
-  capability: 'core',
-  schema: {
-    name: 'browser_screen_move_mouse',
-    description: 'Move mouse to a given position',
-    inputSchema: zodToJsonSchema(moveMouseSchema),
-  },
-
-  handle: async (context, params) => {
-    const validatedParams = moveMouseSchema.parse(params);
-    const tab = context.currentTab();
-    await tab.page.mouse.move(validatedParams.x, validatedParams.y);
-    return {
-      content: [{ type: 'text', text: `Moved mouse to (${validatedParams.x}, ${validatedParams.y})` }],
-    };
-  },
-};
-
-const clickSchema = elementSchema.extend({
-  x: z.number().describe('X coordinate'),
-  y: z.number().describe('Y coordinate'),
-});
-
-const click: Tool = {
-  capability: 'core',
-  schema: {
-    name: 'browser_screen_click',
-    description: 'Click left mouse button',
-    inputSchema: zodToJsonSchema(clickSchema),
-  },
-
-  handle: async (context, params) => {
-    return await context.currentTab().runAndWait(async tab => {
-      const validatedParams = clickSchema.parse(params);
-      await tab.page.mouse.move(validatedParams.x, validatedParams.y);
-      await tab.page.mouse.down();
-      await tab.page.mouse.up();
-    }, {
-      status: 'Clicked mouse',
-    });
-  },
-};
-
-const dragSchema = 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'),
-});
-
-const drag: Tool = {
-  capability: 'core',
-  schema: {
-    name: 'browser_screen_drag',
-    description: 'Drag left mouse button',
-    inputSchema: zodToJsonSchema(dragSchema),
-  },
-
-  handle: async (context, params) => {
-    const validatedParams = dragSchema.parse(params);
-    return await context.currentTab().runAndWait(async tab => {
-      await tab.page.mouse.move(validatedParams.startX, validatedParams.startY);
-      await tab.page.mouse.down();
-      await tab.page.mouse.move(validatedParams.endX, validatedParams.endY);
-      await tab.page.mouse.up();
-    }, {
-      status: `Dragged mouse from (${validatedParams.startX}, ${validatedParams.startY}) to (${validatedParams.endX}, ${validatedParams.endY})`,
-    });
-  },
-};
-
-const typeSchema = 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)'),
-});
-
-const type: Tool = {
-  capability: 'core',
-  schema: {
-    name: 'browser_screen_type',
-    description: 'Type text',
-    inputSchema: zodToJsonSchema(typeSchema),
-  },
-
-  handle: async (context, params) => {
-    const validatedParams = typeSchema.parse(params);
-    return await context.currentTab().runAndWait(async tab => {
-      await tab.page.keyboard.type(validatedParams.text);
-      if (validatedParams.submit)
-        await tab.page.keyboard.press('Enter');
-    }, {
-      status: `Typed text "${validatedParams.text}"`,
-    });
-  },
-};
-
-export default [
-  screenshot,
-  moveMouse,
-  click,
-  drag,
-  type,
-];

src/tools/screenshot.ts

@@ -0,0 +1,90 @@
+/**
+ * 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';
+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.'),
+}).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',
+    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 (context, params) => {
+    const tab = context.currentTabOrDie();
+    const snapshot = tab.snapshotOrDie();
+    const fileType = params.raw ? 'png' : 'jpeg';
+    const fileName = await outputFile(context.config, params.filename ?? `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({ element: params.element || '', ref: 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.clientSupportsImages();
+    const action = async () => {
+      const screenshot = locator ? await locator.screenshot(options) : await tab.page.screenshot(options);
+      return {
+        content: includeBase64 ? [{
+          type: 'image' as 'image',
+          data: screenshot.toString('base64'),
+          mimeType: fileType === 'png' ? 'image/png' : 'image/jpeg',
+        }] : []
+      };
+    };
+
+    return {
+      code,
+      action,
+      captureSnapshot: true,
+      waitForNetwork: false,
+    };
+  }
+});
+
+export default [
+  screenshot,
+];

src/tools/snapshot.ts

@@ -15,94 +15,126 @@
  */
 
 import { z } from 'zod';
-import zodToJsonSchema from 'zod-to-json-schema';
 
-import type * as playwright from 'playwright';
-import type { Tool } from './tool';
+import { defineTool } from './tool.js';
+import * as javascript from '../javascript.js';
+import { generateLocator } from './utils.js';
 
-const snapshot: Tool = {
+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: zodToJsonSchema(z.object({})),
+    inputSchema: z.object({}),
+    type: 'readOnly',
   },
 
   handle: async context => {
-    const tab = await context.ensureTab();
-    return await tab.run(async () => {}, { captureSnapshot: true });
+    await context.ensureTab();
+
+    return {
+      code: [`// <internal code to capture accessibility snapshot>`],
+      captureSnapshot: true,
+      waitForNetwork: false,
+    };
   },
-};
+});
 
 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: Tool = {
+const click = defineTool({
   capability: 'core',
   schema: {
     name: 'browser_click',
+    title: 'Click',
     description: 'Perform click on a web page',
-    inputSchema: zodToJsonSchema(elementSchema),
+    inputSchema: elementSchema,
+    type: 'destructive',
   },
 
   handle: async (context, params) => {
-    const validatedParams = elementSchema.parse(params);
-    return await context.currentTab().runAndWaitWithSnapshot(async snapshot => {
-      const locator = snapshot.refLocator(validatedParams.ref);
-      await locator.click();
-    }, {
-      status: `Clicked "${validatedParams.element}"`,
-    });
-  },
-};
+    const tab = context.currentTabOrDie();
+    const locator = tab.snapshotOrDie().refLocator(params);
 
-const dragSchema = z.object({
-  startElement: z.string().describe('Human-readable source element description used to obtain the permission to interact with the element'),
-  startRef: z.string().describe('Exact source element reference from the page snapshot'),
-  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'),
+    const code = [
+      `// Click ${params.element}`,
+      `await page.${await generateLocator(locator)}.click();`
+    ];
+
+    return {
+      code,
+      action: () => locator.click(),
+      captureSnapshot: true,
+      waitForNetwork: true,
+    };
+  },
 });
 
-const drag: Tool = {
+const drag = defineTool({
   capability: 'core',
   schema: {
     name: 'browser_drag',
+    title: 'Drag mouse',
     description: 'Perform drag and drop between two elements',
-    inputSchema: zodToJsonSchema(dragSchema),
+    inputSchema: z.object({
+      startElement: z.string().describe('Human-readable source element description used to obtain the permission to interact with the element'),
+      startRef: z.string().describe('Exact source element reference from the page snapshot'),
+      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 validatedParams = dragSchema.parse(params);
-    return await context.currentTab().runAndWaitWithSnapshot(async snapshot => {
-      const startLocator = snapshot.refLocator(validatedParams.startRef);
-      const endLocator = snapshot.refLocator(validatedParams.endRef);
-      await startLocator.dragTo(endLocator);
-    }, {
-      status: `Dragged "${validatedParams.startElement}" to "${validatedParams.endElement}"`,
-    });
-  },
-};
+    const snapshot = context.currentTabOrDie().snapshotOrDie();
+    const startLocator = snapshot.refLocator({ ref: params.startRef, element: params.startElement });
+    const endLocator = snapshot.refLocator({ ref: params.endRef, element: params.endElement });
 
-const hover: Tool = {
+    const code = [
+      `// Drag ${params.startElement} to ${params.endElement}`,
+      `await page.${await generateLocator(startLocator)}.dragTo(page.${await generateLocator(endLocator)});`
+    ];
+
+    return {
+      code,
+      action: () => startLocator.dragTo(endLocator),
+      captureSnapshot: true,
+      waitForNetwork: true,
+    };
+  },
+});
+
+const hover = defineTool({
   capability: 'core',
   schema: {
     name: 'browser_hover',
+    title: 'Hover mouse',
     description: 'Hover over element on page',
-    inputSchema: zodToJsonSchema(elementSchema),
+    inputSchema: elementSchema,
+    type: 'readOnly',
   },
 
   handle: async (context, params) => {
-    const validatedParams = elementSchema.parse(params);
-    return await context.currentTab().runAndWaitWithSnapshot(async snapshot => {
-      const locator = snapshot.refLocator(validatedParams.ref);
-      await locator.hover();
-    }, {
-      status: `Hovered over "${validatedParams.element}"`,
-    });
+    const snapshot = context.currentTabOrDie().snapshotOrDie();
+    const locator = snapshot.refLocator(params);
+
+    const code = [
+      `// Hover over ${params.element}`,
+      `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'),
@@ -110,75 +142,79 @@ const typeSchema = elementSchema.extend({
   slowly: z.boolean().optional().describe('Whether to type one character at a time. Useful for triggering key handlers in the page. By default entire text is filled in at once.'),
 });
 
-const type: Tool = {
+const type = defineTool({
   capability: 'core',
   schema: {
     name: 'browser_type',
+    title: 'Type text',
     description: 'Type text into editable element',
-    inputSchema: zodToJsonSchema(typeSchema),
+    inputSchema: typeSchema,
+    type: 'destructive',
   },
 
   handle: async (context, params) => {
-    const validatedParams = typeSchema.parse(params);
-    return await context.currentTab().runAndWaitWithSnapshot(async snapshot => {
-      const locator = snapshot.refLocator(validatedParams.ref);
-      if (validatedParams.slowly)
-        await locator.pressSequentially(validatedParams.text);
-      else
-        await locator.fill(validatedParams.text);
-      if (validatedParams.submit)
-        await locator.press('Enter');
-    }, {
-      status: `Typed "${validatedParams.text}" into "${validatedParams.element}"`,
-    });
+    const snapshot = context.currentTabOrDie().snapshotOrDie();
+    const locator = snapshot.refLocator(params);
+
+    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,
+    };
   },
-};
+});
 
 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: Tool = {
+const selectOption = defineTool({
   capability: 'core',
   schema: {
     name: 'browser_select_option',
+    title: 'Select option',
     description: 'Select an option in a dropdown',
-    inputSchema: zodToJsonSchema(selectOptionSchema),
+    inputSchema: selectOptionSchema,
+    type: 'destructive',
   },
 
   handle: async (context, params) => {
-    const validatedParams = selectOptionSchema.parse(params);
-    return await context.currentTab().runAndWaitWithSnapshot(async snapshot => {
-      const locator = snapshot.refLocator(validatedParams.ref);
-      await locator.selectOption(validatedParams.values);
-    }, {
-      status: `Selected option in "${validatedParams.element}"`,
-    });
-  },
-};
+    const snapshot = context.currentTabOrDie().snapshotOrDie();
+    const locator = snapshot.refLocator(params);
 
-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.'),
-});
+    const code = [
+      `// Select options [${params.values.join(', ')}] in ${params.element}`,
+      `await page.${await generateLocator(locator)}.selectOption(${javascript.formatObject(params.values)});`
+    ];
 
-const screenshot: Tool = {
-  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: zodToJsonSchema(screenshotSchema),
-  },
-
-  handle: async (context, params) => {
-    const validatedParams = screenshotSchema.parse(params);
-    const tab = context.currentTab();
-    const options: playwright.PageScreenshotOptions = validatedParams.raw ? { type: 'png', scale: 'css' } : { type: 'jpeg', quality: 50, scale: 'css' };
-    const screenshot = await tab.page.screenshot(options);
     return {
-      content: [{ type: 'image', data: screenshot.toString('base64'), mimeType: validatedParams.raw ? 'image/png' : 'image/jpeg' }],
+      code,
+      action: () => locator.selectOption(params.values).then(() => {}),
+      captureSnapshot: true,
+      waitForNetwork: true,
     };
   },
-};
+});
 
 export default [
   snapshot,
@@ -187,5 +223,4 @@ export default [
   hover,
   type,
   selectOption,
-  screenshot,
 ];

src/tools/tabs.ts

@@ -15,95 +15,120 @@
  */
 
 import { z } from 'zod';
-import { zodToJsonSchema } from 'zod-to-json-schema';
+import { defineTool, type ToolFactory } from './tool.js';
 
-import type { ToolFactory, Tool } from './tool';
-
-const listTabs: Tool = {
+const listTabs = defineTool({
   capability: 'tabs',
+
   schema: {
     name: 'browser_tab_list',
+    title: 'List tabs',
     description: 'List browser tabs',
-    inputSchema: zodToJsonSchema(z.object({})),
+    inputSchema: z.object({}),
+    type: 'readOnly',
   },
+
   handle: async context => {
+    await context.ensureTab();
     return {
-      content: [{
-        type: 'text',
-        text: await context.listTabs(),
-      }],
+      code: [`// <internal code to list tabs>`],
+      captureSnapshot: false,
+      waitForNetwork: false,
+      resultOverride: {
+        content: [{
+          type: 'text',
+          text: await context.listTabsMarkdown(),
+        }],
+      },
     };
   },
-};
-
-const selectTabSchema = z.object({
-  index: z.number().describe('The index of the tab to select'),
 });
 
-const selectTab: ToolFactory = captureSnapshot => ({
+const selectTab: ToolFactory = captureSnapshot => defineTool({
   capability: 'tabs',
+
   schema: {
     name: 'browser_tab_select',
+    title: 'Select a tab',
     description: 'Select a tab by index',
-    inputSchema: zodToJsonSchema(selectTabSchema),
+    inputSchema: z.object({
+      index: z.number().describe('The index of the tab to select'),
+    }),
+    type: 'readOnly',
   },
+
   handle: async (context, params) => {
-    const validatedParams = selectTabSchema.parse(params);
-    await context.selectTab(validatedParams.index);
-    const currentTab = await context.ensureTab();
-    return await currentTab.run(async () => {}, { captureSnapshot });
+    await context.selectTab(params.index);
+    const code = [
+      `// <internal code to select tab ${params.index}>`,
+    ];
+
+    return {
+      code,
+      captureSnapshot,
+      waitForNetwork: false
+    };
   },
 });
 
-const newTabSchema = 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.'),
-});
-
-const newTab: Tool = {
+const newTab: ToolFactory = captureSnapshot => defineTool({
   capability: 'tabs',
+
   schema: {
     name: 'browser_tab_new',
+    title: 'Open a new tab',
     description: 'Open a new tab',
-    inputSchema: zodToJsonSchema(newTabSchema),
+    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) => {
-    const validatedParams = newTabSchema.parse(params);
-    await context.newTab();
-    if (validatedParams.url)
-      await context.currentTab().navigate(validatedParams.url);
-    return await context.currentTab().run(async () => {}, { captureSnapshot: true });
-  },
-};
 
-const closeTabSchema = z.object({
-  index: z.number().optional().describe('The index of the tab to close. Closes current tab if not provided.'),
+  handle: async (context, params) => {
+    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
+    };
+  },
 });
 
-const closeTab: ToolFactory = captureSnapshot => ({
+const closeTab: ToolFactory = captureSnapshot => defineTool({
   capability: 'tabs',
+
   schema: {
     name: 'browser_tab_close',
+    title: 'Close a tab',
     description: 'Close a tab',
-    inputSchema: zodToJsonSchema(closeTabSchema),
+    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) => {
-    const validatedParams = closeTabSchema.parse(params);
-    await context.closeTab(validatedParams.index);
-    const currentTab = context.currentTab();
-    if (currentTab)
-      return await currentTab.run(async () => {}, { captureSnapshot });
+    await context.closeTab(params.index);
+    const code = [
+      `// <internal code to close tab ${params.index}>`,
+    ];
     return {
-      content: [{
-        type: 'text',
-        text: await context.listTabs(),
-      }],
+      code,
+      captureSnapshot,
+      waitForNetwork: false
     };
   },
 });
 
 export default (captureSnapshot: boolean) => [
   listTabs,
-  newTab,
+  newTab(captureSnapshot),
   selectTab(captureSnapshot),
   closeTab(captureSnapshot),
 ];

src/tools/testing.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 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',
+    title: 'Generate a Playwright test',
+    description: 'Generate a Playwright test for given scenario',
+    inputSchema: generateTestSchema,
+    type: 'readOnly',
+  },
+
+  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,27 +14,55 @@
  * limitations under the License.
  */
 
-import type { ImageContent, TextContent } from '@modelcontextprotocol/sdk/types';
-import type { JsonSchema7Type } from 'zod-to-json-schema';
-import type { Context } from '../context';
+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 ToolCapability = 'core' | 'tabs' | 'pdf' | 'history' | 'wait' | 'files' | 'install';
-
-export type ToolSchema = {
+export type ToolSchema<Input extends InputType> = {
   name: string;
+  title: string;
   description: string;
-  inputSchema: JsonSchema7Type;
+  inputSchema: Input;
+  type: 'readOnly' | 'destructive';
 };
 
+type InputType = z.Schema;
+
+export type FileUploadModalState = {
+  type: 'fileChooser';
+  description: string;
+  fileChooser: playwright.FileChooser;
+};
+
+export type DialogModalState = {
+  type: 'dialog';
+  description: string;
+  dialog: playwright.Dialog;
+};
+
+export type ModalState = FileUploadModalState | DialogModalState;
+
+export type ToolActionResult = { content?: (ImageContent | TextContent)[] } | undefined | void;
+
 export type ToolResult = {
-  content: (ImageContent | TextContent)[];
-  isError?: boolean;
+  code: string[];
+  action?: () => Promise<ToolActionResult>;
+  captureSnapshot: boolean;
+  waitForNetwork: boolean;
+  resultOverride?: ToolActionResult;
 };
 
-export type Tool = {
+export type Tool<Input extends InputType = InputType> = {
   capability: ToolCapability;
-  schema: ToolSchema;
-  handle: (context: Context, params?: Record<string, any>) => Promise<ToolResult>;
+  schema: ToolSchema<Input>;
+  clearsModalState?: ModalState['type'];
+  handle: (context: Context, params: z.output<Input>) => Promise<ToolResult>;
 };
 
-export type ToolFactory = (snapshot: boolean) => Tool;
+export type ToolFactory = (snapshot: boolean) => Tool<any>;
+
+export function defineTool<Input extends InputType>(tool: Tool<Input>): Tool<Input> {
+  return tool;
+}

src/tools/utils.ts

@@ -15,8 +15,10 @@
  */
 
 import type * as playwright from 'playwright';
+import type { Context } from '../context.js';
+import type { Tab } from '../tab.js';
 
-export async function waitForCompletion<R>(page: playwright.Page, callback: () => Promise<R>): Promise<R> {
+export async function waitForCompletion<R>(context: Context, tab: Tab, callback: () => Promise<R>): Promise<R> {
   const requests = new Set<playwright.Request>();
   let frameNavigated = false;
   let waitCallback: () => void = () => {};
@@ -35,9 +37,7 @@ export async function waitForCompletion<R>(page: playwright.Page, callback: () =
     frameNavigated = true;
     dispose();
     clearTimeout(timeout);
-    void frame.waitForLoadState('load').then(() => {
-      waitCallback();
-    });
+    void tab.waitForLoadState('load').then(waitCallback);
   };
 
   const onTimeout = () => {
@@ -45,15 +45,15 @@ export async function waitForCompletion<R>(page: playwright.Page, callback: () =
     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);
   };
 
@@ -62,7 +62,7 @@ export async function waitForCompletion<R>(page: playwright.Page, callback: () =
     if (!requests.size && !frameNavigated)
       waitCallback();
     await waitBarrier;
-    await page.evaluate(() => new Promise(f => setTimeout(f, 1000)));
+    await context.waitForTimeout(1000);
     return result;
   } finally {
     dispose();
@@ -70,5 +70,23 @@ export async function waitForCompletion<R>(page: playwright.Page, callback: () =
 }
 
 export function sanitizeForFilePath(s: string) {
-  return s.replace(/[\x00-\x2C\x2E-\x2F\x3A-\x40\x5B-\x60\x7B-\x7F]+/g, '-');
+  const sanitize = (s: string) => s.replace(/[\x00-\x2C\x2E-\x2F\x3A-\x40\x5B-\x60\x7B-\x7F]+/g, '-');
+  const separator = s.lastIndexOf('.');
+  if (separator === -1)
+    return sanitize(s);
+  return sanitize(s.substring(0, separator)) + '.' + sanitize(s.substring(separator + 1));
+}
+
+export async function generateLocator(locator: playwright.Locator): Promise<string> {
+  try {
+    return await (locator as any)._generateLocatorString();
+  } catch (e) {
+    if (e instanceof Error && /locator._generateLocatorString: Timeout .* exceeded/.test(e.message))
+      throw new Error('Ref not found, likely because element was removed. Use browser_snapshot to see what elements are currently on the page.');
+    throw e;
+  }
+}
+
+export async function callOnPageNoTrace<T>(page: playwright.Page, callback: (page: playwright.Page) => Promise<T>): Promise<T> {
+  return await (page as any)._wrapApiCall(() => callback(page), { internal: true });
 }

src/tools/vision.ts

@@ -0,0 +1,213 @@
+/**
+ * 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',
+    title: 'Take a screenshot',
+    description: 'Take a screenshot of the current page',
+    inputSchema: z.object({}),
+    type: 'readOnly',
+  },
+
+  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',
+    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 (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',
+    title: 'Click',
+    description: 'Click left mouse button',
+    inputSchema: elementSchema.extend({
+      x: z.number().describe('X coordinate'),
+      y: z.number().describe('Y coordinate'),
+    }),
+    type: 'destructive',
+  },
+
+  handle: async (context, params) => {
+    const tab = context.currentTabOrDie();
+    const code = [
+      `// Click mouse at coordinates (${params.x}, ${params.y})`,
+      `await page.mouse.move(${params.x}, ${params.y});`,
+      `await page.mouse.down();`,
+      `await page.mouse.up();`,
+    ];
+    const action = async () => {
+      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',
+    title: 'Drag mouse',
+    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'),
+    }),
+    type: 'destructive',
+  },
+
+  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',
+    title: 'Type text',
+    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)'),
+    }),
+    type: 'destructive',
+  },
+
+  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/wait.ts

@@ -0,0 +1,70 @@
+/**
+ * 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, type ToolFactory } from './tool.js';
+
+const wait: ToolFactory = captureSnapshot => defineTool({
+  capability: 'wait',
+
+  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) => {
+    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(10000, 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' });
+    }
+
+    return {
+      code,
+      captureSnapshot,
+      waitForNetwork: false,
+    };
+  },
+});
+
+export default (captureSnapshot: boolean) => [
+  wait(captureSnapshot),
+];

src/transport.ts

@@ -0,0 +1,149 @@
+/**
+ * Copyright (c) Microsoft Corporation.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+import http from 'node:http';
+import assert from 'node:assert';
+import crypto from 'node: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 type { AddressInfo } from 'node:net';
+import type { Server } from './server.js';
+
+export async function startStdioTransport(server: Server) {
+  await server.createConnection(new StdioServerTransport());
+}
+
+const testDebug = debug('pw:mcp:test');
+
+async function handleSSE(server: Server, 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}`);
+    const connection = await server.createConnection(transport);
+    res.on('close', () => {
+      testDebug(`delete SSE session: ${transport.sessionId}`);
+      sessions.delete(transport.sessionId);
+      // eslint-disable-next-line no-console
+      void connection.close().catch(e => console.error(e));
+    });
+    return;
+  }
+
+  res.statusCode = 405;
+  res.end('Method not allowed');
+}
+
+async function handleStreamable(server: Server, 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: sessionId => {
+        sessions.set(sessionId, transport);
+      }
+    });
+    transport.onclose = () => {
+      if (transport.sessionId)
+        sessions.delete(transport.sessionId);
+    };
+    await server.createConnection(transport);
+    await transport.handleRequest(req, res);
+    return;
+  }
+
+  res.statusCode = 400;
+  res.end('Invalid request');
+}
+
+export async function startHttpServer(config: { host?: string, port?: number }): Promise<http.Server> {
+  const { host, port } = config;
+  const httpServer = http.createServer();
+  await new Promise<void>((resolve, reject) => {
+    httpServer.on('error', reject);
+    httpServer.listen(port, host, () => {
+      resolve();
+      httpServer.removeListener('error', reject);
+    });
+  });
+  return httpServer;
+}
+
+export function startHttpTransport(httpServer: http.Server, mcpServer: Server) {
+  const sseSessions = new Map<string, SSEServerTransport>();
+  const streamableSessions = new Map<string, StreamableHTTPServerTransport>();
+  httpServer.on('request', async (req, res) => {
+    const url = new URL(`http://localhost${req.url}`);
+    if (url.pathname.startsWith('/mcp'))
+      await handleStreamable(mcpServer, req, res, streamableSessions);
+    else
+      await handleSSE(mcpServer, req, res, url, sseSessions);
+  });
+  const url = httpAddressToString(httpServer.address());
+  const message = [
+    `Listening on ${url}`,
+    'Put this in your client config:',
+    JSON.stringify({
+      'mcpServers': {
+        'playwright': {
+          'url': `${url}/sse`
+        }
+      }
+    }, undefined, 2),
+    'If your client supports streamable HTTP, you can use the /mcp endpoint instead.',
+  ].join('\n');
+    // eslint-disable-next-line no-console
+  console.error(message);
+}
+
+export function httpAddressToString(address: string | AddressInfo | null): string {
+  assert(address, 'Could not bind server socket');
+  if (typeof address === 'string')
+    return address;
+  const resolvedPort = address.port;
+  let resolvedHost = address.family === 'IPv4' ? address.address : `[${address.address}]`;
+  if (resolvedHost === '0.0.0.0' || resolvedHost === '[::]')
+    resolvedHost = 'localhost';
+  return `http://${resolvedHost}:${resolvedPort}`;
+}

tests/basic.spec.ts

@@ -1,254 +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 fs from 'fs/promises';
-import { test, expect } from './fixtures';
-
-test('browser_navigate', async ({ client }) => {
-  expect(await client.callTool({
-    name: 'browser_navigate',
-    arguments: {
-      url: 'data:text/html,<html><title>Title</title><body>Hello, world!</body></html>',
-    },
-  })).toHaveTextContent(`
-Navigated to data:text/html,<html><title>Title</title><body>Hello, world!</body></html>
-
-- Page URL: data:text/html,<html><title>Title</title><body>Hello, world!</body></html>
-- Page Title: Title
-- Page Snapshot
-\`\`\`yaml
-- text: Hello, world!
-\`\`\`
-`
-  );
-});
-
-test('browser_click', async ({ client }) => {
-  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(`Clicked "Submit button"
-
-- 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>',
-    },
-  });
-
-  expect(await client.callTool({
-    name: 'browser_select_option',
-    arguments: {
-      element: 'Select',
-      ref: 's1e3',
-      values: ['bar'],
-    },
-  })).toHaveTextContent(`Selected option in "Select"
-
-- Page URL: data:text/html,<html><title>Title</title><select><option value="foo">Foo</option><option value="bar">Bar</option></select></html>
-- Page Title: Title
-- Page Snapshot
-\`\`\`yaml
-- combobox [ref=s2e3]:
-    - option "Foo" [ref=s2e4]
-    - option "Bar" [selected] [ref=s2e5]
-\`\`\`
-`);
-});
-
-test('browser_select_option (multiple)', async ({ client }) => {
-  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>',
-    },
-  });
-
-  expect(await client.callTool({
-    name: 'browser_select_option',
-    arguments: {
-      element: 'Select',
-      ref: 's1e3',
-      values: ['bar', 'baz'],
-    },
-  })).toHaveTextContent(`Selected option in "Select"
-
-- 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 Title: Title
-- Page Snapshot
-\`\`\`yaml
-- listbox [ref=s2e3]:
-    - option "Foo" [ref=s2e4]
-    - option "Bar" [selected] [ref=s2e5]
-    - option "Baz" [selected] [ref=s2e6]
-\`\`\`
-`);
-});
-
-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>',
-    },
-  })).toContainTextContent('- textbox [ref=s1e3]');
-
-  expect(await client.callTool({
-    name: 'browser_click',
-    arguments: {
-      element: 'Textbox',
-      ref: 's1e3',
-    },
-  })).toContainTextContent('There is a file chooser visible that requires browser_file_upload to be called');
-
-  const filePath = test.info().outputPath('test.txt');
-  await fs.writeFile(filePath, 'Hello, world!');
-
-  {
-    const response = await client.callTool({
-      name: 'browser_file_upload',
-      arguments: {
-        paths: [filePath],
-      },
-    });
-
-    expect(response).not.toContainTextContent('There is a file chooser visible that requires browser_file_upload to be called');
-    expect(response).toContainTextContent('textbox [ref=s3e3]: C:\\fakepath\\test.txt');
-  }
-
-  {
-    const response = await client.callTool({
-      name: 'browser_click',
-      arguments: {
-        element: 'Textbox',
-        ref: 's3e3',
-      },
-    });
-
-    expect(response).toContainTextContent('There is a file chooser visible that requires browser_file_upload to be called');
-    expect(response).toContainTextContent('button "Button" [ref=s4e4]');
-  }
-
-  {
-    const response = await client.callTool({
-      name: 'browser_click',
-      arguments: {
-        element: 'Button',
-        ref: 's4e4',
-      },
-    });
-
-    expect(response, 'not submitting browser_file_upload dismisses file chooser').not.toContainTextContent('There is a file chooser visible that requires browser_file_upload to be called');
-  }
-});
-
-test('browser_type', async ({ client }) => {
-  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,
-    },
-  });
-  const resource = await client.readResource({
-    uri: 'browser://console',
-  });
-  expect(resource.contents).toEqual([{
-    uri: 'browser://console',
-    mimeType: 'text/plain',
-    text: '[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,
-    },
-  });
-  const resource = await client.readResource({
-    uri: 'browser://console',
-  });
-  expect(resource.contents).toEqual([{
-    uri: 'browser://console',
-    mimeType: 'text/plain',
-    text: [
-      '[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>',
-    },
-  });
-
-  const response = await client.callTool({
-    name: 'browser_resize',
-    arguments: {
-      width: 390,
-      height: 780,
-    },
-  });
-  expect(response).toContainTextContent('Resized browser window');
-  expect(response).toContainTextContent('Window size: 390x780');
-});

tests/browser-server.spec.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 path from 'path';
+import url from 'node:url';
+
+import { spawn } from 'child_process';
+import { test as baseTest, expect } from './fixtures.js';
+
+import type { ChildProcess } from 'child_process';
+
+const __filename = url.fileURLToPath(import.meta.url);
+
+const test = baseTest.extend<{ agentEndpoint: (options?: { args?: string[] }) => Promise<{ url: URL, stdout: () => string }> }>({
+  agentEndpoint: async ({}, use) => {
+    let cp: ChildProcess | undefined;
+    await use(async (options?: { args?: string[] }) => {
+      if (cp)
+        throw new Error('Process already running');
+
+      cp = spawn('node', [
+        path.join(path.dirname(__filename), '../lib/browserServer.js'),
+        ...(options?.args || []),
+      ], {
+        stdio: 'pipe',
+        env: {
+          ...process.env,
+          DEBUG: 'pw:mcp:test',
+          DEBUG_COLORS: '0',
+          DEBUG_HIDE_DATE: '1',
+        },
+      });
+      let stdout = '';
+      const url = await new Promise<string>(resolve => cp!.stdout?.on('data', data => {
+        stdout += data.toString();
+        const match = stdout.match(/Listening on (http:\/\/.*)/);
+        if (match)
+          resolve(match[1]);
+      }));
+
+      return { url: new URL(url), stdout: () => stdout };
+    });
+    cp?.kill('SIGTERM');
+  },
+});
+
+test.skip(({ mcpBrowser }) => mcpBrowser !== 'chrome', 'Agent is CDP-only for now');
+
+test('browser lifecycle', async ({ agentEndpoint, startClient, server }) => {
+  const { url: agentUrl } = await agentEndpoint();
+  const { client: client1 } = await startClient({ args: ['--browser-agent', agentUrl.toString()] });
+  expect(await client1.callTool({
+    name: 'browser_navigate',
+    arguments: { url: server.HELLO_WORLD },
+  })).toContainTextContent('Hello, world!');
+
+  const { client: client2 } = await startClient({ args: ['--browser-agent', agentUrl.toString()] });
+  expect(await client2.callTool({
+    name: 'browser_navigate',
+    arguments: { url: server.HELLO_WORLD },
+  })).toContainTextContent('Hello, world!');
+
+  await client1.close();
+  await client2.close();
+});

tests/capabilities.spec.ts

@@ -14,14 +14,17 @@
  * limitations under the License.
  */
 
-import { test, expect } from './fixtures';
+import { test, expect } from './fixtures.js';
 
 test('test snapshot tool list', async ({ client }) => {
   const { tools } = await client.listTools();
   expect(new Set(tools.map(t => t.name))).toEqual(new Set([
     'browser_click',
+    'browser_console_messages',
     'browser_drag',
     'browser_file_upload',
+    'browser_generate_playwright_test',
+    'browser_handle_dialog',
     'browser_hover',
     'browser_select_option',
     'browser_type',
@@ -30,6 +33,7 @@ test('test snapshot tool list', async ({ client }) => {
     'browser_navigate_back',
     'browser_navigate_forward',
     'browser_navigate',
+    'browser_network_requests',
     'browser_pdf_save',
     'browser_press_key',
     'browser_resize',
@@ -39,7 +43,7 @@ test('test snapshot tool list', async ({ client }) => {
     'browser_tab_new',
     'browser_tab_select',
     'browser_take_screenshot',
-    'browser_wait',
+    'browser_wait_for',
   ]));
 });
 
@@ -47,11 +51,15 @@ 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',
@@ -64,22 +72,12 @@ test('test vision tool list', async ({ visionClient }) => {
     'browser_tab_list',
     'browser_tab_new',
     'browser_tab_select',
-    'browser_wait',
+    'browser_wait_for',
   ]));
 });
 
-test('test resources list', async ({ client }) => {
-  const { resources } = await client.listResources();
-  expect(resources).toEqual([
-    expect.objectContaining({
-      uri: 'browser://console',
-      mimeType: 'text/plain',
-    }),
-  ]);
-});
-
 test('test capabilities', async ({ startClient }) => {
-  const client = await startClient({
+  const { client } = await startClient({
     args: ['--caps="core"'],
   });
   const { tools } = await client.listTools();

tests/cdp.spec.ts

@@ -14,30 +14,28 @@
  * limitations under the License.
  */
 
-import { test, expect } from './fixtures';
+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=${cdpEndpoint}`] });
+test.skip(({ mcpMode }) => mcpMode === 'extension', 'Connecting to CDP server is not supported in combination with --extension');
+
+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>',
-    },
-  })).toHaveTextContent(`
-Navigated to data:text/html,<html><title>Title</title><body>Hello, world!</body></html>
-
-- Page URL: data:text/html,<html><title>Title</title><body>Hello, world!</body></html>
-- Page Title: Title
-- Page Snapshot
-\`\`\`yaml
-- text: Hello, world!
-\`\`\`
-`
-  );
+    arguments: { url: server.HELLO_WORLD },
+  })).toContainTextContent(`- generic [ref=e1]: Hello, world!`);
 });
 
-test('cdp server reuse tab', async ({ cdpEndpoint, startClient }) => {
-  const client = await startClient({ args: [`--cdp-endpoint=${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',
@@ -45,17 +43,52 @@ 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 current snapshot available. Capture a snapshot or navigate to a new location first.`);
 
   expect(await client.callTool({
     name: 'browser_snapshot',
-    arguments: {},
   })).toHaveTextContent(`
-- Page URL: data:text/html,hello world
-- Page Title: 
+- Ran Playwright code:
+\`\`\`js
+// <internal code to capture accessibility snapshot>
+\`\`\`
+
+- Page URL: ${server.HELLO_WORLD}
+- Page Title: Title
 - Page Snapshot
 \`\`\`yaml
-- text: hello world
+- generic [ref=e1]: Hello, world!
 \`\`\`
 `);
 });
+
+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: server.PREFIX },
+  })).toContainTextContent(`Error: browserType.connectOverCDP: connect ECONNREFUSED`);
+  await cdpServer.start();
+  expect(await client.callTool({
+    name: 'browser_navigate',
+    arguments: { url: server.PREFIX },
+  })).toContainTextContent(`- generic [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/config.spec.ts

@@ -0,0 +1,65 @@
+/**
+ * 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) => {
+  test.skip(mcpMode === 'extension', 'Connecting to CDP server does not use user data dir');
+  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) => {
+    test.skip(mcpMode === 'extension', 'Extension mode only supports Chromium');
+    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`);
+  });
+});

tests/console.spec.ts

@@ -14,22 +14,31 @@
  * limitations under the License.
  */
 
-import { test, expect } from './fixtures';
+import { test, expect } from './fixtures.js';
+
+test('browser_console_messages', async ({ client, server }) => {
+  server.setContent('/', `
+    <!DOCTYPE html>
+    <html>
+      <script>
+        console.log("Hello, world!");
+        console.error("Error");
+      </script>
+    </html>
+  `, 'text/html');
 
-test('browser://console', async ({ client }) => {
   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.readResource({
-    uri: 'browser://console',
+  const resource = await client.callTool({
+    name: 'browser_console_messages',
   });
-  expect(resource.contents).toEqual([{
-    uri: 'browser://console',
-    mimeType: 'text/plain',
-    text: '[LOG] Hello, world!\n[ERROR] Error',
-  }]);
+  expect(resource).toHaveTextContent([
+    '[LOG] Hello, world!',
+    '[ERROR] Error',
+  ].join('\n'));
 });

tests/core.spec.ts

@@ -0,0 +1,277 @@
+/**
+ * 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_navigate', async ({ client, server }) => {
+  expect(await client.callTool({
+    name: 'browser_navigate',
+    arguments: { url: server.HELLO_WORLD },
+  })).toHaveTextContent(`
+- Ran Playwright code:
+\`\`\`js
+// Navigate to ${server.HELLO_WORLD}
+await page.goto('${server.HELLO_WORLD}');
+\`\`\`
+
+- Page URL: ${server.HELLO_WORLD}
+- Page Title: Title
+- Page Snapshot
+\`\`\`yaml
+- generic [ref=e1]: Hello, world!
+\`\`\`
+`
+  );
+});
+
+test('browser_click', async ({ client, server }) => {
+  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 URL: ${server.PREFIX}
+- Page Title: Title
+- Page Snapshot
+\`\`\`yaml
+- button "Submit" [ref=e2]
+\`\`\`
+`);
+});
+
+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: server.PREFIX },
+  });
+
+  expect(await client.callTool({
+    name: 'browser_select_option',
+    arguments: {
+      element: 'Select',
+      ref: 'e2',
+      values: ['bar'],
+    },
+  })).toHaveTextContent(`
+- Ran Playwright code:
+\`\`\`js
+// Select options [bar] in Select
+await page.getByRole('combobox').selectOption(['bar']);
+\`\`\`
+
+- Page URL: ${server.PREFIX}
+- Page Title: Title
+- Page Snapshot
+\`\`\`yaml
+- combobox [ref=e2]:
+  - option "Foo"
+  - option "Bar" [selected]
+\`\`\`
+`);
+});
+
+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: server.PREFIX },
+  });
+
+  expect(await client.callTool({
+    name: 'browser_select_option',
+    arguments: {
+      element: 'Select',
+      ref: 'e2',
+      values: ['bar', 'baz'],
+    },
+  })).toHaveTextContent(`
+- Ran Playwright code:
+\`\`\`js
+// Select options [bar, baz] in Select
+await page.getByRole('listbox').selectOption(['bar', 'baz']);
+\`\`\`
+
+- Page URL: ${server.PREFIX}
+- Page Title: Title
+- Page Snapshot
+\`\`\`yaml
+- listbox [ref=e2]:
+  - option "Foo" [ref=e3]
+  - option "Bar" [selected] [ref=e4]
+  - option "Baz" [selected] [ref=e5]
+\`\`\`
+`);
+});
+
+test('browser_type', async ({ client, server }) => {
+  server.setContent('/', `
+    <!DOCTYPE html>
+    <html>
+      <input type='keypress' onkeypress="console.log('Key pressed:', event.key, ', Text:', event.target.value)"></input>
+    </html>
+  `, 'text/html');
+
+  await client.callTool({
+    name: 'browser_navigate',
+    arguments: {
+      url: server.PREFIX,
+    },
+  });
+  await client.callTool({
+    name: 'browser_type',
+    arguments: {
+      element: 'textbox',
+      ref: 'e2',
+      text: 'Hi!',
+      submit: true,
+    },
+  });
+  expect(await client.callTool({
+    name: 'browser_console_messages',
+  })).toHaveTextContent('[LOG] Key pressed: Enter , Text: Hi!');
+});
+
+test('browser_type (slowly)', async ({ client, server }) => {
+  server.setContent('/', `
+    <input type='text' onkeydown="console.log('Key pressed:', event.key, 'Text:', event.target.value)"></input>
+  `, 'text/html');
+
+  await client.callTool({
+    name: 'browser_navigate',
+    arguments: {
+      url: server.PREFIX,
+    },
+  });
+  await client.callTool({
+    name: 'browser_type',
+    arguments: {
+      element: 'textbox',
+      ref: 'e2',
+      text: 'Hi!',
+      submit: true,
+      slowly: true,
+    },
+  });
+  expect(await client.callTool({
+    name: 'browser_console_messages',
+  })).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, 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: server.PREFIX },
+  });
+
+  const response = await client.callTool({
+    name: 'browser_resize',
+    arguments: {
+      width: 390,
+      height: 780,
+    },
+  });
+  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' })).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 not found');
+});

tests/device.spec.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 { test, expect } from './fixtures.js';
+
+test('--device should work', async ({ startClient, server, mcpMode }) => {
+  test.skip(mcpMode === 'extension', 'Viewport is not supported when connecting via CDP. There we re-use the browser viewport.');
+  const { client } = await startClient({
+    args: ['--device', 'iPhone 15'],
+  });
+
+  server.route('/', (req, res) => {
+    res.writeHead(200, { 'Content-Type': 'text/html' });
+    res.end(`
+      <head>
+        <meta name="viewport" content="width=device-width, initial-scale=1">
+      </head>
+      <body></body>
+      <script>
+        document.body.textContent = window.innerWidth + "x" + window.innerHeight;
+      </script>
+    `);
+  });
+
+  expect(await client.callTool({
+    name: 'browser_navigate',
+    arguments: {
+      url: server.PREFIX,
+    },
+  })).toContainTextContent(`393x659`);
+});

tests/dialogs.spec.ts

@@ -0,0 +1,212 @@
+/**
+ * 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';
+
+// https://github.com/microsoft/playwright/issues/35663
+test.skip(({ mcpBrowser, mcpHeadless }) => mcpBrowser === 'webkit' && mcpHeadless);
+
+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: 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).toHaveTextContent(`- Ran Playwright code:
+\`\`\`js
+// <internal code to handle "alert" dialog>
+\`\`\`
+
+- Page URL: ${server.PREFIX}
+- Page Title: 
+- Page Snapshot
+\`\`\`yaml
+- button "Button" [ref=e2]
+\`\`\`
+`);
+});
+
+test('two alert dialogs', async ({ client, server }) => {
+  test.fixme(true, 'Race between the dialog and ariaSnapshot');
+
+  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: 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 1"]: 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');
+});
+
+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`);
+
+  const result = await client.callTool({
+    name: 'browser_handle_dialog',
+    arguments: {
+      accept: true,
+    },
+  });
+
+  expect(result).not.toContainTextContent('### Modal state');
+  expect(result).toContainTextContent('// <internal code to handle "confirm" dialog>');
+  expect(result).toContainTextContent(`- Page Snapshot
+\`\`\`yaml
+- generic [ref=e1]: "true"
+\`\`\``);
+});
+
+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: 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`);
+
+  const result = await client.callTool({
+    name: 'browser_handle_dialog',
+    arguments: {
+      accept: false,
+    },
+  });
+
+  expect(result).toContainTextContent(`- Page Snapshot
+\`\`\`yaml
+- generic [ref=e1]: "false"
+\`\`\``);
+});
+
+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: server.PREFIX },
+  })).toContainTextContent('- button "Button" [ref=e2]');
+
+  expect(await client.callTool({
+    name: 'browser_click',
+    arguments: {
+      element: 'Button',
+      ref: 'e2',
+    },
+  })).toContainTextContent(`### Modal state
+- ["prompt" dialog with message "Prompt"]: can be handled by the "browser_handle_dialog" tool`);
+
+  const result = await client.callTool({
+    name: 'browser_handle_dialog',
+    arguments: {
+      accept: true,
+      promptText: 'Answer',
+    },
+  });
+
+  expect(result).toContainTextContent(`- Page Snapshot
+\`\`\`yaml
+- generic [ref=e1]: Answer
+\`\`\``);
+});

tests/extension.spec.ts

@@ -0,0 +1,43 @@
+/**
+ * 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 url from 'url';
+import path from 'path';
+import { spawnSync } from 'child_process';
+
+import { test, expect } from './fixtures.js';
+
+import { createConnection } from '@playwright/mcp';
+
+test.skip(({ mcpMode }) => mcpMode !== 'extension');
+
+test('does not allow --cdp-endpoint', async ({  startClient }) => {
+  await expect(createConnection({
+    browser: { browserName: 'firefox' },
+    ...({ extension: true })
+  })).rejects.toThrow(/Extension mode is only supported for Chromium browsers/);
+});
+
+// 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', '--extension',
+  ]);
+  expect(result.error).toBeUndefined();
+  expect(result.status).toBe(1);
+  expect(result.stderr.toString()).toContain('Device emulation is not supported with extension mode.');
+});

tests/files.spec.ts

@@ -0,0 +1,149 @@
+/**
+ * Copyright (c) Microsoft Corporation.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+import { test, expect } from './fixtures.js';
+import fs from 'fs/promises';
+
+test('browser_file_upload', async ({ client, server }, testInfo) => {
+  server.setContent('/', `
+    <input type="file" />
+    <button>Button</button>
+  `, 'text/html');
+
+  expect(await client.callTool({
+    name: 'browser_navigate',
+    arguments: { url: server.PREFIX },
+  })).toContainTextContent(`
+\`\`\`yaml
+- generic [ref=e1]:
+  - button "Choose File" [ref=e2]
+  - button "Button" [ref=e3]
+\`\`\``);
+
+  {
+    expect(await client.callTool({
+      name: 'browser_file_upload',
+      arguments: { paths: [] },
+    })).toHaveTextContent(`
+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());
+  }
+
+  expect(await client.callTool({
+    name: 'browser_click',
+    arguments: {
+      element: 'Textbox',
+      ref: 'e2',
+    },
+  })).toContainTextContent(`### Modal state
+- [File chooser]: can be handled by the "browser_file_upload" tool`);
+
+  const filePath = testInfo.outputPath('test.txt');
+  await fs.writeFile(filePath, 'Hello, world!');
+
+  {
+    const response = await client.callTool({
+      name: 'browser_file_upload',
+      arguments: {
+        paths: [filePath],
+      },
+    });
+
+    expect(response).not.toContainTextContent('### Modal state');
+    expect(response).toContainTextContent(`
+\`\`\`yaml
+- generic [ref=e1]:
+  - button "Choose File" [ref=e2]
+  - button "Button" [ref=e3]
+\`\`\``);
+  }
+
+  {
+    const response = await client.callTool({
+      name: 'browser_click',
+      arguments: {
+        element: 'Textbox',
+        ref: 'e2',
+      },
+    });
+
+    expect(response).toContainTextContent('- [File chooser]: can be handled by the \"browser_file_upload\" tool');
+  }
+
+  {
+    const response = await client.callTool({
+      name: 'browser_click',
+      arguments: {
+        element: 'Button',
+        ref: 'e3',
+      },
+    });
+
+    expect(response).toContainTextContent(`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, server, mcpMode }, testInfo) => {
+  test.fixme(mcpMode === 'extension', 'Downloads are on the Browser CDP domain and not supported with --extension');
+  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) => {
+  test.fixme(mcpMode === 'extension', 'Downloads are on the Browser CDP domain and not supported with --extension');
+  const { client } = await startClient({
+    config: { outputDir: testInfo.outputPath('output') },
+  });
+
+  test.skip(mcpBrowser === 'webkit' && process.platform === 'linux', 'https://github.com/microsoft/playwright/blob/8e08fdb52c27bb75de9bf87627bf740fadab2122/tests/library/download.spec.ts#L436');
+  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: server.PREFIX + 'download',
+    },
+  })).toContainTextContent('### Downloads');
+});

tests/fixtures.ts

@@ -14,48 +14,99 @@
  * limitations under the License.
  */
 
+import fs from 'fs';
+import url from 'url';
 import path from 'path';
+import net from 'net';
 import { chromium } from 'playwright';
+import { fork } from 'child_process';
 
 import { test as baseTest, expect as baseExpect } from '@playwright/test';
 import { StdioClientTransport } from '@modelcontextprotocol/sdk/client/stdio.js';
+import { SSEClientTransport } from '@modelcontextprotocol/sdk/client/sse.js';
 import { Client } from '@modelcontextprotocol/sdk/client/index.js';
-import { spawn } from 'child_process';
+import { TestServer } from './testserver/index.ts';
+import { ManualPromise } from '../src/manualPromise.js';
 
-type Fixtures = {
-  client: Client;
-  visionClient: Client;
-  startClient: (options?: { args?: string[] }) => Promise<Client>;
-  wsEndpoint: string;
-  cdpEndpoint: string;
+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' | 'extension' | undefined;
 };
 
-export const test = baseTest.extend<Fixtures>({
+type CDPServer = {
+  endpoint: string;
+  start: () => Promise<BrowserContext>;
+};
+
+type TestFixtures = {
+  client: Client;
+  visionClient: Client;
+  startClient: (options?: { clientName?: string, args?: string[], config?: Config }) => Promise<{ client: Client, stderr: () => string }>;
+  wsEndpoint: string;
+  cdpServer: CDPServer;
+  server: TestServer;
+  httpsServer: TestServer;
+  mcpHeadless: boolean;
+  startMcpExtension: (relayServerURL: string) => Promise<void>;
+};
+
+type WorkerFixtures = {
+  _workerServers: { server: TestServer, httpsServer: TestServer };
+};
+
+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'] }));
+    const { client } = await startClient({ args: ['--vision'] });
+    await use(client);
   },
 
-  startClient: async ({ }, use, testInfo) => {
-    const userDataDir = testInfo.outputPath('user-data-dir');
-    let client: StdioClientTransport | undefined;
+  startClient: async ({ mcpHeadless, mcpBrowser, mcpMode, startMcpExtension }, use, testInfo) => {
+    const userDataDir = mcpMode !== 'docker' ? testInfo.outputPath('user-data-dir') : undefined;
+    const configDir = path.dirname(test.info().config.configFile!);
+    let client: Client | undefined;
 
-    use(async options => {
-      const args = ['--headless', '--user-data-dir', userDataDir];
+    await use(async options => {
+      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)
+        args.push(`--browser=${mcpBrowser}`);
       if (options?.args)
         args.push(...options.args);
-      const transport = new StdioClientTransport({
-        command: 'node',
-        args: [path.join(__dirname, '../cli.js'), ...args],
+      if (options?.config) {
+        const configFile = testInfo.outputPath('config.json');
+        await fs.promises.writeFile(configFile, JSON.stringify(options.config, null, 2));
+        args.push(`--config=${path.relative(configDir, configFile)}`);
+      }
+
+      client = new Client({ name: options?.clientName ?? 'test', version: '1.0.0' });
+      const { transport, stderr, relayServerURL } = await createTransport(args, mcpMode);
+      let stderrBuffer = '';
+      stderr?.on('data', data => {
+        if (process.env.PWMCP_DEBUG)
+          process.stderr.write(data);
+        stderrBuffer += data.toString();
       });
-      const client = new Client({ name: 'test', version: '1.0.0' });
       await client.connect(transport);
+      if (mcpMode === 'extension')
+        await startMcpExtension(relayServerURL!);
       await client.ping();
-      return client;
+      return { client, stderr: () => stderrBuffer };
     });
 
     await client?.close();
@@ -67,30 +118,166 @@ export const test = baseTest.extend<Fixtures>({
     await browserServer.close();
   },
 
-  cdpEndpoint: async ({ }, use, testInfo) => {
-    const port = 3200 + (+process.env.TEST_PARALLEL_INDEX!);
-    const executablePath = chromium.executablePath();
-    const browserProcess = spawn(executablePath, [
-      `--user-data-dir=${testInfo.outputPath('user-data-dir')}`,
-      `--remote-debugging-port=${port}`,
-      `--no-first-run`,
-      `--no-sandbox`,
-      `--headless`,
-      `data:text/html,hello world`,
-    ], {
-      stdio: 'pipe',
+  cdpServer: async ({ mcpBrowser }, use, testInfo) => {
+    test.skip(!['chrome', 'msedge', 'chromium'].includes(mcpBrowser!), 'CDP is not supported for non-Chromium browsers');
+
+    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 browserContext;
+      }
     });
-    await new Promise<void>(resolve => {
-      browserProcess.stderr.on('data', data => {
-        if (data.toString().includes('DevTools listening on '))
-          resolve();
+    await browserContext?.close();
+  },
+
+  mcpHeadless: async ({ headless }, use) => {
+    await use(headless);
+  },
+
+  mcpBrowser: ['chrome', { option: true }],
+
+  mcpMode: [undefined, { option: true }],
+
+  startMcpExtension: async ({ mcpMode, mcpHeadless }, use) => {
+    let context: BrowserContext | undefined;
+    await use(async (relayServerURL: string) => {
+      if (mcpMode !== 'extension')
+        throw new Error('Must be running in MCP extension mode to use this fixture.');
+      const cdpPort = await findFreePort();
+      const pathToExtension = path.join(url.fileURLToPath(import.meta.url), '../../extension');
+      context = await chromium.launchPersistentContext('', {
+        headless: mcpHeadless,
+        args: [
+          `--disable-extensions-except=${pathToExtension}`,
+          `--load-extension=${pathToExtension}`,
+          '--enable-features=AllowContentInitiatedDataUrlNavigations',
+        ],
+        channel: 'chromium',
+        ...{ assistantMode: true, cdpPort },
       });
+      const popupPage = await context.newPage();
+      const page = context.pages()[0];
+      await page.bringToFront();
+      // Do not auto dismiss dialogs.
+      page.on('dialog', () => { });
+      await expect.poll(() => context?.serviceWorkers()).toHaveLength(1);
+      // Connect to the relay server.
+      await popupPage.goto(new URL('/popup.html', context.serviceWorkers()[0].url()).toString());
+      await popupPage.getByRole('textbox', { name: 'Bridge Server URL:' }).clear();
+      await popupPage.getByRole('textbox', { name: 'Bridge Server URL:' }).fill(relayServerURL);
+      await popupPage.getByRole('button', { name: 'Share This Tab' }).click();
     });
-    await use(`http://localhost:${port}`);
-    browserProcess.kill();
+    await context?.close();
+  },
+
+  _workerServers: [async ({ }, use, workerInfo) => {
+    const port = 8907 + workerInfo.workerIndex * 4;
+    const server = await TestServer.create(port);
+
+    const httpsPort = port + 1;
+    const httpsServer = await TestServer.createHTTPS(httpsPort);
+
+    await use({ server, httpsServer });
+
+    await Promise.all([
+      server.stop(),
+      httpsServer.stop(),
+    ]);
+  }, { scope: 'worker' }],
+
+  server: async ({ _workerServers }, use) => {
+    _workerServers.server.reset();
+    await use(_workerServers.server);
+  },
+
+  httpsServer: async ({ _workerServers }, use) => {
+    _workerServers.httpsServer.reset();
+    await use(_workerServers.httpsServer);
   },
 });
 
+async function createTransport(args: string[], mcpMode: TestOptions['mcpMode']): Promise<{
+  transport: Transport,
+  stderr: Stream | null,
+  relayServerURL?: string,
+}> {
+  // 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,
+    };
+  }
+  if (mcpMode === 'extension') {
+    const relay = fork(path.join(__filename, '../../cli.js'), [...args, '--extension', '--port=0'], {
+      stdio: 'pipe'
+    });
+    const cdpRelayServerReady = new ManualPromise<string>();
+    const sseEndpointPromise = new ManualPromise<string>();
+    let stderrBuffer = '';
+    relay.stderr!.on('data', data => {
+      stderrBuffer += data.toString();
+      const match = stderrBuffer.match(/Listening on (http:\/\/.*)/);
+      if (match)
+        sseEndpointPromise.resolve(match[1].toString());
+      const extensionMatch = stderrBuffer.match(/CDP relay server started on (ws:\/\/.*\/extension)/);
+      if (extensionMatch)
+        cdpRelayServerReady.resolve(extensionMatch[1].toString());
+    });
+    relay.on('exit', () => {
+      sseEndpointPromise.reject(new Error(`Process exited`));
+      cdpRelayServerReady.reject(new Error(`Process exited`));
+    });
+    const relayServerURL = await cdpRelayServerReady;
+    const sseEndpoint = await sseEndpointPromise;
+
+    const transport = new SSEClientTransport(new URL(sseEndpoint));
+    // We cannot just add  transport.onclose here as Client.connect() overrides it.
+    const origClose = transport.close;
+    transport.close = async () => {
+      await origClose.call(transport);
+      relay.kill();
+    };
+    return {
+      transport,
+      stderr: relay.stderr!,
+      relayServerURL,
+    };
+  }
+
+  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({
@@ -144,3 +331,18 @@ export const expect = baseExpect.extend({
     };
   },
 });
+
+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);
+  });
+}
+
+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

@@ -0,0 +1,50 @@
+/**
+ * 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';
+
+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) => {
+        res.writeHead(200, { 'Content-Type': 'text/html' });
+        res.end(`
+          <body></body>
+          <script>
+            document.body.textContent = navigator.userAgent;
+          </script>
+        `);
+      });
+
+      const response = await client.callTool({
+        name: 'browser_navigate',
+        arguments: {
+          url: server.PREFIX,
+        },
+      });
+
+      expect(response).toContainTextContent(`Mozilla/5.0`);
+      if (mcpHeadless)
+        expect(response).toContainTextContent(`HeadlessChrome`);
+      else
+        expect(response).not.toContainTextContent(`HeadlessChrome`);
+    });
+  });
+}

tests/iframes.spec.ts

@@ -14,7 +14,7 @@
  * limitations under the License.
  */
 
-import { test, expect } from './fixtures';
+import { test, expect } from './fixtures.js';
 
 test('stitched aria frames', async ({ client }) => {
   expect(await client.callTool({
@@ -24,20 +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 [ref=e1]:
+  - heading "Hello" [level=1] [ref=e2]
+  - iframe [ref=e3]:
+    - generic [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('Clicked "World"');
+  })).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 pages available.`);
+});

tests/launch.spec.ts

@@ -14,44 +14,146 @@
  * limitations under the License.
  */
 
-import { test, expect } from './fixtures';
+import fs from 'fs';
 
-test('test reopen browser', async ({ client }) => {
+import { test, expect, formatOutput } from './fixtures.js';
+
+test.skip(({ mcpMode }) => mcpMode === 'extension', 'launch scenarios are not supported with --extension - the browser is already launched');
+
+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',
-  })).toHaveTextContent('Page closed');
+  })).toContainTextContent('Browser closed successfully.');
 
   expect(await client.callTool({
     name: 'browser_navigate',
-    arguments: {
-      url: 'data:text/html,<html><title>Title</title><body>Hello, world!</body></html>',
-    },
-  })).toHaveTextContent(`
-Navigated to data:text/html,<html><title>Title</title><body>Hello, world!</body></html>
+    arguments: { url: server.HELLO_WORLD },
+  })).toContainTextContent(`- generic [ref=e1]: Hello, world!`);
 
-- Page URL: data:text/html,<html><title>Title</title><body>Hello, world!</body></html>
-- Page Title: Title
-- Page Snapshot
-\`\`\`yaml
-- text: 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 { test, expect } from './fixtures.js';
+import fs from 'node:fs/promises';
+import child_process from 'node:child_process';
+
+test('library can be used from CommonJS', { annotation: { type: 'issue', description: 'https://github.com/microsoft/playwright-mcp/issues/456' } }, async ({}, testInfo) => {
+  const file = testInfo.outputPath('main.cjs');
+  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

@@ -0,0 +1,45 @@
+/**
+ * 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_network_requests', async ({ client, server }) => {
+  server.setContent('/', `
+    <button onclick="fetch('/json')">Click me</button>
+  `, 'text/html');
+
+  server.setContent('/json', JSON.stringify({ name: 'John Doe' }), 'application/json');
+
+  await client.callTool({
+    name: 'browser_navigate',
+    arguments: {
+      url: server.PREFIX,
+    },
+  });
+
+  await client.callTool({
+    name: 'browser_click',
+    arguments: {
+      element: 'Click me button',
+      ref: 'e2',
+    },
+  });
+
+  await expect.poll(() => client.callTool({
+    name: 'browser_network_requests',
+  })).toHaveTextContent(`[GET] ${`${server.PREFIX}`} => [200] OK
+[GET] ${`${server.PREFIX}json`} => [200] OK`);
+});

tests/pdf.spec.ts

@@ -14,15 +14,15 @@
  * limitations under the License.
  */
 
-import { test, expect } from './fixtures';
+import fs from 'fs';
 
-test('save as pdf unavailable', async ({ startClient }) => {
-  const client = await startClient({ args: ['--caps="no-pdf"'] });
+import { test, expect } from './fixtures.js';
+
+test('save as pdf unavailable', async ({ startClient, server }) => {
+  const { client } = await startClient({ args: ['--caps="no-pdf"'] });
   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,26 +30,54 @@ test('save as pdf unavailable', async ({ startClient }) => {
   })).toHaveTextContent(/Tool \"browser_pdf_save\" not found/);
 });
 
-test('save as pdf', async ({ client }) => {
+test('save as pdf', async ({ startClient, mcpBrowser, server }, testInfo) => {
+  const { client } = await startClient({
+    config: { outputDir: testInfo.outputPath('output') },
+  });
+
+  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>',
-    },
-  })).toHaveTextContent(`
-Navigated to data:text/html,<html><title>Title</title><body>Hello, world!</body></html>
-
-- Page URL: data:text/html,<html><title>Title</title><body>Hello, world!</body></html>
-- Page Title: Title
-- Page Snapshot
-\`\`\`yaml
-- text: Hello, world!
-\`\`\`
-`
-  );
+    arguments: { url: server.HELLO_WORLD },
+  })).toContainTextContent(`- generic [ref=e1]: Hello, world!`);
 
   const response = await client.callTool({
     name: 'browser_pdf_save',
   });
-  expect(response).toHaveTextContent(/^Saved as.*page-[^:]+.pdf$/);
+  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 },
+  });
+
+  expect(await client.callTool({
+    name: 'browser_navigate',
+    arguments: { url: server.HELLO_WORLD },
+  })).toContainTextContent(`- generic [ref=e1]: Hello, world!`);
+
+  expect(await client.callTool({
+    name: 'browser_pdf_save',
+    arguments: {
+      filename: 'output.pdf',
+    },
+  })).toEqual({
+    content: [
+      {
+        type: 'text',
+        text: expect.stringContaining(`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

@@ -0,0 +1,232 @@
+/**
+ * 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 { test, expect } from './fixtures.js';
+
+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: server.HELLO_WORLD },
+  })).toContainTextContent(`Navigate to http://localhost`);
+
+  expect(await client.callTool({
+    name: 'browser_take_screenshot',
+  })).toEqual({
+    content: [
+      {
+        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 ({ 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]`);
+
+  expect(await client.callTool({
+    name: 'browser_take_screenshot',
+    arguments: {
+      element: 'hello button',
+      ref: 'e1',
+    },
+  })).toEqual({
+    content: [
+      {
+        data: expect.any(String),
+        mimeType: 'image/jpeg',
+        type: 'image',
+      },
+      {
+        text: expect.stringContaining(`page.getByText('Hello, world!').screenshot`),
+        type: 'text',
+      },
+    ],
+  });
+});
+
+test('--output-dir should work', 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`);
+
+  await client.callTool({
+    name: 'browser_take_screenshot',
+  });
+
+  expect(fs.existsSync(outputDir)).toBeTruthy();
+  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$/);
+});
+
+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: [
+        {
+          data: expect.any(String),
+          mimeType: `image/${ext}`,
+          type: 'image',
+        },
+        {
+          text: expect.stringMatching(
+              new RegExp(`page-\\d{4}-\\d{2}-\\d{2}T\\d{2}-\\d{2}-\\d{2}\\-\\d{3}Z\\.${ext}`)
+          ),
+          type: 'text',
+        },
+      ],
+    });
+
+    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: [
+      {
+        data: expect.any(String),
+        mimeType: 'image/jpeg',
+        type: 'image',
+      },
+      {
+        text: expect.stringContaining(`output.jpeg`),
+        type: 'text',
+      },
+    ],
+  });
+
+  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: server.HELLO_WORLD },
+  })).toContainTextContent(`Navigate to http://localhost`);
+
+  await client.callTool({
+    name: 'browser_take_screenshot',
+  });
+
+  expect(await client.callTool({
+    name: 'browser_take_screenshot',
+  })).toEqual({
+    content: [
+      {
+        text: expect.stringContaining(`Screenshot viewport and save it as`),
+        type: 'text',
+      },
+    ],
+  });
+});
+
+test('browser_take_screenshot (cursor)', async ({ startClient, server }, testInfo) => {
+  const outputDir = testInfo.outputPath('output');
+
+  const { client } = await startClient({
+    clientName: 'cursor:vscode',
+    config: { outputDir },
+  });
+
+  expect(await client.callTool({
+    name: 'browser_navigate',
+    arguments: { url: server.HELLO_WORLD },
+  })).toContainTextContent(`Navigate to http://localhost`);
+
+  await client.callTool({
+    name: 'browser_take_screenshot',
+  });
+
+  expect(await client.callTool({
+    name: 'browser_take_screenshot',
+  })).toEqual({
+    content: [
+      {
+        text: expect.stringContaining(`Screenshot viewport and save it as`),
+        type: 'text',
+      },
+    ],
+  });
+});

tests/sse.spec.ts

@@ -14,29 +14,235 @@
  * limitations under the License.
  */
 
-import { spawn } from 'node:child_process';
+import fs from 'node:fs';
+import url from 'node:url';
+
+import { ChildProcess, spawn } from 'node:child_process';
 import path from 'node:path';
-import { test } from './fixtures';
+import { SSEClientTransport } from '@modelcontextprotocol/sdk/client/sse.js';
+import { StreamableHTTPClientTransport } from '@modelcontextprotocol/sdk/client/streamableHttp.js';
+import { Client } from '@modelcontextprotocol/sdk/client/index.js';
 
-test('sse transport', async () => {
-  const cp = spawn('node', [path.join(__dirname, '../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:\/\/.*)/);
-      if (match)
-        resolve(match[1]);
-    }));
+import { test as baseTest, expect } from './fixtures.js';
+import type { Config } from '../config.d.ts';
 
-    // 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(url));
-    const client = new Client({ name: 'test', version: '1.0.0' });
-    await client.connect(transport);
-    await client.ping();
-  } finally {
-    cp.kill();
-  }
+// NOTE: Can be removed when we drop Node.js 18 support and changed to import.meta.filename.
+const __filename = url.fileURLToPath(import.meta.url);
+
+baseTest.skip(({ mcpMode }) => mcpMode === 'extension', 'Extension tests run via SSE anyways');
+
+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('sse transport', async ({ serverEndpoint }) => {
+  const { url } = await serverEndpoint();
+  const transport = new SSEClientTransport(url);
+  const client = new Client({ name: 'test', version: '1.0.0' });
+  await client.connect(transport);
+  await client.ping();
+});
+
+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(url);
+  const client = new Client({ name: 'test', version: '1.0.0' });
+  await client.connect(transport);
+  await client.ping();
+});
+
+test('sse transport browser lifecycle (isolated)', async ({ serverEndpoint, server }) => {
+  const { url, stderr } = await serverEndpoint({ args: ['--isolated'] });
+
+  const transport1 = new SSEClientTransport(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(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(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(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(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(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(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(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(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('streamable 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();
+  expect(transport.sessionId, 'has session support').toBeDefined();
 });

tests/tabs.spec.ts

@@ -14,9 +14,7 @@
  * limitations under the License.
  */
 
-import { chromium } from 'playwright';
-
-import { test, expect } from './fixtures';
+import { test, expect } from './fixtures.js';
 
 import type { Client } from '@modelcontextprotocol/sdk/client/index.js';
 
@@ -29,32 +27,60 @@ async function createTab(client: Client, title: string, body: string) {
   });
 }
 
+test.skip(({ mcpMode }) => mcpMode === 'extension', 'Multi-tab scenarios are not supported with --extension');
+
+test('list initial tabs', async ({ client }) => {
+  expect(await client.callTool({
+    name: 'browser_tab_list',
+  })).toHaveTextContent(`### Open tabs
+- 1: (current) [] (about:blank)`);
+});
+
+test('list first tab', async ({ client }) => {
+  await createTab(client, 'Tab one', 'Body one');
+  expect(await client.callTool({
+    name: 'browser_tab_list',
+  })).toHaveTextContent(`### Open tabs
+- 1: [] (about:blank)
+- 2: (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(`
-Open tabs:
+- Ran Playwright code:
+\`\`\`js
+// <internal code to open a new tab>
+\`\`\`
+
+### Open tabs
 - 1: [] (about:blank)
 - 2: (current) [Tab one] (data:text/html,<title>Tab one</title><body>Body one</body>)
 
-Current tab:
+### Current tab
 - Page URL: data:text/html,<title>Tab one</title><body>Body one</body>
 - Page Title: Tab one
 - Page Snapshot
 \`\`\`yaml
-- text: Body one
+- generic [ref=e1]: Body one
 \`\`\``);
 
   expect(await createTab(client, 'Tab two', 'Body two')).toHaveTextContent(`
-Open tabs:
+- Ran Playwright code:
+\`\`\`js
+// <internal code to open a new tab>
+\`\`\`
+
+### 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:
+### Current tab
 - Page URL: data:text/html,<title>Tab two</title><body>Body two</body>
 - Page Title: Tab two
 - Page Snapshot
 \`\`\`yaml
-- text: Body two
+- generic [ref=e1]: Body two
 \`\`\``);
 });
 
@@ -67,17 +93,22 @@ test('select tab', async ({ client }) => {
       index: 2,
     },
   })).toHaveTextContent(`
-Open tabs:
+- Ran Playwright code:
+\`\`\`js
+// <internal code to select tab 2>
+\`\`\`
+
+### 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:
+### Current tab
 - Page URL: data:text/html,<title>Tab one</title><body>Body one</body>
 - Page Title: Tab one
 - Page Snapshot
 \`\`\`yaml
-- text: Body one
+- generic [ref=e1]: Body one
 \`\`\``);
 });
 
@@ -90,30 +121,32 @@ test('close tab', async ({ client }) => {
       index: 3,
     },
   })).toHaveTextContent(`
-Open tabs:
+- Ran Playwright code:
+\`\`\`js
+// <internal code to close tab 3>
+\`\`\`
+
+### Open tabs
 - 1: [] (about:blank)
 - 2: (current) [Tab one] (data:text/html,<title>Tab one</title><body>Body one</body>)
 
-Current tab:
+### Current tab
 - Page URL: data:text/html,<title>Tab one</title><body>Body one</body>
 - Page Title: Tab one
 - Page Snapshot
 \`\`\`yaml
-- text: Body one
+- generic [ref=e1]: Body one
 \`\`\``);
 });
 
-test('reuse first tab when navigating', async ({ startClient, cdpEndpoint }) => {
-  const browser = await chromium.connectOverCDP(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=${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/cert.pem

@@ -0,0 +1,29 @@
+-----BEGIN CERTIFICATE-----
+MIIFCjCCAvKgAwIBAgIULU/gkDm8IqC7PG8u3RID0AYyP6gwDQYJKoZIhvcNAQEL
+BQAwGjEYMBYGA1UEAwwPcGxheXdyaWdodC10ZXN0MB4XDTIzMDgxMDIyNTc1MFoX
+DTMzMDgwNzIyNTc1MFowGjEYMBYGA1UEAwwPcGxheXdyaWdodC10ZXN0MIICIjAN
+BgkqhkiG9w0BAQEFAAOCAg8AMIICCgKCAgEArbS99qjKcnHr5G0Zc2xhDaOZnjQv
+Fbiqxf/nbXt/7WaqryzpVKu7AT1ainBvuPEo7If9DhVnfF//2pGl0gbU31OU4/mr
+ymQmczGEyZvOBDsZhtCif54o5OoO0BjhODNT8OWec9RT87n6RkH58MHlOi8xsPxQ
+9n5U1CN/h2DyQF3aRKunEFCgtwPKWSjG+J/TAI9i0aSENXPiR8wjTrjg79s8Ehuj
+NN8Wk6rKLU3sepG3GIMID5vLsVa2t9xqn562sP95Ee+Xp2YX3z7oYK99QCJdzacw
+alhMHob1GCEKjDyxsD2IFRi7Dysiutfyzy3pMo6NALxFrwKVhWX0L4zVFIsI6JlV
+dK8dHmDk0MRSqgB9sWXvEfSTXADEe8rncFSFpFz4Z8RNLmn5YSzQJzokNn41DUCP
+dZTlTkcGTqvn5NqoY4sOV8rkFbgmTcqyijV/sebPjxCbJNcNmaSWa9FJ5IjRTpzM
+38wLmxn+eKGK68n2JB3P7JP6LtsBShQEpXAF3rFfyNsP1bjquvGZVSjV8w/UwPE4
+kV5eq3j3D4913Zfxvzjp6PEmhStG0EQtIXvx/TRoYpaNWypIgZdbkZQp1HUIQL15
+D2Web4nazP3so1FC3ZgbrJZ2ozoadjLMp49NcSFdh+WRyVKuo0DIqR0zaiAzzf2D
+G1q7TLKimM3XBMUCAwEAAaNIMEYwCQYDVR0TBAIwADALBgNVHQ8EBAMCBeAwLAYD
+VR0RBCUwI4IJbG9jYWxob3N0hwR/AAABhxAAAAAAAAAAAAAAAAAAAAABMA0GCSqG
+SIb3DQEBCwUAA4ICAQAvC5M1JFc21WVSLPvE2iVbt4HmirO3EENdDqs+rTYG5VJG
+iE5ZuI6h/LjS5ptTfKovXQKaMr3pwp1pLMd/9q+6ZR1Hs9Z2wF6OZan4sb0uT32Y
+1KGlj86QMiiSLdrJ/1Z9JHskHYNCep1ZTsUhGk0qqiNv+G3K2y7ZpvrT/xlnYMth
+KLTuSVUwM8BBEPrCRLoXuaEy0LnvMvMVepIfP8tnMIL6zqmj3hXMPe4r4OFV/C5o
+XX25bC7GyuPWIRYn2OWP92J1CODZD1rGRoDtmvqrQpHdeX9RYcKH0ZLZoIf5L3Hf
+pPUtVkw3QGtjvKeG3b9usxaV9Od2Z08vKKk1PRkXFe8gqaeyicK7YVIOMTSuspAf
+JeJEHns6Hg61Exbo7GwdX76xlmQ/Z43E9BPHKgLyZ9WuJ0cysqN4aCyvS9yws9to
+ki7iMZqJUsmE2o09n9VaEsX6uQANZtLjI9wf+IgJuueDTNrkzQkhU7pbaPMsSG40
+AgGY/y4BR0H8sbhNnhqtZH7RcXV9VCJoPBAe+YiuXRiXyZHWxwBRyBE3e7g4MKHg
+hrWtaWUAs7gbavHwjqgU63iVItDSk7t4fCiEyObjK09AaNf2DjjaSGf8YGza4bNy
+BjYinYJ6/eX//gp+abqfocFbBP7D9zRDgMIbVmX/Ey6TghKiLkZOdbzcpO4Wgg==
+-----END CERTIFICATE-----

tests/testserver/index.ts

@@ -0,0 +1,172 @@
+/**
+ * Copyright 2017 Google Inc. All rights reserved.
+ * Modifications 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 url from 'node:url';
+import http from 'http';
+import https from 'https';
+import path from 'path';
+import debug from 'debug';
+
+const fulfillSymbol = Symbol('fulfil callback');
+const rejectSymbol = Symbol('reject callback');
+
+// NOTE: Can be removed when we drop Node.js 18 support and changed to import.meta.filename.
+const __filename = url.fileURLToPath(import.meta.url);
+
+export class TestServer {
+  private _server: http.Server;
+  readonly debugServer: any;
+  private _routes = new Map<string, (request: http.IncomingMessage, response: http.ServerResponse) => any>();
+  private _csp = new Map<string, string>();
+  private _extraHeaders = new Map<string, object>();
+  private _requestSubscribers = new Map<string, Promise<any>>();
+  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);
+    await new Promise(x => server._server.once('listening', x));
+    return server;
+  }
+
+  static async createHTTPS(port: number): Promise<TestServer> {
+    const server = new TestServer(port, {
+      key: await fs.promises.readFile(path.join(path.dirname(__filename), 'key.pem')),
+      cert: await fs.promises.readFile(path.join(path.dirname(__filename), 'cert.pem')),
+      passphrase: 'aaaa',
+    });
+    await new Promise(x => server._server.once('listening', x));
+    return server;
+  }
+
+  constructor(port: number, sslOptions?: object) {
+    if (sslOptions)
+      this._server = https.createServer(sslOptions, this._onRequest.bind(this));
+    else
+      this._server = http.createServer(this._onRequest.bind(this));
+    this._server.listen(port);
+    this.debugServer = debug('pw:testserver');
+
+    const cross_origin = '127.0.0.1';
+    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.HELLO_WORLD = `${this.PREFIX}hello-world`;
+  }
+
+  setCSP(path: string, csp: string) {
+    this._csp.set(path, csp);
+  }
+
+  setExtraHeaders(path: string, object: Record<string, string>) {
+    this._extraHeaders.set(path, object);
+  }
+
+  async stop() {
+    this.reset();
+    await new Promise(x => this._server.close(x));
+  }
+
+  route(path: string, handler: (request: http.IncomingMessage, response: http.ServerResponse) => any) {
+    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!) || {};
+      res.writeHead(302, { ...headers, location: to });
+      res.end();
+    });
+  }
+
+  waitForRequest(path: string): Promise<http.IncomingMessage> {
+    let promise = this._requestSubscribers.get(path);
+    if (promise)
+      return promise;
+    let fulfill, reject;
+    promise = new Promise((f, r) => {
+      fulfill = f;
+      reject = r;
+    });
+    promise[fulfillSymbol] = fulfill;
+    promise[rejectSymbol] = reject;
+    this._requestSubscribers.set(path, promise);
+    return promise;
+  }
+
+  reset() {
+    this._routes.clear();
+    this._csp.clear();
+    this._extraHeaders.clear();
+    this._server.closeAllConnections();
+    const error = new Error('Static Server has been reset');
+    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) {
+    request.on('error', error => {
+      if ((error as any).code === 'ECONNRESET')
+        response.end();
+      else
+        throw error;
+    });
+    (request as any).postBody = new Promise(resolve => {
+      const chunks: Buffer[] = [];
+      request.on('data', chunk => {
+        chunks.push(chunk);
+      });
+      request.on('end', () => resolve(Buffer.concat(chunks)));
+    });
+    const path = request.url || '/';
+    this.debugServer(`request ${request.method} ${path}`);
+    // Notify request subscriber.
+    if (this._requestSubscribers.has(path)) {
+      this._requestSubscribers.get(path)![fulfillSymbol].call(null, request);
+      this._requestSubscribers.delete(path);
+    }
+    const handler = this._routes.get(path);
+    if (handler) {
+      handler.call(null, request, response);
+    } else {
+      response.writeHead(404);
+      response.end();
+    }
+  }
+}

tests/testserver/key.pem

@@ -0,0 +1,52 @@
+-----BEGIN PRIVATE KEY-----
+MIIJQgIBADANBgkqhkiG9w0BAQEFAASCCSwwggkoAgEAAoICAQCttL32qMpycevk
+bRlzbGENo5meNC8VuKrF/+dte3/tZqqvLOlUq7sBPVqKcG+48Sjsh/0OFWd8X//a
+kaXSBtTfU5Tj+avKZCZzMYTJm84EOxmG0KJ/nijk6g7QGOE4M1Pw5Z5z1FPzufpG
+QfnwweU6LzGw/FD2flTUI3+HYPJAXdpEq6cQUKC3A8pZKMb4n9MAj2LRpIQ1c+JH
+zCNOuODv2zwSG6M03xaTqsotTex6kbcYgwgPm8uxVra33Gqfnraw/3kR75enZhff
+Puhgr31AIl3NpzBqWEwehvUYIQqMPLGwPYgVGLsPKyK61/LPLekyjo0AvEWvApWF
+ZfQvjNUUiwjomVV0rx0eYOTQxFKqAH2xZe8R9JNcAMR7yudwVIWkXPhnxE0uaflh
+LNAnOiQ2fjUNQI91lOVORwZOq+fk2qhjiw5XyuQVuCZNyrKKNX+x5s+PEJsk1w2Z
+pJZr0UnkiNFOnMzfzAubGf54oYrryfYkHc/sk/ou2wFKFASlcAXesV/I2w/VuOq6
+8ZlVKNXzD9TA8TiRXl6rePcPj3Xdl/G/OOno8SaFK0bQRC0he/H9NGhilo1bKkiB
+l1uRlCnUdQhAvXkPZZ5vidrM/eyjUULdmBuslnajOhp2Msynj01xIV2H5ZHJUq6j
+QMipHTNqIDPN/YMbWrtMsqKYzdcExQIDAQABAoICAGqXttpdyZ1g+vg5WpzRrNzJ
+v8KtExepMmI+Hq24U1BC6AqG7MfgeejQ1XaOeIBsvEgpSsgRqmdQIZjmN3Mibg59
+I6ih1SFlQ5L8mBd/XHSML6Xi8VSOoVmXp29bVRk/pgr1XL6HVN0DCumCIvXyhc+m
+lj+dFbGs5DEpd2CDxSRqcz4gd2wzjevAj7MWqsJ2kOyPEHzFD7wdWIXmZuQv3xhQ
+2BPkkcon+5qx+07BupOcR1brUU8Cs4QnSgiZYXSB2GnU215+P/mhVJTR7ZcnGRz5
++cXxCmy3sj4pYs1juS1FMWSM3azUeDVeqvks+vrXmXpEr5H79mbmlwo8/hMPwNDO
+07HRZwa8T01aT9EYVm0lIOYjMF/2f6j6cu2apJtjXICOksR2HefRBVXQirOxRHma
+9XAYfNkZ/2164ZbgFmJv9khFnegPEuth9tLVdFIeGSmsG0aX9tH63zGT2NROyyLc
+QXPqsDl2CxCYPRs2oiGkM9dnfP1wAOp96sq42GIuN7ykfqfRnwAIvvnLKvyCq1vR
+pIno3CIX6vnzt+1/Hrmv13b0L6pJPitpXwKWHv9zJKBTpN8HEzP3Qmth2Ef60/7/
+CBo1PVTd1A6zcU7816flg7SCY+Vk+OxVHV3dGBIIqN9SfrQ8BPcOl6FNV5Anbrnv
+CpSw+LzH9n5xympDnk0BAoIBAQDjenvDfCnrNVeqx8+sYaYey4/WPVLXOQhREvRY
+oOtX9eqlNSi20+Wl+iuXmyj8wdHrDET7rfjCbpDQ7u105yzLw4gy4qIRDKZ1nE45
+YX+tm8mZgBqRnTp0DoGOArqmp3IKXJtUYmpbTz9tOfY7Usb1o1epb4winEB+Pl+8
+mgXOEo8xvWBzKeRA7tE73V64Mwbvbo9Ff2EguhXweQP29yBkEjT4iViayuHUmyPt
+hOVSMj2oFQuQGPdhAk7nUXojSGK/Zas/AGpH9CHH9De0h4m08vd3oM4vj0HwzgjU
+Co9aRa9SAH7EiaocOTcjDRPxWdZPHhxmrVRIYlF0MNmOAkXJAoIBAQDDfEqu4sNi
+pq74VXVatQqhzCILZo+o48bdgEjF7mF99mqPj8rwIDrEoEriDK861kenLc3vWKRY
+5wh1iX3S896re9kUMoxx6p4heYTcsOJ9BbkcpT8bJPZx9gBJb4jJENeVf1exf6sG
+RhFnulpzReRRaUjX2yAkyUPfc8YcUt+Nalrg+2W0fzeLCUpABCAcj2B1Vv7qRZHj
+oEtlCV5Nz+iMhrwIa16g9c8wGt5DZb4PI+VIJ6EYkdsjhgqIF0T/wDq9/habGBPo
+mHN+/DX3hCJWN2QgoVGJskHGt0zDMgiEgXfLZ2Grl02vQtq+mW2O2vGVeUd9Y5Ew
+RUiY4bSRTrUdAoIBAHxL1wiP9c/By+9TUtScXssA681ioLtdPIAgXUd4VmAvzVEM
+ZPzRd/BjbCJg89p4hZ1rjN4Ax6ZmB9dCVpnEH6QPaYJ0d53dTa+CAvQzpDJWp6eq
+adobEW+M5ZmVQCwD3rpus6k+RWMzQDMMstDjgDeEU0gP3YCj5FGW/3TsrDNXzMqe
+8e67ey9Hzyho43K+3xFBViPhYE8jnw1Q8quliRtlH3CWi8W5CgDD7LPCJBPvw+Tt
+6u2H1tQ5EKgwyw4wZVSz1wiLz4cVjMfXWADa9pHbGQFS6pbuLlfIHObQBliLLysd
+ficiGcNmOAx8/uKn9gQxLc+k8iLDJkLY1mdUMpECggEAJLl87k37ltTpmg2z9k58
+qNjIrIugAYKJIaOwCD84YYmhi0bgQSxM3hOe/ciUQuFupKGeRpDIj0sX87zYvoDC
+HEUwCvNUHzKMco15wFwasJIarJ7+tALFqbMlaqZhdCSN27AIsXfikVMogewoge9n
+bUPyQ1sPNtn4vknptfh7tv18BTg1aytbK+ua31vnDHaDEIg/a5OWTMUYZOrVpJii
+f4PwX0SMioCjY84oY1EB26ZKtLt9MDh2ir3rzJVSiRl776WEaa6kTtYVHI4VNWLF
+cJ0HWnnz74JliQd2jFUh9IK+FqBdYPcTyREuNxBr3KKVMBeQrqW96OubL913JrU6
+oQKCAQEA0yzORUouT0yleWs7RmzBlT9OLD/3cBYJMf/r1F8z8OQjB8fU1jKbO1Cs
+q4l+o9FmI+eHkgc3xbEG0hahOFWm/hTTli9vzksxurgdawZELThRkK33uTU9pKla
+Okqx3Ru/iMOW2+DQUx9UB+jK+hSAgq4gGqLeJVyaBerIdLQLlvqxrwSxjvvj+wJC
+Y66mgRzdCi6VDF1vV0knCrQHK6tRwcPozu/k4zjJzvdbMJnKEy2S7Vh6vO8lEPJm
+MQtaHPpmz+F4z14b9unNIiSbHO60Q4O+BwIBCzxApQQbFg63vBLYYwEMRd7hh92s
+ZkZVSOEp+sYBf/tmptlKr49nO+dTjQ==
+-----END PRIVATE KEY-----

tests/testserver/san.cnf

@@ -0,0 +1,19 @@
+# openssl req -new -x509 -days 3650 -key key.pem -out cert.pem -config san.cnf -extensions v3_req
+
+[req]
+distinguished_name = req_distinguished_name
+req_extensions = v3_req
+prompt = no
+
+[req_distinguished_name]
+CN = playwright-test
+
+[v3_req]
+basicConstraints = CA:FALSE
+keyUsage = nonRepudiation, digitalSignature, keyEncipherment
+subjectAltName = @alt_names
+
+[alt_names]
+DNS.1 = localhost
+IP.1 = 127.0.0.1
+IP.2 = ::1

tests/trace.spec.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 fs from 'fs';
+import path from 'path';
+
+import { test, expect } from './fixtures.js';
+
+test('check that trace is saved', async ({ startClient, server, mcpMode }, testInfo) => {
+  test.fixme(mcpMode === 'extension', 'Tracing is not supported via CDP');
+
+  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();
+});

tests/wait.spec.ts

@@ -0,0 +1,85 @@
+/**
+ * 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_wait_for(text)', async ({ client, server }) => {
+  server.setContent('/', `
+    <script>
+      function update() {
+        setTimeout(() => {
+          document.querySelector('div').textContent = 'Text to appear';
+        }, 1000);
+      }
+    </script>
+    <body>
+      <button onclick="update()">Click me</button>
+      <div>Text to disappear</div>
+    </body>
+  `, 'text/html');
+
+  await client.callTool({
+    name: 'browser_navigate',
+    arguments: { url: server.PREFIX },
+  });
+
+  await client.callTool({
+    name: 'browser_click',
+    arguments: {
+      element: 'Click me',
+      ref: 'e2',
+    },
+  });
+
+  expect(await client.callTool({
+    name: 'browser_wait_for',
+    arguments: { text: 'Text to appear' },
+  })).toContainTextContent(`- generic [ref=e3]: Text to appear`);
+});
+
+test('browser_wait_for(textGone)', async ({ client, server }) => {
+  server.setContent('/', `
+    <script>
+      function update() {
+        setTimeout(() => {
+          document.querySelector('div').textContent = 'Text to appear';
+        }, 1000);
+      }
+    </script>
+    <body>
+      <button onclick="update()">Click me</button>
+      <div>Text to disappear</div>
+    </body>
+  `, 'text/html');
+
+  await client.callTool({
+    name: 'browser_navigate',
+    arguments: { url: server.PREFIX },
+  });
+
+  await client.callTool({
+    name: 'browser_click',
+    arguments: {
+      element: 'Click me',
+      ref: 'e2',
+    },
+  });
+
+  expect(await client.callTool({
+    name: 'browser_wait_for',
+    arguments: { textGone: 'Text to disappear' },
+  })).toContainTextContent(`- generic [ref=e3]: Text to appear`);
+});

tests/webdriver.spec.ts

@@ -0,0 +1,38 @@
+/**
+ * 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('do not falsely advertise user agent as a test driver', async ({ client, server, mcpBrowser }) => {
+  test.skip(mcpBrowser === 'firefox');
+  test.skip(mcpBrowser === 'webkit');
+  server.route('/', (req, res) => {
+    res.writeHead(200, { 'Content-Type': 'text/html' });
+    res.end(`
+      <body></body>
+      <script>
+        document.body.textContent = 'webdriver: ' + navigator.webdriver;
+      </script>
+    `);
+  });
+
+  expect(await client.callTool({
+    name: 'browser_navigate',
+    arguments: {
+      url: server.PREFIX,
+    },
+  })).toContainTextContent('webdriver: false');
+});

tsconfig.all.json

@@ -0,0 +1,4 @@
+{
+  "extends": "./tsconfig.json",
+  "include": ["**/*.ts", "**/*.js"],
+}

tsconfig.json

@@ -1,12 +1,13 @@
 {
   "compilerOptions": {
     "target": "ESNext",
-    "skipLibCheck": true,
     "esModuleInterop": true,
-    "moduleResolution": "node",
+    "moduleResolution": "nodenext",
     "strict": true,
-    "module": "CommonJS",
-    "outDir": "./lib"
+    "module": "NodeNext",
+    "rootDir": "src",
+    "outDir": "./lib",
+    "resolveJsonModule": true
   },
   "include": [
     "src",

utils/generate-links.js

@@ -0,0 +1,6 @@
+const config = JSON.stringify({ name: 'playwright', command: 'npx', args: ["@playwright/mcp@latest"] });
+const urlForWebsites = `vscode:mcp/install?${encodeURIComponent(config)}`;
+// Github markdown does not allow linking to `vscode:` directly, so you can use our redirect:
+const urlForGithub = `https://insiders.vscode.dev/redirect?url=${encodeURIComponent(urlForWebsites)}`;
+
+console.log(urlForGithub);

utils/update-readme.js

@@ -0,0 +1,194 @@
+#!/usr/bin/env node
+/**
+ * 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.
+ */
+// @ts-check
+
+import fs from 'node:fs'
+import path from 'node:path'
+import url from 'node:url'
+import zodToJsonSchema from 'zod-to-json-schema'
+
+import commonTools from '../lib/tools/common.js';
+import consoleTools from '../lib/tools/console.js';
+import dialogsTools from '../lib/tools/dialogs.js';
+import filesTools from '../lib/tools/files.js';
+import installTools from '../lib/tools/install.js';
+import keyboardTools from '../lib/tools/keyboard.js';
+import navigateTools from '../lib/tools/navigate.js';
+import networkTools from '../lib/tools/network.js';
+import pdfTools from '../lib/tools/pdf.js';
+import snapshotTools from '../lib/tools/snapshot.js';
+import tabsTools from '../lib/tools/tabs.js';
+import screenshotTools from '../lib/tools/screenshot.js';
+import testTools from '../lib/tools/testing.js';
+import visionTools from '../lib/tools/vision.js';
+import waitTools from '../lib/tools/wait.js';
+import { execSync } from 'node:child_process';
+
+const categories = {
+  'Interactions': [
+    ...snapshotTools,
+    ...keyboardTools(true),
+    ...waitTools(true),
+    ...filesTools(true),
+    ...dialogsTools(true),
+  ],
+  'Navigation': [
+    ...navigateTools(true),
+  ],
+  'Resources': [
+    ...screenshotTools,
+    ...pdfTools,
+    ...networkTools,
+    ...consoleTools,
+  ],
+  'Utilities': [
+    ...installTools,
+    ...commonTools(true),
+  ],
+  'Tabs': [
+    ...tabsTools(true),
+  ],
+  'Testing': [
+    ...testTools,
+  ],
+  'Vision mode': [
+    ...visionTools,
+    ...keyboardTools(),
+    ...waitTools(false),
+    ...filesTools(false),
+    ...dialogsTools(false),
+  ],
+};
+
+// NOTE: Can be removed when we drop Node.js 18 support and changed to import.meta.filename.
+const __filename = url.fileURLToPath(import.meta.url);
+
+/**
+ * @param {import('../src/tools/tool.js').ToolSchema<any>} tool 
+ * @returns {string[]}
+ */
+function formatToolForReadme(tool) {
+  const lines = /** @type {string[]} */ ([]);
+  lines.push(`<!-- NOTE: This has been generated via ${path.basename(__filename)} -->`);
+  lines.push(``);
+  lines.push(`- **${tool.name}**`);
+  lines.push(`  - Title: ${tool.title}`);
+  lines.push(`  - Description: ${tool.description}`);
+
+  const inputSchema = /** @type {any} */ (zodToJsonSchema(tool.inputSchema || {}));
+  const requiredParams = inputSchema.required || [];
+  if (inputSchema.properties && Object.keys(inputSchema.properties).length) {
+    lines.push(`  - Parameters:`);
+    Object.entries(inputSchema.properties).forEach(([name, param]) => {
+      const optional = !requiredParams.includes(name);
+      const meta = /** @type {string[]} */ ([]);
+      if (param.type)
+        meta.push(param.type);
+      if (optional)
+        meta.push('optional');
+      lines.push(`    - \`${name}\` ${meta.length ? `(${meta.join(', ')})` : ''}: ${param.description}`);
+    });
+  } else {
+    lines.push(`  - Parameters: None`);
+  }
+  lines.push(`  - Read-only: **${tool.type === 'readOnly'}**`);
+  lines.push('');
+  return lines;
+}
+
+/**
+ * @param {string} content
+ * @param {string} startMarker
+ * @param {string} endMarker
+ * @param {string[]} generatedLines
+ * @returns {Promise<string>}
+ */
+async function updateSection(content, startMarker, endMarker, generatedLines) {
+  const startMarkerIndex = content.indexOf(startMarker);
+  const endMarkerIndex = content.indexOf(endMarker);
+  if (startMarkerIndex === -1 || endMarkerIndex === -1)
+    throw new Error('Markers for generated section not found in README');
+
+  return [
+    content.slice(0, startMarkerIndex + startMarker.length),
+    '',
+    generatedLines.join('\n'),
+    '',
+    content.slice(endMarkerIndex),
+  ].join('\n');
+}
+
+/**
+ * @param {string} content
+ * @returns {Promise<string>}
+ */
+async function updateTools(content) {
+  console.log('Loading tool information from compiled modules...');
+
+  const totalTools = Object.values(categories).flat().length;
+  console.log(`Found ${totalTools} tools`);
+
+  const generatedLines = /** @type {string[]} */ ([]);
+  for (const [category, categoryTools] of Object.entries(categories)) {
+    generatedLines.push(`<details>\n<summary><b>${category}</b></summary>`);
+    generatedLines.push('');
+    for (const tool of categoryTools)
+      generatedLines.push(...formatToolForReadme(tool.schema));
+    generatedLines.push(`</details>`);
+    generatedLines.push('');
+  }
+
+  const startMarker = `<!--- Tools generated by ${path.basename(__filename)} -->`;
+  const endMarker = `<!--- End of tools generated section -->`;
+  return updateSection(content, startMarker, endMarker, generatedLines);
+}
+
+/**
+ * @param {string} content
+ * @returns {Promise<string>}
+ */
+async function updateOptions(content) {
+  console.log('Listing options...');
+  const output = execSync('node cli.js --help');
+  const lines = output.toString().split('\n');
+  const firstLine = lines.findIndex(line => line.includes('--version'));
+  lines.splice(0, firstLine + 1);
+  const lastLine = lines.findIndex(line => line.includes('--help'));
+  lines.splice(lastLine);
+  const startMarker = `<!--- Options generated by ${path.basename(__filename)} -->`;
+  const endMarker = `<!--- End of options generated section -->`;
+  return updateSection(content, startMarker, endMarker, [
+    '```',
+    '> npx @playwright/mcp@latest --help',
+    ...lines,
+    '```',
+  ]);
+}
+
+async function updateReadme() {
+  const readmePath = path.join(path.dirname(__filename), '..', 'README.md');
+  const readmeContent = await fs.promises.readFile(readmePath, 'utf-8');
+  const withTools = await updateTools(readmeContent);
+  const withOptions = await updateOptions(withTools);
+  await fs.promises.writeFile(readmePath, withOptions, 'utf-8');
+  console.log('README updated successfully');
+}
+
+updateReadme().catch(err => {
+  console.error('Error updating README:', err);
+  process.exit(1);
+});