chore: roll Playwright to 1.59.0-alpha-1773608981000 (#1461)

## Summary
- Roll playwright and playwright-core to `1.59.0-alpha-1773451864000`
- Fix `install-browser` CLI command registration (was calling
`parseAsync` before registering the subcommand)
- Add `selector` parameter to accessibility snapshot documentation
- Add CLAUDE.md

.github/workflows/ci.yml

@@ -6,6 +6,10 @@ on:
   pull_request:
     branches: [ main ]
 
+env:
+  PWMCP_DEBUG: '1'
+  PWDEBUGIMPL: '1'
+
 jobs:
   lint:
     runs-on: ubuntu-latest
@@ -21,7 +25,7 @@ jobs:
     - name: Ensure no changes
       run: git diff --exit-code
 
-  test_mcp:
+  test:
     strategy:
       fail-fast: false
       matrix:
@@ -38,9 +42,20 @@ jobs:
       run: npm ci
     - name: Playwright install
       run: npx playwright install --with-deps
-    - name: Run tests
-      run: npm run test
-      working-directory: ./packages/playwright-mcp
+    - name: Build
+      run: npm run build
+    - name: Run playwright-mcp tests
+      id: test-mcp
+      run: npm run test --workspace=packages/playwright-mcp
+      continue-on-error: true
+    - name: Run extension tests
+      id: test-extension
+      if: matrix.os == 'macos-15'
+      run: npm run test --workspace=packages/extension
+      continue-on-error: true
+    - name: Check test results
+      if: steps.test-mcp.outcome == 'failure' || steps.test-extension.outcome == 'failure'
+      run: exit 1
 
   test_mcp_docker:
     runs-on: ubuntu-latest
@@ -73,35 +88,3 @@ jobs:
       working-directory: ./packages/playwright-mcp
       env:
         MCP_IN_DOCKER: 1
-
-  test_extension:
-    runs-on: macos-latest
-    steps:
-    - uses: actions/checkout@v4
-    - name: Use Node.js 20
-      uses: actions/setup-node@v4
-      with:
-        node-version: '20' # crypto.randomUUID(); stalls in v18.20.8
-        cache: 'npm'
-    - name: Install dependencies
-      run: npm ci
-    - name: Playwright install
-      run: npx playwright install --with-deps
-    - name: Build extension
-      run: npm run build
-      working-directory: ./packages/extension
-    - name: Upload artifact
-      uses: actions/upload-artifact@v4
-      with:
-        name: extension
-        path: ./extension/dist
-        retention-days: 7
-    - name: Run tests
-      run: |
-        if [[ "$(uname)" == "Linux" ]]; then
-          xvfb-run --auto-servernum --server-args="-screen 0 1280x960x24" -- npm run test
-        else
-          npm run test
-        fi
-      shell: bash
-      working-directory: ./packages/extension

.github/workflows/publish.yml

@@ -73,27 +73,6 @@ jobs:
       - run: npm publish
         working-directory: ./packages/playwright-mcp
 
-  publish-cli-release-npm:
-    if: github.event_name == 'release'
-    runs-on: ubuntu-latest
-    permissions:
-      contents: read
-      id-token: write  # Required for OIDC npm publishing
-    steps:
-      - uses: actions/checkout@v5
-      - uses: actions/setup-node@v5
-        with:
-          node-version: 20
-          registry-url: https://registry.npmjs.org/
-      # Ensure npm 11.5.1 or later is installed (for OIDC npm publishing)
-      - name: Update npm
-        run: npm install -g npm@latest
-      - run: npm ci
-      - run: npx playwright install --with-deps
-      - run: npm run lint
-      - run: npm publish
-        working-directory: ./packages/playwright-cli
-
   publish-mcp-release-docker:
     if: github.event_name == 'release'
     runs-on: ubuntu-latest
@@ -156,6 +135,8 @@ jobs:
       - name: Build extension
         working-directory: ./packages/extension
         run: npm run build
+        env:
+          SET_EXTENSION_PUBLIC_KEY_IN_MANIFEST: 1
       - name: Get extension version
         id: get-version
         working-directory: ./packages/extension

CLAUDE.md

@@ -0,0 +1,31 @@
+## Commit Convention
+
+Semantic commit messages: `label(scope): description`
+
+Labels: `fix`, `feat`, `chore`, `docs`, `test`, `devops`
+
+```bash
+git checkout -b fix-39562
+# ... make changes ...
+git add <changed-files>
+git commit -m "$(cat <<'EOF'
+fix(proxy): handle SOCKS proxy authentication
+
+Fixes: https://github.com/microsoft/playwright/issues/39562
+EOF
+)"
+git push origin fix-39562
+gh pr create --repo microsoft/playwright --head username:fix-39562 \
+  --title "fix(proxy): handle SOCKS proxy authentication" \
+  --body "$(cat <<'EOF'
+## Summary
+- <describe the change very! briefly>
+
+Fixes https://github.com/microsoft/playwright/issues/39562
+EOF
+)"
+```
+
+Never add Co-Authored-By agents in commit message.
+Branch naming for issue fixes: `fix-<issue-number>`
+

README.md

@@ -72,6 +72,26 @@ amp mcp add playwright -- npx @playwright/mcp@latest
 
 </details>
 
+<details>
+<summary>Antigravity</summary>
+
+Add via the Antigravity settings or by updating your configuration file:
+
+```json
+{
+  "mcpServers": {
+    "playwright": {
+      "command": "npx",
+      "args": [
+        "@playwright/mcp@latest"
+      ]
+    }
+  }
+}
+```
+
+</details>
+
 <details>
 <summary>Claude Code</summary>
 
@@ -340,9 +360,10 @@ Playwright MCP server supports following arguments. They can be provided in the
 | --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. Important: *does not* serve as a security boundary and *does not* affect redirects.<br>*env* `PLAYWRIGHT_MCP_BLOCKED_ORIGINS` |
 | --block-service-workers | block service workers<br>*env* `PLAYWRIGHT_MCP_BLOCK_SERVICE_WORKERS` |
 | --browser <browser> | browser or chrome channel to use, possible values: chrome, firefox, webkit, msedge.<br>*env* `PLAYWRIGHT_MCP_BROWSER` |
-| --caps <caps> | comma-separated list of additional capabilities to enable, possible values: vision, pdf.<br>*env* `PLAYWRIGHT_MCP_CAPS` |
+| --caps <caps> | comma-separated list of additional capabilities to enable, possible values: vision, pdf, devtools.<br>*env* `PLAYWRIGHT_MCP_CAPS` |
 | --cdp-endpoint <endpoint> | CDP endpoint to connect to.<br>*env* `PLAYWRIGHT_MCP_CDP_ENDPOINT` |
 | --cdp-header <headers...> | CDP headers to send with the connect request, multiple can be specified.<br>*env* `PLAYWRIGHT_MCP_CDP_HEADER` |
+| --cdp-timeout <timeout> | timeout in milliseconds for connecting to CDP endpoint, defaults to 30000ms<br>*env* `PLAYWRIGHT_MCP_CDP_TIMEOUT` |
 | --codegen <lang> | specify the language to use for code generation, possible values: "typescript", "none". Default is "typescript".<br>*env* `PLAYWRIGHT_MCP_CODEGEN` |
 | --config <path> | path to the configuration file.<br>*env* `PLAYWRIGHT_MCP_CONFIG` |
 | --console-level <level> | level of console messages to return: "error", "warning", "info", "debug". Each level includes the messages of more severe levels.<br>*env* `PLAYWRIGHT_MCP_CONSOLE_LEVEL` |
@@ -363,9 +384,8 @@ Playwright MCP server supports following arguments. They can be provided in the
 | --port <port> | port to listen on for SSE transport.<br>*env* `PLAYWRIGHT_MCP_PORT` |
 | --proxy-bypass <bypass> | comma-separated domains to bypass proxy, for example ".com,chromium.org,.domain.com"<br>*env* `PLAYWRIGHT_MCP_PROXY_BYPASS` |
 | --proxy-server <proxy> | specify proxy server, for example "http://myproxy:3128" or "socks5://myproxy:8080"<br>*env* `PLAYWRIGHT_MCP_PROXY_SERVER` |
+| --sandbox | enable the sandbox for all process types that are normally not sandboxed.<br>*env* `PLAYWRIGHT_MCP_SANDBOX` |
 | --save-session | Whether to save the Playwright MCP session into the output directory.<br>*env* `PLAYWRIGHT_MCP_SAVE_SESSION` |
-| --save-trace | Whether to save the Playwright Trace of the session into the output directory.<br>*env* `PLAYWRIGHT_MCP_SAVE_TRACE` |
-| --save-video <size> | Whether to save the video of the session into the output directory. For example "--save-video=800x600"<br>*env* `PLAYWRIGHT_MCP_SAVE_VIDEO` |
 | --secrets <path> | path to a file containing secrets in the dotenv format<br>*env* `PLAYWRIGHT_MCP_SECRETS` |
 | --shared-browser-context | reuse the same browser context between all connected HTTP clients.<br>*env* `PLAYWRIGHT_MCP_SHARED_BROWSER_CONTEXT` |
 | --snapshot-mode <mode> | when taking snapshots for responses, specifies the mode to use. Can be "incremental", "full", or "none". Default is incremental.<br>*env* `PLAYWRIGHT_MCP_SNAPSHOT_MODE` |
@@ -537,6 +557,13 @@ npx @playwright/mcp@latest --config path/to/config.json
     initScript?: string[];
   },
 
+  /**
+   * Connect to a running browser instance (Edge/Chrome only). If specified, `browser`
+   * config is ignored.
+   * Requires the "Playwright MCP Bridge" browser extension to be installed.
+   */
+  extension?: boolean;
+
   server?: {
     /**
      * The port to listen on for SSE or MCP transport.
@@ -560,6 +587,7 @@ npx @playwright/mcp@latest --config path/to/config.json
    *   - 'core': Core browser automation features.
    *   - 'pdf': PDF generation and manipulation.
    *   - 'vision': Coordinate-based interactions.
+   *   - 'devtools': Developer tools features.
    */
   capabilities?: ToolCapability[];
 
@@ -568,19 +596,6 @@ npx @playwright/mcp@latest --config path/to/config.json
    */
   saveSession?: boolean;
 
-  /**
-   * Whether to save the Playwright trace of the session into the output directory.
-   */
-  saveTrace?: boolean;
-
-  /**
-   * If specified, saves the Playwright video of the session into the output directory.
-   */
-  saveVideo?: {
-    width: number;
-    height: number;
-  };
-
   /**
    * Reuse the same browser context between all connected HTTP clients.
    */
@@ -613,11 +628,19 @@ npx @playwright/mcp@latest --config path/to/config.json
   network?: {
     /**
      * List of origins to allow the browser to request. Default is to allow all. Origins matching both `allowedOrigins` and `blockedOrigins` will be blocked.
+     *
+     * Supported formats:
+     * - Full origin: `https://example.com:8080` - matches only that origin
+     * - Wildcard port: `http://localhost:*` - matches any port on localhost with http protocol
      */
     allowedOrigins?: string[];
 
     /**
      * List of origins to block the browser to request. Origins matching both `allowedOrigins` and `blockedOrigins` will be blocked.
+     *
+     * Supported formats:
+     * - Full origin: `https://example.com:8080` - matches only that origin
+     * - Wildcard port: `http://localhost:*` - matches any port on localhost with http protocol
      */
     blockedOrigins?: string[];
   };
@@ -637,6 +660,11 @@ npx @playwright/mcp@latest --config path/to/config.json
      * Configures default navigation timeout: https://playwright.dev/docs/api/class-page#page-set-default-navigation-timeout. Defaults to 60000ms.
      */
     navigation?: number;
+
+    /**
+     * Configures default expect timeout: https://playwright.dev/docs/test-timeouts#expect-timeout. Defaults to 5000ms.
+     */
+    expect?: number;
   };
 
   /**
@@ -689,6 +717,10 @@ And then in MCP client config, set the `url` to the HTTP endpoint:
 }
 ```
 
+## Security
+
+Playwright MCP is **not** a security boundary. See [MCP Security Best Practices](https://modelcontextprotocol.io/docs/tutorials/security/security_best_practices) for guidance on securing your deployment.
+
 <details>
 <summary><b>Docker</b></summary>
 
@@ -713,7 +745,7 @@ docker run -d -i --rm --init --pull=always \
   --name playwright \
   -p 8931:8931 \
   mcr.microsoft.com/playwright/mcp \
-  cli.js --headless --browser chromium --no-sandbox --port 8931
+  cli.js --headless --browser chromium --no-sandbox --port 8931 --host 0.0.0.0
 ```
 
 The server will listen on host port **8931** and can be reached by any MCP client.  
@@ -762,6 +794,7 @@ http.createServer(async (req, res) => {
   - Parameters:
     - `element` (string, optional): Human-readable element description used to obtain permission to interact with the element
     - `ref` (string): Exact target element reference from the page snapshot
+    - `selector` (string, optional): CSS or role selector for the target element, when "ref" is not available
     - `doubleClick` (boolean, optional): Whether to perform a double click instead of a single click
     - `button` (string, optional): Button to click, defaults to left
     - `modifiers` (array, optional): Modifier keys to press
@@ -782,6 +815,7 @@ http.createServer(async (req, res) => {
   - Description: Returns all console messages
   - Parameters:
     - `level` (string): Level of the console messages to return. Each level includes the messages of more severe levels. Defaults to "info".
+    - `all` (boolean, optional): Return all console messages since the beginning of the session, not just since the last navigation. Defaults to false.
     - `filename` (string, optional): Filename to save the console messages to. If not provided, messages are returned as text.
   - Read-only: **true**
 
@@ -793,8 +827,10 @@ http.createServer(async (req, res) => {
   - 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
+    - `startSelector` (string, optional): CSS or role selector for the source element, when ref is not available
     - `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
+    - `endSelector` (string, optional): CSS or role selector for the target element, when ref is not available
   - Read-only: **false**
 
 <!-- NOTE: This has been generated via update-readme.js -->
@@ -806,6 +842,7 @@ http.createServer(async (req, res) => {
     - `function` (string): () => { /* code */ } or (element) => { /* code */ } when element is provided
     - `element` (string, optional): Human-readable element description used to obtain permission to interact with the element
     - `ref` (string, optional): Exact target element reference from the page snapshot
+    - `selector` (string, optional): CSS or role selector for the target element, when "ref" is not available.
   - Read-only: **false**
 
 <!-- NOTE: This has been generated via update-readme.js -->
@@ -844,6 +881,7 @@ http.createServer(async (req, res) => {
   - Parameters:
     - `element` (string, optional): Human-readable element description used to obtain permission to interact with the element
     - `ref` (string): Exact target element reference from the page snapshot
+    - `selector` (string, optional): CSS or role selector for the target element, when "ref" is not available
   - Read-only: **false**
 
 <!-- NOTE: This has been generated via update-readme.js -->
@@ -909,6 +947,7 @@ http.createServer(async (req, res) => {
   - Parameters:
     - `element` (string, optional): Human-readable element description used to obtain permission to interact with the element
     - `ref` (string): Exact target element reference from the page snapshot
+    - `selector` (string, optional): CSS or role selector for the target element, when "ref" is not available
     - `values` (array): Array of values to select in the dropdown. This can be a single value or multiple values.
   - Read-only: **false**
 
@@ -919,6 +958,7 @@ http.createServer(async (req, res) => {
   - Description: Capture accessibility snapshot of the current page, this is better than screenshot
   - Parameters:
     - `filename` (string, optional): Save snapshot to markdown file instead of returning it in the response.
+    - `selector` (string, optional): Element selector of the root element to capture a partial snapshot instead of the whole page
   - Read-only: **true**
 
 <!-- NOTE: This has been generated via update-readme.js -->
@@ -931,6 +971,7 @@ http.createServer(async (req, res) => {
     - `filename` (string, optional): File name to save the screenshot to. Defaults to `page-{timestamp}.{png|jpeg}` if not specified. Prefer relative file names to stay within the output directory.
     - `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.
+    - `selector` (string, optional): CSS or role selector for the target element, when "ref" is not available.
     - `fullPage` (boolean, optional): When true, takes a screenshot of the full scrollable page, instead of the currently visible viewport. Cannot be used with element screenshots.
   - Read-only: **true**
 
@@ -942,6 +983,7 @@ http.createServer(async (req, res) => {
   - Parameters:
     - `element` (string, optional): Human-readable element description used to obtain permission to interact with the element
     - `ref` (string): Exact target element reference from the page snapshot
+    - `selector` (string, optional): CSS or role selector for the target element, when "ref" is not available
     - `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.
@@ -978,14 +1020,266 @@ http.createServer(async (req, res) => {
 <details>
 <summary><b>Browser installation</b></summary>
 
+</details>
+
+<details>
+<summary><b>Configuration (opt-in via --caps=config)</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.
+- **browser_get_config**
+  - Title: Get config
+  - Description: Get the final resolved config after merging CLI options, environment variables and config file.
+  - Parameters: None
+  - Read-only: **true**
+
+</details>
+
+<details>
+<summary><b>Network (opt-in via --caps=network)</b></summary>
+
+<!-- NOTE: This has been generated via update-readme.js -->
+
+- **browser_network_state_set**
+  - Title: Set network state
+  - Description: Sets the browser network state to online or offline. When offline, all network requests will fail.
+  - Parameters:
+    - `state` (string): Set to "offline" to simulate offline mode, "online" to restore network connectivity
+  - Read-only: **false**
+
+<!-- NOTE: This has been generated via update-readme.js -->
+
+- **browser_route**
+  - Title: Mock network requests
+  - Description: Set up a route to mock network requests matching a URL pattern
+  - Parameters:
+    - `pattern` (string): URL pattern to match (e.g., "**/api/users", "**/*.{png,jpg}")
+    - `status` (number, optional): HTTP status code to return (default: 200)
+    - `body` (string, optional): Response body (text or JSON string)
+    - `contentType` (string, optional): Content-Type header (e.g., "application/json", "text/html")
+    - `headers` (array, optional): Headers to add in "Name: Value" format
+    - `removeHeaders` (string, optional): Comma-separated list of header names to remove from request
+  - Read-only: **false**
+
+<!-- NOTE: This has been generated via update-readme.js -->
+
+- **browser_route_list**
+  - Title: List network routes
+  - Description: List all active network routes
+  - Parameters: None
+  - Read-only: **true**
+
+<!-- NOTE: This has been generated via update-readme.js -->
+
+- **browser_unroute**
+  - Title: Remove network routes
+  - Description: Remove network routes matching a pattern (or all routes if no pattern specified)
+  - Parameters:
+    - `pattern` (string, optional): URL pattern to unroute (omit to remove all routes)
+  - Read-only: **false**
+
+</details>
+
+<details>
+<summary><b>Storage (opt-in via --caps=storage)</b></summary>
+
+<!-- NOTE: This has been generated via update-readme.js -->
+
+- **browser_cookie_clear**
+  - Title: Clear cookies
+  - Description: Clear all cookies
   - Parameters: None
   - Read-only: **false**
 
+<!-- NOTE: This has been generated via update-readme.js -->
+
+- **browser_cookie_delete**
+  - Title: Delete cookie
+  - Description: Delete a specific cookie
+  - Parameters:
+    - `name` (string): Cookie name to delete
+  - Read-only: **false**
+
+<!-- NOTE: This has been generated via update-readme.js -->
+
+- **browser_cookie_get**
+  - Title: Get cookie
+  - Description: Get a specific cookie by name
+  - Parameters:
+    - `name` (string): Cookie name to get
+  - Read-only: **true**
+
+<!-- NOTE: This has been generated via update-readme.js -->
+
+- **browser_cookie_list**
+  - Title: List cookies
+  - Description: List all cookies (optionally filtered by domain/path)
+  - Parameters:
+    - `domain` (string, optional): Filter cookies by domain
+    - `path` (string, optional): Filter cookies by path
+  - Read-only: **true**
+
+<!-- NOTE: This has been generated via update-readme.js -->
+
+- **browser_cookie_set**
+  - Title: Set cookie
+  - Description: Set a cookie with optional flags (domain, path, expires, httpOnly, secure, sameSite)
+  - Parameters:
+    - `name` (string): Cookie name
+    - `value` (string): Cookie value
+    - `domain` (string, optional): Cookie domain
+    - `path` (string, optional): Cookie path
+    - `expires` (number, optional): Cookie expiration as Unix timestamp
+    - `httpOnly` (boolean, optional): Whether the cookie is HTTP only
+    - `secure` (boolean, optional): Whether the cookie is secure
+    - `sameSite` (string, optional): Cookie SameSite attribute
+  - Read-only: **false**
+
+<!-- NOTE: This has been generated via update-readme.js -->
+
+- **browser_localstorage_clear**
+  - Title: Clear localStorage
+  - Description: Clear all localStorage
+  - Parameters: None
+  - Read-only: **false**
+
+<!-- NOTE: This has been generated via update-readme.js -->
+
+- **browser_localstorage_delete**
+  - Title: Delete localStorage item
+  - Description: Delete a localStorage item
+  - Parameters:
+    - `key` (string): Key to delete
+  - Read-only: **false**
+
+<!-- NOTE: This has been generated via update-readme.js -->
+
+- **browser_localstorage_get**
+  - Title: Get localStorage item
+  - Description: Get a localStorage item by key
+  - Parameters:
+    - `key` (string): Key to get
+  - Read-only: **true**
+
+<!-- NOTE: This has been generated via update-readme.js -->
+
+- **browser_localstorage_list**
+  - Title: List localStorage
+  - Description: List all localStorage key-value pairs
+  - Parameters: None
+  - Read-only: **true**
+
+<!-- NOTE: This has been generated via update-readme.js -->
+
+- **browser_localstorage_set**
+  - Title: Set localStorage item
+  - Description: Set a localStorage item
+  - Parameters:
+    - `key` (string): Key to set
+    - `value` (string): Value to set
+  - Read-only: **false**
+
+<!-- NOTE: This has been generated via update-readme.js -->
+
+- **browser_sessionstorage_clear**
+  - Title: Clear sessionStorage
+  - Description: Clear all sessionStorage
+  - Parameters: None
+  - Read-only: **false**
+
+<!-- NOTE: This has been generated via update-readme.js -->
+
+- **browser_sessionstorage_delete**
+  - Title: Delete sessionStorage item
+  - Description: Delete a sessionStorage item
+  - Parameters:
+    - `key` (string): Key to delete
+  - Read-only: **false**
+
+<!-- NOTE: This has been generated via update-readme.js -->
+
+- **browser_sessionstorage_get**
+  - Title: Get sessionStorage item
+  - Description: Get a sessionStorage item by key
+  - Parameters:
+    - `key` (string): Key to get
+  - Read-only: **true**
+
+<!-- NOTE: This has been generated via update-readme.js -->
+
+- **browser_sessionstorage_list**
+  - Title: List sessionStorage
+  - Description: List all sessionStorage key-value pairs
+  - Parameters: None
+  - Read-only: **true**
+
+<!-- NOTE: This has been generated via update-readme.js -->
+
+- **browser_sessionstorage_set**
+  - Title: Set sessionStorage item
+  - Description: Set a sessionStorage item
+  - Parameters:
+    - `key` (string): Key to set
+    - `value` (string): Value to set
+  - Read-only: **false**
+
+<!-- NOTE: This has been generated via update-readme.js -->
+
+- **browser_set_storage_state**
+  - Title: Restore storage state
+  - Description: Restore storage state (cookies, local storage) from a file. This clears existing cookies and local storage before restoring.
+  - Parameters:
+    - `filename` (string): Path to the storage state file to restore from
+  - Read-only: **false**
+
+<!-- NOTE: This has been generated via update-readme.js -->
+
+- **browser_storage_state**
+  - Title: Save storage state
+  - Description: Save storage state (cookies, local storage) to a file for later reuse
+  - Parameters:
+    - `filename` (string, optional): File name to save the storage state to. Defaults to `storage-state-{timestamp}.json` if not specified.
+  - Read-only: **true**
+
+</details>
+
+<details>
+<summary><b>DevTools (opt-in via --caps=devtools)</b></summary>
+
+<!-- NOTE: This has been generated via update-readme.js -->
+
+- **browser_start_tracing**
+  - Title: Start tracing
+  - Description: Start trace recording
+  - Parameters: None
+  - Read-only: **true**
+
+<!-- NOTE: This has been generated via update-readme.js -->
+
+- **browser_start_video**
+  - Title: Start video
+  - Description: Start video recording
+  - Parameters:
+    - `size` (object, optional): Video size
+  - Read-only: **true**
+
+<!-- NOTE: This has been generated via update-readme.js -->
+
+- **browser_stop_tracing**
+  - Title: Stop tracing
+  - Description: Stop trace recording
+  - Parameters: None
+  - Read-only: **true**
+
+<!-- NOTE: This has been generated via update-readme.js -->
+
+- **browser_stop_video**
+  - Title: Stop video
+  - Description: Stop video recording
+  - Parameters:
+    - `filename` (string, optional): Filename to save the video
+  - Read-only: **true**
+
 </details>
 
 <details>
@@ -995,10 +1289,13 @@ http.createServer(async (req, res) => {
 
 - **browser_mouse_click_xy**
   - Title: Click
-  - Description: Click left mouse button at a given position
+  - Description: Click mouse button at a given position
   - Parameters:
     - `x` (number): X coordinate
     - `y` (number): Y coordinate
+    - `button` (string, optional): Button to click, defaults to left
+    - `clickCount` (number, optional): Number of clicks, defaults to 1
+    - `delay` (number, optional): Time to wait between mouse down and mouse up in milliseconds, defaults to 0
   - Read-only: **false**
 
 <!-- NOTE: This has been generated via update-readme.js -->
@@ -1078,6 +1375,7 @@ http.createServer(async (req, res) => {
   - Parameters:
     - `element` (string, optional): Human-readable element description used to obtain permission to interact with the element
     - `ref` (string): Exact target element reference from the page snapshot
+    - `selector` (string, optional): CSS or role selector for the target element, when "ref" is not available
   - Read-only: **true**
 
 <!-- NOTE: This has been generated via update-readme.js -->
@@ -1098,6 +1396,7 @@ http.createServer(async (req, res) => {
   - Parameters:
     - `element` (string): Human-readable list description
     - `ref` (string): Exact target element reference that points to the list
+    - `selector` (string, optional): CSS or role selector for the target list, when "ref" is not available.
     - `items` (array): Items to verify
   - Read-only: **false**
 
@@ -1118,32 +1417,12 @@ http.createServer(async (req, res) => {
   - Parameters:
     - `type` (string): Type of the element
     - `element` (string): Human-readable element description
-    - `ref` (string): Exact target element reference that points to the element
+    - `ref` (string): Exact target element reference from the page snapshot
+    - `selector` (string, optional): CSS or role selector for the target element, when "ref" is not available
     - `value` (string): Value to verify. For checkbox, use "true" or "false".
   - Read-only: **false**
 
 </details>
 
-<details>
-<summary><b>Tracing (opt-in via --caps=tracing)</b></summary>
-
-<!-- NOTE: This has been generated via update-readme.js -->
-
-- **browser_start_tracing**
-  - Title: Start tracing
-  - Description: Start trace recording
-  - Parameters: None
-  - Read-only: **true**
-
-<!-- NOTE: This has been generated via update-readme.js -->
-
-- **browser_stop_tracing**
-  - Title: Stop tracing
-  - Description: Stop trace recording
-  - Parameters: None
-  - Read-only: **true**
-
-</details>
-
 
 <!--- End of tools generated section -->

package.json

@@ -1,6 +1,6 @@
 {
   "name": "playwright-mcp-internal",
-  "version": "0.0.61",
+  "version": "0.0.68",
   "private": true,
   "repository": {
     "type": "git",
@@ -17,14 +17,16 @@
     "docker-run": "docker run -it -p 8080:8080 --name playwright-mcp-dev playwright-mcp-dev:latest",
     "lint": "npm run lint --workspaces",
     "test": "npm run test --workspaces",
-    "build": "npm run build --workspaces"
+    "build": "npm run build --workspaces",
+    "bump": "npm version --workspaces --no-git-tag-version",
+    "roll": "node roll.js"
   },
   "workspaces": [
     "packages/*"
   ],
   "devDependencies": {
     "@modelcontextprotocol/sdk": "^1.25.2",
-    "@playwright/test": "1.59.0-alpha-1769452054000",
+    "@playwright/test": "1.59.0-alpha-1773608981000",
     "@types/node": "^24.3.0"
   }
 }

packages/extension/README.md

@@ -10,16 +10,9 @@ The Playwright MCP Chrome Extension allows you to connect to pages in your exist
 
 ## Installation Steps
 
-### Download the Extension
+### Install the Extension
 
-Download the latest Chrome extension from GitHub:
-- **Download link**: https://github.com/microsoft/playwright-mcp/releases
-
-### Load Chrome Extension
-
-1. Open Chrome and navigate to `chrome://extensions/`
-2. Enable "Developer mode" (toggle in the top right corner)
-3. Click "Load unpacked" and select the extension directory
+Install [Playwright MCP Bridge](https://chromewebstore.google.com/detail/playwright-mcp-bridge/mmlmfjhmonkocbjadbfplnigmagldckm) from the Chrome Web Store.
 
 ### Configure Playwright MCP server
 

packages/extension/manifest.json

@@ -1,14 +1,12 @@
 {
   "manifest_version": 3,
   "name": "Playwright MCP Bridge",
-  "version": "0.0.61",
+  "version": "0.0.68",
   "description": "Share browser tabs with Playwright MCP server",
-  "key": "MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEA9nMS2b0WCohjVHPGb8D9qAdkbIngDqoAjTeSccHJijgcONejge+OJxOQOMLu7b0ovt1c9BiEJa5JcpM+EHFVGL1vluBxK71zmBy1m2f9vZF3HG0LSCp7YRkum9rAIEthDwbkxx6XTvpmAY5rjFa/NON6b9Hlbo+8peUSkoOK7HTwYnnI36asZ9eUTiveIf+DMPLojW2UX33vDWG2UKvMVDewzclb4+uLxAYshY7Mx8we/b44xu+Anb/EBLKjOPk9Yh541xJ5Ozc8EiP/5yxOp9c/lRiYUHaRW+4r0HKZyFt0eZ52ti2iM4Nfk7jRXR7an3JPsUIf5deC/1cVM/+1ZQIDAQAB",
   "permissions": [
     "debugger",
     "activeTab",
-    "tabs",
-    "storage"
+    "tabs"
   ],
   "host_permissions": [
     "<all_urls>"

packages/extension/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@playwright/mcp-extension",
-  "version": "0.0.61",
+  "version": "0.0.68",
   "description": "Playwright MCP Browser Extension",
   "private": true,
   "repository": {
@@ -27,10 +27,11 @@
     "@types/react": "^18.2.66",
     "@types/react-dom": "^18.2.22",
     "@vitejs/plugin-react": "^4.0.0",
+    "minimist": "^1.2.5",
     "react": "^18.2.0",
     "react-dom": "^18.2.0",
     "typescript": "^5.8.2",
-    "vite": "^5.4.21",
+    "vite": "^7.3.1",
     "vite-plugin-static-copy": "^3.1.1"
   }
 }

packages/extension/src/background.ts

@@ -190,7 +190,6 @@ class TabShareExtension {
             chrome.tabs.sendMessage(tabId, { type: 'connectionTimeout' });
           }
         }, 5000);
-        return;
       }
     }
   }

packages/extension/tests/extension.spec.ts

@@ -14,9 +14,10 @@
  * limitations under the License.
  */
 
-import fs from 'fs';
+import fs from 'fs/promises';
 import path from 'path';
 import { chromium } from 'playwright';
+import { spawn } from 'child_process';
 import { test as base, expect } from '../../playwright-mcp/tests/fixtures';
 
 import type { Client } from '@modelcontextprotocol/sdk/client/index.js';
@@ -28,16 +29,35 @@ type BrowserWithExtension = {
   launch: (mode?: 'disable-extension') => Promise<BrowserContext>;
 };
 
+type CliResult = {
+  output: string;
+  error: string;
+};
+
 type TestFixtures = {
   browserWithExtension: BrowserWithExtension,
   pathToExtension: string,
   useShortConnectionTimeout: (timeoutMs: number) => void
   overrideProtocolVersion: (version: number) => void
+  cli: (...args: string[]) => Promise<CliResult>;
 };
 
+const extensionPublicKey = 'MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAwRsUUO4mmbCi4JpmrIoIw31iVW9+xUJRZ6nSzya17PQkaUPDxe1IpgM+vpd/xB6mJWlJSyE1Lj95c0sbomGfVY1M0zUeKbaRVcAb+/a6m59gNR+ubFlmTX0nK9/8fE2FpRB9D+4N5jyeIPQuASW/0oswI2/ijK7hH5NTRX8gWc/ROMSgUj7rKhTAgBrICt/NsStgDPsxRTPPJnhJ/ViJtM1P5KsSYswE987DPoFnpmkFpq8g1ae0eYbQfXy55ieaacC4QWyJPj3daU2kMfBQw7MXnnk0H/WDxouMOIHnd8MlQxpEMqAihj7KpuONH+MUhuj9HEQo4df6bSaIuQ0b4QIDAQAB';
+const extensionId = 'mmlmfjhmonkocbjadbfplnigmagldckm';
+
 const test = base.extend<TestFixtures>({
-  pathToExtension: async ({}, use) => {
-    await use(path.resolve(__dirname, '../dist'));
+  pathToExtension: async ({}, use, testInfo) => {
+    const extensionDir = testInfo.outputPath('extension');
+    const srcDir = path.resolve(__dirname, '../dist');
+    await fs.cp(srcDir, extensionDir, { recursive: true });
+    const manifestPath = path.join(extensionDir, 'manifest.json');
+    const manifest = JSON.parse(await fs.readFile(manifestPath, 'utf8'));
+    // We don't hardcode the key in manifest, but for the tests we set the key field
+    // to ensure that locally installed extension has the same id as the one published
+    // in the store.
+    manifest.key = extensionPublicKey;
+    await fs.writeFile(manifestPath, JSON.stringify(manifest, null, 2));
+    await use(extensionDir);
   },
 
   browserWithExtension: async ({ mcpBrowser, pathToExtension }, use, testInfo) => {
@@ -71,6 +91,9 @@ const test = base.extend<TestFixtures>({
       }
     });
     await browserContext?.close();
+
+    // Free up disk space.
+    await fs.rm(userDataDir, { recursive: true, force: true }).catch(() => {});
   },
 
   useShortConnectionTimeout: async ({}, use) => {
@@ -85,9 +108,73 @@ const test = base.extend<TestFixtures>({
       process.env.PWMCP_TEST_PROTOCOL_VERSION = version.toString();
     });
     process.env.PWMCP_TEST_PROTOCOL_VERSION = undefined;
-  }
+  },
+
+  cli: async ({ mcpBrowser }, use, testInfo) => {
+    await use(async (...args: string[]) => {
+      return await runCli(args, { mcpBrowser, testInfo });
+    });
+
+    // Cleanup sessions
+    await runCli(['close-all'], { mcpBrowser, testInfo }).catch(() => {});
+
+    const daemonDir = path.join(testInfo.outputDir, 'daemon');
+    await fs.rm(daemonDir, { recursive: true, force: true }).catch(() => {});
+  },
 });
 
+async function runCli(
+  args: string[],
+  options: { mcpBrowser?: string, testInfo: any },
+): Promise<CliResult> {
+  const stepTitle = `cli ${args.join(' ')}`;
+
+  return await test.step(stepTitle, async () => {
+    const testInfo = options.testInfo;
+
+    // Path to the terminal CLI
+    const cliPath = path.join(__dirname, '../../../node_modules/playwright/lib/cli/client/program.js');
+
+    return new Promise<CliResult>((resolve, reject) => {
+      let stdout = '';
+      let stderr = '';
+
+      const childProcess = spawn(process.execPath, [cliPath, ...args], {
+        cwd: testInfo.outputPath(),
+        env: {
+          ...process.env,
+          PLAYWRIGHT_DAEMON_INSTALL_DIR: testInfo.outputPath(),
+          PLAYWRIGHT_DAEMON_SESSION_DIR: testInfo.outputPath('daemon'),
+          PLAYWRIGHT_DAEMON_SOCKETS_DIR: path.join(testInfo.project.outputDir, 'daemon-sockets'),
+          PLAYWRIGHT_MCP_BROWSER: options.mcpBrowser,
+          PLAYWRIGHT_MCP_HEADLESS: 'false',
+        },
+        detached: true,
+      });
+
+      childProcess.stdout?.on('data', (data) => {
+        stdout += data.toString();
+      });
+
+      childProcess.stderr?.on('data', (data) => {
+        if (process.env.PWMCP_DEBUG)
+          process.stderr.write(data);
+        stderr += data.toString();
+      });
+
+      childProcess.on('close', async (code) => {
+        await testInfo.attach(stepTitle, { body: stdout, contentType: 'text/plain' });
+        resolve({
+          output: stdout.trim(),
+          error: stderr.trim(),
+        });
+      });
+
+      childProcess.on('error', reject);
+    });
+  });
+}
+
 async function startWithExtensionFlag(browserWithExtension: BrowserWithExtension, startClient: StartClient): Promise<Client> {
   const { client } = await startClient({
     args: [`--extension`],
@@ -101,17 +188,13 @@ async function startWithExtensionFlag(browserWithExtension: BrowserWithExtension
 }
 
 const testWithOldExtensionVersion = test.extend({
-  pathToExtension: async ({}, use, testInfo) => {
-    const extensionDir = testInfo.outputPath('extension');
-    const oldPath = path.resolve(__dirname, '../dist');
-
-    await fs.promises.cp(oldPath, extensionDir, { recursive: true });
-    const manifestPath = path.join(extensionDir, 'manifest.json');
-    const manifest = JSON.parse(await fs.promises.readFile(manifestPath, 'utf8'));
+  pathToExtension: async ({ pathToExtension }, use, testInfo) => {
+    const manifestPath = path.join(pathToExtension, 'manifest.json');
+    const manifest = JSON.parse(await fs.readFile(manifestPath, 'utf8'));
+    manifest.key = extensionPublicKey;
     manifest.version = '0.0.1';
-    await fs.promises.writeFile(manifestPath, JSON.stringify(manifest, null, 2) + '\n');
-
-    await use(extensionDir);
+    await fs.writeFile(manifestPath, JSON.stringify(manifest, null, 2));
+    await use(pathToExtension);
   },
 });
 
@@ -121,7 +204,7 @@ test(`navigate with extension`, async ({ browserWithExtension, startClient, serv
   const client = await startWithExtensionFlag(browserWithExtension, startClient);
 
   const confirmationPagePromise = browserContext.waitForEvent('page', page => {
-    return page.url().startsWith('chrome-extension://jakfalbnbhgkpmoaakfflhflbfpkailf/connect.html');
+    return page.url().startsWith(`chrome-extension://${extensionId}/connect.html`);
   });
 
   const navigateResponse = client.callTool({
@@ -152,7 +235,7 @@ test(`snapshot of an existing page`, async ({ browserWithExtension, startClient,
   expect(browserContext.pages()).toHaveLength(3);
 
   const confirmationPagePromise = browserContext.waitForEvent('page', page => {
-    return page.url().startsWith('chrome-extension://jakfalbnbhgkpmoaakfflhflbfpkailf/connect.html');
+    return page.url().startsWith(`chrome-extension://${extensionId}/connect.html`);
   });
 
   const navigateResponse = client.callTool({
@@ -180,7 +263,7 @@ test(`extension not installed timeout`, async ({ browserWithExtension, startClie
   const client = await startWithExtensionFlag(browserWithExtension, startClient);
 
   const confirmationPagePromise = browserContext.waitForEvent('page', page => {
-    return page.url().startsWith('chrome-extension://jakfalbnbhgkpmoaakfflhflbfpkailf/connect.html');
+    return page.url().startsWith(`chrome-extension://${extensionId}/connect.html`);
   });
 
   expect(await client.callTool({
@@ -203,7 +286,7 @@ testWithOldExtensionVersion(`works with old extension version`, async ({ browser
   const client = await startWithExtensionFlag(browserWithExtension, startClient);
 
   const confirmationPagePromise = browserContext.waitForEvent('page', page => {
-    return page.url().startsWith('chrome-extension://jakfalbnbhgkpmoaakfflhflbfpkailf/connect.html');
+    return page.url().startsWith(`chrome-extension://${extensionId}/connect.html`);
   });
 
   const navigateResponse = client.callTool({
@@ -230,7 +313,7 @@ test(`extension needs update`, async ({ browserWithExtension, startClient, serve
   const client = await startWithExtensionFlag(browserWithExtension, startClient);
 
   const confirmationPagePromise = browserContext.waitForEvent('page', page => {
-    return page.url().startsWith('chrome-extension://jakfalbnbhgkpmoaakfflhflbfpkailf/connect.html');
+    return page.url().startsWith(`chrome-extension://${extensionId}/connect.html`);
   });
 
   const navigateResponse = client.callTool({
@@ -251,7 +334,7 @@ test(`custom executablePath`, async ({ startClient, server, useShortConnectionTi
   useShortConnectionTimeout(1000);
 
   const executablePath = test.info().outputPath('echo.sh');
-  await fs.promises.writeFile(executablePath, '#!/bin/bash\necho "Custom exec args: $@" > "$(dirname "$0")/output.txt"', { mode: 0o755 });
+  await fs.writeFile(executablePath, '#!/bin/bash\necho "Custom exec args: $@" > "$(dirname "$0")/output.txt"', { mode: 0o755 });
 
   const { client } = await startClient({
     args: [`--extension`],
@@ -272,14 +355,14 @@ test(`custom executablePath`, async ({ startClient, server, useShortConnectionTi
     error: expect.stringContaining('Extension connection timeout.'),
     isError: true,
   });
-  expect(await fs.promises.readFile(test.info().outputPath('output.txt'), 'utf8')).toContain('Custom exec args: chrome-extension://jakfalbnbhgkpmoaakfflhflbfpkailf/connect.html?');
+  expect(await fs.readFile(test.info().outputPath('output.txt'), 'utf8')).toMatch(new RegExp(`Custom exec args.*chrome-extension://${extensionId}/connect\\.html\\?`));
 });
 
 test(`bypass connection dialog with token`, async ({ browserWithExtension, startClient, server }) => {
   const browserContext = await browserWithExtension.launch();
 
   const page = await browserContext.newPage();
-  await page.goto('chrome-extension://jakfalbnbhgkpmoaakfflhflbfpkailf/status.html');
+  await page.goto(`chrome-extension://${extensionId}/status.html`);
   const token = await page.locator('.auth-token-code').textContent();
   const [name, value] = token?.split('=') || [];
 
@@ -302,3 +385,38 @@ test(`bypass connection dialog with token`, async ({ browserWithExtension, start
     snapshot: expect.stringContaining(`- generic [active] [ref=e1]: Hello, world!`),
   });
 });
+
+test.describe('CLI with extension', () => {
+  test('open <url> --extension', async ({ browserWithExtension, cli, server }, testInfo) => {
+    const browserContext = await browserWithExtension.launch();
+
+    // Write config file with userDataDir 
+    const configPath = testInfo.outputPath('cli-config.json');
+    await fs.writeFile(configPath, JSON.stringify({
+      browser: {
+        userDataDir: browserWithExtension.userDataDir,
+      }
+    }, null, 2));
+
+    const confirmationPagePromise = browserContext.waitForEvent('page', page => {
+      return page.url().startsWith(`chrome-extension://${extensionId}/connect.html`);
+    });
+
+    // Start the CLI command in the background
+    const cliPromise = cli('open', server.HELLO_WORLD, '--extension', `--config=cli-config.json`);
+
+    // Wait for the confirmation page to appear
+    const confirmationPage = await confirmationPagePromise;
+
+    // Click the Connect button
+    await confirmationPage.locator('.tab-item', { hasText: 'Playwright MCP extension' }).getByRole('button', { name: 'Connect' }).click();
+
+    // Wait for the CLI command to complete
+    const { output } = await cliPromise;
+
+    // Verify the output
+    expect(output).toContain(`### Page`);
+    expect(output).toContain(`- Page URL: ${server.HELLO_WORLD}`);
+    expect(output).toContain(`- Page Title: Title`);
+  });
+});

packages/extension/vite.config.mts

@@ -19,6 +19,10 @@ import { defineConfig } from 'vite';
 import react from '@vitejs/plugin-react';
 import { viteStaticCopy } from 'vite-plugin-static-copy';
 
+// Public key matching the Chrome Web Store listing — used to fix the extension ID across installs.
+// Set SET_EXTENSION_PUBLIC_KEY_IN_MANIFEST=1 in release builds to inject it into the manifest.
+const extensionPublicKey = 'MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAwRsUUO4mmbCi4JpmrIoIw31iVW9+xUJRZ6nSzya17PQkaUPDxe1IpgM+vpd/xB6mJWlJSyE1Lj95c0sbomGfVY1M0zUeKbaRVcAb+/a6m59gNR+ubFlmTX0nK9/8fE2FpRB9D+4N5jyeIPQuASW/0oswI2/ijK7hH5NTRX8gWc/ROMSgUj7rKhTAgBrICt/NsStgDPsxRTPPJnhJ/ViJtM1P5KsSYswE987DPoFnpmkFpq8g1ae0eYbQfXy55ieaacC4QWyJPj3daU2kMfBQw7MXnnk0H/WDxouMOIHnd8MlQxpEMqAihj7KpuONH+MUhuj9HEQo4df6bSaIuQ0b4QIDAQAB';
+
 // https://vitejs.dev/config/
 export default defineConfig({
   plugins: [
@@ -31,7 +35,14 @@ export default defineConfig({
         },
         {
           src: '../../manifest.json',
-          dest: '.'
+          dest: '.',
+          ...(!!process.env.SET_EXTENSION_PUBLIC_KEY_IN_MANIFEST ? {
+            transform: (content: string) => {
+              const manifest = JSON.parse(content);
+              manifest.key = extensionPublicKey;
+              return JSON.stringify(manifest, null, 2);
+            }
+          } : {})
         }
       ]
     })

packages/playwright-cli-stub/README.md

@@ -0,0 +1,7 @@
+# 🎭 Playwright CLI
+
+This package has moved to @playwright/cli.
+
+```sh
+$ npm i -g @playwright/cli
+```

packages/playwright-cli-stub/package.json

@@ -0,0 +1,19 @@
+{
+  "name": "playwright-cli",
+  "version": "0.262.0",
+  "description": "Deprecated package, use @playwright/cli instead.",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/microsoft/playwright-cli.git"
+  },
+  "homepage": "https://playwright.dev",
+  "scripts": {
+    "lint": "echo OK",
+    "build": "echo OK",
+    "test": "echo OK"
+  },
+  "author": {
+    "name": "Microsoft Corporation"
+  },
+  "license": "Apache-2.0"
+}

packages/playwright-cli/.npmignore

@@ -1,4 +0,0 @@
-**/*
-!README.md
-!LICENSE
-!playwright-cli.js

packages/playwright-cli/README.md

@@ -1,391 +0,0 @@
-# playwright-cli
-
-Playwright CLI with SKILLS
-
-### Playwright CLI vs Playwright MCP
-
-This package provides CLI interface into Playwright. If you are using **coding agents**, that is the best fit.
-
-- **CLI**: Modern **coding agents** increasingly favor CLI–based workflows exposed as SKILLs over MCP because CLI invocations are more token-efficient: they avoid loading large tool schemas and verbose accessibility trees into the model context, allowing agents to act through concise, purpose-built commands. This makes CLI + SKILLs better suited for high-throughput coding agents that must balance browser automation with large codebases, tests, and reasoning within limited context windows.
-
-- **MCP**: MCP remains relevant for specialized agentic loops that benefit from persistent state, rich introspection, and iterative reasoning over page structure, such as exploratory automation, self-healing tests, or long-running autonomous workflows where maintaining continuous browser context outweighs token cost concerns. Learn more about [Playwright MCP](https://github.com/microsoft/playwright-mcp).
-
-### Key Features
-
-- **Token-efficient**. Does not force page data into LLM.
-
-### Requirements
-- Node.js 18 or newer
-- Claude Code, GitHub Copilot, or any other coding agent.
-
-## Getting Started
-
-## Installation
-
-```bash
-npm install -g @playwright/cli@latest
-playwright-cli --help
-```
-
-## Demo
-
-```
-> Use playwright skills to test https://demo.playwright.dev/todomvc/.
-  Take screenshots for all successful and failing scenarios. 
-```
-
-Your agent will be running commands, but it does not mean you can't play with it manually:
-
-```
-playwright-cli open https://demo.playwright.dev/todomvc/ --headed
-playwright-cli type "Buy groceries"
-playwright-cli press Enter
-playwright-cli type "Water flowers"
-playwright-cli press Enter
-playwright-cli check e21
-playwright-cli check e35
-playwright-cli screenshot
-```
-
-### Skills-less operation
-
-Point your agent at the CLI and let it cook. It'll read the skill off `playwright-cli --help` on its own:
-
-```
-Test the "add todo" flow on https://demo.playwright.dev/todomvc using playwright-cli.
-Check playwright-cli --help for available commands.
-```
-
-### Installing skills
-
-Claude Code, GitHub copilot and others will let you install the Playwright skills into the agentic loop.
-
-#### plugin (recommended)
-```bash
-/plugin marketplace add microsoft/playwright-cli
-/plugin install playwright-cli
-```
-
-#### manual
-
-```bash
-mkdir -p .claude/skills/playwright-cli
-curl -o .claude/skills/playwright-cli/SKILL.md \
-  https://raw.githubusercontent.com/microsoft/playwright-cli/main/skills/playwright-cli/SKILL.md
-```
-
-## Headed operation
-
-Playwright CLI is headless by default. If you'd like to see the browser, pass `--headed` to `open`:
-
-```bash
-playwright-cli open https://playwright.dev --headed
-```
-
-## Sessions
-
-Playwright CLI will use a dedicated persistent profile by default. It means that
-your cookies and other storage state will be preserved between the calls. You can use different
-instances of the browser for different projects with sessions.
-
-Following will result in two browsers with separate profiles being available. Pass `--session` to
-the invocation to talk to a specific browser.
-
-```bash
-playwright-cli open https://playwright.dev
-playwright-cli --session=example open https://example.com
-playwright-cli session-list
-```
-
-You can run your coding agent with the `PLAYWRIGHT_CLI_SESSION` environment variable:
-
-```bash
-PLAYWRIGHT_CLI_SESSION=todo-app claude .
-```
-
-Or instruct it to prepend `--session` to the calls.
-
-Manage your sessions as follows:
-
-```bash
-playwright-cli session-list             # list all sessions
-playwright-cli session-stop [name]      # stop session
-playwright-cli session-stop-all         # stop all sessions
-playwright-cli session-delete [name]    # delete session data along with the profiles
-```
-
-<!-- BEGIN GENERATED CLI HELP -->
-
-## Commands
-
-### Core
-
-```bash
-playwright-cli open <url>               # open url
-playwright-cli close                    # close the page
-playwright-cli type <text>              # type text into editable element
-playwright-cli click <ref> [button]     # perform click on a web page
-playwright-cli dblclick <ref> [button]  # perform double click on a web page
-playwright-cli fill <ref> <text>        # fill text into editable element
-playwright-cli drag <startRef> <endRef> # perform drag and drop between two elements
-playwright-cli hover <ref>              # hover over element on page
-playwright-cli select <ref> <val>       # select an option in a dropdown
-playwright-cli upload <file>            # upload one or multiple files
-playwright-cli check <ref>              # check a checkbox or radio button
-playwright-cli uncheck <ref>            # uncheck a checkbox or radio button
-playwright-cli snapshot                 # capture page snapshot to obtain element ref
-playwright-cli eval <func> [ref]        # evaluate javascript expression on page or element
-playwright-cli dialog-accept [prompt]   # accept a dialog
-playwright-cli dialog-dismiss           # dismiss a dialog
-playwright-cli resize <w> <h>           # resize the browser window
-```
-
-### Navigation
-
-```bash
-playwright-cli go-back                  # go back to the previous page
-playwright-cli go-forward               # go forward to the next page
-playwright-cli reload                   # reload the current page
-```
-
-### Keyboard
-
-```bash
-playwright-cli press <key>              # press a key on the keyboard, `a`, `arrowleft`
-playwright-cli keydown <key>            # press a key down on the keyboard
-playwright-cli keyup <key>              # press a key up on the keyboard
-```
-
-### Mouse
-
-```bash
-playwright-cli mousemove <x> <y>        # move mouse to a given position
-playwright-cli mousedown [button]       # press mouse down
-playwright-cli mouseup [button]         # press mouse up
-playwright-cli mousewheel <dx> <dy>     # scroll mouse wheel
-```
-
-### Save as
-
-```bash
-playwright-cli screenshot [ref]         # screenshot of the current page or element
-playwright-cli pdf                      # save page as pdf
-```
-
-### Tabs
-
-```bash
-playwright-cli tab-list                 # list all tabs
-playwright-cli tab-new [url]            # create a new tab
-playwright-cli tab-close [index]        # close a browser tab
-playwright-cli tab-select <index>       # select a browser tab
-```
-
-### DevTools
-
-```bash
-playwright-cli console [min-level]      # list console messages
-playwright-cli network                  # list all network requests since loading the page
-playwright-cli run-code <code>          # run playwright code snippet
-playwright-cli tracing-start            # start trace recording
-playwright-cli tracing-stop             # stop trace recording
-```
-<!-- END GENERATED CLI HELP -->
-
-## Configuration file
-
-The Playwright CLI can be configured using a JSON configuration file. You can specify the configuration file using the `--config` command line option:
-
-```bash
-playwright-cli --config path/to/config.json open example.com
-```
-
-Playwright CLI will load config from `playwright-cli.json` by default so that you did not need to specify it every time.
-
-<details>
-<summary>Configuration file schema</summary>
-
-```typescript
-{
-  /**
-   * The browser to use.
-   */
-  browser?: {
-    /**
-     * 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;
-
-    /**
-     * CDP headers to send with the connect request.
-     */
-    cdpHeaders?: Record<string, string>;
-
-    /**
-     * Timeout in milliseconds for connecting to CDP endpoint. Defaults to 30000 (30 seconds). Pass 0 to disable timeout.
-     */
-    cdpTimeout?: number;
-
-    /**
-     * Remote endpoint to connect to an existing Playwright server.
-     */
-    remoteEndpoint?: string;
-
-    /**
-     * Paths to TypeScript files to add as initialization scripts for Playwright page.
-     */
-    initPage?: string[];
-
-    /**
-     * Paths to JavaScript files to add as initialization scripts.
-     * The scripts will be evaluated in every page before any of the page's scripts.
-     */
-    initScript?: string[];
-  },
-
-  /**
-   * If specified, saves the Playwright video of the session into the output directory.
-   */
-  saveVideo?: {
-    width: number;
-    height: number;
-  };
-
-  /**
-   * The directory to save output files.
-   */
-  outputDir?: string;
-
-  /**
-   * Whether to save snapshots, console messages, network logs and other session logs to a file or to the standard output. Defaults to "stdout".
-   */
-  outputMode?: 'file' | 'stdout';
-
-  console?: {
-    /**
-     * The level of console messages to return. Each level includes the messages of more severe levels. Defaults to "info".
-     */
-    level?: 'error' | 'warning' | 'info' | 'debug';
-  },
-
-  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[];
-  };
-
-  /**
-   * Specify the attribute to use for test ids, defaults to "data-testid".
-   */
-  testIdAttribute?: string;
-
-  timeouts?: {
-    /*
-     * Configures default action timeout: https://playwright.dev/docs/api/class-page#page-set-default-timeout. Defaults to 5000ms.
-     */
-    action?: number;
-
-    /*
-     * Configures default navigation timeout: https://playwright.dev/docs/api/class-page#page-set-default-navigation-timeout. Defaults to 60000ms.
-     */
-    navigation?: number;
-  };
-
-  /**
-   * Whether to allow file uploads from anywhere on the file system.
-   * By default (false), file uploads are restricted to paths within the MCP roots only.
-   */
-  allowUnrestrictedFileAccess?: boolean;
-
-  /**
-   * Specify the language to use for code generation.
-   */
-  codegen?: 'typescript' | 'none';
-}
-```
-
-</details>
-
-## Environment
-
-| Environment |
-|-------------|
-| `PLAYWRIGHT_MCP_ALLOWED_HOSTS` comma-separated list of hosts this server is allowed to serve from. Defaults to the host the server is bound to. Pass '*' to disable the host check. |
-| `PLAYWRIGHT_MCP_ALLOWED_ORIGINS` semicolon-separated list of TRUSTED origins to allow the browser to request. Default is to allow all. Important: *does not* serve as a security boundary and *does not* affect redirects. |
-| `PLAYWRIGHT_MCP_ALLOW_UNRESTRICTED_FILE_ACCESS` allow access to files outside of the workspace roots. Also allows unrestricted access to file:// URLs. By default access to file system is restricted to workspace root directories (or cwd if no roots are configured) only, and navigation to file:// URLs is blocked. |
-| `PLAYWRIGHT_MCP_BLOCKED_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. Important: *does not* serve as a security boundary and *does not* affect redirects. |
-| `PLAYWRIGHT_MCP_BLOCK_SERVICE_WORKERS` block service workers |
-| `PLAYWRIGHT_MCP_BROWSER` browser or chrome channel to use, possible values: chrome, firefox, webkit, msedge. |
-| `PLAYWRIGHT_MCP_CAPS` comma-separated list of additional capabilities to enable, possible values: vision, pdf. |
-| `PLAYWRIGHT_MCP_CDP_ENDPOINT` CDP endpoint to connect to. |
-| `PLAYWRIGHT_MCP_CDP_HEADER` CDP headers to send with the connect request, multiple can be specified. |
-| `PLAYWRIGHT_MCP_CODEGEN` specify the language to use for code generation, possible values: "typescript", "none". Default is "typescript". |
-| `PLAYWRIGHT_MCP_CONFIG` path to the configuration file. |
-| `PLAYWRIGHT_MCP_CONSOLE_LEVEL` level of console messages to return: "error", "warning", "info", "debug". Each level includes the messages of more severe levels. |
-| `PLAYWRIGHT_MCP_DEVICE` device to emulate, for example: "iPhone 15" |
-| `PLAYWRIGHT_MCP_EXECUTABLE_PATH` path to the browser executable. |
-| `PLAYWRIGHT_MCP_EXTENSION` Connect to a running browser instance (Edge/Chrome only). Requires the "Playwright MCP Bridge" browser extension to be installed. |
-| `PLAYWRIGHT_MCP_GRANT_PERMISSIONS` List of permissions to grant to the browser context, for example "geolocation", "clipboard-read", "clipboard-write". |
-| `PLAYWRIGHT_MCP_HEADLESS` run browser in headless mode, headed by default |
-| `PLAYWRIGHT_MCP_HOST` host to bind server to. Default is localhost. Use 0.0.0.0 to bind to all interfaces. |
-| `PLAYWRIGHT_MCP_IGNORE_HTTPS_ERRORS` ignore https errors |
-| `PLAYWRIGHT_MCP_INIT_PAGE` path to TypeScript file to evaluate on Playwright page object |
-| `PLAYWRIGHT_MCP_INIT_SCRIPT` path to JavaScript file to add as an initialization script. The script will be evaluated in every page before any of the page's scripts. Can be specified multiple times. |
-| `PLAYWRIGHT_MCP_ISOLATED` keep the browser profile in memory, do not save it to disk. |
-| `PLAYWRIGHT_MCP_IMAGE_RESPONSES` whether to send image responses to the client. Can be "allow" or "omit", Defaults to "allow". |
-| `PLAYWRIGHT_MCP_NO_SANDBOX` disable the sandbox for all process types that are normally sandboxed. |
-| `PLAYWRIGHT_MCP_OUTPUT_DIR` path to the directory for output files. |
-| `PLAYWRIGHT_MCP_OUTPUT_MODE` whether to save snapshots, console messages, network logs to a file or to the standard output. Can be "file" or "stdout". Default is "stdout". |
-| `PLAYWRIGHT_MCP_PORT` port to listen on for SSE transport. |
-| `PLAYWRIGHT_MCP_PROXY_BYPASS` comma-separated domains to bypass proxy, for example ".com,chromium.org,.domain.com" |
-| `PLAYWRIGHT_MCP_PROXY_SERVER` specify proxy server, for example "http://myproxy:3128" or "socks5://myproxy:8080" |
-| `PLAYWRIGHT_MCP_SAVE_SESSION` Whether to save the Playwright MCP session into the output directory. |
-| `PLAYWRIGHT_MCP_SAVE_TRACE` Whether to save the Playwright Trace of the session into the output directory. |
-| `PLAYWRIGHT_MCP_SAVE_VIDEO` Whether to save the video of the session into the output directory. For example "--save-video=800x600" |
-| `PLAYWRIGHT_MCP_SECRETS` path to a file containing secrets in the dotenv format |
-| `PLAYWRIGHT_MCP_SHARED_BROWSER_CONTEXT` reuse the same browser context between all connected HTTP clients. |
-| `PLAYWRIGHT_MCP_SNAPSHOT_MODE` when taking snapshots for responses, specifies the mode to use. Can be "incremental", "full", or "none". Default is incremental. |
-| `PLAYWRIGHT_MCP_STORAGE_STATE` path to the storage state file for isolated sessions. |
-| `PLAYWRIGHT_MCP_TEST_ID_ATTRIBUTE` specify the attribute to use for test ids, defaults to "data-testid" |
-| `PLAYWRIGHT_MCP_TIMEOUT_ACTION` specify action timeout in milliseconds, defaults to 5000ms |
-| `PLAYWRIGHT_MCP_TIMEOUT_NAVIGATION` specify navigation timeout in milliseconds, defaults to 60000ms |
-| `PLAYWRIGHT_MCP_USER_AGENT` specify user agent string |
-| `PLAYWRIGHT_MCP_USER_DATA_DIR` path to the user data directory. If not specified, a temporary directory will be created. |
-| `PLAYWRIGHT_MCP_VIEWPORT_SIZE` specify browser viewport size in pixels, for example "1280x720" |

packages/playwright-cli/package.json

@@ -1,30 +0,0 @@
-{
-  "name": "@playwright/cli",
-  "version": "0.0.61",
-  "description": "Playwright CLI",
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/microsoft/playwright-cli.git"
-  },
-  "homepage": "https://playwright.dev",
-  "engines": {
-    "node": ">=18"
-  },
-  "author": {
-    "name": "Microsoft Corporation"
-  },
-  "license": "Apache-2.0",
-  "scripts": {
-    "lint": "echo OK",
-    "build": "echo OK",
-    "test": "echo OK"
-  },
-  "dependencies": {
-    "minimist": "^1.2.5",
-    "playwright": "1.59.0-alpha-1769452054000",
-    "playwright-core": "1.59.0-alpha-1769452054000"
-  },
-  "bin": {
-    "playwright-cli": "playwright-cli.js"
-  }
-}

packages/playwright-mcp/cli.js

@@ -16,9 +16,17 @@
  */
 
 const { program } = require('playwright-core/lib/utilsBundle');
-const { decorateCommand } = require('playwright/lib/mcp/program');
+const { decorateMCPCommand } = require('playwright-core/lib/tools/mcp/program');
+
+if (process.argv.includes('install-browser')) {
+  const argv = process.argv.map(arg => arg === 'install-browser' ? 'install' : arg);
+  const { program: mainProgram } = require('playwright-core/lib/cli/program');
+  mainProgram.parse(argv);
+  return;
+}
 
 const packageJSON = require('./package.json');
 const p = program.version('Version ' + packageJSON.version).name('Playwright MCP');
-decorateCommand(p, packageJSON.version)
+decorateMCPCommand(p, packageJSON.version)
+
 void program.parseAsync(process.argv);

packages/playwright-mcp/config.d.ts

@@ -17,16 +17,18 @@
 import type * as playwright from 'playwright';
 
 export type ToolCapability =
+  'config' |
   'core' |
-  'core-input' |
   'core-navigation' |
   'core-tabs' |
-  'core-install' |
   'core-input' |
-  'vision' |
+  'core-install' |
+  'network' |
   'pdf' |
+  'storage' |
   'testing' |
-  'tracing';
+  'vision' |
+  'devtools';
 
 export type Config = {
   /**
@@ -96,6 +98,13 @@ export type Config = {
     initScript?: string[];
   },
 
+  /**
+   * Connect to a running browser instance (Edge/Chrome only). If specified, `browser`
+   * config is ignored.
+   * Requires the "Playwright MCP Bridge" browser extension to be installed.
+   */
+  extension?: boolean;
+
   server?: {
     /**
      * The port to listen on for SSE or MCP transport.
@@ -119,6 +128,7 @@ export type Config = {
    *   - 'core': Core browser automation features.
    *   - 'pdf': PDF generation and manipulation.
    *   - 'vision': Coordinate-based interactions.
+   *   - 'devtools': Developer tools features.
    */
   capabilities?: ToolCapability[];
 
@@ -127,19 +137,6 @@ export type Config = {
    */
   saveSession?: boolean;
 
-  /**
-   * Whether to save the Playwright trace of the session into the output directory.
-   */
-  saveTrace?: boolean;
-
-  /**
-   * If specified, saves the Playwright video of the session into the output directory.
-   */
-  saveVideo?: {
-    width: number;
-    height: number;
-  };
-
   /**
    * Reuse the same browser context between all connected HTTP clients.
    */
@@ -172,11 +169,19 @@ export type Config = {
   network?: {
     /**
      * List of origins to allow the browser to request. Default is to allow all. Origins matching both `allowedOrigins` and `blockedOrigins` will be blocked.
+     *
+     * Supported formats:
+     * - Full origin: `https://example.com:8080` - matches only that origin
+     * - Wildcard port: `http://localhost:*` - matches any port on localhost with http protocol
      */
     allowedOrigins?: string[];
 
     /**
      * List of origins to block the browser to request. Origins matching both `allowedOrigins` and `blockedOrigins` will be blocked.
+     *
+     * Supported formats:
+     * - Full origin: `https://example.com:8080` - matches only that origin
+     * - Wildcard port: `http://localhost:*` - matches any port on localhost with http protocol
      */
     blockedOrigins?: string[];
   };
@@ -196,6 +201,11 @@ export type Config = {
      * Configures default navigation timeout: https://playwright.dev/docs/api/class-page#page-set-default-navigation-timeout. Defaults to 60000ms.
      */
     navigation?: number;
+
+    /**
+     * Configures default expect timeout: https://playwright.dev/docs/test-timeouts#expect-timeout. Defaults to 5000ms.
+     */
+    expect?: number;
   };
 
   /**

packages/playwright-mcp/index.js

@@ -15,5 +15,5 @@
  * limitations under the License.
  */
 
-const { createConnection } = require('playwright/lib/mcp/index');
+const { createConnection } = require('playwright-core/lib/tools/exports');
 module.exports = { createConnection };

packages/playwright-mcp/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@playwright/mcp",
-  "version": "0.0.61",
+  "version": "0.0.68",
   "description": "Playwright Tools for MCP",
   "repository": {
     "type": "git",
@@ -14,6 +14,7 @@
     "name": "Microsoft Corporation"
   },
   "license": "Apache-2.0",
+  "mcpName": "io.github.microsoft/playwright-mcp",
   "scripts": {
     "lint": "node update-readme.js",
     "test": "playwright test",
@@ -22,9 +23,7 @@
     "wtest": "playwright test --project=webkit",
     "dtest": "MCP_IN_DOCKER=1 playwright test --project=chromium-docker",
     "build": "echo OK",
-    "npm-publish": "npm run lint && npm run test && npm publish",
-    "copy-config": "cp ../../../playwright/packages/playwright/src/mcp/config.d.ts . && perl -pi -e \"s|import type \\* as playwright from 'playwright-core';|import type * as playwright from 'playwright';|\" ./config.d.ts",
-    "roll": "npm run copy-config && npm run lint"
+    "npm-publish": "npm run lint && npm run test && npm publish"
   },
   "exports": {
     "./package.json": "./package.json",
@@ -34,8 +33,8 @@
     }
   },
   "dependencies": {
-    "playwright": "1.59.0-alpha-1769452054000",
-    "playwright-core": "1.59.0-alpha-1769452054000"
+    "playwright": "1.59.0-alpha-1773608981000",
+    "playwright-core": "1.59.0-alpha-1773608981000"
   },
   "bin": {
     "playwright-mcp": "cli.js"

packages/playwright-mcp/tests/capabilities.spec.ts

@@ -30,7 +30,6 @@ test('test snapshot tool list', async ({ client }) => {
     'browser_select_option',
     'browser_type',
     'browser_close',
-    'browser_install',
     'browser_navigate_back',
     'browser_navigate',
     'browser_network_requests',

packages/playwright-mcp/tests/cli.spec.ts

@@ -1,4 +1,3 @@
-#!/usr/bin/env node
 /**
  * Copyright (c) Microsoft Corporation.
  *
@@ -14,10 +13,13 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
+import child_process from 'child_process';
+import path from 'path';
+import { test, expect } from './fixtures';
 
-const { program } = require('playwright/lib/mcp/terminal/program');
-const packageJSON = require('./package.json');
-program({ version: packageJSON.version }).catch(e => {
-  console.error(e.message);
-  process.exit(1);
+const cliPath = path.resolve(__dirname, '..', 'cli.js');
+
+test('install-browser --help', async () => {
+  const output = child_process.execSync(`node ${cliPath} install-browser --help`, { encoding: 'utf-8' });
+  expect(output).toContain('install');
 });

packages/playwright-mcp/update-readme.js

@@ -20,23 +20,32 @@ const fs = require('fs')
 const path = require('path')
 const { execSync } = require('child_process');
 
-const { browserTools } = require('playwright/lib/mcp/browser/tools');
+const { browserTools } = require('playwright-core/lib/tools/exports');
 
-const capabilities = {
+const capabilities = /** @type {Record<string, string>} */ ({
   'core-navigation': 'Core automation',
   'core': 'Core automation',
   'core-tabs': 'Tab management',
   'core-input': 'Core automation',
   'core-install': 'Browser installation',
-  'vision': 'Coordinate-based (opt-in via --caps=vision)',
-  'pdf': 'PDF generation (opt-in via --caps=pdf)',
-  'testing': 'Test assertions (opt-in via --caps=testing)',
-  'tracing': 'Tracing (opt-in via --caps=tracing)',
-};
+  'config': 'Configuration',
+  'network': 'Network',
+  'storage': 'Storage',
+  'devtools': 'DevTools',
+  'vision': 'Coordinate-based',
+  'pdf': 'PDF generation',
+  'testing': 'Test assertions',
+});
+
+const knownCapabilities = new Set(Object.keys(capabilities));
+const unknownCapabilities = [...new Set(browserTools.map(tool => tool.capability))].filter(cap => !knownCapabilities.has(cap));
+if (unknownCapabilities.length)
+  throw new Error(`Unknown tool capabilities: ${unknownCapabilities.join(', ')}. Please update the capabilities map in ${path.basename(__filename)}.`);
 
 /** @type {Record<string, any[]>} */
 const toolsByCapability = {};
-for (const [capability, title] of Object.entries(capabilities)) {
+for (const capability of Object.keys(capabilities)) {
+  const title = capabilityTitle(capability);
   let tools = browserTools.filter(tool => tool.capability === capability && !tool.skillOnly);
   tools = (toolsByCapability[title] || []).concat(tools);
   toolsByCapability[title] = tools;
@@ -44,6 +53,15 @@ for (const [capability, title] of Object.entries(capabilities)) {
 for (const [, tools] of Object.entries(toolsByCapability))
   tools.sort((a, b) => a.schema.name.localeCompare(b.schema.name));
 
+/**
+ * @param {string} capability
+ * @returns {string}
+ */
+function capabilityTitle(capability) {
+  const title = capabilities[capability];
+  return capability.startsWith('core') ? title : `${title} (opt-in via --caps=${capability})`;
+}
+
 /**
  * @param {any} tool
  * @returns {string[]}

roll.js

@@ -0,0 +1,58 @@
+const fs = require('fs');
+const path = require('path');
+const { execSync } = require('child_process');
+
+function copyConfig() {
+  const src = path.join(__dirname, '..', 'playwright', 'packages', 'playwright-core', 'src', 'tools', 'mcp', 'config.d.ts');
+  const dst = path.join(__dirname, 'packages', 'playwright-mcp', 'config.d.ts');
+  let content = fs.readFileSync(src, 'utf-8');
+  content = content.replace(
+    "import type * as playwright from 'playwright-core';",
+    "import type * as playwright from 'playwright';"
+  );
+  fs.writeFileSync(dst, content);
+  console.log(`Copied config.d.ts from ${src} to ${dst}`);
+}
+
+function updatePlaywrightVersion(version) {
+  const packagesDir = path.join(__dirname, 'packages');
+  const files = [path.join(__dirname, 'package.json')];
+  for (const entry of fs.readdirSync(packagesDir, { withFileTypes: true })) {
+    const pkgJson = path.join(packagesDir, entry.name, 'package.json');
+    if (fs.existsSync(pkgJson))
+      files.push(pkgJson);
+  }
+
+  for (const file of files) {
+    const json = JSON.parse(fs.readFileSync(file, 'utf-8'));
+    let updated = false;
+    for (const section of ['dependencies', 'devDependencies']) {
+      for (const pkg of ['@playwright/test', 'playwright', 'playwright-core']) {
+        if (json[section]?.[pkg]) {
+          json[section][pkg] = version;
+          updated = true;
+        }
+      }
+    }
+    if (updated) {
+      fs.writeFileSync(file, JSON.stringify(json, null, 2) + '\n');
+      console.log(`Updated ${file}`);
+    }
+  }
+
+  execSync('npm install', { cwd: __dirname, stdio: 'inherit' });
+}
+
+function doRoll(version) {
+  updatePlaywrightVersion(version);
+  copyConfig();
+  // update readme
+  execSync('npm run lint', { cwd: __dirname, stdio: 'inherit' });
+}
+
+let version = process.argv[2];
+if (!version) {
+  version = execSync('npm info playwright@next version', { encoding: 'utf-8' }).trim();
+  console.log(`Using next playwright version: ${version}`);
+}
+doRoll(version);