[ { "path": ".agent/rules/coding.md", "content": "---\ntrigger: always_on\n---\n\n# Instructions\n\n- Use only scripts from `package.json` to run commands.\n- Use `npm run build` to run tsc and test build.\n- Use `npm run test` to build and run tests, run all tests to verify correctness.\n- Use `npm run test path-to-test.ts` to build and run a single test file, for example, `npm run test tests/McpContext.test.ts`.\n- Use `npm run format` to fix formatting and get linting errors.\n\n## Rules for TypeScript\n\n- Do not use `any` type.\n- Do not use `as` keyword for type casting.\n- Do not use `!` operator for type assertion.\n- Do not use `// @ts-ignore` comments.\n- Do not use `// @ts-nocheck` comments.\n- Do not use `// @ts-expect-error` comments.\n- Prefer `for..of` instead of `forEach`.\n" }, { "path": ".claude-plugin/marketplace.json", "content": "{\n \"name\": \"chrome-devtools-plugins\",\n \"version\": \"1.0.0\",\n \"description\": \"Bundled plugins for actuating and debugging the Chrome browser.\",\n \"owner\": {\n \"name\": \"Chrome DevTools Team\",\n \"email\": \"devtools-dev@chromium.org\"\n },\n \"plugins\": [\n {\n \"name\": \"chrome-devtools-mcp\",\n \"source\": \"./\",\n \"description\": \"Reliable automation, in-depth debugging, and performance analysis in Chrome using Chrome DevTools and Puppeteer\"\n }\n ]\n}\n" }, { "path": ".claude-plugin/plugin.json", "content": "{\n \"name\": \"chrome-devtools-mcp\",\n \"version\": \"latest\",\n \"description\": \"Reliable automation, in-depth debugging, and performance analysis in Chrome using Chrome DevTools and Puppeteer\",\n \"mcpServers\": {\n \"chrome-devtools\": {\n \"command\": \"npx\",\n \"args\": [\"chrome-devtools-mcp@latest\"]\n }\n }\n}\n" }, { "path": ".gitattributes", "content": "* text=auto eol=lf\n" }, { "path": ".github/ISSUE_TEMPLATE/01-bug.yml", "content": "name: Bug report\ndescription: File a bug report for chrome-devtools-mcp\ntitle: ''\ntype: 'Bug'\nbody:\n - id: description\n type: textarea\n attributes:\n label: Description of the bug\n description: >\n A clear and concise description of what the bug is.\n placeholder:\n validations:\n required: true\n\n - id: reproduce\n type: textarea\n attributes:\n label: Reproduction\n description: >\n Steps to reproduce the behavior:\n placeholder: |\n 1. Use tool '...'\n 2. Then use tool '...'\n\n - id: expectation\n type: textarea\n attributes:\n label: Expectation\n description: A clear and concise description of what you expected to happen.\n\n - id: mcp-configuration\n type: textarea\n attributes:\n label: MCP configuration\n\n - id: chrome-devtools-mcp-version\n type: input\n attributes:\n label: Chrome DevTools MCP version\n validations:\n required: true\n\n - id: chrome-version\n type: input\n attributes:\n label: Chrome version\n\n - id: coding-agent-version\n type: input\n attributes:\n label: Coding agent version\n\n - id: model-version\n type: input\n attributes:\n label: Model version\n\n - id: chat-log\n type: input\n attributes:\n label: Chat log\n\n - id: node-version\n type: input\n attributes:\n label: Node version\n description: >\n Please verify you have the minimal supported version listed in the README.md\n\n - id: operating-system\n type: dropdown\n attributes:\n label: Operating system\n description: What supported operating system are you running?\n options:\n - Windows\n - Windows Subsystem for Linux (WSL)\n - macOS\n - Linux\n\n - type: checkboxes\n id: provide-pr\n attributes:\n label: Extra checklist\n options:\n - label: I want to provide a PR to fix this bug\n" }, { "path": ".github/ISSUE_TEMPLATE/02-feature.yml", "content": "name: Feature\ndescription: Suggest an idea for for chrome-devtools-mcp\ntitle: ''\ntype: 'Feature'\nlabels:\n - feature\nbody:\n - id: description\n type: textarea\n attributes:\n label: Is your feature request related to a problem? Please describe.\n description: >\n A clear and concise description of what the problem is. Ex. I'm always frustrated when [...]\n placeholder:\n validations:\n required: true\n\n - id: solution\n type: textarea\n attributes:\n label: Describe the solution you'd like\n description: >\n A clear and concise description of what you want to happen.\n placeholder:\n validations:\n required: true\n\n - id: alternatives\n type: textarea\n attributes:\n label: Describe alternatives you've considered\n description: >\n A clear and concise description of any alternative solutions or features you've considered.\n placeholder:\n validations:\n required: true\n\n - id: additional-context\n type: textarea\n attributes:\n label: Additional context\n description: >\n Add any other context or screenshots about the feature request here.\n placeholder:\n" }, { "path": ".github/ISSUE_TEMPLATE/03-task.yml", "content": "name: Task\ndescription: Work tracking for mainainers only!\ntitle: '[Task]:'\ntype: 'Task'\nbody:\n - type: markdown\n attributes:\n value: |\n ### This issue type should be used only by mainainers!\n Task are to track small non user facing issue or improvements. \n The issue will be closed if it does not follow those rules.\n - type: textarea\n attributes:\n label: 'Task to do:'\n id: task\n validations:\n required: true\n" }, { "path": ".github/ISSUE_TEMPLATE/config.yml", "content": "blank_issues_enabled: false\n" }, { "path": ".github/dependabot.yml", "content": "version: 2\nupdates:\n - package-ecosystem: npm\n directory: /\n schedule:\n interval: weekly\n day: 'sunday'\n time: '02:00'\n timezone: Europe/Berlin\n groups:\n dependencies:\n dependency-type: production\n patterns:\n - '*'\n dev-dependencies:\n dependency-type: development\n exclude-patterns:\n - 'puppeteer*'\n - 'chrome-devtools-frontend'\n - '@modelcontextprotocol/sdk'\n - 'yargs'\n - 'debug'\n - 'core-js'\n patterns:\n - '*'\n # breaks often so better to roll separetely.\n bundled-devtools:\n patterns:\n - 'chrome-devtools-frontend'\n bundled:\n patterns:\n - 'puppeteer*'\n - '@modelcontextprotocol/sdk'\n - 'yargs'\n - 'debug'\n - 'core-js'\n - package-ecosystem: github-actions\n directory: /\n schedule:\n interval: weekly\n day: 'sunday'\n time: '04:00'\n timezone: Europe/Berlin\n groups:\n all:\n patterns:\n - '*'\n" }, { "path": ".github/workflows/conventional-commit.yml", "content": "name: 'Conventional Commit'\n\non:\n merge_group:\n pull_request_target:\n types:\n # Defaults\n # https://docs.github.com/en/actions/reference/workflows-and-actions/events-that-trigger-workflows#pull_request_target\n - opened\n - reopened\n - synchronize\n # Tracks editing PR title or description, or base branch changes\n # https://docs.github.com/en/webhooks/webhook-events-and-payloads?actionType=edited#pull_request\n - edited\n\njobs:\n main:\n name: '[Required] Validate PR title'\n runs-on: ubuntu-latest\n permissions:\n pull-requests: read\n steps:\n - if: github.event_name != 'merge_group'\n uses: amannn/action-semantic-pull-request@48f256284bd46cdaab1048c3721360e808335d50 # v6.1.1\n env:\n GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}\n" }, { "path": ".github/workflows/pre-release.yml", "content": "name: Pre-release\n\npermissions: read-all\n\non:\n workflow_dispatch:\n push:\n branches:\n - release-please-*\n\njobs:\n pre-release:\n name: 'Verify artifacts before release'\n runs-on: ubuntu-latest\n steps:\n - name: Check out repository\n uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2\n with:\n fetch-depth: 2\n\n - name: Set up Node.js\n uses: actions/setup-node@53b83947a5a98c8d113130e565377fae1a50d02f # v6.3.0\n with:\n cache: npm\n node-version-file: '.nvmrc'\n registry-url: 'https://registry.npmjs.org'\n\n # Ensure npm 11.5.1 or later is installed\n - name: Update npm\n run: npm install -g npm@latest\n\n - name: Install dependencies\n run: npm ci\n\n - name: Build and bundle\n run: npm run bundle\n env:\n NODE_ENV: 'production'\n\n - name: Verify server.json\n run: npm run verify-server-json-version\n\n - name: Verify npm package\n run: npm run verify-npm-package\n" }, { "path": ".github/workflows/presubmit.yml", "content": "name: Check code before submitting\n\npermissions: read-all\n\non:\n merge_group:\n push:\n branches:\n - main\n pull_request:\n\njobs:\n check-format:\n name: '[Required] Check correct format'\n runs-on: ubuntu-latest\n\n steps:\n - name: Check out repository\n uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2\n with:\n fetch-depth: 2\n\n - name: Set up Node.js\n uses: actions/setup-node@53b83947a5a98c8d113130e565377fae1a50d02f # v6.3.0\n with:\n cache: npm\n node-version-file: '.nvmrc'\n\n - name: Install dependencies\n run: npm ci\n\n - name: Run format check\n run: npm run check-format\n\n check-docs:\n name: '[Required] Check docs updated'\n runs-on: ubuntu-latest\n\n steps:\n - name: Check out repository\n uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2\n with:\n fetch-depth: 2\n\n - name: Set up Node.js\n uses: actions/setup-node@53b83947a5a98c8d113130e565377fae1a50d02f # v6.3.0\n with:\n cache: npm\n node-version-file: '.nvmrc'\n\n - name: Install dependencies\n run: npm ci\n\n - name: Generate\n run: npm run gen\n\n - name: Check if autogenerated code and docs are out of date\n run: |\n diff_file=$(mktemp doc_diff_XXXXXX)\n git diff --color > $diff_file\n if [[ -s $diff_file ]]; then\n echo \"Please update the documentation by running 'npm run gen'. The following was the diff\"\n cat $diff_file\n rm $diff_file\n exit 1\n fi\n rm $diff_file\n" }, { "path": ".github/workflows/publish-to-npm-on-tag.yml", "content": "name: publish-on-tag\n\non:\n push:\n tags:\n - 'chrome-devtools-mcp-v*'\n workflow_dispatch:\n inputs:\n npm-publish:\n description: 'Try to publish to NPM'\n default: false\n type: boolean\n mcp-publish:\n description: 'Try to publish to MCP registry'\n default: true\n type: boolean\n\npermissions:\n id-token: write # Required for OIDC\n contents: read\n\njobs:\n publish-to-npm:\n runs-on: ubuntu-latest\n if: ${{ (github.event_name != 'workflow_dispatch') || (inputs.npm-publish && always()) }}\n steps:\n - name: Check out repository\n uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2\n with:\n fetch-depth: 2\n\n - name: Set up Node.js\n uses: actions/setup-node@53b83947a5a98c8d113130e565377fae1a50d02f # v6.3.0\n with:\n cache: npm\n node-version-file: '.nvmrc'\n registry-url: 'https://registry.npmjs.org'\n\n # Ensure npm 11.5.1 or later is installed\n - name: Update npm\n run: npm install -g npm@latest\n\n - name: Install dependencies\n run: npm ci\n\n - name: Build and bundle\n run: npm run bundle\n env:\n NODE_ENV: 'production'\n\n - name: Publish\n run: |\n npm publish --provenance --access public\n\n publish-to-mcp-registry:\n runs-on: ubuntu-latest\n needs: publish-to-npm\n if: ${{ (github.event_name != 'workflow_dispatch' && needs.publish-to-npm.result == 'success') || (inputs.mcp-publish && always()) }}\n steps:\n - name: Check out repository\n uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2\n with:\n fetch-depth: 2\n\n - name: Set up Node.js\n uses: actions/setup-node@53b83947a5a98c8d113130e565377fae1a50d02f # v6.3.0\n with:\n cache: npm\n node-version-file: '.nvmrc'\n registry-url: 'https://registry.npmjs.org'\n\n # Ensure npm 11.5.1 or later is installed\n - name: Update npm\n run: npm install -g npm@latest\n\n - name: Install dependencies\n run: npm ci\n\n - name: Build and bundle\n run: npm run bundle\n env:\n NODE_ENV: 'production'\n\n - name: Install MCP Publisher\n run: |\n export OS=$(uname -s | tr '[:upper:]' '[:lower:]')_$(uname -m | sed 's/x86_64/amd64/;s/aarch64/arm64/')\n curl -L \"https://github.com/modelcontextprotocol/registry/releases/latest/download/mcp-publisher_${OS}.tar.gz\" | tar xz mcp-publisher\n\n - name: Login to MCP Registry\n run: ./mcp-publisher login github-oidc\n\n - name: Publish to MCP Registry\n run: ./mcp-publisher publish\n" }, { "path": ".github/workflows/release-please.yml", "content": "on:\n push:\n branches:\n - main\n\npermissions: read-all\nname: release-please\n\njobs:\n release-please:\n runs-on: ubuntu-latest\n steps:\n - uses: googleapis/release-please-action@v4\n with:\n token: ${{ secrets.BROWSER_AUTOMATION_BOT_TOKEN }}\n target-branch: main\n config-file: release-please-config.json\n manifest-file: .release-please-manifest.json\n" }, { "path": ".github/workflows/run-tests.yml", "content": "name: Compile and run tests\n\npermissions: read-all\n\non:\n merge_group:\n push:\n branches:\n - main\n pull_request:\n\njobs:\n run-tests:\n name: Tests on ${{ matrix.os }} with node ${{ matrix.node }}\n runs-on: ${{ matrix.os }}\n strategy:\n fail-fast: false\n matrix:\n os:\n - ubuntu-latest\n - windows-latest\n - macos-latest\n node:\n - 20\n - 22\n - 23\n - 24\n steps:\n - name: Check out repository\n uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2\n with:\n fetch-depth: 2\n\n - name: Set up Node.js\n uses: actions/setup-node@53b83947a5a98c8d113130e565377fae1a50d02f # v6.3.0\n with:\n cache: npm\n node-version: 22 # build works only with 22+.\n\n - name: Install dependencies\n shell: bash\n run: npm ci\n\n - name: Build\n run: npm run bundle\n env:\n NODE_OPTIONS: '--max_old_space_size=4096'\n\n - name: Set up Node.js\n uses: actions/setup-node@53b83947a5a98c8d113130e565377fae1a50d02f # v6.3.0\n with:\n cache: npm\n node-version: ${{ matrix.node }}\n\n - name: Disable AppArmor\n if: ${{ matrix.os == 'ubuntu-latest' }}\n shell: bash\n run: echo 0 | sudo tee /proc/sys/kernel/apparmor_restrict_unprivileged_userns\n\n - name: Run tests\n shell: bash\n # Retry tests if they fail in the merge queue.\n run: npm run test:no-build -- ${{ github.event_name == 'merge_group' && '--retry' || '' }}\n\n # Gating job for branch protection.\n test-success:\n name: '[Required] Tests passed'\n runs-on: ubuntu-latest\n needs: run-tests\n if: ${{ !cancelled() }}\n steps:\n - if: ${{ needs.run-tests.result != 'success' }}\n run: 'exit 1'\n - run: 'exit 0'\n" }, { "path": ".gitignore", "content": "# Logs\nlogs\n*.log\nnpm-debug.log*\nyarn-debug.log*\nyarn-error.log*\nlerna-debug.log*\n.pnpm-debug.log*\n\ntrace.json\ntrace.json.gz\n\n# Diagnostic reports (https://nodejs.org/api/report.html)\nreport.[0-9]*.[0-9]*.[0-9]*.[0-9]*.json\n\n# Runtime data\npids\n*.pid\n*.seed\n*.pid.lock\n\n# Directory for instrumented libs generated by jscoverage/JSCover\nlib-cov\n\n# Coverage directory used by tools like istanbul\ncoverage\n*.lcov\n\n# nyc test coverage\n.nyc_output\n\n# Grunt intermediate storage (https://gruntjs.com/creating-plugins#storing-task-files)\n.grunt\n\n# Bower dependency directory (https://bower.io/)\nbower_components\n\n# node-waf configuration\n.lock-wscript\n\n# Compiled binary addons (https://nodejs.org/api/addons.html)\nbuild/Release\n\n# Dependency directories\nnode_modules/\njspm_packages/\n\n# Snowpack dependency directory (https://snowpack.dev/)\nweb_modules/\n\n# TypeScript cache\n*.tsbuildinfo\n\n# Optional npm cache directory\n.npm\n\n# Optional eslint cache\n.eslintcache\n\n# Optional stylelint cache\n.stylelintcache\n\n# Microbundle cache\n.rpt2_cache/\n.rts2_cache_cjs/\n.rts2_cache_es/\n.rts2_cache_umd/\n\n# Optional REPL history\n.node_repl_history\n\n# Output of 'npm pack'\n*.tgz\n\n# Yarn Integrity file\n.yarn-integrity\n\n# dotenv environment variable files\n.env\n.env.development.local\n.env.test.local\n.env.production.local\n.env.local\n\n# parcel-bundler cache (https://parceljs.org/)\n.cache\n.parcel-cache\n\n# Next.js build output\n.next\nout\n\n# Nuxt.js build / generate output\n.nuxt\ndist\n\n# Gatsby files\n.cache/\n# Comment in the public line in if your project uses Gatsby and not Next.js\n# https://nextjs.org/blog/next-9-1#public-directory-support\n# public\n\n# vuepress build output\n.vuepress/dist\n\n# vuepress v2.x temp and cache directory\n.temp\n.cache\n\n# vitepress build output\n**/.vitepress/dist\n\n# vitepress cache directory\n**/.vitepress/cache\n\n# Docusaurus cache and generated files\n.docusaurus\n\n# Serverless directories\n.serverless/\n\n# FuseBox cache\n.fusebox/\n\n# DynamoDB Local files\n.dynamodb/\n\n# TernJS port file\n.tern-port\n\n# Stores VSCode versions used for testing VSCode extensions\n.vscode-test\n\n# Stores VSCode specific settings\n.vscode\n!.vscode/*.template.json\n!.vscode/extensions.json\n\n# yarn v2\n.yarn/cache\n.yarn/unplugged\n.yarn/build-state.yml\n.yarn/install-state.gz\n.pnp.*\n\n# Build output directory\nbuild/\n\nlog.txt\n\n.DS_Store" }, { "path": ".mcp.json", "content": "{\n \"chrome-devtools\": {\n \"command\": \"npx\",\n \"args\": [\"chrome-devtools-mcp@latest\"]\n }\n}\n" }, { "path": ".nvmrc", "content": "v22" }, { "path": ".prettierignore", "content": "# Prettier-only ignores.\nCHANGELOG.md\nsrc/third_party/lighthouse-devtools-mcp-bundle.js" }, { "path": ".prettierrc.cjs", "content": "/**\n * @license\n * Copyright 2025 Google LLC\n * SPDX-License-Identifier: Apache-2.0\n */\n\n/**\n * @type {import('prettier').Config}\n */\nmodule.exports = {\n bracketSpacing: false,\n singleQuote: true,\n trailingComma: 'all',\n arrowParens: 'avoid',\n singleAttributePerLine: true,\n htmlWhitespaceSensitivity: 'strict',\n endOfLine: 'lf',\n};\n" }, { "path": ".release-please-manifest.json", "content": "{\n \".\": \"0.20.2\"\n}\n" }, { "path": "CHANGELOG.md", "content": "# Changelog\n\n## [0.20.2](https://github.com/ChromeDevTools/chrome-devtools-mcp/compare/chrome-devtools-mcp-v0.20.1...chrome-devtools-mcp-v0.20.2) (2026-03-18)\n\n\n### 📄 Documentation\n\n* add troubleshooting for Claude Code plugin HTTPS clone failures ([#1195](https://github.com/ChromeDevTools/chrome-devtools-mcp/issues/1195)) ([d082ca4](https://github.com/ChromeDevTools/chrome-devtools-mcp/commit/d082ca4ecd35a023d09f9c1ff949d5fb0c3fb069))\n\n## [0.20.1](https://github.com/ChromeDevTools/chrome-devtools-mcp/compare/chrome-devtools-mcp-v0.20.0...chrome-devtools-mcp-v0.20.1) (2026-03-16)\n\n\n### 🛠️ Fixes\n\n* update VS Code manual installation powershell command ([#1151](https://github.com/ChromeDevTools/chrome-devtools-mcp/issues/1151)) ([6c64a5b](https://github.com/ChromeDevTools/chrome-devtools-mcp/commit/6c64a5b543714796b25a12dc6f2be7a1e683e8bd))\n\n\n### ⚡ Performance\n\n* use CDP to find open DevTools pages. ([#1150](https://github.com/ChromeDevTools/chrome-devtools-mcp/issues/1150)) ([94de19c](https://github.com/ChromeDevTools/chrome-devtools-mcp/commit/94de19cdcdae9e31d0962b273ce352dc248eb5a8))\n\n## [0.20.0](https://github.com/ChromeDevTools/chrome-devtools-mcp/compare/chrome-devtools-mcp-v0.19.0...chrome-devtools-mcp-v0.20.0) (2026-03-11)\n\n\n### 🎉 Features\n\n* experimental `chrome-devtools` CLI ([#1100](https://github.com/ChromeDevTools/chrome-devtools-mcp/issues/1100)) ([1ac574e](https://github.com/ChromeDevTools/chrome-devtools-mcp/commit/1ac574e7154948e86e414e5149fb975a190d5bb0))\n\n\n### 📄 Documentation\n\n* fix typo ([#1155](https://github.com/ChromeDevTools/chrome-devtools-mcp/issues/1155)) ([b59cabc](https://github.com/ChromeDevTools/chrome-devtools-mcp/commit/b59cabcc1d59802ffd7d9667040188e46192357d))\n* fix typos and improve phrasing ([#1130](https://github.com/ChromeDevTools/chrome-devtools-mcp/issues/1130)) ([70d4f36](https://github.com/ChromeDevTools/chrome-devtools-mcp/commit/70d4f365dc619a5743e697c30800f7065bc6227d))\n* revise contribution process and add release process ([#1134](https://github.com/ChromeDevTools/chrome-devtools-mcp/issues/1134)) ([d7d26a1](https://github.com/ChromeDevTools/chrome-devtools-mcp/commit/d7d26a103b840e2feb7cb9af6a242edda94f1ddf))\n* **troubleshooting:** add symptom for missing tools due to read-only mode ([#1148](https://github.com/ChromeDevTools/chrome-devtools-mcp/issues/1148)) ([57e7d51](https://github.com/ChromeDevTools/chrome-devtools-mcp/commit/57e7d51e8ca1e2ee325a9e7a9c64c033acbe6d6a))\n* Update troubleshooting for MCP server connection errors ([#1017](https://github.com/ChromeDevTools/chrome-devtools-mcp/issues/1017)) ([00f9c31](https://github.com/ChromeDevTools/chrome-devtools-mcp/commit/00f9c3108ab9caefca57998439052c728298920b))\n\n\n### 🏗️ Refactor\n\n* move main files ([#1120](https://github.com/ChromeDevTools/chrome-devtools-mcp/issues/1120)) ([c2d8009](https://github.com/ChromeDevTools/chrome-devtools-mcp/commit/c2d8009ff75f76bce1ec4cf79c2467b50d81725e))\n\n## [0.19.0](https://github.com/ChromeDevTools/chrome-devtools-mcp/compare/chrome-devtools-mcp-v0.18.1...chrome-devtools-mcp-v0.19.0) (2026-03-05)\n\n\n### 🎉 Features\n\n* add pageId routing for parallel multi-agent workflows ([#1022](https://github.com/ChromeDevTools/chrome-devtools-mcp/issues/1022)) ([caf601a](https://github.com/ChromeDevTools/chrome-devtools-mcp/commit/caf601a32832bb87cfac801a6bbeacb87508412f)), closes [#1019](https://github.com/ChromeDevTools/chrome-devtools-mcp/issues/1019)\n* Add skill which helps with onboarding of the mcp server ([#1083](https://github.com/ChromeDevTools/chrome-devtools-mcp/issues/1083)) ([7273f16](https://github.com/ChromeDevTools/chrome-devtools-mcp/commit/7273f16ec08f6d5b46a2693b0ad4d559086ded89))\n* integrate Lighthouse audits ([#831](https://github.com/ChromeDevTools/chrome-devtools-mcp/issues/831)) ([dfdac26](https://github.com/ChromeDevTools/chrome-devtools-mcp/commit/dfdac2648e560d756a8711ad3bb1fa470be8e7c9))\n\n\n### 🛠️ Fixes\n\n* improve error messages around --auto-connect ([#1075](https://github.com/ChromeDevTools/chrome-devtools-mcp/issues/1075)) ([bcb852d](https://github.com/ChromeDevTools/chrome-devtools-mcp/commit/bcb852dd2e440b0005f4a9ad270a1a7998767907))\n* improve tool descriptions ([#965](https://github.com/ChromeDevTools/chrome-devtools-mcp/issues/965)) ([bdbbc84](https://github.com/ChromeDevTools/chrome-devtools-mcp/commit/bdbbc84c125bdd48f4be48aa476bec0323de611c))\n* repair broken markdown and extract snippets in a11y-debugging skill ([#1096](https://github.com/ChromeDevTools/chrome-devtools-mcp/issues/1096)) ([adac7c5](https://github.com/ChromeDevTools/chrome-devtools-mcp/commit/adac7c537ee304f324c5e7284fb363396d1773f5))\n* simplify emulation and script tools ([#1073](https://github.com/ChromeDevTools/chrome-devtools-mcp/issues/1073)) ([e51ba47](https://github.com/ChromeDevTools/chrome-devtools-mcp/commit/e51ba4720338951e621585b77efc6a0e07678d99))\n* simplify focus state management ([#1063](https://github.com/ChromeDevTools/chrome-devtools-mcp/issues/1063)) ([f763da2](https://github.com/ChromeDevTools/chrome-devtools-mcp/commit/f763da24a10e27605c0a5069853ce7c92974eec2))\n* tweak lighthouse description ([#1112](https://github.com/ChromeDevTools/chrome-devtools-mcp/issues/1112)) ([5538180](https://github.com/ChromeDevTools/chrome-devtools-mcp/commit/55381804ae7ffa8a1e5933b621a9b8390b3000ff))\n\n\n### 📄 Documentation\n\n* Adapt a11y skill to utilize Lighthouse ([#1054](https://github.com/ChromeDevTools/chrome-devtools-mcp/issues/1054)) ([21634e6](https://github.com/ChromeDevTools/chrome-devtools-mcp/commit/21634e660c346e469ae62116b1824538f51567dd))\n* add feature release checklist to CONTRIBUTING.md ([#1118](https://github.com/ChromeDevTools/chrome-devtools-mcp/issues/1118)) ([0378457](https://github.com/ChromeDevTools/chrome-devtools-mcp/commit/03784577ffb6e238bcb2d637bff9ad759723ea7b))\n* fix typo in README regarding slim mode ([#1093](https://github.com/ChromeDevTools/chrome-devtools-mcp/issues/1093)) ([92f2c7b](https://github.com/ChromeDevTools/chrome-devtools-mcp/commit/92f2c7b48b56a6b1d6ac7c9e2f2e92beb26bcf62))\n\n\n### 🏗️ Refactor\n\n* clean up more of the context getters ([#1062](https://github.com/ChromeDevTools/chrome-devtools-mcp/issues/1062)) ([9628dab](https://github.com/ChromeDevTools/chrome-devtools-mcp/commit/9628dabcb4d39f0b94d152a0fc419e049246a29d))\n* consistently use McpPage in tools ([#1057](https://github.com/ChromeDevTools/chrome-devtools-mcp/issues/1057)) ([302e5a0](https://github.com/ChromeDevTools/chrome-devtools-mcp/commit/302e5a04191ba0558e3c79f1486d01d5eb0f6896))\n* improve type safety for page scoped tools ([#1051](https://github.com/ChromeDevTools/chrome-devtools-mcp/issues/1051)) ([5f694c6](https://github.com/ChromeDevTools/chrome-devtools-mcp/commit/5f694c60ffd21f8b022554c92b2ad4cbdb457375))\n* make cdp resolvers use McpPage ([#1060](https://github.com/ChromeDevTools/chrome-devtools-mcp/issues/1060)) ([d6c06c5](https://github.com/ChromeDevTools/chrome-devtools-mcp/commit/d6c06c56a7b8e4968318adc9fc7c820ace9f5bd9))\n* move dialog handling to McpPage ([#1059](https://github.com/ChromeDevTools/chrome-devtools-mcp/issues/1059)) ([40c241b](https://github.com/ChromeDevTools/chrome-devtools-mcp/commit/40c241bbfc80d6282953ab325b30a597d3d85ade))\n* move server to a separate file ([#1043](https://github.com/ChromeDevTools/chrome-devtools-mcp/issues/1043)) ([a8bf3e5](https://github.com/ChromeDevTools/chrome-devtools-mcp/commit/a8bf3e585682c3126dfd378e9f98b5dc7ab6045d))\n* remove page passing via context ([#1061](https://github.com/ChromeDevTools/chrome-devtools-mcp/issues/1061)) ([4cb5a17](https://github.com/ChromeDevTools/chrome-devtools-mcp/commit/4cb5a17b57f57d8a367cd423c960ba122b9952e3))\n* set defaults to performance trace tool ([#1090](https://github.com/ChromeDevTools/chrome-devtools-mcp/issues/1090)) ([dfa9b79](https://github.com/ChromeDevTools/chrome-devtools-mcp/commit/dfa9b79a4ecc9e67f5b043f2dd97f6889d1fee0b))\n* simplify the response texts ([#1095](https://github.com/ChromeDevTools/chrome-devtools-mcp/issues/1095)) ([cb0079e](https://github.com/ChromeDevTools/chrome-devtools-mcp/commit/cb0079efbbd41874f6913772fe3f2a037e9f5f8f))\n* type-cast as internal CdpPage interface ([#1064](https://github.com/ChromeDevTools/chrome-devtools-mcp/issues/1064)) ([2d5e4fa](https://github.com/ChromeDevTools/chrome-devtools-mcp/commit/2d5e4fa3579650a384ff21c88c2e6b9cda031e1a))\n\n## [0.18.1](https://github.com/ChromeDevTools/chrome-devtools-mcp/compare/chrome-devtools-mcp-v0.18.0...chrome-devtools-mcp-v0.18.1) (2026-02-25)\n\n\n### 🛠️ Fixes\n\n* remove endsWith for filePath in memory tools ([#1041](https://github.com/ChromeDevTools/chrome-devtools-mcp/issues/1041)) ([d0622d5](https://github.com/ChromeDevTools/chrome-devtools-mcp/commit/d0622d52d46ac72a28bc22f93a337fb5007214c7))\n\n## [0.18.0](https://github.com/ChromeDevTools/chrome-devtools-mcp/compare/chrome-devtools-mcp-v0.17.3...chrome-devtools-mcp-v0.18.0) (2026-02-24)\n\n\n### 🎉 Features\n\n* `--slim` mode for maximum token savings ([#958](https://github.com/ChromeDevTools/chrome-devtools-mcp/issues/958)) ([c402b43](https://github.com/ChromeDevTools/chrome-devtools-mcp/commit/c402b43697d834994c4fc141305189082da14bee))\n* add a new skill for accessibility debugging and auditing with Chrome DevTools MCP. ([#1002](https://github.com/ChromeDevTools/chrome-devtools-mcp/issues/1002)) ([b0c6d04](https://github.com/ChromeDevTools/chrome-devtools-mcp/commit/b0c6d042e4d68763acf989edc8097ce07e85dc7a))\n* add experimental screencast recording tools ([#941](https://github.com/ChromeDevTools/chrome-devtools-mcp/issues/941)) ([33446d4](https://github.com/ChromeDevTools/chrome-devtools-mcp/commit/33446d457e4386fadcfe4ddf6c7a43b2e9098c9a))\n* add skill to debug and optimize LCP ([#993](https://github.com/ChromeDevTools/chrome-devtools-mcp/issues/993)) ([2cd9b95](https://github.com/ChromeDevTools/chrome-devtools-mcp/commit/2cd9b95346226aa52cce18f6ab889a2ae194806c))\n* add storage-isolated browser contexts ([#991](https://github.com/ChromeDevTools/chrome-devtools-mcp/issues/991)) ([59f6477](https://github.com/ChromeDevTools/chrome-devtools-mcp/commit/59f6477a70eb07585e9a510089f1dfc840a012fd))\n* add take_memory_snapshot tool ([#1023](https://github.com/ChromeDevTools/chrome-devtools-mcp/issues/1023)) ([7ffdc5e](https://github.com/ChromeDevTools/chrome-devtools-mcp/commit/7ffdc5ee4d9df9f62f03354fa758fb4d022c3b08))\n* support any-match text arrays in wait_for ([#1011](https://github.com/ChromeDevTools/chrome-devtools-mcp/issues/1011)) ([496ab1b](https://github.com/ChromeDevTools/chrome-devtools-mcp/commit/496ab1b45f7a283a1432643777e0795a17f33667))\n* support type_text ([#1026](https://github.com/ChromeDevTools/chrome-devtools-mcp/issues/1026)) ([b5d01b5](https://github.com/ChromeDevTools/chrome-devtools-mcp/commit/b5d01b5fe65fa20f9b76555b86a749960a5d1738))\n\n\n### 🛠️ Fixes\n\n* detect X server display on Linux ([#1027](https://github.com/ChromeDevTools/chrome-devtools-mcp/issues/1027)) ([1746ed9](https://github.com/ChromeDevTools/chrome-devtools-mcp/commit/1746ed9ee11c212f78dcbb00af99a0400595e778))\n\n\n### ♻️ Chores\n\n* cleanup string and structured console formatters ([#1005](https://github.com/ChromeDevTools/chrome-devtools-mcp/issues/1005)) ([0d78685](https://github.com/ChromeDevTools/chrome-devtools-mcp/commit/0d78685a5b37dc68bb11a1088ff8816ecff3bb82))\n* extract version in a seprate file ([#1032](https://github.com/ChromeDevTools/chrome-devtools-mcp/issues/1032)) ([0106865](https://github.com/ChromeDevTools/chrome-devtools-mcp/commit/0106865aad6d51b6cb590bf98ccaf7078e8d7436))\n* move emulation settings to context ([#1000](https://github.com/ChromeDevTools/chrome-devtools-mcp/issues/1000)) ([bc3c40e](https://github.com/ChromeDevTools/chrome-devtools-mcp/commit/bc3c40e8f961433fb2ae858482d66f9a55fdde32))\n* optimize slim tool descriptions and params ([#1028](https://github.com/ChromeDevTools/chrome-devtools-mcp/issues/1028)) ([ca6635d](https://github.com/ChromeDevTools/chrome-devtools-mcp/commit/ca6635d5a5d5e8b7b9944fa8b4e1063e6269a5f2))\n* simplify JavaScript code examples, update code block language, and refine descriptions in a11y debugging skill documentation. ([#1009](https://github.com/ChromeDevTools/chrome-devtools-mcp/issues/1009)) ([5cedcaa](https://github.com/ChromeDevTools/chrome-devtools-mcp/commit/5cedcaad2c8a5e488064e21fb56cbd8643345440))\n* types for JSON output of IssueFormatter ([#1007](https://github.com/ChromeDevTools/chrome-devtools-mcp/issues/1007)) ([9ef4479](https://github.com/ChromeDevTools/chrome-devtools-mcp/commit/9ef4479bec39c5f2651d6ebb63e9ec0fecf8bf89))\n\n## [0.17.3](https://github.com/ChromeDevTools/chrome-devtools-mcp/compare/chrome-devtools-mcp-v0.17.2...chrome-devtools-mcp-v0.17.3) (2026-02-19)\n\n\n### 🛠️ Fixes\n\n* remove clean from prepare ([#997](https://github.com/ChromeDevTools/chrome-devtools-mcp/issues/997)) ([2016b98](https://github.com/ChromeDevTools/chrome-devtools-mcp/commit/2016b98217bf5aa8d65c6668b1e46c8a3400276f))\n\n## [0.17.2](https://github.com/ChromeDevTools/chrome-devtools-mcp/compare/chrome-devtools-mcp-v0.17.1...chrome-devtools-mcp-v0.17.2) (2026-02-19)\n\n\n### 🛠️ Fixes\n\n* check that combobox is actually a select element before filling out options ([#979](https://github.com/ChromeDevTools/chrome-devtools-mcp/issues/979)) ([d2bc489](https://github.com/ChromeDevTools/chrome-devtools-mcp/commit/d2bc489e4351551ba62a104433839c4198ecae84))\n* handle network request pagination correctly ([#980](https://github.com/ChromeDevTools/chrome-devtools-mcp/issues/980)) ([0d9f422](https://github.com/ChromeDevTools/chrome-devtools-mcp/commit/0d9f422201538aa847a50417f1ed370e3a6c95b2))\n\n\n### 📄 Documentation\n\n* Add a note about previously installed server installations ([#982](https://github.com/ChromeDevTools/chrome-devtools-mcp/issues/982)) ([c0009f7](https://github.com/ChromeDevTools/chrome-devtools-mcp/commit/c0009f7ab2f15bedd1c4ceb609db77bcb3c96f2d))\n* update codex doc URL ([#987](https://github.com/ChromeDevTools/chrome-devtools-mcp/issues/987)) ([ebbbea7](https://github.com/ChromeDevTools/chrome-devtools-mcp/commit/ebbbea7f9d20e4dea902d06e9b86dfe1cc9b221f))\n\n\n### ♻️ Chores\n\n* **network:** de-duplicate String and JSON formatters ([#985](https://github.com/ChromeDevTools/chrome-devtools-mcp/issues/985)) ([1896dbb](https://github.com/ChromeDevTools/chrome-devtools-mcp/commit/1896dbb5a7cdc3fc0bcc5e665aee986a1180b014))\n* remove text from the status code for Network requests ([#778](https://github.com/ChromeDevTools/chrome-devtools-mcp/issues/778)) ([327a388](https://github.com/ChromeDevTools/chrome-devtools-mcp/commit/327a3884d8443b8591c06ddb3f9081771ae973c3))\n\n## [0.17.1](https://github.com/ChromeDevTools/chrome-devtools-mcp/compare/chrome-devtools-mcp-v0.17.0...chrome-devtools-mcp-v0.17.1) (2026-02-16)\n\n\n### 📄 Documentation\n\n* Add 'Progressive Complexity' and 'Reference over Value' design principles. ([#939](https://github.com/ChromeDevTools/chrome-devtools-mcp/issues/939)) ([8d765c0](https://github.com/ChromeDevTools/chrome-devtools-mcp/commit/8d765c0aef7bbcd476c7e7fbe9ea63ee26cf4fa6))\n* add Katalon Studio setup instructions to README ([#929](https://github.com/ChromeDevTools/chrome-devtools-mcp/issues/929)) ([6cfef24](https://github.com/ChromeDevTools/chrome-devtools-mcp/commit/6cfef24ec734ed62221c66bdf03b09ce000f5bfe))\n* add MCP config for Claude plugin + docs ([#944](https://github.com/ChromeDevTools/chrome-devtools-mcp/issues/944)) ([a781da4](https://github.com/ChromeDevTools/chrome-devtools-mcp/commit/a781da4434c3490901b28017bc7aa40493ef8dcc))\n* estimate tokens using tiktoken ([#959](https://github.com/ChromeDevTools/chrome-devtools-mcp/issues/959)) ([fd0a919](https://github.com/ChromeDevTools/chrome-devtools-mcp/commit/fd0a9193b37be4c5cda21dc4904093c7b58d61be))\n* improve Claude Code installation instructions ([#947](https://github.com/ChromeDevTools/chrome-devtools-mcp/issues/947)) ([3ec5b7e](https://github.com/ChromeDevTools/chrome-devtools-mcp/commit/3ec5b7e7a2d97c9f0165c5af3317c531a9dc058f))\n* Update README with WSL configuration details ([#946](https://github.com/ChromeDevTools/chrome-devtools-mcp/issues/946)) ([107c46a](https://github.com/ChromeDevTools/chrome-devtools-mcp/commit/107c46a4dbd2ba7c7b9217a75ae2b1871d3c7f0d))\n\n\n### ♻️ Chores\n\n* rename files to have more consistent style ([#935](https://github.com/ChromeDevTools/chrome-devtools-mcp/issues/935)) ([9e1f9ac](https://github.com/ChromeDevTools/chrome-devtools-mcp/commit/9e1f9ac69667ddc3e2917e2c30e5ee940a03d853))\n\n## [0.17.0](https://github.com/ChromeDevTools/chrome-devtools-mcp/compare/chrome-devtools-mcp-v0.16.0...chrome-devtools-mcp-v0.17.0) (2026-02-10)\n\n\n### 🎉 Features\n\n* include Error.cause chain for uncaught errors and logged Errors ([#906](https://github.com/ChromeDevTools/chrome-devtools-mcp/issues/906)) ([05b01ec](https://github.com/ChromeDevTools/chrome-devtools-mcp/commit/05b01ecaba47cf1ce38564636663222c9cab46de))\n* Integrate CrUX data into performance trace summaries ([#733](https://github.com/ChromeDevTools/chrome-devtools-mcp/issues/733)) ([b747f9d](https://github.com/ChromeDevTools/chrome-devtools-mcp/commit/b747f9d74a12d2119b6531476b2f88ab66be0ff8))\n* show message and stack trace in details when console.log'ging Error objects ([#902](https://github.com/ChromeDevTools/chrome-devtools-mcp/issues/902)) ([ffa00da](https://github.com/ChromeDevTools/chrome-devtools-mcp/commit/ffa00dab1b65b2eac8db215e0289317b8ed9b725))\n\n\n### 🛠️ Fixes\n\n* console formatter hides frames from ignored scripts ([#927](https://github.com/ChromeDevTools/chrome-devtools-mcp/issues/927)) ([8e2380b](https://github.com/ChromeDevTools/chrome-devtools-mcp/commit/8e2380b434d9659ffa8a7043d2589261772fa04f))\n* limit stack traces to 50 lines ([#923](https://github.com/ChromeDevTools/chrome-devtools-mcp/issues/923)) ([caea23a](https://github.com/ChromeDevTools/chrome-devtools-mcp/commit/caea23a7cf33c87cd4ce426eb2a10724aba3cc71))\n\n\n### 📄 Documentation\n\n* add macOS Web Bluetooth troubleshooting note ([#930](https://github.com/ChromeDevTools/chrome-devtools-mcp/issues/930)) ([3c9528b](https://github.com/ChromeDevTools/chrome-devtools-mcp/commit/3c9528b43d9bbff166fcfcfee321149ff44ddd21)), closes [#917](https://github.com/ChromeDevTools/chrome-devtools-mcp/issues/917)\n\n## [0.16.0](https://github.com/ChromeDevTools/chrome-devtools-mcp/compare/chrome-devtools-mcp-v0.15.1...chrome-devtools-mcp-v0.16.0) (2026-02-04)\n\n\n### 🎉 Features\n\n* include source-mapped stack trace for uncaught errors ([#876](https://github.com/ChromeDevTools/chrome-devtools-mcp/issues/876)) ([ecef712](https://github.com/ChromeDevTools/chrome-devtools-mcp/commit/ecef712e70b47ae81eb3364d0aed801ec1c91a70))\n\n\n### 🛠️ Fixes\n\n* accidental extra typing in the fill tool ([#886](https://github.com/ChromeDevTools/chrome-devtools-mcp/issues/886)) ([3d6e59d](https://github.com/ChromeDevTools/chrome-devtools-mcp/commit/3d6e59dda42be3c6fd97446344a28cbbaa5809b3))\n* update evaluateScript description formatting ([#880](https://github.com/ChromeDevTools/chrome-devtools-mcp/issues/880)) ([24db9dd](https://github.com/ChromeDevTools/chrome-devtools-mcp/commit/24db9dd78cd4f054d291322685b4f47601da3f5a))\n* use 1-based line/column and fix wasm offsets in stack frames ([#884](https://github.com/ChromeDevTools/chrome-devtools-mcp/issues/884)) ([7e1ec81](https://github.com/ChromeDevTools/chrome-devtools-mcp/commit/7e1ec81fb63ec8b7c6d77dbdc88beef4240243ba))\n\n\n### 📄 Documentation\n\n* mention source-mapped stack traces in 'Key features' ([#883](https://github.com/ChromeDevTools/chrome-devtools-mcp/issues/883)) ([579d18a](https://github.com/ChromeDevTools/chrome-devtools-mcp/commit/579d18a3f4d1d8d05bf267a39de7f2f53e719b17))\n* remove outdated --channel=beta note ([#882](https://github.com/ChromeDevTools/chrome-devtools-mcp/issues/882)) ([acdb5c9](https://github.com/ChromeDevTools/chrome-devtools-mcp/commit/acdb5c9bb3f249c5a9ce1d4a3e84c580af999141))\n\n## [0.15.1](https://github.com/ChromeDevTools/chrome-devtools-mcp/compare/chrome-devtools-mcp-v0.15.0...chrome-devtools-mcp-v0.15.1) (2026-01-30)\n\n\n### 🛠️ Fixes\n\n* disable usage statistics when CI or CHROME_DEVTOOLS_MCP_NO_USAGE_STATISTICS env is set ([#862](https://github.com/ChromeDevTools/chrome-devtools-mcp/issues/862)) ([c0435a2](https://github.com/ChromeDevTools/chrome-devtools-mcp/commit/c0435a2d53eb51b7500fc5cce50344520ea164e7))\n* respect custom timeouts in navigate tools ([#865](https://github.com/ChromeDevTools/chrome-devtools-mcp/issues/865)) ([a0aeb97](https://github.com/ChromeDevTools/chrome-devtools-mcp/commit/a0aeb97693fd5ca641f45ebcd4ce3b4b08ce21b8))\n\n## [0.15.0](https://github.com/ChromeDevTools/chrome-devtools-mcp/compare/chrome-devtools-mcp-v0.14.0...chrome-devtools-mcp-v0.15.0) (2026-01-28)\n\n\n### 🎉 Features\n\n* Add ability to inject script to run on page load ([#568](https://github.com/ChromeDevTools/chrome-devtools-mcp/issues/568)) ([d845ad4](https://github.com/ChromeDevTools/chrome-devtools-mcp/commit/d845ad48584a49aa57b11de308beeb17ed0b2e10))\n* enable usage statistics by default with opt-out ([#855](https://github.com/ChromeDevTools/chrome-devtools-mcp/issues/855)) ([7e279f1](https://github.com/ChromeDevTools/chrome-devtools-mcp/commit/7e279f1b67c5cfd4ad033a4147c51fe20a7833f7))\n* support testing light and dark mode ([#858](https://github.com/ChromeDevTools/chrome-devtools-mcp/issues/858)) ([5a23a8c](https://github.com/ChromeDevTools/chrome-devtools-mcp/commit/5a23a8c201d30d40395e283f4434d933826333fa))\n\n## [0.14.0](https://github.com/ChromeDevTools/chrome-devtools-mcp/compare/chrome-devtools-mcp-v0.13.0...chrome-devtools-mcp-v0.14.0) (2026-01-27)\n\n\n### 🎉 Features\n\n* add a skill for using chrome-devtools-mcp ([#830](https://github.com/ChromeDevTools/chrome-devtools-mcp/issues/830)) ([aa0a367](https://github.com/ChromeDevTools/chrome-devtools-mcp/commit/aa0a3679f59ab441908d31252afee1cd56102da8))\n* add background parameter to new_page tool ([#837](https://github.com/ChromeDevTools/chrome-devtools-mcp/issues/837)) ([d756888](https://github.com/ChromeDevTools/chrome-devtools-mcp/commit/d7568881ba4aa0e2c10dc6148fd0ef941fee10d5))\n* allow skipping snapshot generation for input tools ([#821](https://github.com/ChromeDevTools/chrome-devtools-mcp/issues/821)) ([4b8e9f2](https://github.com/ChromeDevTools/chrome-devtools-mcp/commit/4b8e9f287572e0a95c30b5ca612acf08bf79595b))\n* include stack trace in 'get_console_message' tool ([#740](https://github.com/ChromeDevTools/chrome-devtools-mcp/issues/740)) ([a3a0021](https://github.com/ChromeDevTools/chrome-devtools-mcp/commit/a3a00210a30f78045244bc897ee736bdbdc36007))\n* support device viewport and user agent emulation ([#798](https://github.com/ChromeDevTools/chrome-devtools-mcp/issues/798)) ([a816967](https://github.com/ChromeDevTools/chrome-devtools-mcp/commit/a8169676f920f88965a2574f53affe15c1278b43))\n* support filePath for network request and response bodies ([#795](https://github.com/ChromeDevTools/chrome-devtools-mcp/issues/795)) ([6d0e4ca](https://github.com/ChromeDevTools/chrome-devtools-mcp/commit/6d0e4cab28a8498c2783c1c0c6436c655de7b336))\n\n\n### 🛠️ Fixes\n\n* handle beforeunload dialogs in navigations ([#788](https://github.com/ChromeDevTools/chrome-devtools-mcp/issues/788)) ([9b21f8b](https://github.com/ChromeDevTools/chrome-devtools-mcp/commit/9b21f8b2e972f78f58c6f633851466356330c77d))\n* improve error handling for console messages ([#844](https://github.com/ChromeDevTools/chrome-devtools-mcp/issues/844)) ([dc43ede](https://github.com/ChromeDevTools/chrome-devtools-mcp/commit/dc43ede1f20302bd2feb706e63bcf992b4a66a96))\n* improve error reporting when retrieving the element ([#845](https://github.com/ChromeDevTools/chrome-devtools-mcp/issues/845)) ([f7dd003](https://github.com/ChromeDevTools/chrome-devtools-mcp/commit/f7dd00340a8ac5af7fbe4922f2a1d27d99d933cc))\n* improve performance tool description ([#800](https://github.com/ChromeDevTools/chrome-devtools-mcp/issues/800)) ([aa9a176](https://github.com/ChromeDevTools/chrome-devtools-mcp/commit/aa9a1769568aca2a357f186b2e80b38b2ed76323))\n* increase timeouts for long text input ([#787](https://github.com/ChromeDevTools/chrome-devtools-mcp/issues/787)) ([a83a338](https://github.com/ChromeDevTools/chrome-devtools-mcp/commit/a83a33835148905b538b39be93f6115774f91696))\n* make request and response handling more robust ([#846](https://github.com/ChromeDevTools/chrome-devtools-mcp/issues/846)) ([695817f](https://github.com/ChromeDevTools/chrome-devtools-mcp/commit/695817f6d6da5fcb94934fb1c2be8b006522f53b))\n* re-use node ids across snapshots ([#814](https://github.com/ChromeDevTools/chrome-devtools-mcp/issues/814)) ([a6cd2cd](https://github.com/ChromeDevTools/chrome-devtools-mcp/commit/a6cd2cd3f2bd823f0e044d7796fd8ff2c100cda3))\n\n\n### 📄 Documentation\n\n* add a mention of evals into contributing.md ([#773](https://github.com/ChromeDevTools/chrome-devtools-mcp/issues/773)) ([9a31ac7](https://github.com/ChromeDevTools/chrome-devtools-mcp/commit/9a31ac7abab5890d11fec627bbdcbb8051452453))\n* document how to add extensions to gemini-cli ([#834](https://github.com/ChromeDevTools/chrome-devtools-mcp/issues/834)) ([0610d11](https://github.com/ChromeDevTools/chrome-devtools-mcp/commit/0610d11aa9add484951b76adef557eed5e2bd275))\n* update auto-connect docs ([#779](https://github.com/ChromeDevTools/chrome-devtools-mcp/issues/779)) ([a106fba](https://github.com/ChromeDevTools/chrome-devtools-mcp/commit/a106fbadbc1a487ce4c53a9eb783c98e524c0a9e))\n* Update README.md to include a link to Android debugging ([#783](https://github.com/ChromeDevTools/chrome-devtools-mcp/issues/783)) ([6e52e66](https://github.com/ChromeDevTools/chrome-devtools-mcp/commit/6e52e66a7a7ebbf1f2e2080a857f72192036eb0c))\n\n## [0.13.0](https://github.com/ChromeDevTools/chrome-devtools-mcp/compare/chrome-devtools-mcp-v0.12.1...chrome-devtools-mcp-v0.13.0) (2026-01-14)\n\n\n### 🎉 Features\n\n* Allow opting out of default Chrome launch arguments ([#729](https://github.com/ChromeDevTools/chrome-devtools-mcp/issues/729)) ([9a51af2](https://github.com/ChromeDevTools/chrome-devtools-mcp/commit/9a51af219fc9216cd463bef9363716283f41f36a))\n* support filePath in performance tools ([#686](https://github.com/ChromeDevTools/chrome-devtools-mcp/issues/686)) ([68ae2f8](https://github.com/ChromeDevTools/chrome-devtools-mcp/commit/68ae2f8253e2ba5c34436e25df114874c537f6df))\n\n\n### 🛠️ Fixes\n\n* support resize_page when browser window is maximized/fullscreenwindow state ([#748](https://github.com/ChromeDevTools/chrome-devtools-mcp/issues/748)) ([4d9ac22](https://github.com/ChromeDevTools/chrome-devtools-mcp/commit/4d9ac227ddff6fc4aec44e46673f6e44a8168db9))\n* use relative path for plugin source in marketplace ([#724](https://github.com/ChromeDevTools/chrome-devtools-mcp/issues/724)) ([5c1ecf8](https://github.com/ChromeDevTools/chrome-devtools-mcp/commit/5c1ecf835ac8aad4947d0a8f82c899acd4115b64))\n\n\n### 📄 Documentation\n\n* add experimental chrome on android guide ([#691](https://github.com/ChromeDevTools/chrome-devtools-mcp/issues/691)) ([4a87702](https://github.com/ChromeDevTools/chrome-devtools-mcp/commit/4a87702ca6913ed62987f71e080f3d481d13b8d8))\n* autoConnect - clarify how the mcp server selects a profile ([#693](https://github.com/ChromeDevTools/chrome-devtools-mcp/issues/693)) ([28b8ff8](https://github.com/ChromeDevTools/chrome-devtools-mcp/commit/28b8ff816461760c82e9b19b70f288bc7fa2fa38))\n* claude code broken link ([#707](https://github.com/ChromeDevTools/chrome-devtools-mcp/issues/707)) ([1f532b8](https://github.com/ChromeDevTools/chrome-devtools-mcp/commit/1f532b8fafa0fa60aaf94c302bad663fab1c12ea))\n* enhance cli docs + sort required vs opt params ([#674](https://github.com/ChromeDevTools/chrome-devtools-mcp/issues/674)) ([81cbd99](https://github.com/ChromeDevTools/chrome-devtools-mcp/commit/81cbd99f52d013d07bdcf21a0840f61a16bacd33))\n* update auto connect docs to mention min Chrome version ([#681](https://github.com/ChromeDevTools/chrome-devtools-mcp/issues/681)) ([ab2340f](https://github.com/ChromeDevTools/chrome-devtools-mcp/commit/ab2340f40127dcdabde6887a411163ce9d130394))\n* Update Claude Code instructions in README.md ([#711](https://github.com/ChromeDevTools/chrome-devtools-mcp/issues/711)) ([f81cd2d](https://github.com/ChromeDevTools/chrome-devtools-mcp/commit/f81cd2d8dfc35da8c718b227e0ee4c4d7c5daca8))\n* update readme to include OpenCode example ([#560](https://github.com/ChromeDevTools/chrome-devtools-mcp/issues/560)) ([fbba3c9](https://github.com/ChromeDevTools/chrome-devtools-mcp/commit/fbba3c9461cec8113216fa4569e879c85312ea29))\n\n\n### ♻️ Chores\n\n* change pageIdx to page ids ([#741](https://github.com/ChromeDevTools/chrome-devtools-mcp/issues/741)) ([a23c6ba](https://github.com/ChromeDevTools/chrome-devtools-mcp/commit/a23c6ba8c9e1da90c885e68946635a8cc536a11e))\n\n## [0.12.1](https://github.com/ChromeDevTools/chrome-devtools-mcp/compare/chrome-devtools-mcp-v0.12.0...chrome-devtools-mcp-v0.12.1) (2025-12-12)\n\n\n### 🛠️ Fixes\n\n* catch unexpected error in event handlers ([#672](https://github.com/ChromeDevTools/chrome-devtools-mcp/issues/672)) ([ca0f560](https://github.com/ChromeDevTools/chrome-devtools-mcp/commit/ca0f5607f18bf04134e85ea1f61d1a839a47827b))\n* log unhandledRejection instead of crashing ([#673](https://github.com/ChromeDevTools/chrome-devtools-mcp/issues/673)) ([f59b4a2](https://github.com/ChromeDevTools/chrome-devtools-mcp/commit/f59b4a2ed8b09e1d64916552ee6db49b978fe9a7))\n* make bringToFront optional in select_page ([#668](https://github.com/ChromeDevTools/chrome-devtools-mcp/issues/668)) ([ceae17b](https://github.com/ChromeDevTools/chrome-devtools-mcp/commit/ceae17be26b0a812f1b013dcebaed9beb510e7b3))\n* Update installation badges in README.md for VS Code ([#660](https://github.com/ChromeDevTools/chrome-devtools-mcp/issues/660)) ([61ede1c](https://github.com/ChromeDevTools/chrome-devtools-mcp/commit/61ede1c0531ea8b028d9a5cbb28fcdc00cc521e0))\n\n\n### 📄 Documentation\n\n* Add debug instructions ([#670](https://github.com/ChromeDevTools/chrome-devtools-mcp/issues/670)) ([a8aae66](https://github.com/ChromeDevTools/chrome-devtools-mcp/commit/a8aae6652e205b87ac2efa29217b7cbd18dcbbe6))\n* explain new auto connection feature ([#664](https://github.com/ChromeDevTools/chrome-devtools-mcp/issues/664)) ([a537a8c](https://github.com/ChromeDevTools/chrome-devtools-mcp/commit/a537a8c8cef4f2a3493e9f7de47345d565b6fc9f))\n\n## [0.12.0](https://github.com/ChromeDevTools/chrome-devtools-mcp/compare/chrome-devtools-mcp-v0.11.0...chrome-devtools-mcp-v0.12.0) (2025-12-09)\n\n\n### 🎉 Features\n\n* support --auto-connect to a Chrome instance ([#651](https://github.com/ChromeDevTools/chrome-devtools-mcp/issues/651)) ([6ab6d85](https://github.com/ChromeDevTools/chrome-devtools-mcp/commit/6ab6d85d50226cf12a62563430f552e783f428b2))\n* support --user-data-dir with --auto-connect ([#654](https://github.com/ChromeDevTools/chrome-devtools-mcp/issues/654)) ([e3c59bc](https://github.com/ChromeDevTools/chrome-devtools-mcp/commit/e3c59bcd9c284f3be99cc15e22116b887f04cdab))\n\n\n### 🛠️ Fixes\n\n* map channel for resolveDefaultUserDataDir ([#658](https://github.com/ChromeDevTools/chrome-devtools-mcp/issues/658)) ([6f59b39](https://github.com/ChromeDevTools/chrome-devtools-mcp/commit/6f59b3975abda50536f8b890f3245662b22e3657))\n\n\n### 📄 Documentation\n\n* Add AX design principles ([#643](https://github.com/ChromeDevTools/chrome-devtools-mcp/issues/643)) ([90ed192](https://github.com/ChromeDevTools/chrome-devtools-mcp/commit/90ed192c558d36faf9f6300be1c1fd5abd464d8a))\n* improve autoConnect docs ([#653](https://github.com/ChromeDevTools/chrome-devtools-mcp/issues/653)) ([09111cc](https://github.com/ChromeDevTools/chrome-devtools-mcp/commit/09111cc16464bed27cd623f3b345d3885db12521))\n\n## [0.11.0](https://github.com/ChromeDevTools/chrome-devtools-mcp/compare/chrome-devtools-mcp-v0.10.2...chrome-devtools-mcp-v0.11.0) (2025-12-03)\n\n\n### 🎉 Features\n\n* **emulation:** add geolocation emulation tool ([#634](https://github.com/ChromeDevTools/chrome-devtools-mcp/issues/634)) ([3991e4c](https://github.com/ChromeDevTools/chrome-devtools-mcp/commit/3991e4c2a9c28bf8180f9057ce804d978c39529d))\n* integrate DevTools issues into the console tools ([#636](https://github.com/ChromeDevTools/chrome-devtools-mcp/issues/636)) ([d892145](https://github.com/ChromeDevTools/chrome-devtools-mcp/commit/d8921453c77a1c0815059fb9bc72c0cd769a7bd4))\n* support --user-data-dir ([#622](https://github.com/ChromeDevTools/chrome-devtools-mcp/issues/622)) ([fcaf553](https://github.com/ChromeDevTools/chrome-devtools-mcp/commit/fcaf55354c2afbdbae538e27eb4b6d02f2e87985))\n\n\n### 🛠️ Fixes\n\n* handle error messages that are not instanceof Error ([#618](https://github.com/ChromeDevTools/chrome-devtools-mcp/issues/618)) ([a67528a](https://github.com/ChromeDevTools/chrome-devtools-mcp/commit/a67528a046746c7131d5265f6c94613d607aaf90))\n* handle the case when all pages are filtered out ([#616](https://github.com/ChromeDevTools/chrome-devtools-mcp/issues/616)) ([bff5c65](https://github.com/ChromeDevTools/chrome-devtools-mcp/commit/bff5c6569003fdbc207448d89a8be6a9a8172ca0))\n* ignore hash parts of URLs when finding DevTools ([#608](https://github.com/ChromeDevTools/chrome-devtools-mcp/issues/608)) ([52533d0](https://github.com/ChromeDevTools/chrome-devtools-mcp/commit/52533d0c695354b816807de253f0ec17099aa9d7))\n* ignore quality for png ([#589](https://github.com/ChromeDevTools/chrome-devtools-mcp/issues/589)) ([2eaf268](https://github.com/ChromeDevTools/chrome-devtools-mcp/commit/2eaf2689c3360f88479f4cdab8ddde5899378e33))\n* include a note about selected elements missing from the snapshot ([#593](https://github.com/ChromeDevTools/chrome-devtools-mcp/issues/593)) ([80e77fd](https://github.com/ChromeDevTools/chrome-devtools-mcp/commit/80e77fd9a35a3dc5c451cc5b070b8baa574c686c))\n* prevent dropping license notices on some files when publishing ([#604](https://github.com/ChromeDevTools/chrome-devtools-mcp/issues/604)) ([94752ff](https://github.com/ChromeDevTools/chrome-devtools-mcp/commit/94752ffade847671ebfd15e4013a5b5cdf8377df))\n* rename page content to latest page snapshot ([#579](https://github.com/ChromeDevTools/chrome-devtools-mcp/issues/579)) ([9cb99ad](https://github.com/ChromeDevTools/chrome-devtools-mcp/commit/9cb99ad3e65054f4ea12a39358719f6630a020d0))\n* **wait_for:** respect the provided timeout ([#630](https://github.com/ChromeDevTools/chrome-devtools-mcp/issues/630)) ([6b0984a](https://github.com/ChromeDevTools/chrome-devtools-mcp/commit/6b0984aa7dca6f651afd1fed56246893810781c9)), closes [#624](https://github.com/ChromeDevTools/chrome-devtools-mcp/issues/624)\n\n\n### 📄 Documentation\n\n* add Antigravity config ([#580](https://github.com/ChromeDevTools/chrome-devtools-mcp/issues/580)) ([6f9182f](https://github.com/ChromeDevTools/chrome-devtools-mcp/commit/6f9182f4b60f1f6ff8d321fec35545712828686e))\n* add Qoder CLI to the MCP client configuration section in the README. ([#552](https://github.com/ChromeDevTools/chrome-devtools-mcp/issues/552)) ([1a16f15](https://github.com/ChromeDevTools/chrome-devtools-mcp/commit/1a16f15546e227a0708f89d3084c98d4916db53f))\n* add VS Code install badges ([#532](https://github.com/ChromeDevTools/chrome-devtools-mcp/issues/532)) ([cc4d065](https://github.com/ChromeDevTools/chrome-devtools-mcp/commit/cc4d065dd6081a2a9fbcc3d8ebb1536e5426116e))\n* clarify browser-url parameter in README ([#613](https://github.com/ChromeDevTools/chrome-devtools-mcp/issues/613)) ([05cf8cb](https://github.com/ChromeDevTools/chrome-devtools-mcp/commit/05cf8cb8a6c68506282075bc1522c81f0b84f07b))\n* Fix Antigravity docs ([#605](https://github.com/ChromeDevTools/chrome-devtools-mcp/issues/605)) ([fae2608](https://github.com/ChromeDevTools/chrome-devtools-mcp/commit/fae260888748ece77b368a13ee913153caffcef7))\n* update readme to explain agy's browser integration ([#612](https://github.com/ChromeDevTools/chrome-devtools-mcp/issues/612)) ([2d89865](https://github.com/ChromeDevTools/chrome-devtools-mcp/commit/2d89865ddbff6e77332c6157f687dcc2f0bef892))\n\n\n### ♻️ Chores\n\n* avoid throwing in resolveCdpElementId ([#606](https://github.com/ChromeDevTools/chrome-devtools-mcp/issues/606)) ([eb261fd](https://github.com/ChromeDevTools/chrome-devtools-mcp/commit/eb261fd48b6753db246d24b77e1f477dc7a9455e))\n\n## [0.10.2](https://github.com/ChromeDevTools/chrome-devtools-mcp/compare/chrome-devtools-mcp-v0.10.1...chrome-devtools-mcp-v0.10.2) (2025-11-19)\n\n\n### 📄 Documentation\n\n* add Factory CLI configuration to MCP clients ([#523](https://github.com/ChromeDevTools/chrome-devtools-mcp/issues/523)) ([016e2fd](https://github.com/ChromeDevTools/chrome-devtools-mcp/commit/016e2fd6ee57447103f7385285dd503b5576a860))\n\n\n### ♻️ Chores\n\n* clear issue aggregator on page navigation ([#565](https://github.com/ChromeDevTools/chrome-devtools-mcp/issues/565)) ([c3784d1](https://github.com/ChromeDevTools/chrome-devtools-mcp/commit/c3784d1990a926f651951e4eef05520c5c448964))\n* disable issues in list_console_messages for now ([#575](https://github.com/ChromeDevTools/chrome-devtools-mcp/issues/575)) ([08e9a9f](https://github.com/ChromeDevTools/chrome-devtools-mcp/commit/08e9a9f42e6ff1a92c60b3e958b0817c7b785afc))\n* simplify issue management ([#564](https://github.com/ChromeDevTools/chrome-devtools-mcp/issues/564)) ([3b016f1](https://github.com/ChromeDevTools/chrome-devtools-mcp/commit/3b016f1a814b1a69750813548b3f35e79bfb6fef))\n\n## [0.10.1](https://github.com/ChromeDevTools/chrome-devtools-mcp/compare/chrome-devtools-mcp-v0.10.0...chrome-devtools-mcp-v0.10.1) (2025-11-07)\n\n\n### 🛠️ Fixes\n\n* avoid no page selected errors ([#537](https://github.com/ChromeDevTools/chrome-devtools-mcp/issues/537)) ([4724bbb](https://github.com/ChromeDevTools/chrome-devtools-mcp/commit/4724bbba9327fc162cd1f0372e608f6ebefc59cc))\n\n## [0.10.0](https://github.com/ChromeDevTools/chrome-devtools-mcp/compare/chrome-devtools-mcp-v0.9.0...chrome-devtools-mcp-v0.10.0) (2025-11-05)\n\n\n### 🎉 Features\n\n* add a press_key tool ([#458](https://github.com/ChromeDevTools/chrome-devtools-mcp/issues/458)) ([b427392](https://github.com/ChromeDevTools/chrome-devtools-mcp/commit/b4273923928704e718e0a0f8b5cc86758416e994))\n* add insightSetId to performance_analyze_insight ([#518](https://github.com/ChromeDevTools/chrome-devtools-mcp/issues/518)) ([36504d2](https://github.com/ChromeDevTools/chrome-devtools-mcp/commit/36504d29caf637b2d7bf231204c0478b54220c83))\n* an option to ignore cache on reload ([#485](https://github.com/ChromeDevTools/chrome-devtools-mcp/issues/485)) ([8e56307](https://github.com/ChromeDevTools/chrome-devtools-mcp/commit/8e56307d623fe3651262287b30544ed70426b0b8))\n* detect network requests inspected in DevTools UI ([#477](https://github.com/ChromeDevTools/chrome-devtools-mcp/issues/477)) ([796aed7](https://github.com/ChromeDevTools/chrome-devtools-mcp/commit/796aed72b7126ed4332888ffbc06d6cb678265ef))\n* fetch DOM node selected in the DevTools Elements panel ([#486](https://github.com/ChromeDevTools/chrome-devtools-mcp/issues/486)) ([4a83574](https://github.com/ChromeDevTools/chrome-devtools-mcp/commit/4a83574961d8d6b974037db56fc8bdbbb91f79b6))\n* support page reload ([#462](https://github.com/ChromeDevTools/chrome-devtools-mcp/issues/462)) ([d177087](https://github.com/ChromeDevTools/chrome-devtools-mcp/commit/d17708798194486b2571092aa67838085da7231e))\n* support saving snapshots to file ([#463](https://github.com/ChromeDevTools/chrome-devtools-mcp/issues/463)) ([b0ce08a](https://github.com/ChromeDevTools/chrome-devtools-mcp/commit/b0ce08ae2ce422813fef3f28c18f2cb6c976d9fc))\n\n\n### 🛠️ Fixes\n\n* Augment fix to prevent stray OGS frames in NTP from causing hangs. ([#521](https://github.com/ChromeDevTools/chrome-devtools-mcp/issues/521)) ([d90abd4](https://github.com/ChromeDevTools/chrome-devtools-mcp/commit/d90abd4e9e534417622d7f4676e9c3dbeb39ea8d))\n* improve get_network_request description ([#500](https://github.com/ChromeDevTools/chrome-devtools-mcp/issues/500)) ([2f448e8](https://github.com/ChromeDevTools/chrome-devtools-mcp/commit/2f448e84ea8d3a44687c74b3577edf882ef2c19f))\n* work around NTP iframes causing hangs ([#504](https://github.com/ChromeDevTools/chrome-devtools-mcp/issues/504)) ([cca5ff4](https://github.com/ChromeDevTools/chrome-devtools-mcp/commit/cca5ff471c2d2c663e63ade1e2ea58f9a7f5a2cd))\n\n\n### 📄 Documentation\n\n* add Windsurf to the editor config README ([#493](https://github.com/ChromeDevTools/chrome-devtools-mcp/issues/493)) ([63a5d82](https://github.com/ChromeDevTools/chrome-devtools-mcp/commit/63a5d824c2d914c9007e2b837fa292f5ba74ceed))\n* fix typos in README.md exlcude -> exclude ([#513](https://github.com/ChromeDevTools/chrome-devtools-mcp/issues/513)) ([8854a34](https://github.com/ChromeDevTools/chrome-devtools-mcp/commit/8854a3400c3a6b84c761bf8ed82769fc2dec7366))\n* remove unnecessary replace ([#475](https://github.com/ChromeDevTools/chrome-devtools-mcp/issues/475)) ([40e1753](https://github.com/ChromeDevTools/chrome-devtools-mcp/commit/40e1753d2e874bb22005dbebdb551da304a80033))\n\n\n### ♻️ Chores\n\n* connect to DevTools targets by default ([#466](https://github.com/ChromeDevTools/chrome-devtools-mcp/issues/466)) ([a41e440](https://github.com/ChromeDevTools/chrome-devtools-mcp/commit/a41e4407996b8090f8cccc85f6c4696006fc31ec))\n* detect DevTools page for each page ([#467](https://github.com/ChromeDevTools/chrome-devtools-mcp/issues/467)) ([1560ff2](https://github.com/ChromeDevTools/chrome-devtools-mcp/commit/1560ff23cad28ab63c1cf9fb1b961db886bc4a3e))\n* merge emulate tools into one ([#494](https://github.com/ChromeDevTools/chrome-devtools-mcp/issues/494)) ([c06f452](https://github.com/ChromeDevTools/chrome-devtools-mcp/commit/c06f4522ee8f762b59c60c2fd23a0deaaa544766))\n\n## [0.9.0](https://github.com/ChromeDevTools/chrome-devtools-mcp/compare/chrome-devtools-mcp-v0.8.1...chrome-devtools-mcp-v0.9.0) (2025-10-22)\n\n\n### 🎉 Features\n\n* add claude marketplace and plugin json ([#396](https://github.com/ChromeDevTools/chrome-devtools-mcp/issues/396)) ([0498611](https://github.com/ChromeDevTools/chrome-devtools-mcp/commit/0498611429f769c6ccae365674003d2bd538c292))\n* add filters and pagination to the console messages tool ([#387](https://github.com/ChromeDevTools/chrome-devtools-mcp/issues/387)) ([15d942c](https://github.com/ChromeDevTools/chrome-devtools-mcp/commit/15d942c4f3335b35f1cba8e8634651688323663d))\n* add WebSocket endpoint and custom headers support ([#404](https://github.com/ChromeDevTools/chrome-devtools-mcp/issues/404)) ([41d6a10](https://github.com/ChromeDevTools/chrome-devtools-mcp/commit/41d6a107baee0d14a1c14573f958d44198de23aa))\n* allow configuring tool categories ([#454](https://github.com/ChromeDevTools/chrome-devtools-mcp/issues/454)) ([0fe2b8a](https://github.com/ChromeDevTools/chrome-devtools-mcp/commit/0fe2b8a2b4d64b9da5f7d1adccc5425fd7cbec34))\n* expose previous navigations to the MCP ([#419](https://github.com/ChromeDevTools/chrome-devtools-mcp/issues/419)) ([165cf9c](https://github.com/ChromeDevTools/chrome-devtools-mcp/commit/165cf9c70b7f91dc116558547a870281f29da710))\n* support previous navigation for Console messages ([#452](https://github.com/ChromeDevTools/chrome-devtools-mcp/issues/452)) ([6f24362](https://github.com/ChromeDevTools/chrome-devtools-mcp/commit/6f243620391f0c608f51d464257cf3222d653e9e))\n* support stable id for network requests ([#375](https://github.com/ChromeDevTools/chrome-devtools-mcp/issues/375)) ([f4d7b49](https://github.com/ChromeDevTools/chrome-devtools-mcp/commit/f4d7b49bb112b4336bef0d90059485f41f71e4f1))\n* support verbose snapshots ([#388](https://github.com/ChromeDevTools/chrome-devtools-mcp/issues/388)) ([d47aaa9](https://github.com/ChromeDevTools/chrome-devtools-mcp/commit/d47aaa96ff990c49dd07a481ea1924f85881eafa))\n* tool to get a verbose single console message ([#435](https://github.com/ChromeDevTools/chrome-devtools-mcp/issues/435)) ([9205593](https://github.com/ChromeDevTools/chrome-devtools-mcp/commit/92055933dc44e5d200dda2ee4ae0e365b24281bb))\n* use stable id for network request querying ([#382](https://github.com/ChromeDevTools/chrome-devtools-mcp/issues/382)) ([579819b](https://github.com/ChromeDevTools/chrome-devtools-mcp/commit/579819b5e76f7a34c7c5c0877ac1e5e284beb328))\n\n\n### 🛠️ Fixes\n\n* allow evaluating in Frames ([#443](https://github.com/ChromeDevTools/chrome-devtools-mcp/issues/443)) ([053f1f8](https://github.com/ChromeDevTools/chrome-devtools-mcp/commit/053f1f830d051ec415f4b00e645f5a1aff8554a1))\n* better wording for evaluate_script ([#392](https://github.com/ChromeDevTools/chrome-devtools-mcp/issues/392)) ([2313fda](https://github.com/ChromeDevTools/chrome-devtools-mcp/commit/2313fdacad72a1bc5c4d8f1cbdd80fd64ba91771))\n* indicate when request and response bodies are not available ([#446](https://github.com/ChromeDevTools/chrome-devtools-mcp/issues/446)) ([7d47d6b](https://github.com/ChromeDevTools/chrome-devtools-mcp/commit/7d47d6b2f40bf08def29de3ca37b1a4a28ce6777))\n* pageerror for non-error types ([#442](https://github.com/ChromeDevTools/chrome-devtools-mcp/issues/442)) ([b6b42ec](https://github.com/ChromeDevTools/chrome-devtools-mcp/commit/b6b42ecb998dd4f8fbf4a8e7a49f461333a41103))\n* retrieve data correctly with fewer than 3 navigations ([#451](https://github.com/ChromeDevTools/chrome-devtools-mcp/issues/451)) ([4c65f59](https://github.com/ChromeDevTools/chrome-devtools-mcp/commit/4c65f59cf9f62662cf903fbbd19b67a8828d674a))\n\n\n### 📄 Documentation\n\n* add instructions for Qoder ([#386](https://github.com/ChromeDevTools/chrome-devtools-mcp/issues/386)) ([d8df784](https://github.com/ChromeDevTools/chrome-devtools-mcp/commit/d8df784127afd590eb02e0060378465ae115a7a4))\n* add VM-to-host remote debugging workaround ([#399](https://github.com/ChromeDevTools/chrome-devtools-mcp/issues/399)) ([9f9dab0](https://github.com/ChromeDevTools/chrome-devtools-mcp/commit/9f9dab0787f19c5730b65daf148c382fb2d9e365))\n* Update Copilot CLI instructions ([#423](https://github.com/ChromeDevTools/chrome-devtools-mcp/issues/423)) ([c7733a8](https://github.com/ChromeDevTools/chrome-devtools-mcp/commit/c7733a818050e50830c9a8e3d62bb80892cf9121))\n\n\n### ♻️ Chores\n\n* bundle all dependencies together ([#450](https://github.com/ChromeDevTools/chrome-devtools-mcp/issues/450)) ([914b980](https://github.com/ChromeDevTools/chrome-devtools-mcp/commit/914b980113353fd41b301da397aa45975090487a))\n* bundle modelcontextprotocol-sdk ([#409](https://github.com/ChromeDevTools/chrome-devtools-mcp/issues/409)) ([6c8432b](https://github.com/ChromeDevTools/chrome-devtools-mcp/commit/6c8432b6b69d5d56d0dee01968882492033f2dc1))\n* bundle puppeteer-core ([#417](https://github.com/ChromeDevTools/chrome-devtools-mcp/issues/417)) ([b443033](https://github.com/ChromeDevTools/chrome-devtools-mcp/commit/b443033000e46a992ea7fa071af0f9ec304b9ea7))\n* bundle zod together with modelcontextprotocol/sdk ([#414](https://github.com/ChromeDevTools/chrome-devtools-mcp/issues/414)) ([800e7e8](https://github.com/ChromeDevTools/chrome-devtools-mcp/commit/800e7e836433f3f1b2bfafa12ed35a991404d270))\n* cleanup data fetching ([#441](https://github.com/ChromeDevTools/chrome-devtools-mcp/issues/441)) ([5c871c3](https://github.com/ChromeDevTools/chrome-devtools-mcp/commit/5c871c3bd98127996011f269faddd8d8e7163917))\n* dispose listeners on page destroyed ([#318](https://github.com/ChromeDevTools/chrome-devtools-mcp/issues/318)) ([76d5e94](https://github.com/ChromeDevTools/chrome-devtools-mcp/commit/76d5e9416d833299561242ac45c0ce7813e61dbe))\n* extract common paginate type ([#415](https://github.com/ChromeDevTools/chrome-devtools-mcp/issues/415)) ([29fd602](https://github.com/ChromeDevTools/chrome-devtools-mcp/commit/29fd60216ca1394c46a266c6f853f8d65418e861))\n* store the last 3 navigations in PageCollector ([#411](https://github.com/ChromeDevTools/chrome-devtools-mcp/issues/411)) ([b873822](https://github.com/ChromeDevTools/chrome-devtools-mcp/commit/b8738221d8cf8322d5f968ee829f03dc83238a05))\n* use different format for reqid ([#380](https://github.com/ChromeDevTools/chrome-devtools-mcp/issues/380)) ([78bf66a](https://github.com/ChromeDevTools/chrome-devtools-mcp/commit/78bf66a7b1eefc93768f39d6d38fd141104fe812))\n\n## [0.8.1](https://github.com/ChromeDevTools/chrome-devtools-mcp/compare/chrome-devtools-mcp-v0.8.0...chrome-devtools-mcp-v0.8.1) (2025-10-13)\n\n\n### Bug Fixes\n\n* add an option value to the snapshot ([#362](https://github.com/ChromeDevTools/chrome-devtools-mcp/issues/362)) ([207137e](https://github.com/ChromeDevTools/chrome-devtools-mcp/commit/207137edd6d8af2f49277d88a30d8afa51671631))\n* improve navigate_page_history error messages ([#321](https://github.com/ChromeDevTools/chrome-devtools-mcp/issues/321)) ([0624029](https://github.com/ChromeDevTools/chrome-devtools-mcp/commit/0624029e0f8735345d202d29dde446b8869d9561))\n* return the default dialog value correctly ([#366](https://github.com/ChromeDevTools/chrome-devtools-mcp/issues/366)) ([f08f808](https://github.com/ChromeDevTools/chrome-devtools-mcp/commit/f08f8080d0be1074a48e5c2ab0a6533f01f65928))\n* update puppeteer to 24.24.1 ([#370](https://github.com/ChromeDevTools/chrome-devtools-mcp/issues/370)) ([477eef4](https://github.com/ChromeDevTools/chrome-devtools-mcp/commit/477eef481a2e6241121ee4aaaed34e8342a8b347))\n\n## [0.8.0](https://github.com/ChromeDevTools/chrome-devtools-mcp/compare/chrome-devtools-mcp-v0.7.1...chrome-devtools-mcp-v0.8.0) (2025-10-10)\n\n\n### Features\n\n* support passing args to Chrome ([#338](https://github.com/ChromeDevTools/chrome-devtools-mcp/issues/338)) ([e1b5363](https://github.com/ChromeDevTools/chrome-devtools-mcp/commit/e1b536365363e1e1a3aa7661dd84290c794510ad))\n\n## [0.7.1](https://github.com/ChromeDevTools/chrome-devtools-mcp/compare/chrome-devtools-mcp-v0.7.0...chrome-devtools-mcp-v0.7.1) (2025-10-10)\n\n\n### Bug Fixes\n\n* document that console and requests are since the last nav ([#335](https://github.com/ChromeDevTools/chrome-devtools-mcp/issues/335)) ([9ad7cbb](https://github.com/ChromeDevTools/chrome-devtools-mcp/commit/9ad7cbb2de3d285e46e5f3e7c098b0a7535c7e7a))\n\n## [0.7.0](https://github.com/ChromeDevTools/chrome-devtools-mcp/compare/chrome-devtools-mcp-v0.6.1...chrome-devtools-mcp-v0.7.0) (2025-10-10)\n\n\n### Features\n\n* Add offline network emulation support to emulate_network command ([#326](https://github.com/ChromeDevTools/chrome-devtools-mcp/issues/326)) ([139ce60](https://github.com/ChromeDevTools/chrome-devtools-mcp/commit/139ce607814bf25ba541a7264ce96a04b2fac871))\n* add request and response body ([#267](https://github.com/ChromeDevTools/chrome-devtools-mcp/issues/267)) ([dd3c143](https://github.com/ChromeDevTools/chrome-devtools-mcp/commit/dd3c14336ee44d057d06231a5bfd5c5bcf661029))\n\n\n### Bug Fixes\n\n* ordering of information in performance trace summary ([#334](https://github.com/ChromeDevTools/chrome-devtools-mcp/issues/334)) ([2d4484a](https://github.com/ChromeDevTools/chrome-devtools-mcp/commit/2d4484a123968754b4840d112b9c1ca59fb29997))\n* publishing to MCP registry ([#313](https://github.com/ChromeDevTools/chrome-devtools-mcp/issues/313)) ([1faec78](https://github.com/ChromeDevTools/chrome-devtools-mcp/commit/1faec78f84569a03f63585fb84df35992bcfe81a))\n* use default ProtocolTimeout ([#315](https://github.com/ChromeDevTools/chrome-devtools-mcp/issues/315)) ([a525f19](https://github.com/ChromeDevTools/chrome-devtools-mcp/commit/a525f199458afb266db4540bf0fa8007323f3301))\n\n## [0.6.1](https://github.com/ChromeDevTools/chrome-devtools-mcp/compare/chrome-devtools-mcp-v0.6.0...chrome-devtools-mcp-v0.6.1) (2025-10-07)\n\n\n### Bug Fixes\n\n* change default screen size in headless ([#299](https://github.com/ChromeDevTools/chrome-devtools-mcp/issues/299)) ([357db65](https://github.com/ChromeDevTools/chrome-devtools-mcp/commit/357db65d18f87b1299a0f6212b7ec982ef187171))\n* **cli:** tolerate empty browser URLs ([#298](https://github.com/ChromeDevTools/chrome-devtools-mcp/issues/298)) ([098a904](https://github.com/ChromeDevTools/chrome-devtools-mcp/commit/098a904b363f3ad81595ed58c25d34dd7d82bcd8))\n* guard performance_stop_trace when tracing inactive ([#295](https://github.com/ChromeDevTools/chrome-devtools-mcp/issues/295)) ([8200194](https://github.com/ChromeDevTools/chrome-devtools-mcp/commit/8200194c8037cc30b8ab815e5ee0d0b2b000bea6))\n\n## [0.6.0](https://github.com/ChromeDevTools/chrome-devtools-mcp/compare/chrome-devtools-mcp-v0.5.1...chrome-devtools-mcp-v0.6.0) (2025-10-01)\n\n\n### Features\n\n* **screenshot:** add WebP format support with quality parameter ([#220](https://github.com/ChromeDevTools/chrome-devtools-mcp/issues/220)) ([03e02a2](https://github.com/ChromeDevTools/chrome-devtools-mcp/commit/03e02a2d769fbfc0c98599444dfed5413d15ae6e))\n* **screenshot:** adds ability to output screenshot to a specific pat… ([#172](https://github.com/ChromeDevTools/chrome-devtools-mcp/issues/172)) ([f030726](https://github.com/ChromeDevTools/chrome-devtools-mcp/commit/f03072698ddda8587ce23229d733405f88b7c89e))\n* support --accept-insecure-certs CLI ([#231](https://github.com/ChromeDevTools/chrome-devtools-mcp/issues/231)) ([efb106d](https://github.com/ChromeDevTools/chrome-devtools-mcp/commit/efb106dc94af0057f88c89f810beb65114eeaa4b))\n* support --proxy-server CLI ([#230](https://github.com/ChromeDevTools/chrome-devtools-mcp/issues/230)) ([dfacc75](https://github.com/ChromeDevTools/chrome-devtools-mcp/commit/dfacc75ee9f46137b5194e35fc604b89a00ff53f))\n* support initial viewport in the CLI ([#229](https://github.com/ChromeDevTools/chrome-devtools-mcp/issues/229)) ([ef61a08](https://github.com/ChromeDevTools/chrome-devtools-mcp/commit/ef61a08707056c5078d268a83a2c95d10e224f31))\n* support timeouts in wait_for and navigations ([#228](https://github.com/ChromeDevTools/chrome-devtools-mcp/issues/228)) ([36e64d5](https://github.com/ChromeDevTools/chrome-devtools-mcp/commit/36e64d5ae21e8bb244a18201a23a16932947e938))\n\n\n### Bug Fixes\n\n* **network:** show only selected request ([#236](https://github.com/ChromeDevTools/chrome-devtools-mcp/issues/236)) ([73f0aec](https://github.com/ChromeDevTools/chrome-devtools-mcp/commit/73f0aecd8a48b9d1ee354897fe14d785c80e863e))\n* PageCollector subscribing multiple times ([#241](https://github.com/ChromeDevTools/chrome-devtools-mcp/issues/241)) ([0412878](https://github.com/ChromeDevTools/chrome-devtools-mcp/commit/0412878bf51ae46e48a171183bb38cfbbee1038a))\n* snapshot does not capture Iframe content ([#217](https://github.com/ChromeDevTools/chrome-devtools-mcp/issues/217)) ([ce356f2](https://github.com/ChromeDevTools/chrome-devtools-mcp/commit/ce356f256545e805db74664797de5f42e7b92bed)), closes [#186](https://github.com/ChromeDevTools/chrome-devtools-mcp/issues/186)\n\n## [0.5.1](https://github.com/ChromeDevTools/chrome-devtools-mcp/compare/chrome-devtools-mcp-v0.5.0...chrome-devtools-mcp-v0.5.1) (2025-09-29)\n\n\n### Bug Fixes\n\n* update package.json engines to reflect node20 support ([#210](https://github.com/ChromeDevTools/chrome-devtools-mcp/issues/210)) ([b31e647](https://github.com/ChromeDevTools/chrome-devtools-mcp/commit/b31e64713e0524f28cbf760fad27b25829ec419d))\n\n## [0.5.0](https://github.com/ChromeDevTools/chrome-devtools-mcp/compare/chrome-devtools-mcp-v0.4.0...chrome-devtools-mcp-v0.5.0) (2025-09-29)\n\n\n### Features\n\n* **screenshot:** add JPEG quality parameter support ([#184](https://github.com/ChromeDevTools/chrome-devtools-mcp/issues/184)) ([139cfd1](https://github.com/ChromeDevTools/chrome-devtools-mcp/commit/139cfd135cdb07573fe87d824631fcdb6153186e))\n\n\n### Bug Fixes\n\n* do not error if the dialog was already handled ([#208](https://github.com/ChromeDevTools/chrome-devtools-mcp/issues/208)) ([d9f77f8](https://github.com/ChromeDevTools/chrome-devtools-mcp/commit/d9f77f85098ffe851308c5de05effb03ac21237b))\n* reference to handle_dialog tool ([#209](https://github.com/ChromeDevTools/chrome-devtools-mcp/issues/209)) ([205eef5](https://github.com/ChromeDevTools/chrome-devtools-mcp/commit/205eef5cdff19ccb7ddbd113bb1450cb87e8f398))\n* support node20 ([#52](https://github.com/ChromeDevTools/chrome-devtools-mcp/issues/52)) ([13613b4](https://github.com/ChromeDevTools/chrome-devtools-mcp/commit/13613b4a33ab7cf2d4fb1f4849bfa6b82f546945))\n* update tool reference in an error ([#205](https://github.com/ChromeDevTools/chrome-devtools-mcp/issues/205)) ([7765bb3](https://github.com/ChromeDevTools/chrome-devtools-mcp/commit/7765bb381ad9d01219547faf879a74978188754a))\n\n## [0.4.0](https://github.com/ChromeDevTools/chrome-devtools-mcp/compare/chrome-devtools-mcp-v0.3.0...chrome-devtools-mcp-v0.4.0) (2025-09-26)\n\n\n### Features\n\n* add network request filtering by resource type ([#162](https://github.com/ChromeDevTools/chrome-devtools-mcp/issues/162)) ([59d81a3](https://github.com/ChromeDevTools/chrome-devtools-mcp/commit/59d81a33258a199a3f993c9e02a415f62ef05ce4))\n\n\n### Bug Fixes\n\n* add core web vitals to performance_start_trace description ([#168](https://github.com/ChromeDevTools/chrome-devtools-mcp/issues/168)) ([6cfc977](https://github.com/ChromeDevTools/chrome-devtools-mcp/commit/6cfc9774f4ec7944c70842999506b2bc2018a667))\n* add data format information to trace summary ([#166](https://github.com/ChromeDevTools/chrome-devtools-mcp/issues/166)) ([869dd42](https://github.com/ChromeDevTools/chrome-devtools-mcp/commit/869dd4273e42309c1bb57d44e0e5a6a9506ffad7))\n* expose --debug-file argument ([#164](https://github.com/ChromeDevTools/chrome-devtools-mcp/issues/164)) ([22ec7ee](https://github.com/ChromeDevTools/chrome-devtools-mcp/commit/22ec7ee45cc04892000cf6dc32f3fe58d33855c1))\n* typo in the disclaimers ([#156](https://github.com/ChromeDevTools/chrome-devtools-mcp/issues/156)) ([90f686e](https://github.com/ChromeDevTools/chrome-devtools-mcp/commit/90f686e5df3d880c35ec566c837ee5a98824be28))\n\n## [0.3.0](https://github.com/ChromeDevTools/chrome-devtools-mcp/compare/chrome-devtools-mcp-v0.2.7...chrome-devtools-mcp-v0.3.0) (2025-09-25)\n\n\n### Features\n\n* Add pagination list_network_requests ([#145](https://github.com/ChromeDevTools/chrome-devtools-mcp/issues/145)) ([4c909bb](https://github.com/ChromeDevTools/chrome-devtools-mcp/commit/4c909bb8d7c4a420cb8e3219ec98abf28f5cc664))\n\n\n### Bug Fixes\n\n* avoid reporting page close errors as errors ([#127](https://github.com/ChromeDevTools/chrome-devtools-mcp/issues/127)) ([44cfc8f](https://github.com/ChromeDevTools/chrome-devtools-mcp/commit/44cfc8f945edf9370efe26247f322a59a4a4a7be))\n* clarify the node version message ([#135](https://github.com/ChromeDevTools/chrome-devtools-mcp/issues/135)) ([0cc907a](https://github.com/ChromeDevTools/chrome-devtools-mcp/commit/0cc907a9ad79289a6785e9690c3c6940f0a5de52))\n* do not set channel if executablePath is provided ([#150](https://github.com/ChromeDevTools/chrome-devtools-mcp/issues/150)) ([03b59f0](https://github.com/ChromeDevTools/chrome-devtools-mcp/commit/03b59f0bca024173ad45d7a617994e919d9cbbad))\n* **performance:** ImageDelivery insight errors ([#144](https://github.com/ChromeDevTools/chrome-devtools-mcp/issues/144)) ([d64ba0d](https://github.com/ChromeDevTools/chrome-devtools-mcp/commit/d64ba0d9027540eb707381e2577ae3c1fe014346))\n* roll latest DevTools to handle Insight errors ([#149](https://github.com/ChromeDevTools/chrome-devtools-mcp/issues/149)) ([b2e1e39](https://github.com/ChromeDevTools/chrome-devtools-mcp/commit/b2e1e3944c7fa170584ce36c7b8923b0e6d6c6cb))\n\n## [0.2.7](https://github.com/ChromeDevTools/chrome-devtools-mcp/compare/chrome-devtools-mcp-v0.2.6...chrome-devtools-mcp-v0.2.7) (2025-09-24)\n\n\n### Bug Fixes\n\n* validate and report incompatible Node versions ([#113](https://github.com/ChromeDevTools/chrome-devtools-mcp/issues/113)) ([adfcecf](https://github.com/ChromeDevTools/chrome-devtools-mcp/commit/adfcecf9871938b1ad5d1460e0050b849fb2aa49))\n\n## [0.2.6](https://github.com/ChromeDevTools/chrome-devtools-mcp/compare/chrome-devtools-mcp-v0.2.5...chrome-devtools-mcp-v0.2.6) (2025-09-24)\n\n\n### Bug Fixes\n\n* manually bump server.json versions based on package.json ([#105](https://github.com/ChromeDevTools/chrome-devtools-mcp/issues/105)) ([cae1cf1](https://github.com/ChromeDevTools/chrome-devtools-mcp/commit/cae1cf13d5a97add3b96f20c425f720a1ceabf94))\n\n## [0.2.5](https://github.com/ChromeDevTools/chrome-devtools-mcp/compare/chrome-devtools-mcp-v0.2.4...chrome-devtools-mcp-v0.2.5) (2025-09-24)\n\n\n### Bug Fixes\n\n* add mcpName to package.json ([#103](https://github.com/ChromeDevTools/chrome-devtools-mcp/issues/103)) ([bd0351f](https://github.com/ChromeDevTools/chrome-devtools-mcp/commit/bd0351fd36ae35e41e613f0d15df40aeca17ba94))\n\n## [0.2.4](https://github.com/ChromeDevTools/chrome-devtools-mcp/compare/chrome-devtools-mcp-v0.2.3...chrome-devtools-mcp-v0.2.4) (2025-09-24)\n\n\n### Bug Fixes\n\n* forbid closing the last page ([#90](https://github.com/ChromeDevTools/chrome-devtools-mcp/issues/90)) ([0ca2434](https://github.com/ChromeDevTools/chrome-devtools-mcp/commit/0ca2434a29eb4bc6e570a4ebe21a135d85f4c0f3))\n\n## [0.2.3](https://github.com/ChromeDevTools/chrome-devtools-mcp/compare/chrome-devtools-mcp-v0.2.2...chrome-devtools-mcp-v0.2.3) (2025-09-24)\n\n\n### Bug Fixes\n\n* add a message indicating that no console messages exist ([#91](https://github.com/ChromeDevTools/chrome-devtools-mcp/issues/91)) ([1a4ba4d](https://github.com/ChromeDevTools/chrome-devtools-mcp/commit/1a4ba4d3e05f51a85747816f8638f31230881437))\n* clean up pending promises on action errors ([#84](https://github.com/ChromeDevTools/chrome-devtools-mcp/issues/84)) ([4e7001a](https://github.com/ChromeDevTools/chrome-devtools-mcp/commit/4e7001ac375ec51f55b29e9faf68aff0dd09fa0f))\n\n## [0.2.2](https://github.com/ChromeDevTools/chrome-devtools-mcp/compare/chrome-devtools-mcp-v0.2.1...chrome-devtools-mcp-v0.2.2) (2025-09-23)\n\n\n### Bug Fixes\n\n* cli version being reported as unknown ([#74](https://github.com/ChromeDevTools/chrome-devtools-mcp/issues/74)) ([d6bab91](https://github.com/ChromeDevTools/chrome-devtools-mcp/commit/d6bab912df55dc2e96a8d7893d1906f1fc608d0a))\n* remove unnecessary waiting for navigation ([#83](https://github.com/ChromeDevTools/chrome-devtools-mcp/issues/83)) ([924c042](https://github.com/ChromeDevTools/chrome-devtools-mcp/commit/924c042492222a555074063841ce765342e3b5b9))\n* rework performance parsing & error handling ([#75](https://github.com/ChromeDevTools/chrome-devtools-mcp/issues/75)) ([e8fb30c](https://github.com/ChromeDevTools/chrome-devtools-mcp/commit/e8fb30c1bfdc2b4ea8c2daf74b24aa82210f99be))\n\n## [0.2.1](https://github.com/ChromeDevTools/chrome-devtools-mcp/compare/chrome-devtools-mcp-v0.2.0...chrome-devtools-mcp-v0.2.1) (2025-09-23)\n\n\n### Bug Fixes\n\n* add 'on the selected page' to performance tools ([#69](https://github.com/ChromeDevTools/chrome-devtools-mcp/issues/69)) ([b877f7a](https://github.com/ChromeDevTools/chrome-devtools-mcp/commit/b877f7a3053d0cdf2aad1fefc26cf7b913eb95ce))\n* **emulation:** correctly report info for selected page ([#63](https://github.com/ChromeDevTools/chrome-devtools-mcp/issues/63)) ([1e8662f](https://github.com/ChromeDevTools/chrome-devtools-mcp/commit/1e8662f06860aecb5c01ed4ff1515ceb9dac26e4))\n* expose timeout when Emulation is enabled ([#73](https://github.com/ChromeDevTools/chrome-devtools-mcp/issues/73)) ([0208bfd](https://github.com/ChromeDevTools/chrome-devtools-mcp/commit/0208bfdcf6924953879408c18f4c20da544bf4ff))\n* fix browserUrl not working ([#53](https://github.com/ChromeDevTools/chrome-devtools-mcp/issues/53)) ([a6923b8](https://github.com/ChromeDevTools/chrome-devtools-mcp/commit/a6923b8d9397d12ee0f9fe67dd62b10088ec6e87))\n* increase timeouts in case of Emulation ([#71](https://github.com/ChromeDevTools/chrome-devtools-mcp/issues/71)) ([c509c64](https://github.com/ChromeDevTools/chrome-devtools-mcp/commit/c509c64576e1be1ddc283653004ef08a117907a2))\n* **windows:** work around Chrome not reporting reasons for crash ([#64](https://github.com/ChromeDevTools/chrome-devtools-mcp/issues/64)) ([d545741](https://github.com/ChromeDevTools/chrome-devtools-mcp/commit/d5457412a4a76726547190fb3a46bb78c9d6645c))\n\n## [0.2.0](https://github.com/ChromeDevTools/chrome-devtools-mcp/compare/chrome-devtools-mcp-v0.1.0...chrome-devtools-mcp-v0.2.0) (2025-09-17)\n\n\n### Features\n\n* add performance_analyze_insight tool. ([#42](https://github.com/ChromeDevTools/chrome-devtools-mcp/issues/42)) ([21e175b](https://github.com/ChromeDevTools/chrome-devtools-mcp/commit/21e175b862c624d7a2d07802141187edf2d2e489))\n* support script evaluate arguments ([#40](https://github.com/ChromeDevTools/chrome-devtools-mcp/issues/40)) ([c663f4d](https://github.com/ChromeDevTools/chrome-devtools-mcp/commit/c663f4d7f9c0b868e8b4750f6441525939bfe920))\n* use Performance Trace Formatter in trace output ([#36](https://github.com/ChromeDevTools/chrome-devtools-mcp/issues/36)) ([0cb6147](https://github.com/ChromeDevTools/chrome-devtools-mcp/commit/0cb6147b870e17bc3a624e9c6396d963a3e16b44))\n* validate uids ([#37](https://github.com/ChromeDevTools/chrome-devtools-mcp/issues/37)) ([014a8bc](https://github.com/ChromeDevTools/chrome-devtools-mcp/commit/014a8bc52ecc58080cedeb8023d44f4a55055a05))\n\n\n### Bug Fixes\n\n* change profile folder name to browser-profile ([#39](https://github.com/ChromeDevTools/chrome-devtools-mcp/issues/39)) ([36115d7](https://github.com/ChromeDevTools/chrome-devtools-mcp/commit/36115d757abbae0502ffee814f55368d2ca59b9e))\n* refresh context based on the browser instance ([#44](https://github.com/ChromeDevTools/chrome-devtools-mcp/issues/44)) ([93f4579](https://github.com/ChromeDevTools/chrome-devtools-mcp/commit/93f4579dd9aca3beef2bd9f2930ddfcc4069c0e3))\n* update puppeteer to fix a11y snapshot issues ([#43](https://github.com/ChromeDevTools/chrome-devtools-mcp/issues/43)) ([b58f787](https://github.com/ChromeDevTools/chrome-devtools-mcp/commit/b58f787234a34d5fcb01b336f5fb14e1c55ecdd5))\n\n## [0.1.0](https://github.com/ChromeDevTools/chrome-devtools-mcp/compare/chrome-devtools-mcp-v0.0.2...chrome-devtools-mcp-v0.1.0) (2025-09-16)\n\n\n### Features\n\n* improve tools with awaiting common events ([#10](https://github.com/ChromeDevTools/chrome-devtools-mcp/issues/10)) ([dba8b3c](https://github.com/ChromeDevTools/chrome-devtools-mcp/commit/dba8b3c5fad0d1bca26aaf172751c51188799927))\n* initial version ([31a0bdc](https://github.com/ChromeDevTools/chrome-devtools-mcp/commit/31a0bdce266a33eaca9a7daae4611abb78ff5a25))\n\n\n### Bug Fixes\n\n* define tracing categories ([#21](https://github.com/ChromeDevTools/chrome-devtools-mcp/issues/21)) ([c939456](https://github.com/ChromeDevTools/chrome-devtools-mcp/commit/c93945657cc96ac7ba213730a750c16e9ab87526))\n* detect multiple instances and throw ([#12](https://github.com/ChromeDevTools/chrome-devtools-mcp/issues/12)) ([732267d](https://github.com/ChromeDevTools/chrome-devtools-mcp/commit/732267db5fea0048ed1fcc530bcdd074df4126be))\n* make sure tool calls are processed sequentially ([#22](https://github.com/ChromeDevTools/chrome-devtools-mcp/issues/22)) ([a76b23d](https://github.com/ChromeDevTools/chrome-devtools-mcp/commit/a76b23dccf074a13304b0341178665465a2c3399))\n" }, { "path": "CONTRIBUTING.md", "content": "# How to contribute\n\nWe'd love to accept your patches and contributions to this project.\n\n## Before you begin\n\n### Sign our Contributor License Agreement\n\nContributions to this project must be accompanied by a\n[Contributor License Agreement](https://cla.developers.google.com/about) (CLA).\nYou (or your employer) retain the copyright to your contribution; this simply\ngives us permission to use and redistribute your contributions as part of the\nproject.\n\nIf you or your current employer have already signed the Google CLA (even if it\nwas for a different project), you probably don't need to do it again.\n\nVisit to see your current agreements or to\nsign a new one.\n\n### Review our community guidelines\n\nThis project follows\n[Google's Open Source Community Guidelines](https://opensource.google/conduct/).\n\n## Development process\n\n### Code reviews\n\nAll submissions, including submissions by project members, require review. We\nuse GitHub pull requests for this purpose. Consult\n[GitHub Help](https://help.github.com/articles/about-pull-requests/) for more\ninformation on using pull requests.\n\n### Conventional commits\n\nPlease follow [conventional commits](https://www.conventionalcommits.org/en/v1.0.0/)\nfor PR and commit titles.\n\n### Feature release checklist\n\nUse `chore:` for commits containing incomplete features that are not available\nto users yet. Once the feature is ready to be released, create a PR with a\n`feat:` prefix that enables the feature. The following criteria need to be\ncompleted:\n\n- Documentation for the feature is up to date. For example, README.md and tools\n reference are updated.\n- The feature can be used with Chrome stable or version restrictions are\n documented otherwise.\n- Corresponding skills are updated or new skills are added if needed.\n- The feature fulfills the use case by its own or in conjunction with existing\n features (we want to avoid features that offer some tools but cannot be used\n successfully to debug things).\n\n### Release process\n\nReleasing `chrome-devtools-mcp` is automated by GitHub Actions. To release a new\nversion, [search for a PR titled `chore(main): release chrome-devtools-mcp`](https://github.com/ChromeDevTools/chrome-devtools-mcp/pulls?q=is%3Apr+is%3Aopen+%22chore%28main%29%3A+release+chrome-devtools-mcp%22)\nand review, test, and land it. The release PR is automatically opened if there\nare any changes on the main branch that show up in the changelog.\n\n## Installation\n\nCheck that you are using node version specified in .nvmrc, then run following commands:\n\n```sh\ngit clone https://github.com/ChromeDevTools/chrome-devtools-mcp.git\ncd chrome-devtools-mcp\nnpm ci\nnpm run build\n```\n\n### Testing with @modelcontextprotocol/inspector\n\n```sh\nnpx @modelcontextprotocol/inspector node /build/src/bin/chrome-devtools-mcp.js\n```\n\n### Testing with an MCP client\n\nAdd the MCP server to your client's config.\n\n```json\n{\n \"mcpServers\": {\n \"chrome-devtools\": {\n \"command\": \"node\",\n \"args\": [\"/path-to/build/src/bin/chrome-devtools-mcp.js\"]\n }\n }\n}\n```\n\n#### Using with VS Code SSH\n\nWhen running the `@modelcontextprotocol/inspector` it spawns 2 services - one on port `6274` and one on `6277`.\nUsually VS Code automatically detects and forwards `6274` but fails to detect `6277` so you need to manually forward it.\n\n### Debugging\n\nTo write debug logs to `log.txt` in the working directory, run with the following commands:\n\n```sh\nnpx @modelcontextprotocol/inspector node /build/src/bin/chrome-devtools-mcp.js --log-file=/your/desired/path/log.txt\n```\n\nYou can use the `DEBUG` environment variable as usual to control categories that are logged.\n\n### Updating documentation\n\nWhen adding a new tool or updating a tool name or description, make sure to run `npm run gen` to generate the tool reference documentation.\n\n### Contributing to Evals\n\nWe use Gemini to evaluate the MCP server tools in `scripts/eval_scenarios`.\nEach scenario is a TypeScript file that exports a `scenario` object implementing `TestScenario`.\n\n- **prompt**: The prompt to send to the model.\n- **maxTurns**: Maximum number of conversation turns.\n- **expectations**: A function that verifies the tool calls made by the model.\n- **htmlRoute** (Optional): Serve custom HTML content for the test at a specific path.\n\nWe look to test that the tools are used correctly without too rigid assertions. Avoid asserting exact argument values if they can vary (e.g., natural language reasoning), but ensure the core parameters (like URLs or selectors) were correct.\n\nExample:\n\n```ts\nimport {TestScenario} from '../eval_gemini.js';\n\nexport const scenario: TestScenario = {\n prompt: 'Navigate to example.com',\n maxTurns: 2,\n expectations: calls => {\n // Check that at least one call was 'browse_page'\n const navigation = calls.find(c => c.name === 'browse_page');\n if (!navigation) throw new Error('Model did not browse the page');\n // Verify essential args\n if (navigation.args.url !== 'http://example.com') {\n throw new Error(`Wrong URL: ${navigation.args.url}`);\n }\n },\n};\n```\n\n## Restrictions on JSON schema\n\n- no .nullable(), no .object() types.\n- represent complex object as a short formatted string.\n\nTODO: implement eslint for schema https://github.com/ChromeDevTools/chrome-devtools-mcp/issues/1076\n" }, { "path": "LICENSE", "content": "\n Apache License\n Version 2.0, January 2004\n http://www.apache.org/licenses/\n\n TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION\n\n 1. Definitions.\n\n \"License\" shall mean the terms and conditions for use, reproduction,\n and distribution as defined by Sections 1 through 9 of this document.\n\n \"Licensor\" shall mean the copyright owner or entity authorized by\n the copyright owner that is granting the License.\n\n \"Legal Entity\" shall mean the union of the acting entity and all\n other entities that control, are controlled by, or are under common\n control with that entity. For the purposes of this definition,\n \"control\" means (i) the power, direct or indirect, to cause the\n direction or management of such entity, whether by contract or\n otherwise, or (ii) ownership of fifty percent (50%) or more of the\n outstanding shares, or (iii) beneficial ownership of such entity.\n\n \"You\" (or \"Your\") shall mean an individual or Legal Entity\n exercising permissions granted by this License.\n\n \"Source\" form shall mean the preferred form for making modifications,\n including but not limited to software source code, documentation\n source, and configuration files.\n\n \"Object\" form shall mean any form resulting from mechanical\n transformation or translation of a Source form, including but\n not limited to compiled object code, generated documentation,\n and conversions to other media types.\n\n \"Work\" shall mean the work of authorship, whether in Source or\n Object form, made available under the License, as indicated by a\n copyright notice that is included in or attached to the work\n (an example is provided in the Appendix below).\n\n \"Derivative Works\" shall mean any work, whether in Source or Object\n form, that is based on (or derived from) the Work and for which the\n editorial revisions, annotations, elaborations, or other modifications\n represent, as a whole, an original work of authorship. For the purposes\n of this License, Derivative Works shall not include works that remain\n separable from, or merely link (or bind by name) to the interfaces of,\n the Work and Derivative Works thereof.\n\n \"Contribution\" shall mean any work of authorship, including\n the original version of the Work and any modifications or additions\n to that Work or Derivative Works thereof, that is intentionally\n submitted to Licensor for inclusion in the Work by the copyright owner\n or by an individual or Legal Entity authorized to submit on behalf of\n the copyright owner. For the purposes of this definition, \"submitted\"\n means any form of electronic, verbal, or written communication sent\n to the Licensor or its representatives, including but not limited to\n communication on electronic mailing lists, source code control systems,\n and issue tracking systems that are managed by, or on behalf of, the\n Licensor for the purpose of discussing and improving the Work, but\n excluding communication that is conspicuously marked or otherwise\n designated in writing by the copyright owner as \"Not a Contribution.\"\n\n \"Contributor\" shall mean Licensor and any individual or Legal Entity\n on behalf of whom a Contribution has been received by Licensor and\n subsequently incorporated within the Work.\n\n 2. Grant of Copyright License. Subject to the terms and conditions of\n this License, each Contributor hereby grants to You a perpetual,\n worldwide, non-exclusive, no-charge, royalty-free, irrevocable\n copyright license to reproduce, prepare Derivative Works of,\n publicly display, publicly perform, sublicense, and distribute the\n Work and such Derivative Works in Source or Object form.\n\n 3. Grant of Patent License. Subject to the terms and conditions of\n this License, each Contributor hereby grants to You a perpetual,\n worldwide, non-exclusive, no-charge, royalty-free, irrevocable\n (except as stated in this section) patent license to make, have made,\n use, offer to sell, sell, import, and otherwise transfer the Work,\n where such license applies only to those patent claims licensable\n by such Contributor that are necessarily infringed by their\n Contribution(s) alone or by combination of their Contribution(s)\n with the Work to which such Contribution(s) was submitted. If You\n institute patent litigation against any entity (including a\n cross-claim or counterclaim in a lawsuit) alleging that the Work\n or a Contribution incorporated within the Work constitutes direct\n or contributory patent infringement, then any patent licenses\n granted to You under this License for that Work shall terminate\n as of the date such litigation is filed.\n\n 4. Redistribution. You may reproduce and distribute copies of the\n Work or Derivative Works thereof in any medium, with or without\n modifications, and in Source or Object form, provided that You\n meet the following conditions:\n\n (a) You must give any other recipients of the Work or\n Derivative Works a copy of this License; and\n\n (b) You must cause any modified files to carry prominent notices\n stating that You changed the files; and\n\n (c) You must retain, in the Source form of any Derivative Works\n that You distribute, all copyright, patent, trademark, and\n attribution notices from the Source form of the Work,\n excluding those notices that do not pertain to any part of\n the Derivative Works; and\n\n (d) If the Work includes a \"NOTICE\" text file as part of its\n distribution, then any Derivative Works that You distribute must\n include a readable copy of the attribution notices contained\n within such NOTICE file, excluding those notices that do not\n pertain to any part of the Derivative Works, in at least one\n of the following places: within a NOTICE text file distributed\n as part of the Derivative Works; within the Source form or\n documentation, if provided along with the Derivative Works; or,\n within a display generated by the Derivative Works, if and\n wherever such third-party notices normally appear. The contents\n of the NOTICE file are for informational purposes only and\n do not modify the License. You may add Your own attribution\n notices within Derivative Works that You distribute, alongside\n or as an addendum to the NOTICE text from the Work, provided\n that such additional attribution notices cannot be construed\n as modifying the License.\n\n You may add Your own copyright statement to Your modifications and\n may provide additional or different license terms and conditions\n for use, reproduction, or distribution of Your modifications, or\n for any such Derivative Works as a whole, provided Your use,\n reproduction, and distribution of the Work otherwise complies with\n the conditions stated in this License.\n\n 5. Submission of Contributions. Unless You explicitly state otherwise,\n any Contribution intentionally submitted for inclusion in the Work\n by You to the Licensor shall be under the terms and conditions of\n this License, without any additional terms or conditions.\n Notwithstanding the above, nothing herein shall supersede or modify\n the terms of any separate license agreement you may have executed\n with Licensor regarding such Contributions.\n\n 6. Trademarks. This License does not grant permission to use the trade\n names, trademarks, service marks, or product names of the Licensor,\n except as required for reasonable and customary use in describing the\n origin of the Work and reproducing the content of the NOTICE file.\n\n 7. Disclaimer of Warranty. Unless required by applicable law or\n agreed to in writing, Licensor provides the Work (and each\n Contributor provides its Contributions) on an \"AS IS\" BASIS,\n WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or\n implied, including, without limitation, any warranties or conditions\n of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A\n PARTICULAR PURPOSE. You are solely responsible for determining the\n appropriateness of using or redistributing the Work and assume any\n risks associated with Your exercise of permissions under this License.\n\n 8. Limitation of Liability. In no event and under no legal theory,\n whether in tort (including negligence), contract, or otherwise,\n unless required by applicable law (such as deliberate and grossly\n negligent acts) or agreed to in writing, shall any Contributor be\n liable to You for damages, including any direct, indirect, special,\n incidental, or consequential damages of any character arising as a\n result of this License or out of the use or inability to use the\n Work (including but not limited to damages for loss of goodwill,\n work stoppage, computer failure or malfunction, or any and all\n other commercial damages or losses), even if such Contributor\n has been advised of the possibility of such damages.\n\n 9. Accepting Warranty or Additional Liability. While redistributing\n the Work or Derivative Works thereof, You may choose to offer,\n and charge a fee for, acceptance of support, warranty, indemnity,\n or other liability obligations and/or rights consistent with this\n License. However, in accepting such obligations, You may act only\n on Your own behalf and on Your sole responsibility, not on behalf\n of any other Contributor, and only if You agree to indemnify,\n defend, and hold each Contributor harmless for any liability\n incurred by, or claims asserted against, such Contributor by reason\n of your accepting any such warranty or additional liability.\n\n END OF TERMS AND CONDITIONS\n\n APPENDIX: How to apply the Apache License to your work.\n\n To apply the Apache License to your work, attach the following\n boilerplate notice, with the fields enclosed by brackets \"[]\"\n replaced with your own identifying information. (Don't include\n the brackets!) The text should be enclosed in the appropriate\n comment syntax for the file format. We also recommend that a\n file or class name and description of purpose be included on the\n same \"printed page\" as the copyright notice for easier\n identification within third-party archives.\n\n Copyright [yyyy] [name of copyright owner]\n\n Licensed under the Apache License, Version 2.0 (the \"License\");\n you may not use this file except in compliance with the License.\n You may obtain a copy of the License at\n\n http://www.apache.org/licenses/LICENSE-2.0\n\n Unless required by applicable law or agreed to in writing, software\n distributed under the License is distributed on an \"AS IS\" BASIS,\n WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n See the License for the specific language governing permissions and\n limitations under the License." }, { "path": "README.md", "content": "# Chrome DevTools MCP\n\n[![npm chrome-devtools-mcp package](https://img.shields.io/npm/v/chrome-devtools-mcp.svg)](https://npmjs.org/package/chrome-devtools-mcp)\n\n`chrome-devtools-mcp` lets your coding agent (such as Gemini, Claude, Cursor or Copilot)\ncontrol and inspect a live Chrome browser. It acts as a Model-Context-Protocol\n(MCP) server, giving your AI coding assistant access to the full power of\nChrome DevTools for reliable automation, in-depth debugging, and performance analysis.\n\n## [Tool reference](./docs/tool-reference.md) | [Changelog](./CHANGELOG.md) | [Contributing](./CONTRIBUTING.md) | [Troubleshooting](./docs/troubleshooting.md) | [Design Principles](./docs/design-principles.md)\n\n## Key features\n\n- **Get performance insights**: Uses [Chrome\n DevTools](https://github.com/ChromeDevTools/devtools-frontend) to record\n traces and extract actionable performance insights.\n- **Advanced browser debugging**: Analyze network requests, take screenshots and\n check browser console messages (with source-mapped stack traces).\n- **Reliable automation**. Uses\n [puppeteer](https://github.com/puppeteer/puppeteer) to automate actions in\n Chrome and automatically wait for action results.\n\n## Disclaimers\n\n`chrome-devtools-mcp` exposes content of the browser instance to the MCP clients\nallowing them to inspect, debug, and modify any data in the browser or DevTools.\nAvoid sharing sensitive or personal information that you don't want to share with\nMCP clients.\n\nPerformance tools may send trace URLs to the Google CrUX API to fetch real-user\nexperience data. This helps provide a holistic performance picture by\npresenting field data alongside lab data. This data is collected by the [Chrome\nUser Experience Report (CrUX)](https://developer.chrome.com/docs/crux). To disable\nthis, run with the `--no-performance-crux` flag.\n\n## **Usage statistics**\n\nGoogle collects usage statistics (such as tool invocation success rates, latency, and environment information) to improve the reliability and performance of Chrome DevTools MCP.\n\nData collection is **enabled by default**. You can opt-out by passing the `--no-usage-statistics` flag when starting the server:\n\n```json\n\"args\": [\"-y\", \"chrome-devtools-mcp@latest\", \"--no-usage-statistics\"]\n```\n\nGoogle handles this data in accordance with the [Google Privacy Policy](https://policies.google.com/privacy).\n\nGoogle's collection of usage statistics for Chrome DevTools MCP is independent from the Chrome browser's usage statistics. Opting out of Chrome metrics does not automatically opt you out of this tool, and vice-versa.\n\nCollection is disabled if CHROME_DEVTOOLS_MCP_NO_USAGE_STATISTICS or CI env variables are set.\n\n## Requirements\n\n- [Node.js](https://nodejs.org/) v20.19 or a newer [latest maintenance LTS](https://github.com/nodejs/Release#release-schedule) version.\n- [Chrome](https://www.google.com/chrome/) current stable version or newer.\n- [npm](https://www.npmjs.com/).\n\n## Getting started\n\nAdd the following config to your MCP client:\n\n```json\n{\n \"mcpServers\": {\n \"chrome-devtools\": {\n \"command\": \"npx\",\n \"args\": [\"-y\", \"chrome-devtools-mcp@latest\"]\n }\n }\n}\n```\n\n> [!NOTE] \n> Using `chrome-devtools-mcp@latest` ensures that your MCP client will always use the latest version of the Chrome DevTools MCP server.\n\nIf you are interested in doing only basic browser tasks, use the `--slim` mode:\n\n```json\n{\n \"mcpServers\": {\n \"chrome-devtools\": {\n \"command\": \"npx\",\n \"args\": [\"-y\", \"chrome-devtools-mcp@latest\", \"--slim\", \"--headless\"]\n }\n }\n}\n```\n\nSee [Slim tool reference](./docs/slim-tool-reference.md).\n\n### MCP Client configuration\n\n
\n Amp\n Follow https://ampcode.com/manual#mcp and use the config provided above. You can also install the Chrome DevTools MCP server using the CLI:\n\n```bash\namp mcp add chrome-devtools -- npx chrome-devtools-mcp@latest\n```\n\n
\n\n
\n Antigravity\n\nTo use the Chrome DevTools MCP server follow the instructions from Antigravity's docs to install a custom MCP server. Add the following config to the MCP servers config:\n\n```bash\n{\n \"mcpServers\": {\n \"chrome-devtools\": {\n \"command\": \"npx\",\n \"args\": [\n \"chrome-devtools-mcp@latest\",\n \"--browser-url=http://127.0.0.1:9222\",\n \"-y\"\n ]\n }\n }\n}\n```\n\nThis will make the Chrome DevTools MCP server automatically connect to the browser that Antigravity is using. If you are not using port 9222, make sure to adjust accordingly.\n\nChrome DevTools MCP will not start the browser instance automatically using this approach because the Chrome DevTools MCP server connects to Antigravity's built-in browser. If the browser is not already running, you have to start it first by clicking the Chrome icon at the top right corner.\n\n
\n\n
\n Claude Code\n\n**Install via CLI (MCP only)**\n\nUse the Claude Code CLI to add the Chrome DevTools MCP server (guide):\n\n```bash\nclaude mcp add chrome-devtools --scope user npx chrome-devtools-mcp@latest\n```\n\n**Install as a Plugin (MCP + Skills)**\n\n> [!NOTE] \n> If you already had Chrome DevTools MCP installed previously for Claude Code, make sure to remove it first from your installation and configuration files.\n\nTo install Chrome DevTools MCP with skills, add the marketplace registry in Claude Code:\n\n```sh\n/plugin marketplace add ChromeDevTools/chrome-devtools-mcp\n```\n\nThen, install the plugin:\n\n```sh\n/plugin install chrome-devtools-mcp\n```\n\nRestart Claude Code to have the MCP server and skills load (check with `/skills`).\n\n> [!TIP]\n> If the plugin installation fails with a `Failed to clone repository` error (e.g., HTTPS connectivity issues behind a corporate firewall), see the [troubleshooting guide](./docs/troubleshooting.md#claude-code-plugin-installation-fails-with-failed-to-clone-repository) for workarounds, or use the CLI installation method above instead.\n\n
\n\n
\n Cline\n Follow https://docs.cline.bot/mcp/configuring-mcp-servers and use the config provided above.\n
\n\n
\n Codex\n Follow the configure MCP guide\n using the standard config from above. You can also install the Chrome DevTools MCP server using the Codex CLI:\n\n```bash\ncodex mcp add chrome-devtools -- npx chrome-devtools-mcp@latest\n```\n\n**On Windows 11**\n\nConfigure the Chrome install location and increase the startup timeout by updating `.codex/config.toml` and adding the following `env` and `startup_timeout_ms` parameters:\n\n```\n[mcp_servers.chrome-devtools]\ncommand = \"cmd\"\nargs = [\n \"/c\",\n \"npx\",\n \"-y\",\n \"chrome-devtools-mcp@latest\",\n]\nenv = { SystemRoot=\"C:\\\\Windows\", PROGRAMFILES=\"C:\\\\Program Files\" }\nstartup_timeout_ms = 20_000\n```\n\n
\n\n
\n Copilot CLI\n\nStart Copilot CLI:\n\n```\ncopilot\n```\n\nStart the dialog to add a new MCP server by running:\n\n```\n/mcp add\n```\n\nConfigure the following fields and press `CTRL+S` to save the configuration:\n\n- **Server name:** `chrome-devtools`\n- **Server Type:** `[1] Local`\n- **Command:** `npx -y chrome-devtools-mcp@latest`\n\n
\n\n
\n Copilot / VS Code\n\n**Click the button to install:**\n\n[\"Install](https://vscode.dev/redirect/mcp/install?name=io.github.ChromeDevTools%2Fchrome-devtools-mcp&config=%7B%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22chrome-devtools-mcp%22%5D%2C%22env%22%3A%7B%7D%7D)\n\n[\"Install](https://insiders.vscode.dev/redirect?url=vscode-insiders%3Amcp%2Finstall%3F%257B%2522name%2522%253A%2522io.github.ChromeDevTools%252Fchrome-devtools-mcp%2522%252C%2522config%2522%253A%257B%2522command%2522%253A%2522npx%2522%252C%2522args%2522%253A%255B%2522-y%2522%252C%2522chrome-devtools-mcp%2522%255D%252C%2522env%2522%253A%257B%257D%257D%257D)\n\n**Or install manually:**\n\nFollow the MCP install guide,\nwith the standard config from above. You can also install the Chrome DevTools MCP server using the VS Code CLI:\n\nFor macOS and Linux:\n\n```bash\ncode --add-mcp '{\"name\":\"io.github.ChromeDevTools/chrome-devtools-mcp\",\"command\":\"npx\",\"args\":[\"-y\",\"chrome-devtools-mcp\"],\"env\":{}}'\n```\n\nFor Windows (PowerShell):\n\n```powershell\ncode --add-mcp '{\"\"\"name\"\"\":\"\"\"io.github.ChromeDevTools/chrome-devtools-mcp\"\"\",\"\"\"command\"\"\":\"\"\"npx\"\"\",\"\"\"args\"\"\":[\"\"\"-y\"\"\",\"\"\"chrome-devtools-mcp\"\"\"]}'\n```\n\n
\n\n
\n Cursor\n\n**Click the button to install:**\n\n[\"Install](https://cursor.com/en/install-mcp?name=chrome-devtools&config=eyJjb21tYW5kIjoibnB4IC15IGNocm9tZS1kZXZ0b29scy1tY3BAbGF0ZXN0In0%3D)\n\n**Or install manually:**\n\nGo to `Cursor Settings` -> `MCP` -> `New MCP Server`. Use the config provided above.\n\n
\n\n
\n Factory CLI\nUse the Factory CLI to add the Chrome DevTools MCP server (guide):\n\n```bash\ndroid mcp add chrome-devtools \"npx -y chrome-devtools-mcp@latest\"\n```\n\n
\n\n
\n Gemini CLI\nInstall the Chrome DevTools MCP server using the Gemini CLI.\n\n**Project wide:**\n\n```bash\n# Either MCP only:\ngemini mcp add chrome-devtools npx chrome-devtools-mcp@latest\n# Or as a Gemini extension (MCP+Skills):\ngemini extensions install --auto-update https://github.com/ChromeDevTools/chrome-devtools-mcp\n```\n\n**Globally:**\n\n```bash\ngemini mcp add -s user chrome-devtools npx chrome-devtools-mcp@latest\n```\n\nAlternatively, follow the MCP guide and use the standard config from above.\n\n
\n\n
\n Gemini Code Assist\n Follow the configure MCP guide\n using the standard config from above.\n
\n\n
\n JetBrains AI Assistant & Junie\n\nGo to `Settings | Tools | AI Assistant | Model Context Protocol (MCP)` -> `Add`. Use the config provided above.\nThe same way chrome-devtools-mcp can be configured for JetBrains Junie in `Settings | Tools | Junie | MCP Settings` -> `Add`. Use the config provided above.\n\n
\n\n
\n Kiro\n\nIn **Kiro Settings**, go to `Configure MCP` > `Open Workspace or User MCP Config` > Use the configuration snippet provided above.\n\nOr, from the IDE **Activity Bar** > `Kiro` > `MCP Servers` > `Click Open MCP Config`. Use the configuration snippet provided above.\n\n
\n\n
\n Katalon Studio\n\nThe Chrome DevTools MCP server can be used with Katalon StudioAssist via an MCP proxy.\n\n**Step 1:** Install the MCP proxy by following the MCP proxy setup guide.\n\n**Step 2:** Start the Chrome DevTools MCP server with the proxy:\n\n```bash\nmcp-proxy --transport streamablehttp --port 8080 -- npx -y chrome-devtools-mcp@latest\n```\n\n**Note:** You may need to pick another port if 8080 is already in use.\n\n**Step 3:** In Katalon Studio, add the server to StudioAssist with the following settings:\n\n- **Connection URL:** `http://127.0.0.1:8080/mcp`\n- **Transport type:** `HTTP`\n\nOnce connected, the Chrome DevTools MCP tools will be available in StudioAssist.\n\n
\n\n
\n OpenCode\n\nAdd the following configuration to your `opencode.json` file. If you don't have one, create it at `~/.config/opencode/opencode.json` (guide):\n\n```json\n{\n \"$schema\": \"https://opencode.ai/config.json\",\n \"mcp\": {\n \"chrome-devtools\": {\n \"type\": \"local\",\n \"command\": [\"npx\", \"-y\", \"chrome-devtools-mcp@latest\"]\n }\n }\n}\n```\n\n
\n\n
\n Qoder\n\nIn **Qoder Settings**, go to `MCP Server` > `+ Add` > Use the configuration snippet provided above.\n\nAlternatively, follow the MCP guide and use the standard config from above.\n\n
\n\n
\n Qoder CLI\n\nInstall the Chrome DevTools MCP server using the Qoder CLI (guide):\n\n**Project wide:**\n\n```bash\nqodercli mcp add chrome-devtools -- npx chrome-devtools-mcp@latest\n```\n\n**Globally:**\n\n```bash\nqodercli mcp add -s user chrome-devtools -- npx chrome-devtools-mcp@latest\n```\n\n
\n\n
\n Visual Studio\n \n **Click the button to install:**\n \n [\"Install](https://vs-open.link/mcp-install?%7B%22name%22%3A%22chrome-devtools%22%2C%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22chrome-devtools-mcp%40latest%22%5D%7D)\n
\n\n
\n Warp\n\nGo to `Settings | AI | Manage MCP Servers` -> `+ Add` to [add an MCP Server](https://docs.warp.dev/knowledge-and-collaboration/mcp#adding-an-mcp-server). Use the config provided above.\n\n
\n\n
\n Windsurf\n Follow the configure MCP guide\n using the standard config from above.\n
\n\n### Your first prompt\n\nEnter the following prompt in your MCP Client to check if everything is working:\n\n```\nCheck the performance of https://developers.chrome.com\n```\n\nYour MCP client should open the browser and record a performance trace.\n\n> [!NOTE] \n> The MCP server will start the browser automatically once the MCP client uses a tool that requires a running browser instance. Connecting to the Chrome DevTools MCP server on its own will not automatically start the browser.\n\n## Tools\n\nIf you run into any issues, checkout our [troubleshooting guide](./docs/troubleshooting.md).\n\n\n\n- **Input automation** (9 tools)\n - [`click`](docs/tool-reference.md#click)\n - [`drag`](docs/tool-reference.md#drag)\n - [`fill`](docs/tool-reference.md#fill)\n - [`fill_form`](docs/tool-reference.md#fill_form)\n - [`handle_dialog`](docs/tool-reference.md#handle_dialog)\n - [`hover`](docs/tool-reference.md#hover)\n - [`press_key`](docs/tool-reference.md#press_key)\n - [`type_text`](docs/tool-reference.md#type_text)\n - [`upload_file`](docs/tool-reference.md#upload_file)\n- **Navigation automation** (6 tools)\n - [`close_page`](docs/tool-reference.md#close_page)\n - [`list_pages`](docs/tool-reference.md#list_pages)\n - [`navigate_page`](docs/tool-reference.md#navigate_page)\n - [`new_page`](docs/tool-reference.md#new_page)\n - [`select_page`](docs/tool-reference.md#select_page)\n - [`wait_for`](docs/tool-reference.md#wait_for)\n- **Emulation** (2 tools)\n - [`emulate`](docs/tool-reference.md#emulate)\n - [`resize_page`](docs/tool-reference.md#resize_page)\n- **Performance** (4 tools)\n - [`performance_analyze_insight`](docs/tool-reference.md#performance_analyze_insight)\n - [`performance_start_trace`](docs/tool-reference.md#performance_start_trace)\n - [`performance_stop_trace`](docs/tool-reference.md#performance_stop_trace)\n - [`take_memory_snapshot`](docs/tool-reference.md#take_memory_snapshot)\n- **Network** (2 tools)\n - [`get_network_request`](docs/tool-reference.md#get_network_request)\n - [`list_network_requests`](docs/tool-reference.md#list_network_requests)\n- **Debugging** (6 tools)\n - [`evaluate_script`](docs/tool-reference.md#evaluate_script)\n - [`get_console_message`](docs/tool-reference.md#get_console_message)\n - [`lighthouse_audit`](docs/tool-reference.md#lighthouse_audit)\n - [`list_console_messages`](docs/tool-reference.md#list_console_messages)\n - [`take_screenshot`](docs/tool-reference.md#take_screenshot)\n - [`take_snapshot`](docs/tool-reference.md#take_snapshot)\n\n\n\n## Configuration\n\nThe Chrome DevTools MCP server supports the following configuration option:\n\n\n\n- **`--autoConnect`/ `--auto-connect`**\n If specified, automatically connects to a browser (Chrome 144+) running locally from the user data directory identified by the channel param (default channel is stable). Requires the remoted debugging server to be started in the Chrome instance via chrome://inspect/#remote-debugging.\n - **Type:** boolean\n - **Default:** `false`\n\n- **`--browserUrl`/ `--browser-url`, `-u`**\n Connect to a running, debuggable Chrome instance (e.g. `http://127.0.0.1:9222`). For more details see: https://github.com/ChromeDevTools/chrome-devtools-mcp#connecting-to-a-running-chrome-instance.\n - **Type:** string\n\n- **`--wsEndpoint`/ `--ws-endpoint`, `-w`**\n WebSocket endpoint to connect to a running Chrome instance (e.g., ws://127.0.0.1:9222/devtools/browser/). Alternative to --browserUrl.\n - **Type:** string\n\n- **`--wsHeaders`/ `--ws-headers`**\n Custom headers for WebSocket connection in JSON format (e.g., '{\"Authorization\":\"Bearer token\"}'). Only works with --wsEndpoint.\n - **Type:** string\n\n- **`--headless`**\n Whether to run in headless (no UI) mode.\n - **Type:** boolean\n - **Default:** `false`\n\n- **`--executablePath`/ `--executable-path`, `-e`**\n Path to custom Chrome executable.\n - **Type:** string\n\n- **`--isolated`**\n If specified, creates a temporary user-data-dir that is automatically cleaned up after the browser is closed. Defaults to false.\n - **Type:** boolean\n\n- **`--userDataDir`/ `--user-data-dir`**\n Path to the user data directory for Chrome. Default is $HOME/.cache/chrome-devtools-mcp/chrome-profile$CHANNEL_SUFFIX_IF_NON_STABLE\n - **Type:** string\n\n- **`--channel`**\n Specify a different Chrome channel that should be used. The default is the stable channel version.\n - **Type:** string\n - **Choices:** `stable`, `canary`, `beta`, `dev`\n\n- **`--logFile`/ `--log-file`**\n Path to a file to write debug logs to. Set the env variable `DEBUG` to `*` to enable verbose logs. Useful for submitting bug reports.\n - **Type:** string\n\n- **`--viewport`**\n Initial viewport size for the Chrome instances started by the server. For example, `1280x720`. In headless mode, max size is 3840x2160px.\n - **Type:** string\n\n- **`--proxyServer`/ `--proxy-server`**\n Proxy server configuration for Chrome passed as --proxy-server when launching the browser. See https://www.chromium.org/developers/design-documents/network-settings/ for details.\n - **Type:** string\n\n- **`--acceptInsecureCerts`/ `--accept-insecure-certs`**\n If enabled, ignores errors relative to self-signed and expired certificates. Use with caution.\n - **Type:** boolean\n\n- **`--experimentalScreencast`/ `--experimental-screencast`**\n Exposes experimental screencast tools (requires ffmpeg). Install ffmpeg https://www.ffmpeg.org/download.html and ensure it is available in the MCP server PATH.\n - **Type:** boolean\n\n- **`--chromeArg`/ `--chrome-arg`**\n Additional arguments for Chrome. Only applies when Chrome is launched by chrome-devtools-mcp.\n - **Type:** array\n\n- **`--ignoreDefaultChromeArg`/ `--ignore-default-chrome-arg`**\n Explicitly disable default arguments for Chrome. Only applies when Chrome is launched by chrome-devtools-mcp.\n - **Type:** array\n\n- **`--categoryEmulation`/ `--category-emulation`**\n Set to false to exclude tools related to emulation.\n - **Type:** boolean\n - **Default:** `true`\n\n- **`--categoryPerformance`/ `--category-performance`**\n Set to false to exclude tools related to performance.\n - **Type:** boolean\n - **Default:** `true`\n\n- **`--categoryNetwork`/ `--category-network`**\n Set to false to exclude tools related to network.\n - **Type:** boolean\n - **Default:** `true`\n\n- **`--performanceCrux`/ `--performance-crux`**\n Set to false to disable sending URLs from performance traces to CrUX API to get field performance data.\n - **Type:** boolean\n - **Default:** `true`\n\n- **`--usageStatistics`/ `--usage-statistics`**\n Set to false to opt-out of usage statistics collection. Google collects usage data to improve the tool, handled under the Google Privacy Policy (https://policies.google.com/privacy). This is independent from Chrome browser metrics. Disabled if CHROME_DEVTOOLS_MCP_NO_USAGE_STATISTICS or CI env variables are set.\n - **Type:** boolean\n - **Default:** `true`\n\n- **`--slim`**\n Exposes a \"slim\" set of 3 tools covering navigation, script execution and screenshots only. Useful for basic browser tasks.\n - **Type:** boolean\n\n\n\nPass them via the `args` property in the JSON configuration. For example:\n\n```json\n{\n \"mcpServers\": {\n \"chrome-devtools\": {\n \"command\": \"npx\",\n \"args\": [\n \"chrome-devtools-mcp@latest\",\n \"--channel=canary\",\n \"--headless=true\",\n \"--isolated=true\"\n ]\n }\n }\n}\n```\n\n### Connecting via WebSocket with custom headers\n\nYou can connect directly to a Chrome WebSocket endpoint and include custom headers (e.g., for authentication):\n\n```json\n{\n \"mcpServers\": {\n \"chrome-devtools\": {\n \"command\": \"npx\",\n \"args\": [\n \"chrome-devtools-mcp@latest\",\n \"--wsEndpoint=ws://127.0.0.1:9222/devtools/browser/\",\n \"--wsHeaders={\\\"Authorization\\\":\\\"Bearer YOUR_TOKEN\\\"}\"\n ]\n }\n }\n}\n```\n\nTo get the WebSocket endpoint from a running Chrome instance, visit `http://127.0.0.1:9222/json/version` and look for the `webSocketDebuggerUrl` field.\n\nYou can also run `npx chrome-devtools-mcp@latest --help` to see all available configuration options.\n\n## Concepts\n\n### User data directory\n\n`chrome-devtools-mcp` starts a Chrome's stable channel instance using the following user\ndata directory:\n\n- Linux / macOS: `$HOME/.cache/chrome-devtools-mcp/chrome-profile-$CHANNEL`\n- Windows: `%HOMEPATH%/.cache/chrome-devtools-mcp/chrome-profile-$CHANNEL`\n\nThe user data directory is not cleared between runs and shared across\nall instances of `chrome-devtools-mcp`. Set the `isolated` option to `true`\nto use a temporary user data dir instead which will be cleared automatically after\nthe browser is closed.\n\n### Connecting to a running Chrome instance\n\nBy default, the Chrome DevTools MCP server will start a new Chrome instance with a dedicated profile. This might not be ideal in all situations:\n\n- If you would like to maintain the same application state when alternating between manual site testing and agent-driven testing.\n- When the MCP needs to sign into a website. Some accounts may prevent sign-in when the browser is controlled via WebDriver (the default launch mechanism for the Chrome DevTools MCP server).\n- If you're running your LLM inside a sandboxed environment, but you would like to connect to a Chrome instance that runs outside the sandbox.\n\nIn these cases, start Chrome first and let the Chrome DevTools MCP server connect to it. There are two ways to do so:\n\n- **Automatic connection (available in Chrome 144)**: best for sharing state between manual and agent-driven testing.\n- **Manual connection via remote debugging port**: best when running inside a sandboxed environment.\n\n#### Automatically connecting to a running Chrome instance\n\n**Step 1:** Set up remote debugging in Chrome\n\nIn Chrome (\\>= M144), do the following to set up remote debugging:\n\n1. Navigate to `chrome://inspect/#remote-debugging` to enable remote debugging.\n2. Follow the dialog UI to allow or disallow incoming debugging connections.\n\n**Step 2:** Configure Chrome DevTools MCP server to automatically connect to a running Chrome Instance\n\nTo connect the `chrome-devtools-mcp` server to the running Chrome instance, use\n`--autoConnect` command line argument for the MCP server.\n\nThe following code snippet is an example configuration for gemini-cli:\n\n```json\n{\n \"mcpServers\": {\n \"chrome-devtools\": {\n \"command\": \"npx\",\n \"args\": [\"chrome-devtools-mcp@latest\", \"--autoConnect\"]\n }\n }\n}\n```\n\n**Step 3:** Test your setup\n\nMake sure your browser is running. Open gemini-cli and run the following prompt:\n\n```none\nCheck the performance of https://developers.chrome.com\n```\n\n> [!NOTE] \n> The autoConnect option requires the user to start Chrome. If the user has multiple active profiles, the MCP server will connect to the default profile (as determined by Chrome). The MCP server has access to all open windows for the selected profile.\n\nThe Chrome DevTools MCP server will try to connect to your running Chrome\ninstance. It shows a dialog asking for user permission.\n\nClicking **Allow** results in the Chrome DevTools MCP server opening\n[developers.chrome.com](http://developers.chrome.com) and taking a performance\ntrace.\n\n#### Manual connection using port forwarding\n\nYou can connect to a running Chrome instance by using the `--browser-url` option. This is useful if you are running the MCP server in a sandboxed environment that does not allow starting a new Chrome instance.\n\nHere is a step-by-step guide on how to connect to a running Chrome instance:\n\n**Step 1: Configure the MCP client**\n\nAdd the `--browser-url` option to your MCP client configuration. The value of this option should be the URL of the running Chrome instance. `http://127.0.0.1:9222` is a common default.\n\n```json\n{\n \"mcpServers\": {\n \"chrome-devtools\": {\n \"command\": \"npx\",\n \"args\": [\n \"chrome-devtools-mcp@latest\",\n \"--browser-url=http://127.0.0.1:9222\"\n ]\n }\n }\n}\n```\n\n**Step 2: Start the Chrome browser**\n\n> [!WARNING] \n> Enabling the remote debugging port opens up a debugging port on the running browser instance. Any application on your machine can connect to this port and control the browser. Make sure that you are not browsing any sensitive websites while the debugging port is open.\n\nStart the Chrome browser with the remote debugging port enabled. Make sure to close any running Chrome instances before starting a new one with the debugging port enabled. The port number you choose must be the same as the one you specified in the `--browser-url` option in your MCP client configuration.\n\nFor security reasons, [Chrome requires you to use a non-default user data directory](https://developer.chrome.com/blog/remote-debugging-port) when enabling the remote debugging port. You can specify a custom directory using the `--user-data-dir` flag. This ensures that your regular browsing profile and data are not exposed to the debugging session.\n\n**macOS**\n\n```bash\n/Applications/Google\\ Chrome.app/Contents/MacOS/Google\\ Chrome --remote-debugging-port=9222 --user-data-dir=/tmp/chrome-profile-stable\n```\n\n**Linux**\n\n```bash\n/usr/bin/google-chrome --remote-debugging-port=9222 --user-data-dir=/tmp/chrome-profile-stable\n```\n\n**Windows**\n\n```bash\n\"C:\\Program Files\\Google\\Chrome\\Application\\chrome.exe\" --remote-debugging-port=9222 --user-data-dir=\"%TEMP%\\chrome-profile-stable\"\n```\n\n**Step 3: Test your setup**\n\nAfter configuring the MCP client and starting the Chrome browser, you can test your setup by running a simple prompt in your MCP client:\n\n```\nCheck the performance of https://developers.chrome.com\n```\n\nYour MCP client should connect to the running Chrome instance and receive a performance report.\n\nIf you hit VM-to-host port forwarding issues, see the “Remote debugging between virtual machine (VM) and host fails” section in [`docs/troubleshooting.md`](./docs/troubleshooting.md#remote-debugging-between-virtual-machine-vm-and-host-fails).\n\nFor more details on remote debugging, see the [Chrome DevTools documentation](https://developer.chrome.com/docs/devtools/remote-debugging/).\n\n### Debugging Chrome on Android\n\nPlease consult [these instructions](./docs/debugging-android.md).\n\n## Known limitations\n\nSee [Troubleshooting](./docs/troubleshooting.md).\n" }, { "path": "SECURITY.md", "content": "## Security policy\n\nThe Chrome DevTools MCP project takes security very seriously. Please use [Chromium’s process to report security issues](https://www.chromium.org/Home/chromium-security/reporting-security-bugs/).\n" }, { "path": "docs/cli.md", "content": "# Chrome DevTools CLI\n\nThe `chrome-devtools-mcp` package includes an **experimental** CLI interface that allows you to interact with the browser directly from your terminal. This is particularly useful for debugging or when you want an agent to generate scripts that automate browser actions.\n\n## Getting started\n\nInstall the package globally to make the `chrome-devtools` command available:\n\n```sh\nnpm i chrome-devtools-mcp@latest -g\nchrome-devtools status # check if install worked.\n```\n\n## How it works\n\nThe CLI acts as a client to a background `chrome-devtools-mcp` daemon (uses Unix sockets on Linux/Mac and named pipes on Windows).\n\n- **Automatic Start**: The first time you call a tool (e.g., `list_pages`), the CLI automatically starts the MCP server and the browser in the background if they aren't already running.\n- **Persistence**: The same background instance is reused for subsequent commands, preserving the browser state (open pages, cookies, etc.).\n- **Manual Control**: You can explicitly manage the background process using `start`, `stop`, and `status`. The `start` command forwards all subsequent arguments to the underlying MCP server (e.g., `--headless`, `--userDataDir`) but not all args are supported. Run `chrome-devtools start --help` for supported args. Headless and isolated are enabled by default.\n\n```sh\n# Check if the daemon is running\nchrome-devtools status\n\n# Navigate the current page to a URL\nchrome-devtools navigate_page \"https://google.com\"\n\n# Take a screenshot and save it to a file\nchrome-devtools take_screenshot --filePath screenshot.png\n\n# Stop the background daemon when finished\nchrome-devtools stop\n```\n\n## Command Usage\n\nThe CLI supports all tools available in the [Tool reference](./tool-reference.md).\n\n```sh\nchrome-devtools [arguments] [flags]\n```\n\n- **Required Arguments**: Passed as positional arguments.\n- **Optional Arguments**: Passed as flags (e.g., `--filePath`, `--fullPage`).\n\n### Examples\n\n**New Page and Navigation:**\n\n```sh\nchrome-devtools new_page \"https://example.com\"\nchrome-devtools navigate_page \"https://web.dev\" --type url\n```\n\n**Interaction:**\n\n```sh\n# Click an element by its UID from a snapshot\nchrome-devtools click \"element-uid-123\"\n\n# Fill a form field\nchrome-devtools fill \"input-uid-456\" \"search query\"\n```\n\n**Analysis:**\n\n```sh\n# Run a Lighthouse audit (defaults to navigation mode)\nchrome-devtools lighthouse_audit --mode snapshot\n```\n\n## Output format\n\nBy default, the CLI outputs a human-readable summary of the tool's result. For programmatic use, you can request raw JSON:\n\n```sh\nchrome-devtools list_pages --output-format=json\n```\n\n## Troubleshooting\n\nIf the CLI hangs or fails to connect, try stopping the background process:\n\n```sh\nchrome-devtools stop\n```\n\nFor more verbose logs, set the `DEBUG` environment variable:\n\n```sh\nDEBUG=* chrome-devtools list_pages\n```\n\n## CLI generation\n\nImplemented in `scripts/generate-cli.ts`. Some commands are excluded from CLI\ngeneration such as `wait_for` and `fill_form`.\n\n`chrome-devtools-mcp` args are also filtered in `src/bin/chrome-devtools.ts`\nbecause not all args make sense in a CLI interface.\n" }, { "path": "docs/debugging-android.md", "content": "# Experimental: Debugging Chrome on Android\n\nThis is an experimental feature as Puppeteer does not officially support Chrome on Android as a target.\n\nThe workflow below works for most users. See [Troubleshooting: DevTools is not detecting the Android device for more help](https://developer.chrome.com/docs/devtools/remote-debugging#troubleshooting) for more help.\n\n1. Open the Developer Options screen on your Android. See [Configure on-device developer Options](https://developer.android.com/studio/debug/dev-options.html).\n2. Select Enable USB Debugging.\n3. Connect your Android device directly to your development machine using a USB cable.\n4. On your development machine setup port forwarding from your development machine to your android device:\n ```shell\n adb forward tcp:9222 localabstract:chrome_devtools_remote\n ```\n5. Configure your MCP server to connect to the Chrome\n ```json\n \"chrome-devtools\": {\n \"command\": \"npx\",\n \"args\": [\n \"chrome-devtools-mcp@latest\",\n \"--wsEndpoint=ws://127.0.0.1:9222/devtools/browser/\"\n ],\n \"trust\": true\n }\n ```\n6. Test your setup by running the following prompt in your coding agent:\n ```none\n Check the performance of developers.chrome.com\n ```\n\nThe Chrome DevTools MCP server should now control Chrome on your Android device.\n" }, { "path": "docs/design-principles.md", "content": "# Design Principles\n\nThese are rough guidelines to follow when shipping features for the MCP server.\nApply them with nuance.\n\n- **Agent-Agnostic API**: Use standards like MCP. Don't lock in to one LLM. Interoperability is key.\n- **Token-Optimized**: Return semantic summaries. \"LCP was 3.2s\" is better than 50k lines of JSON. Files are the right location for large amounts of data.\n- **Small, Deterministic Blocks**: Give agents composable tools (Click, Screenshot), not magic buttons.\n- **Self-Healing Errors**: Return actionable errors that include context and potential fixes.\n- **Human-Agent Collaboration**: Output must be readable by machines (structured) AND humans (summaries).\n- **Progressive Complexity**: Tools should be simple by default (high-level actions) but offer advanced optional arguments for power users.\n- **Reference over Value**: for heavy assets (screenshots, traces, videos), return a file path or resource URI, never the raw data stream. Some MCP clients support a built-in handling of heavy assets e.g. directly displaying images. This _could_ be an exception.\n" }, { "path": "docs/slim-tool-reference.md", "content": "\n\n# Chrome DevTools MCP Slim Tool Reference (~359 cl100k_base tokens)\n\n- **[Navigation automation](#navigation-automation)** (1 tools)\n - [`navigate`](#navigate)\n- **[Debugging](#debugging)** (2 tools)\n - [`evaluate`](#evaluate)\n - [`screenshot`](#screenshot)\n\n## Navigation automation\n\n### `navigate`\n\n**Description:** Loads a URL\n\n**Parameters:**\n\n- **url** (string) **(required)**: URL to [`navigate`](#navigate) to\n\n---\n\n## Debugging\n\n### `evaluate`\n\n**Description:** Evaluates a JavaScript script\n\n**Parameters:**\n\n- **script** (string) **(required)**: JS script to run on the page\n\n---\n\n### `screenshot`\n\n**Description:** Takes a [`screenshot`](#screenshot)\n\n**Parameters:** None\n\n---\n" }, { "path": "docs/tool-reference.md", "content": "\n\n# Chrome DevTools MCP Tool Reference (~6940 cl100k_base tokens)\n\n- **[Input automation](#input-automation)** (9 tools)\n - [`click`](#click)\n - [`drag`](#drag)\n - [`fill`](#fill)\n - [`fill_form`](#fill_form)\n - [`handle_dialog`](#handle_dialog)\n - [`hover`](#hover)\n - [`press_key`](#press_key)\n - [`type_text`](#type_text)\n - [`upload_file`](#upload_file)\n- **[Navigation automation](#navigation-automation)** (6 tools)\n - [`close_page`](#close_page)\n - [`list_pages`](#list_pages)\n - [`navigate_page`](#navigate_page)\n - [`new_page`](#new_page)\n - [`select_page`](#select_page)\n - [`wait_for`](#wait_for)\n- **[Emulation](#emulation)** (2 tools)\n - [`emulate`](#emulate)\n - [`resize_page`](#resize_page)\n- **[Performance](#performance)** (4 tools)\n - [`performance_analyze_insight`](#performance_analyze_insight)\n - [`performance_start_trace`](#performance_start_trace)\n - [`performance_stop_trace`](#performance_stop_trace)\n - [`take_memory_snapshot`](#take_memory_snapshot)\n- **[Network](#network)** (2 tools)\n - [`get_network_request`](#get_network_request)\n - [`list_network_requests`](#list_network_requests)\n- **[Debugging](#debugging)** (6 tools)\n - [`evaluate_script`](#evaluate_script)\n - [`get_console_message`](#get_console_message)\n - [`lighthouse_audit`](#lighthouse_audit)\n - [`list_console_messages`](#list_console_messages)\n - [`take_screenshot`](#take_screenshot)\n - [`take_snapshot`](#take_snapshot)\n\n## Input automation\n\n### `click`\n\n**Description:** Clicks on the provided element\n\n**Parameters:**\n\n- **uid** (string) **(required)**: The uid of an element on the page from the page content snapshot\n- **dblClick** (boolean) _(optional)_: Set to true for double clicks. Default is false.\n- **includeSnapshot** (boolean) _(optional)_: Whether to include a snapshot in the response. Default is false.\n\n---\n\n### `drag`\n\n**Description:** [`Drag`](#drag) an element onto another element\n\n**Parameters:**\n\n- **from_uid** (string) **(required)**: The uid of the element to [`drag`](#drag)\n- **to_uid** (string) **(required)**: The uid of the element to drop into\n- **includeSnapshot** (boolean) _(optional)_: Whether to include a snapshot in the response. Default is false.\n\n---\n\n### `fill`\n\n**Description:** Type text into a input, text area or select an option from a <select> element.\n\n**Parameters:**\n\n- **uid** (string) **(required)**: The uid of an element on the page from the page content snapshot\n- **value** (string) **(required)**: The value to [`fill`](#fill) in\n- **includeSnapshot** (boolean) _(optional)_: Whether to include a snapshot in the response. Default is false.\n\n---\n\n### `fill_form`\n\n**Description:** [`Fill`](#fill) out multiple form elements at once\n\n**Parameters:**\n\n- **elements** (array) **(required)**: Elements from snapshot to [`fill`](#fill) out.\n- **includeSnapshot** (boolean) _(optional)_: Whether to include a snapshot in the response. Default is false.\n\n---\n\n### `handle_dialog`\n\n**Description:** If a browser dialog was opened, use this command to handle it\n\n**Parameters:**\n\n- **action** (enum: \"accept\", \"dismiss\") **(required)**: Whether to dismiss or accept the dialog\n- **promptText** (string) _(optional)_: Optional prompt text to enter into the dialog.\n\n---\n\n### `hover`\n\n**Description:** [`Hover`](#hover) over the provided element\n\n**Parameters:**\n\n- **uid** (string) **(required)**: The uid of an element on the page from the page content snapshot\n- **includeSnapshot** (boolean) _(optional)_: Whether to include a snapshot in the response. Default is false.\n\n---\n\n### `press_key`\n\n**Description:** Press a key or key combination. Use this when other input methods like [`fill`](#fill)() cannot be used (e.g., keyboard shortcuts, navigation keys, or special key combinations).\n\n**Parameters:**\n\n- **key** (string) **(required)**: A key or a combination (e.g., \"Enter\", \"Control+A\", \"Control++\", \"Control+Shift+R\"). Modifiers: Control, Shift, Alt, Meta\n- **includeSnapshot** (boolean) _(optional)_: Whether to include a snapshot in the response. Default is false.\n\n---\n\n### `type_text`\n\n**Description:** Type text using keyboard into a previously focused input\n\n**Parameters:**\n\n- **text** (string) **(required)**: The text to type\n- **submitKey** (string) _(optional)_: Optional key to press after typing. E.g., \"Enter\", \"Tab\", \"Escape\"\n\n---\n\n### `upload_file`\n\n**Description:** Upload a file through a provided element.\n\n**Parameters:**\n\n- **filePath** (string) **(required)**: The local path of the file to upload\n- **uid** (string) **(required)**: The uid of the file input element or an element that will open file chooser on the page from the page content snapshot\n- **includeSnapshot** (boolean) _(optional)_: Whether to include a snapshot in the response. Default is false.\n\n---\n\n## Navigation automation\n\n### `close_page`\n\n**Description:** Closes the page by its index. The last open page cannot be closed.\n\n**Parameters:**\n\n- **pageId** (number) **(required)**: The ID of the page to close. Call [`list_pages`](#list_pages) to list pages.\n\n---\n\n### `list_pages`\n\n**Description:** Get a list of pages open in the browser.\n\n**Parameters:** None\n\n---\n\n### `navigate_page`\n\n**Description:** Go to a URL, or back, forward, or reload. Use project URL if not specified otherwise.\n\n**Parameters:**\n\n- **handleBeforeUnload** (enum: \"accept\", \"decline\") _(optional)_: Whether to auto accept or beforeunload dialogs triggered by this navigation. Default is accept.\n- **ignoreCache** (boolean) _(optional)_: Whether to ignore cache on reload.\n- **initScript** (string) _(optional)_: A JavaScript script to be executed on each new document before any other scripts for the next navigation.\n- **timeout** (integer) _(optional)_: Maximum wait time in milliseconds. If set to 0, the default timeout will be used.\n- **type** (enum: \"url\", \"back\", \"forward\", \"reload\") _(optional)_: Navigate the page by URL, back or forward in history, or reload.\n- **url** (string) _(optional)_: Target URL (only type=url)\n\n---\n\n### `new_page`\n\n**Description:** Open a new tab and load a URL. Use project URL if not specified otherwise.\n\n**Parameters:**\n\n- **url** (string) **(required)**: URL to load in a new page.\n- **background** (boolean) _(optional)_: Whether to open the page in the background without bringing it to the front. Default is false (foreground).\n- **isolatedContext** (string) _(optional)_: If specified, the page is created in an isolated browser context with the given name. Pages in the same browser context share cookies and storage. Pages in different browser contexts are fully isolated.\n- **timeout** (integer) _(optional)_: Maximum wait time in milliseconds. If set to 0, the default timeout will be used.\n\n---\n\n### `select_page`\n\n**Description:** Select a page as a context for future tool calls.\n\n**Parameters:**\n\n- **pageId** (number) **(required)**: The ID of the page to select. Call [`list_pages`](#list_pages) to get available pages.\n- **bringToFront** (boolean) _(optional)_: Whether to focus the page and bring it to the top.\n\n---\n\n### `wait_for`\n\n**Description:** Wait for the specified text to appear on the selected page.\n\n**Parameters:**\n\n- **text** (array) **(required)**: Non-empty list of texts. Resolves when any value appears on the page.\n- **timeout** (integer) _(optional)_: Maximum wait time in milliseconds. If set to 0, the default timeout will be used.\n\n---\n\n## Emulation\n\n### `emulate`\n\n**Description:** Emulates various features on the selected page.\n\n**Parameters:**\n\n- **colorScheme** (enum: \"dark\", \"light\", \"auto\") _(optional)_: [`Emulate`](#emulate) the dark or the light mode. Set to \"auto\" to reset to the default.\n- **cpuThrottlingRate** (number) _(optional)_: Represents the CPU slowdown factor. Omit or set the rate to 1 to disable throttling\n- **geolocation** (string) _(optional)_: Geolocation (`<latitude>x<longitude>`) to [`emulate`](#emulate). Latitude between -90 and 90. Longitude between -180 and 180. Omit clear the geolocation override.\n- **networkConditions** (enum: \"Offline\", \"Slow 3G\", \"Fast 3G\", \"Slow 4G\", \"Fast 4G\") _(optional)_: Throttle network. Omit to disable throttling.\n- **userAgent** (string) _(optional)_: User agent to [`emulate`](#emulate). Set to empty string to clear the user agent override.\n- **viewport** (string) _(optional)_: [`Emulate`](#emulate) device viewports '<width>x<height>x<devicePixelRatio>[,mobile][,touch][,landscape]'. 'touch' and 'mobile' to [`emulate`](#emulate) mobile devices. 'landscape' to [`emulate`](#emulate) landscape mode.\n\n---\n\n### `resize_page`\n\n**Description:** Resizes the selected page's window so that the page has specified dimension\n\n**Parameters:**\n\n- **height** (number) **(required)**: Page height\n- **width** (number) **(required)**: Page width\n\n---\n\n## Performance\n\n### `performance_analyze_insight`\n\n**Description:** Provides more detailed information on a specific Performance Insight of an insight set that was highlighted in the results of a trace recording.\n\n**Parameters:**\n\n- **insightName** (string) **(required)**: The name of the Insight you want more information on. For example: \"DocumentLatency\" or \"LCPBreakdown\"\n- **insightSetId** (string) **(required)**: The id for the specific insight set. Only use the ids given in the \"Available insight sets\" list.\n\n---\n\n### `performance_start_trace`\n\n**Description:** Start a performance trace on the selected webpage. Use to find frontend performance issues, Core Web Vitals (LCP, INP, CLS), and improve page load speed.\n\n**Parameters:**\n\n- **autoStop** (boolean) _(optional)_: Determines if the trace recording should be automatically stopped.\n- **filePath** (string) _(optional)_: The absolute file path, or a file path relative to the current working directory, to save the raw trace data. For example, trace.json.gz (compressed) or trace.json (uncompressed).\n- **reload** (boolean) _(optional)_: Determines if, once tracing has started, the current selected page should be automatically reloaded. Navigate the page to the right URL using the [`navigate_page`](#navigate_page) tool BEFORE starting the trace if reload or autoStop is set to true.\n\n---\n\n### `performance_stop_trace`\n\n**Description:** Stop the active performance trace recording on the selected webpage.\n\n**Parameters:**\n\n- **filePath** (string) _(optional)_: The absolute file path, or a file path relative to the current working directory, to save the raw trace data. For example, trace.json.gz (compressed) or trace.json (uncompressed).\n\n---\n\n### `take_memory_snapshot`\n\n**Description:** Capture a memory heapsnapshot of the currently selected page to memory leak debugging\n\n**Parameters:**\n\n- **filePath** (string) **(required)**: A path to a .heapsnapshot file to save the heapsnapshot to.\n\n---\n\n## Network\n\n### `get_network_request`\n\n**Description:** Gets a network request by an optional reqid, if omitted returns the currently selected request in the DevTools Network panel.\n\n**Parameters:**\n\n- **reqid** (number) _(optional)_: The reqid of the network request. If omitted returns the currently selected request in the DevTools Network panel.\n- **requestFilePath** (string) _(optional)_: The absolute or relative path to save the request body to. If omitted, the body is returned inline.\n- **responseFilePath** (string) _(optional)_: The absolute or relative path to save the response body to. If omitted, the body is returned inline.\n\n---\n\n### `list_network_requests`\n\n**Description:** List all requests for the currently selected page since the last navigation.\n\n**Parameters:**\n\n- **includePreservedRequests** (boolean) _(optional)_: Set to true to return the preserved requests over the last 3 navigations.\n- **pageIdx** (integer) _(optional)_: Page number to return (0-based). When omitted, returns the first page.\n- **pageSize** (integer) _(optional)_: Maximum number of requests to return. When omitted, returns all requests.\n- **resourceTypes** (array) _(optional)_: Filter requests to only return requests of the specified resource types. When omitted or empty, returns all requests.\n\n---\n\n## Debugging\n\n### `evaluate_script`\n\n**Description:** Evaluate a JavaScript function inside the currently selected page. Returns the response as JSON,\nso returned values have to be JSON-serializable.\n\n**Parameters:**\n\n- **function** (string) **(required)**: A JavaScript function declaration to be executed by the tool in the currently selected page.\n Example without arguments: `() => {\n return document.title\n}` or `async () => {\n return await fetch(\"example.com\")\n}`.\n Example with arguments: `(el) => {\n return el.innerText;\n}`\n\n- **args** (array) _(optional)_: An optional list of arguments to pass to the function.\n\n---\n\n### `get_console_message`\n\n**Description:** Gets a console message by its ID. You can get all messages by calling [`list_console_messages`](#list_console_messages).\n\n**Parameters:**\n\n- **msgid** (number) **(required)**: The msgid of a console message on the page from the listed console messages\n\n---\n\n### `lighthouse_audit`\n\n**Description:** Get Lighthouse score and reports for accessibility, SEO and best practices. This excludes performance. For performance audits, run [`performance_start_trace`](#performance_start_trace)\n\n**Parameters:**\n\n- **device** (enum: \"desktop\", \"mobile\") _(optional)_: Device to [`emulate`](#emulate).\n- **mode** (enum: \"navigation\", \"snapshot\") _(optional)_: \"navigation\" reloads & audits. \"snapshot\" analyzes current state.\n- **outputDirPath** (string) _(optional)_: Directory for reports. If omitted, uses temporary files.\n\n---\n\n### `list_console_messages`\n\n**Description:** List all console messages for the currently selected page since the last navigation.\n\n**Parameters:**\n\n- **includePreservedMessages** (boolean) _(optional)_: Set to true to return the preserved messages over the last 3 navigations.\n- **pageIdx** (integer) _(optional)_: Page number to return (0-based). When omitted, returns the first page.\n- **pageSize** (integer) _(optional)_: Maximum number of messages to return. When omitted, returns all requests.\n- **types** (array) _(optional)_: Filter messages to only return messages of the specified resource types. When omitted or empty, returns all messages.\n\n---\n\n### `take_screenshot`\n\n**Description:** Take a screenshot of the page or element.\n\n**Parameters:**\n\n- **filePath** (string) _(optional)_: The absolute path, or a path relative to the current working directory, to save the screenshot to instead of attaching it to the response.\n- **format** (enum: \"png\", \"jpeg\", \"webp\") _(optional)_: Type of format to save the screenshot as. Default is \"png\"\n- **fullPage** (boolean) _(optional)_: If set to true takes a screenshot of the full page instead of the currently visible viewport. Incompatible with uid.\n- **quality** (number) _(optional)_: Compression quality for JPEG and WebP formats (0-100). Higher values mean better quality but larger file sizes. Ignored for PNG format.\n- **uid** (string) _(optional)_: The uid of an element on the page from the page content snapshot. If omitted takes a pages screenshot.\n\n---\n\n### `take_snapshot`\n\n**Description:** Take a text snapshot of the currently selected page based on the a11y tree. The snapshot lists page elements along with a unique\nidentifier (uid). Always use the latest snapshot. Prefer taking a snapshot over taking a screenshot. The snapshot indicates the element selected\nin the DevTools Elements panel (if any).\n\n**Parameters:**\n\n- **filePath** (string) _(optional)_: The absolute path, or a path relative to the current working directory, to save the snapshot to instead of attaching it to the response.\n- **verbose** (boolean) _(optional)_: Whether to include all possible information available in the full a11y tree. Default is false.\n\n---\n" }, { "path": "docs/troubleshooting.md", "content": "# Troubleshooting\n\n## General tips\n\n- Run `npx chrome-devtools-mcp@latest --help` to test if the MCP server runs on your machine.\n- Make sure that your MCP client uses the same npm and node version as your terminal.\n- When configuring your MCP client, try using the `--yes` argument to `npx` to\n auto-accept installation prompt.\n- Find a specific error in the output of the `chrome-devtools-mcp` server.\n Usually, if your client is an IDE, logs would be in the Output pane.\n- Search the [GitHub repository issues and discussions](https://github.com/ChromeDevTools/chrome-devtools-mcp) for help or existing similar problems.\n\n## Debugging\n\nStart the MCP server with debugging enabled and a log file:\n\n- `DEBUG=* npx chrome-devtools-mcp@latest --log-file=/path/to/chrome-devtools-mcp.log`\n\nUsing `.mcp.json` to debug while using a client:\n\n```json\n{\n \"mcpServers\": {\n \"chrome-devtools\": {\n \"type\": \"stdio\",\n \"command\": \"npx\",\n \"args\": [\n \"chrome-devtools-mcp@latest\",\n \"--log-file\",\n \"/path/to/chrome-devtools-mcp.log\"\n ],\n \"env\": {\n \"DEBUG\": \"*\"\n }\n }\n }\n}\n```\n\n## Specific problems\n\n### `Error [ERR_MODULE_NOT_FOUND]: Cannot find module ...`\n\nThis usually indicates either a non-supported Node version is in use or that the\n`npm`/`npx` cache is corrupted. Try clearing the cache, uninstalling\n`chrome-devtools-mcp` and installing it again. Clear the cache by running:\n\n```sh\nrm -rf ~/.npm/_npx # NOTE: this might remove other installed npx executables.\nnpm cache clean --force\n```\n\n### `Target closed` error\n\nThis indicates that the browser could not be started. Make sure that no Chrome\ninstances are running or close them. Make sure you have the latest stable Chrome\ninstalled and that [your system is able to run Chrome](https://support.google.com/chrome/a/answer/7100626?hl=en).\n\n### Chrome crashes on macOS when using Web Bluetooth\n\nOn macOS, Chrome launched by an MCP client application (such as Claude Desktop) may crash when a Web Bluetooth prompt appears. This is caused by a macOS privacy permission violation (TCC).\n\nTo resolve this, grant Bluetooth permission to the MCP client application in `System Settings > Privacy & Security > Bluetooth`. After granting permission, restart the client application and start a new MCP session.\n\n### Remote debugging between virtual machine (VM) and host fails\n\nWhen attempting to connect to Chrome running on a host machine from within a virtual machine (VM), Chrome may reject the connection due to 'Host' header validation. You can bypass this restriction by creating an SSH tunnel from the VM to the host. In the VM, run:\n\n```sh\nssh -N -L 127.0.0.1:9222:127.0.0.1:9222 @\n```\n\nPoint the MCP connection inside the VM to `http://127.0.0.1:9222`. This allows DevTools to reach the host browser without triggering the Host validation error.\n\n### Operating system sandboxes\n\nSome MCP clients allow sandboxing the MCP server using macOS Seatbelt or Linux\ncontainers. If sandboxes are enabled, `chrome-devtools-mcp` is not able to start\nChrome that requires permissions to create its own sandboxes. As a workaround,\neither disable sandboxing for `chrome-devtools-mcp` in your MCP client or use\n`--browser-url` to connect to a Chrome instance that you start manually outside\nof the MCP client sandbox.\n\n### WSL\n\nBy default, `chrome-devtools-mcp` in WSL requires Chrome to be installed within the Linux environment. While it normally attempts to launch Chrome on the Windows side, this currently fails due to a [known WSL issue](https://github.com/microsoft/WSL/issues/14201). Ensure you are using a [Linux distribution compatible with Chrome](https://support.google.com/chrome/a/answer/7100626).\n\nPossible workarounds include:\n\n- **Install Google Chrome in WSL:**\n - `wget https://dl.google.com/linux/direct/google-chrome-stable_current_amd64.deb`\n - `sudo dpkg -i google-chrome-stable_current_amd64.deb`\n\n- **Use Mirrored networking:**\n 1. Configure [Mirrored networking for WSL](https://learn.microsoft.com/en-us/windows/wsl/networking).\n 2. Start Chrome on the Windows side with:\n `chrome.exe --remote-debugging-port=9222 --user-data-dir=C:\\path\\to\\dir`\n 3. Start `chrome-devtools-mcp` with:\n `npx chrome-devtools-mcp --browser-url http://127.0.0.1:9222`\n\n- **Use Powershell or Git Bash** instead of WSL.\n\n### Windows 10: Error during discovery for MCP server 'chrome-devtools': MCP error -32000: Connection closed\n\n- **Solution 1** Call using `cmd` (For more info https://github.com/modelcontextprotocol/servers/issues/1082#issuecomment-2791786310)\n\n ```json\n \"mcpServers\": {\n \"chrome-devtools\": {\n \"command\": \"cmd\",\n \"args\": [\"/c\", \"npx\", \"-y\", \"chrome-devtools-mcp@latest\"]\n }\n }\n ```\n\n > **The Key Change:** On Windows, running a Node.js package via `npx` often requires the `cmd /c` prefix to be executed correctly from within another process like VSCode's extension host. Therefore, `\"command\": \"npx\"` was replaced with `\"command\": \"cmd\"`, and the actual `npx` command was moved into the `\"args\"` array, preceded by `\"/c\"`. This fix allows Windows to interpret the command correctly and launch the server.\n\n- **Solution 2** Instead of another layer of shell you can write the absolute path to `npx`:\n > Note: The path below is an example. You must adjust it to match the actual location of `npx` on your machine. Depending on your setup, the file extension might be `.cmd`, `.bat`, or `.exe` rather than `.ps1`. Also, ensure you use double backslashes (`\\\\`) as path delimiters, as required by the JSON format.\n ```json\n \"mcpServers\": {\n \"chrome-devtools\": {\n \"command\": \"C:\\\\nvm4w\\\\nodejs\\\\npx.ps1\",\n \"args\": [\"-y\", \"chrome-devtools-mcp@latest\"]\n }\n }\n ```\n\n### Claude Code plugin installation fails with `Failed to clone repository`\n\nWhen installing `chrome-devtools-mcp` as a Claude Code plugin (either from the\nofficial marketplace or via `/plugin marketplace add`), the installation may fail\nwith a timeout error if your environment cannot reach `github.com` on port 443\n(HTTPS):\n\n```\nFailed to download/cache plugin chrome-devtools-mcp: Failed to clone repository:\n Cloning into '...'...\n fatal: unable to access 'https://github.com/ChromeDevTools/chrome-devtools-mcp.git/':\n Failed to connect to github.com port 443\n```\n\nThis can happen in environments with restricted outbound HTTPS connectivity,\ncorporate firewalls, or proxy configurations that block HTTPS git operations.\n\n**Workaround 1: Use SSH instead of HTTPS**\n\nIf you have SSH access to GitHub configured, you can redirect all GitHub HTTPS\nURLs to use SSH by running:\n\n```sh\ngit config --global url.\"git@github.com:\".insteadOf \"https://github.com/\"\n```\n\nThen retry the plugin installation. This tells git to use your SSH key for all\nGitHub operations instead of HTTPS.\n\n**Workaround 2: Install via CLI instead**\n\nIf the plugin marketplace approach fails, you can install `chrome-devtools-mcp`\nas an MCP server directly without cloning the repository:\n\n```sh\nclaude mcp add chrome-devtools --scope user npx chrome-devtools-mcp@latest\n```\n\nThis bypasses the git clone entirely and uses npm/npx to fetch the package. Note\nthat this method installs only the MCP server without the bundled skills.\n\n### Connection timeouts with `--autoConnect`\n\nIf you are using the `--autoConnect` flag and tools like `list_pages`, `new_page`, or `navigate_page` fail with a timeout (e.g., `ProtocolError: Network.enable timed out` or `The socket connection was closed unexpectedly`), this usually means the MCP server cannot handshake with the running Chrome instance correctly. Ensure:\n\n1. Chrome 144+ is **already** running.\n2. Remote debugging is enabled in Chrome via `chrome://inspect/#remote-debugging`.\n3. You have allowed the remote debugging connection prompt in the browser.\n4. There is no other MCP server or tool trying to connect to the same debugging port.\n" }, { "path": "eslint.config.mjs", "content": "/**\n * @license\n * Copyright 2025 Google LLC\n * SPDX-License-Identifier: Apache-2.0\n */\n\nimport js from '@eslint/js';\nimport stylisticPlugin from '@stylistic/eslint-plugin';\nimport {defineConfig, globalIgnores} from 'eslint/config';\nimport importPlugin from 'eslint-plugin-import';\nimport globals from 'globals';\nimport tseslint from 'typescript-eslint';\n\nimport localPlugin from './scripts/eslint_rules/local-plugin.js';\n\nexport default defineConfig([\n globalIgnores([\n '**/node_modules',\n '**/build/',\n 'tests/tools/fixtures/',\n 'src/third_party/lighthouse-devtools-mcp-bundle.js',\n ]),\n importPlugin.flatConfigs.typescript,\n {\n languageOptions: {\n ecmaVersion: 'latest',\n sourceType: 'module',\n\n globals: {\n ...globals.node,\n },\n\n parserOptions: {\n projectService: {\n allowDefaultProject: [\n '.prettierrc.cjs',\n 'puppeteer.config.cjs',\n 'eslint.config.mjs',\n 'rollup.config.mjs',\n ],\n },\n },\n\n parser: tseslint.parser,\n },\n\n plugins: {\n js,\n '@local': localPlugin,\n '@typescript-eslint': tseslint.plugin,\n '@stylistic': stylisticPlugin,\n },\n\n settings: {\n 'import/resolver': {\n typescript: true,\n },\n },\n\n extends: ['js/recommended'],\n },\n tseslint.configs.recommended,\n tseslint.configs.stylistic,\n {\n name: 'TypeScript rules',\n rules: {\n '@local/check-license': 'error',\n curly: ['error', 'all'],\n\n 'no-undef': 'off',\n 'no-unused-vars': 'off',\n '@typescript-eslint/no-unused-vars': [\n 'error',\n {\n argsIgnorePattern: '^_',\n varsIgnorePattern: '^_',\n },\n ],\n '@typescript-eslint/no-explicit-any': [\n 'error',\n {\n ignoreRestArgs: true,\n },\n ],\n // This optimizes the dependency tracking for type-only files.\n '@typescript-eslint/consistent-type-imports': 'error',\n // So type-only exports get elided.\n '@typescript-eslint/consistent-type-exports': 'error',\n // Prefer interfaces over types for shape like.\n '@typescript-eslint/consistent-type-definitions': ['error', 'interface'],\n '@typescript-eslint/array-type': [\n 'error',\n {\n default: 'array-simple',\n },\n ],\n '@typescript-eslint/no-floating-promises': 'error',\n\n 'import/order': [\n 'error',\n {\n 'newlines-between': 'always',\n\n alphabetize: {\n order: 'asc',\n caseInsensitive: true,\n },\n },\n ],\n\n 'import/no-cycle': [\n 'error',\n {\n maxDepth: Infinity,\n },\n ],\n\n 'import/enforce-node-protocol-usage': ['error', 'always'],\n\n '@stylistic/function-call-spacing': 'error',\n '@stylistic/semi': 'error',\n\n 'no-restricted-imports': [\n 'error',\n {\n patterns: [\n {\n regex: '.*chrome-devtools-frontend/(?!mcp/mcp.js$).*',\n message:\n 'Import only the devtools-frontend code exported via node_modules/chrome-devtools-frontend/mcp/mcp.js',\n },\n ],\n },\n ],\n },\n },\n {\n name: 'Tests',\n files: ['**/*.test.ts'],\n rules: {\n // With the Node.js test runner, `describe` and `it` are technically\n // promises, but we don't need to await them.\n '@typescript-eslint/no-floating-promises': 'off',\n },\n },\n]);\n" }, { "path": "gemini-extension.json", "content": "{\n \"name\": \"chrome-devtools-mcp\",\n \"version\": \"latest\",\n \"mcpServers\": {\n \"chrome-devtools\": {\n \"command\": \"npx\",\n \"args\": [\"chrome-devtools-mcp@latest\"]\n }\n }\n}\n" }, { "path": "package.json", "content": "{\n \"name\": \"chrome-devtools-mcp\",\n \"version\": \"0.20.2\",\n \"description\": \"MCP server for Chrome DevTools\",\n \"type\": \"module\",\n \"bin\": {\n \"chrome-devtools-mcp\": \"./build/src/bin/chrome-devtools-mcp.js\",\n \"chrome-devtools\": \"./build/src/bin/chrome-devtools.js\"\n },\n \"main\": \"./build/src/index.js\",\n \"scripts\": {\n \"cli:generate\": \"node --experimental-strip-types scripts/generate-cli.ts\",\n \"clean\": \"node -e \\\"require('fs').rmSync('build', {recursive: true, force: true})\\\"\",\n \"bundle\": \"npm run clean && npm run build && rollup -c rollup.config.mjs && node -e \\\"require('fs').rmSync('build/node_modules', {recursive: true, force: true})\\\" && node --experimental-strip-types scripts/append-lighthouse-notices.ts\",\n \"build\": \"tsc && node --experimental-strip-types --no-warnings=ExperimentalWarning scripts/post-build.ts\",\n \"typecheck\": \"tsc --noEmit\",\n \"format\": \"eslint --cache --fix . && prettier --write --cache .\",\n \"check-format\": \"eslint --cache . && prettier --check --cache .;\",\n \"gen\": \"npm run build && npm run docs:generate && npm run cli:generate && npm run format\",\n \"docs:generate\": \"node --experimental-strip-types scripts/generate-docs.ts\",\n \"start\": \"npm run build && node build/src/index.js\",\n \"start-debug\": \"DEBUG=mcp:* DEBUG_COLORS=false npm run build && node build/src/index.js\",\n \"test\": \"npm run build && node scripts/test.mjs\",\n \"test:no-build\": \"node scripts/test.mjs\",\n \"test:only\": \"npm run build && node scripts/test.mjs --test-only\",\n \"test:update-snapshots\": \"npm run build && node scripts/test.mjs --test-update-snapshots\",\n \"prepare\": \"node --experimental-strip-types scripts/prepare.ts\",\n \"verify-server-json-version\": \"node --experimental-strip-types scripts/verify-server-json-version.ts\",\n \"update-lighthouse\": \"node --experimental-strip-types scripts/update-lighthouse.ts\",\n \"verify-npm-package\": \"node scripts/verify-npm-package.mjs\",\n \"eval\": \"npm run build && node --experimental-strip-types scripts/eval_gemini.ts\",\n \"count-tokens\": \"node --experimental-strip-types scripts/count_tokens.ts\"\n },\n \"files\": [\n \"build/src\",\n \"LICENSE\",\n \"!*.tsbuildinfo\"\n ],\n \"repository\": \"ChromeDevTools/chrome-devtools-mcp\",\n \"author\": \"Google LLC\",\n \"license\": \"Apache-2.0\",\n \"bugs\": {\n \"url\": \"https://github.com/ChromeDevTools/chrome-devtools-mcp/issues\"\n },\n \"homepage\": \"https://github.com/ChromeDevTools/chrome-devtools-mcp#readme\",\n \"mcpName\": \"io.github.ChromeDevTools/chrome-devtools-mcp\",\n \"devDependencies\": {\n \"@eslint/js\": \"^9.35.0\",\n \"@google/genai\": \"^1.37.0\",\n \"@modelcontextprotocol/sdk\": \"1.27.1\",\n \"@rollup/plugin-commonjs\": \"^29.0.0\",\n \"@rollup/plugin-json\": \"^6.1.0\",\n \"@rollup/plugin-node-resolve\": \"^16.0.3\",\n \"@stylistic/eslint-plugin\": \"^5.4.0\",\n \"@types/debug\": \"^4.1.12\",\n \"@types/filesystem\": \"^0.0.36\",\n \"@types/node\": \"^25.0.0\",\n \"@types/sinon\": \"^21.0.0\",\n \"@types/yargs\": \"^17.0.33\",\n \"@typescript-eslint/eslint-plugin\": \"^8.43.0\",\n \"@typescript-eslint/parser\": \"^8.43.0\",\n \"chrome-devtools-frontend\": \"1.0.1599001\",\n \"core-js\": \"3.48.0\",\n \"debug\": \"4.4.3\",\n \"eslint\": \"^9.35.0\",\n \"eslint-import-resolver-typescript\": \"^4.4.4\",\n \"eslint-plugin-import\": \"^2.32.0\",\n \"globals\": \"^17.0.0\",\n \"lighthouse\": \"13.0.3\",\n \"prettier\": \"^3.6.2\",\n \"puppeteer\": \"24.39.1\",\n \"rollup\": \"4.59.0\",\n \"rollup-plugin-cleanup\": \"^3.2.1\",\n \"rollup-plugin-license\": \"^3.6.0\",\n \"sinon\": \"^21.0.0\",\n \"tiktoken\": \"^1.0.22\",\n \"typescript\": \"^5.9.2\",\n \"typescript-eslint\": \"^8.43.0\",\n \"yargs\": \"18.0.0\"\n },\n \"engines\": {\n \"node\": \"^20.19.0 || ^22.12.0 || >=23\"\n }\n}\n" }, { "path": "puppeteer.config.cjs", "content": "/**\n * @license\n * Copyright 2025 Google Inc.\n * SPDX-License-Identifier: Apache-2.0\n */\n\n/**\n * @type {import(\"puppeteer\").Configuration}\n */\nmodule.exports = {\n chrome: {\n skipDownload: false,\n },\n ['chrome-headless-shell']: {\n skipDownload: true,\n },\n firefox: {\n skipDownload: true,\n },\n};\n" }, { "path": "release-please-config.json", "content": "{\n \"changelog-sections\": [\n {\"type\": \"feat\", \"section\": \"🎉 Features\", \"hidden\": false},\n {\"type\": \"fix\", \"section\": \"🛠️ Fixes\", \"hidden\": false},\n {\"type\": \"docs\", \"section\": \"📄 Documentation\", \"hidden\": false},\n\n {\"type\": \"perf\", \"section\": \"⚡ Performance\", \"hidden\": false},\n {\"type\": \"refactor\", \"section\": \"🏗️ Refactor\", \"hidden\": false},\n {\"type\": \"chore\", \"section\": \"♻️ Chores\", \"hidden\": true},\n {\"type\": \"test\", \"section\": \"♻️ Chores\", \"hidden\": true},\n\n {\"type\": \"build\", \"section\": \"⚙️ Automation\", \"hidden\": true},\n {\"type\": \"ci\", \"section\": \"⚙️ Automation\", \"hidden\": true}\n ],\n\n \"packages\": {\n \".\": {\n \"extra-files\": [\n {\n \"type\": \"generic\",\n \"path\": \"src/version.ts\"\n },\n {\n \"type\": \"json\",\n \"path\": \"server.json\",\n \"jsonpath\": \"version\"\n },\n {\n \"type\": \"json\",\n \"path\": \"server.json\",\n \"jsonpath\": \"packages[0].version\"\n }\n ]\n }\n }\n}\n" }, { "path": "rollup.config.mjs", "content": "/**\n * Copyright 2021 Google LLC.\n * Copyright (c) Microsoft Corporation.\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n * http://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\n\n/**\n * @fileoverview taken from {@link https://github.com/GoogleChromeLabs/chromium-bidi/blob/main/rollup.config.mjs | chromium-bidi}\n * and modified to specific requirement.\n */\n\nimport fs from 'node:fs';\nimport path from 'node:path';\n\nimport commonjs from '@rollup/plugin-commonjs';\nimport json from '@rollup/plugin-json';\nimport {nodeResolve} from '@rollup/plugin-node-resolve';\nimport cleanup from 'rollup-plugin-cleanup';\nimport license from 'rollup-plugin-license';\n\nconst isProduction = process.env.NODE_ENV === 'production';\n\nconst allowedLicenses = [\n 'MIT',\n 'Apache 2.0',\n 'Apache-2.0',\n 'BSD-3-Clause',\n 'BSD-2-Clause',\n 'ISC',\n '0BSD',\n];\n\nconst thirdPartyDir = './build/src/third_party';\n\nconst {devDependencies = {}} = JSON.parse(\n fs.readFileSync(path.join(process.cwd(), 'package.json'), 'utf-8'),\n);\n\n// special case for puppeteer, from which we only bundle puppeteer-core\ndevDependencies['puppeteer-core'] = devDependencies['puppeteer'];\n\nconst aggregatedStats = {\n bundlesProcessed: 0,\n totalBundles: 0,\n bundledPackages: new Set(),\n};\n\nconst projectNodeModulesPath =\n path.join(process.cwd(), 'node_modules') + path.sep;\n\nfunction getPackageName(modulePath) {\n // Handle rollup's virtual module paths (paths starting with 0x00)\n const absolutePathStart = modulePath.indexOf(projectNodeModulesPath);\n if (absolutePathStart < 0) {\n return null;\n }\n\n const relativePath = modulePath.slice(\n projectNodeModulesPath.length + absolutePathStart,\n );\n const segments = relativePath.split(path.sep);\n\n // handle scoped packages\n if (segments[0].startsWith('@') && segments[1]) {\n return `${segments[0]}/${segments[1]}`;\n }\n return segments[0];\n}\n\n/**\n * @returns {import('rollup').Plugin}\n */\nfunction listBundledDeps() {\n aggregatedStats.totalBundles++;\n return {\n name: 'gather-bundled-dependencies',\n generateBundle(options, bundle) {\n for (const chunk of Object.values(bundle)) {\n if (chunk.type === 'chunk' && chunk.modules) {\n // chunk.modules is an object where keys are the absolute file paths\n Object.keys(chunk.modules).forEach(modulePath => {\n const packageName = getPackageName(modulePath);\n if (packageName) {\n aggregatedStats.bundledPackages.add(packageName);\n }\n });\n }\n }\n aggregatedStats.bundlesProcessed++;\n\n // Only write the file when the last bundle is finished\n if (aggregatedStats.bundlesProcessed === aggregatedStats.totalBundles) {\n const outputPath = path.join(thirdPartyDir, 'bundled-packages.json');\n\n const bundledDevDeps = Object.fromEntries(\n Object.entries(devDependencies).filter(\n ([name]) =>\n aggregatedStats.bundledPackages.has(name) ||\n name === 'chrome-devtools-frontend' ||\n name === 'lighthouse',\n ),\n );\n\n fs.writeFileSync(outputPath, JSON.stringify(bundledDevDeps, null, 2));\n }\n },\n };\n}\n\nconst seenDependencies = new Map();\n\n/**\n * @param {string} wrapperIndexName\n * @param {import('rollup').OutputOptions} [extraOutputOptions={}]\n * @param {import('rollup').ExternalOption} [external=[]]\n * @returns {import('rollup').RollupOptions}\n */\nconst bundleDependency = (\n wrapperIndexName,\n extraOutputOptions = {},\n external = [],\n) => ({\n input: path.join(thirdPartyDir, wrapperIndexName),\n output: {\n ...extraOutputOptions,\n file: path.join(thirdPartyDir, wrapperIndexName),\n sourcemap: !isProduction,\n format: 'esm',\n },\n plugins: [\n cleanup({\n // Keep license comments. Other comments are removed due to\n // http://b/390559299 and\n // https://github.com/microsoft/TypeScript/issues/60811.\n comments: [/Copyright/i],\n }),\n license({\n thirdParty: {\n allow: {\n test: dependency => {\n return allowedLicenses.includes(dependency.license);\n },\n failOnUnlicensed: true,\n failOnViolation: true,\n },\n output: {\n file: path.join(thirdPartyDir, 'THIRD_PARTY_NOTICES'),\n template(dependencies) {\n for (const dependency of dependencies) {\n const key = `${dependency.name}:${dependency.version}`;\n seenDependencies.set(key, dependency);\n }\n\n const stringifiedDependencies = Array.from(\n seenDependencies.values(),\n ).map(dependency => {\n let arr = [];\n arr.push(`Name: ${dependency.name ?? 'N/A'}`);\n let url = dependency.homepage ?? dependency.repository;\n if (url !== null && typeof url !== 'string') {\n url = url.url;\n }\n arr.push(`URL: ${url ?? 'N/A'}`);\n arr.push(`Version: ${dependency.version ?? 'N/A'}`);\n arr.push(`License: ${dependency.license ?? 'N/A'}`);\n if (dependency.licenseText !== null) {\n arr.push('');\n arr.push(dependency.licenseText.replaceAll('\\r', ''));\n }\n return arr.join('\\n');\n });\n\n // Manual license handling for chrome-devtools-frontend third_party\n const tsConfig = JSON.parse(\n fs.readFileSync(\n path.join(process.cwd(), 'tsconfig.json'),\n 'utf-8',\n ),\n );\n const thirdPartyDirectories = tsConfig.include.filter(location =>\n location.includes(\n 'node_modules/chrome-devtools-frontend/front_end/third_party',\n ),\n );\n\n const manualLicenses = [];\n // Add chrome-devtools-frontend main license\n const cdtfLicensePath = path.join(\n process.cwd(),\n 'node_modules/chrome-devtools-frontend/LICENSE',\n );\n if (fs.existsSync(cdtfLicensePath)) {\n manualLicenses.push(\n [\n 'Name: chrome-devtools-frontend',\n 'License: Apache-2.0',\n '',\n fs.readFileSync(cdtfLicensePath, 'utf-8'),\n ].join('\\n'),\n );\n }\n\n // Add chrome-devtools-frontend main license\n const lighthouseLicensePath = path.join(\n process.cwd(),\n 'node_modules/lighthouse/LICENSE',\n );\n if (fs.existsSync(lighthouseLicensePath)) {\n manualLicenses.push(\n [\n 'Name: lighthouse',\n 'License: Apache-2.0',\n '',\n fs.readFileSync(lighthouseLicensePath, 'utf-8'),\n ].join('\\n'),\n );\n }\n\n for (const thirdPartyDir of thirdPartyDirectories) {\n const fullPath = path.join(process.cwd(), thirdPartyDir);\n const licenseFile = path.join(fullPath, 'LICENSE');\n if (fs.existsSync(licenseFile)) {\n const name = path.basename(thirdPartyDir);\n manualLicenses.push(\n [\n `Name: ${name}`,\n `License:`,\n '',\n fs.readFileSync(licenseFile, 'utf-8').replaceAll('\\r', ''),\n ].join('\\n'),\n );\n }\n }\n\n if (manualLicenses.length > 0) {\n stringifiedDependencies.push(...manualLicenses);\n }\n\n const divider =\n '\\n\\n-------------------- DEPENDENCY DIVIDER --------------------\\n\\n';\n return stringifiedDependencies.join(divider);\n },\n },\n },\n }),\n listBundledDeps(),\n commonjs(),\n json(),\n nodeResolve(),\n ],\n external,\n});\n\nexport default [\n bundleDependency(\n 'index.js',\n {\n inlineDynamicImports: true,\n },\n (source, importer, _isResolved) => {\n if (\n source === 'yargs' &&\n importer &&\n importer.includes('puppeteer-core')\n ) {\n return true;\n }\n\n const existingExternals = [\n './bidi.js',\n '../bidi/bidi.js',\n './lighthouse-devtools-mcp-bundle.js',\n ];\n\n if (existingExternals.includes(source)) {\n return true;\n }\n return false;\n },\n ),\n bundleDependency(\n 'devtools-formatter-worker.js',\n {\n inlineDynamicImports: true,\n },\n (_source, _importer, _isResolved) => false,\n ),\n];\n" }, { "path": "scripts/append-lighthouse-notices.ts", "content": "/**\n * @license\n * Copyright 2026 Google LLC\n * SPDX-License-Identifier: Apache-2.0\n */\n\nimport fs from 'node:fs';\nimport path from 'node:path';\n\nconst ROOT_DIR = process.cwd();\nconst TARGET_DIR = path.join(ROOT_DIR, 'build/src/third_party');\nconst SOURCE_DIR = path.join(ROOT_DIR, 'src/third_party');\n\nfunction main() {\n const lighthouseNotices = fs.readFileSync(\n path.join(SOURCE_DIR, 'LIGHTHOUSE_MCP_BUNDLE_THIRD_PARTY_NOTICES'),\n 'utf8',\n );\n const bundledNotices = fs.readFileSync(\n path.join(TARGET_DIR, 'THIRD_PARTY_NOTICES'),\n 'utf8',\n );\n fs.writeFileSync(\n path.join(TARGET_DIR, 'THIRD_PARTY_NOTICES'),\n bundledNotices +\n '\\n\\n-------------------- DEPENDENCY DIVIDER --------------------\\n\\n' +\n lighthouseNotices,\n );\n console.log('Done.');\n}\n\nmain();\n" }, { "path": "scripts/count_tokens.ts", "content": "/**\n * @license\n * Copyright 2026 Google LLC\n * SPDX-License-Identifier: Apache-2.0\n */\n\nimport {readFileSync} from 'node:fs';\nimport {parseArgs} from 'node:util';\n\nimport {GoogleGenAI} from '@google/genai';\n\nconst ai = new GoogleGenAI({apiKey: process.env.GEMINI_API_KEY});\n\nconst {values, positionals} = parseArgs({\n options: {\n model: {\n type: 'string',\n default: 'gemini-2.5-flash',\n },\n file: {\n type: 'string',\n short: 'f',\n },\n },\n allowPositionals: true,\n});\n\nlet contents = positionals[0];\n\nif (values.file) {\n contents = readFileSync(values.file, 'utf8');\n}\n\nif (!contents) {\n console.error('Usage: npm run count-tokens -- [-f ] []');\n process.exit(1);\n}\n\nconst response = await ai.models.countTokens({\n model: values.model,\n contents,\n});\nconsole.log(`Input: ${values.file || positionals[0]}`);\nconsole.log(`Tokens: ${response.totalTokens}`);\n" }, { "path": "scripts/eslint_rules/check-license-rule.js", "content": "/**\n * @license\n * Copyright 2025 Google LLC\n * SPDX-License-Identifier: Apache-2.0\n */\n\nconst currentYear = new Date().getFullYear();\nconst licenseHeader = `\n/**\n * @license\n * Copyright ${currentYear} Google LLC\n * SPDX-License-Identifier: Apache-2.0\n */\n`;\n\nexport default {\n name: 'check-license',\n meta: {\n type: 'layout',\n docs: {\n description: 'Validate existence of license header',\n },\n fixable: 'code',\n schema: [],\n messages: {\n licenseRule: 'Add license header.',\n emptyLine: 'Add empty line after license header.',\n },\n },\n defaultOptions: [],\n create(context) {\n const sourceCode = context.getSourceCode();\n const comments = sourceCode.getAllComments();\n let insertAfter = [0, 0];\n let header = null;\n // Check only the first 2 comments\n for (let index = 0; index < 2; index++) {\n const comment = comments[index];\n if (!comment) {\n break;\n }\n // Shebang comments should be at the top\n if (\n comment.type === 'Shebang' ||\n (comment.type === 'Line' && comment.value.startsWith('#!'))\n ) {\n insertAfter = comment.range;\n continue;\n }\n if (comment.type === 'Block') {\n header = comment;\n break;\n }\n }\n\n return {\n Program(node) {\n if (context.getFilename().endsWith('.json')) {\n return;\n }\n\n if (\n header &&\n (header.value.includes('@license') ||\n header.value.includes('License') ||\n header.value.includes('Copyright'))\n ) {\n const nextToken = sourceCode.getTokenAfter(header, {\n includeComments: true,\n });\n if (\n nextToken &&\n nextToken.loc.start.line === header.loc.end.line + 1\n ) {\n context.report({\n node: node,\n loc: header.loc,\n messageId: 'emptyLine',\n fix(fixer) {\n return fixer.insertTextAfter(header, '\\n');\n },\n });\n }\n return;\n }\n\n // Add header license\n if (!header || !header.value.includes('@license')) {\n context.report({\n node: node,\n messageId: 'licenseRule',\n fix(fixer) {\n return fixer.insertTextAfterRange(insertAfter, licenseHeader);\n },\n });\n }\n },\n };\n },\n};\n" }, { "path": "scripts/eslint_rules/local-plugin.js", "content": "/**\n * @license\n * Copyright 2025 Google LLC\n * SPDX-License-Identifier: Apache-2.0\n */\n\nimport checkLicenseRule from './check-license-rule.js';\n\nexport default {rules: {'check-license': checkLicenseRule}};\n" }, { "path": "scripts/eval_gemini.ts", "content": "/**\n * @license\n * Copyright 2026 Google LLC\n * SPDX-License-Identifier: Apache-2.0\n */\n\nimport fs from 'node:fs';\nimport path from 'node:path';\nimport {pathToFileURL} from 'node:url';\nimport {parseArgs} from 'node:util';\n\nimport {GoogleGenAI, mcpToTool} from '@google/genai';\nimport {Client} from '@modelcontextprotocol/sdk/client/index.js';\nimport {StdioClientTransport} from '@modelcontextprotocol/sdk/client/stdio.js';\n\nimport {TestServer} from '../build/tests/server.js';\n\nconst ROOT_DIR = path.resolve(import.meta.dirname, '..');\nconst SCENARIOS_DIR = path.join(import.meta.dirname, 'eval_scenarios');\nconst SKILL_PATH = path.join(ROOT_DIR, 'skills', 'chrome-devtools', 'SKILL.md');\n\n// Define schema for our test scenarios\nexport interface CapturedFunctionCall {\n name: string;\n args: Record;\n}\n\nexport interface TestScenario {\n prompt: string;\n maxTurns: number;\n expectations: (calls: CapturedFunctionCall[]) => void;\n htmlRoute?: {\n path: string;\n htmlContent: string;\n };\n /** Extra CLI flags passed to the MCP server (e.g. '--experimental-page-id-routing'). */\n serverArgs?: string[];\n}\n\nasync function loadScenario(scenarioPath: string): Promise {\n const module = await import(pathToFileURL(scenarioPath).href);\n if (!module.scenario) {\n throw new Error(\n `Scenario file ${scenarioPath} does not export a 'scenario' object.`,\n );\n }\n return module.scenario;\n}\n\nasync function runSingleScenario(\n scenarioPath: string,\n apiKey: string,\n server: TestServer,\n modelId: string,\n debug: boolean,\n includeSkill: boolean,\n): Promise {\n const debugLog = (...args: unknown[]) => {\n if (debug) {\n console.log(...args);\n }\n };\n const absolutePath = path.resolve(scenarioPath);\n debugLog(\n `\\n### Running Scenario: ${path.relative(ROOT_DIR, absolutePath)} ###`,\n );\n\n let client: Client | undefined;\n let transport: StdioClientTransport | undefined;\n\n try {\n const loadedScenario = await loadScenario(absolutePath);\n const scenario = {...loadedScenario};\n\n // Prepend skill content if requested\n if (includeSkill) {\n if (!fs.existsSync(SKILL_PATH)) {\n throw new Error(\n `Skill file not found at ${SKILL_PATH}. Please ensure the skill file exists.`,\n );\n }\n const skillContent = fs.readFileSync(SKILL_PATH, 'utf-8');\n scenario.prompt = `${skillContent}\\n\\n---\\n\\n${scenario.prompt}`;\n }\n\n // Append random queryid to avoid caching issues and test distinct runs\n const randomId = Math.floor(Math.random() * 1000000);\n scenario.prompt = `${scenario.prompt}\\nqueryid=${randomId}`;\n\n if (scenario.htmlRoute) {\n server.addHtmlRoute(\n scenario.htmlRoute.path,\n scenario.htmlRoute.htmlContent,\n );\n scenario.prompt = scenario.prompt.replace(\n '',\n server.getRoute(scenario.htmlRoute.path),\n );\n }\n\n // Path to the compiled MCP server\n const serverPath = path.join(ROOT_DIR, 'build/src/index.js');\n if (!fs.existsSync(serverPath)) {\n throw new Error(\n `MCP server not found at ${serverPath}. Please run 'npm run build' first.`,\n );\n }\n\n // Environment variables\n const env: Record = {};\n Object.entries(process.env).forEach(([key, value]) => {\n if (value !== undefined) {\n env[key] = value;\n }\n });\n env['CHROME_DEVTOOLS_MCP_NO_USAGE_STATISTICS'] = 'true';\n\n const args = [serverPath];\n if (!debug) {\n args.push('--headless');\n }\n if (scenario.serverArgs) {\n args.push(...scenario.serverArgs);\n }\n\n transport = new StdioClientTransport({\n command: 'node',\n args,\n env,\n stderr: debug ? 'inherit' : 'ignore',\n });\n\n client = new Client(\n {name: 'gemini-eval-client', version: '1.0.0'},\n {capabilities: {}},\n );\n\n await client.connect(transport);\n\n const allCalls: CapturedFunctionCall[] = [];\n const originalCallTool = client.callTool.bind(client);\n client.callTool = async (request, schema) => {\n // NOTE: request.name is the original name as the MCP client sees it.\n // mcpToTool handles the conversion from Gemini sanitized name to original name.\n debugLog(\n `Executing tool: ${request.name} with args: ${JSON.stringify(request.arguments)}`,\n );\n allCalls.push({\n name: request.name,\n args: (request.arguments as Record) || {},\n });\n const response = await originalCallTool(request, schema);\n debugLog(`Tool response: ${JSON.stringify(response)}`);\n return response;\n };\n\n const ai = new GoogleGenAI({apiKey});\n\n debugLog(`\\n--- Prompt ---\\n${scenario.prompt}`);\n\n const result = await ai.models.generateContent({\n model: modelId,\n contents: scenario.prompt,\n config: {\n tools: [mcpToTool(client)],\n automaticFunctionCalling: {\n maximumRemoteCalls: scenario.maxTurns,\n },\n },\n });\n\n debugLog(`\\n--- Response ---\\n${result.text}`);\n\n debugLog('\\nVerifying expectations...');\n scenario.expectations(allCalls);\n } finally {\n try {\n await client?.close();\n } catch (e) {\n console.error('Error closing client:', e);\n }\n }\n}\n\nasync function main() {\n const apiKey = process.env.GEMINI_API_KEY;\n if (!apiKey) {\n throw new Error('GEMINI_API_KEY environment variable is required.');\n }\n\n const {values, positionals} = parseArgs({\n options: {\n model: {\n type: 'string',\n default: 'gemini-2.5-flash',\n },\n debug: {\n type: 'boolean',\n default: false,\n },\n repeat: {\n type: 'boolean',\n default: false,\n },\n 'include-skill': {\n type: 'boolean',\n default: false,\n },\n },\n allowPositionals: true,\n });\n\n const modelId = values.model;\n const debug = values.debug;\n const repeat = values.repeat;\n const includeSkill = values['include-skill'];\n\n const scenarioFiles =\n positionals.length > 0\n ? positionals.map(p => path.resolve(p))\n : fs\n .readdirSync(SCENARIOS_DIR)\n .filter(file => file.endsWith('.ts') || file.endsWith('.js'))\n .map(file => path.join(SCENARIOS_DIR, file));\n\n const server = new TestServer(TestServer.randomPort());\n await server.start();\n\n let successCount = 0;\n let failureCount = 0;\n\n try {\n for (const scenarioPath of scenarioFiles) {\n for (let i = 1; i <= (repeat ? 3 : 1); i++) {\n try {\n if (debug) {\n console.log(\n `Running scenario: ${path.relative(ROOT_DIR, scenarioPath)} (Run ${i}/3)`,\n );\n }\n await runSingleScenario(\n scenarioPath,\n apiKey,\n server,\n modelId,\n debug,\n includeSkill,\n );\n console.log(`✔ ${path.relative(ROOT_DIR, scenarioPath)} (Run ${i})`);\n successCount++;\n } catch (e) {\n console.error(\n `✖ ${path.relative(ROOT_DIR, scenarioPath)} (Run ${i})`,\n );\n console.error(e);\n failureCount++;\n } finally {\n server.restore();\n }\n }\n }\n } finally {\n await server.stop();\n }\n\n console.log(`\\nSummary: ${successCount} passed, ${failureCount} failed`);\n\n if (failureCount > 0) {\n process.exit(1);\n }\n}\n\nmain().catch(error => {\n console.error('Fatal error:', error);\n process.exit(1);\n});\n" }, { "path": "scripts/eval_scenarios/console_test.ts", "content": "/**\n * @license\n * Copyright 2026 Google LLC\n * SPDX-License-Identifier: Apache-2.0\n */\n\nimport assert from 'node:assert';\n\nimport type {TestScenario} from '../eval_gemini.ts';\n\nexport const scenario: TestScenario = {\n prompt: 'Navigate to and check the console messages.',\n maxTurns: 2,\n htmlRoute: {\n path: '/console_test.html',\n htmlContent: `\n \n `,\n },\n expectations: calls => {\n assert.strictEqual(calls.length, 2);\n assert.ok(\n calls[0].name === 'navigate_page' || calls[0].name === 'new_page',\n 'First call should be navigation',\n );\n assert.strictEqual(\n calls[1].name,\n 'list_console_messages',\n 'Second call should be list_console_messages',\n );\n },\n};\n" }, { "path": "scripts/eval_scenarios/emulation_test.ts", "content": "/**\n * @license\n * Copyright 2026 Google LLC\n * SPDX-License-Identifier: Apache-2.0\n */\n\nimport assert from 'node:assert';\n\nimport type {TestScenario} from '../eval_gemini.ts';\n\nexport const scenario: TestScenario = {\n prompt: 'Emulate offline network conditions.',\n maxTurns: 2,\n expectations: calls => {\n assert.strictEqual(calls.length, 1);\n assert.strictEqual(calls[0].name, 'emulate');\n assert.strictEqual(calls[0].args.networkConditions, 'Offline');\n },\n};\n" }, { "path": "scripts/eval_scenarios/emulation_userAgent_test.ts", "content": "/**\n * @license\n * Copyright 2026 Google LLC\n * SPDX-License-Identifier: Apache-2.0\n */\n\nimport assert from 'node:assert';\n\nimport type {TestScenario} from '../eval_gemini.ts';\n\nexport const scenario: TestScenario = {\n prompt: 'Emulate iPhone 14 user agent',\n maxTurns: 2,\n expectations: calls => {\n assert.strictEqual(calls.length, 1);\n assert.strictEqual(calls[0].name, 'emulate');\n assert.deepStrictEqual(\n calls[0].args.userAgent,\n 'Mozilla/5.0 (iPhone; CPU iPhone OS 16_0 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/16.0 Mobile/15E148 Safari/604.1',\n );\n },\n};\n" }, { "path": "scripts/eval_scenarios/emulation_viewport_test.ts", "content": "/**\n * @license\n * Copyright 2026 Google LLC\n * SPDX-License-Identifier: Apache-2.0\n */\n\nimport assert from 'node:assert';\n\nimport {KnownDevices} from 'puppeteer';\n\nimport type {TestScenario} from '../eval_gemini.ts';\n\nexport const scenario: TestScenario = {\n prompt: 'Emulate iPhone 14 viewport',\n maxTurns: 2,\n expectations: calls => {\n assert.strictEqual(calls.length, 1);\n assert.strictEqual(calls[0].name, 'emulate');\n assert.deepStrictEqual(\n {\n ...(calls[0].args.viewport as object),\n // models might not send defaults.\n isLandscape: KnownDevices['iPhone 14'].viewport.isLandscape ?? false,\n },\n {\n ...KnownDevices['iPhone 14'].viewport,\n height: 844, // Puppeteer is wrong about the expected height.\n },\n );\n },\n};\n" }, { "path": "scripts/eval_scenarios/fix_webpage_issues_test.ts", "content": "/**\n * @license\n * Copyright 2026 Google LLC\n * SPDX-License-Identifier: Apache-2.0\n *\n * Eval scenario: user asks to fix issues with their webpage (no URL given).\n * When no URL is provided, the model should pick the current frontend and run\n * and inspect it. Verifies the MCP server is invoked and the model opens the\n * frontend and inspects it (snapshot, console, or network).\n *\n * Note: Tools like performance_start_trace, take_snapshot, list_console_messages,\n * and list_network_requests do not require a URL in the prompt—they operate on\n * the currently selected page. Only navigate_page/new_page need a URL to open\n * a page; the eval runner injects the test URL when htmlRoute is set.\n */\n\nimport assert from 'node:assert';\n\nimport type {TestScenario} from '../eval_gemini.ts';\n\nconst INSPECTION_TOOLS = [\n 'take_snapshot',\n 'list_console_messages',\n 'list_network_requests',\n];\n\nexport const scenario: TestScenario = {\n prompt: 'Can you fix issues with my webpage?',\n maxTurns: 4,\n htmlRoute: {\n path: '/fix_issues_test.html',\n htmlContent: `\n

Test Page

\n

Some content

\n \n `,\n },\n expectations: calls => {\n const NAVIGATION_TOOLS = ['navigate_page', 'new_page'];\n assert.ok(\n calls.length >= 2,\n 'Expected at least navigation and one inspection',\n );\n const navigationIndex = calls.findIndex(c =>\n NAVIGATION_TOOLS.includes(c.name),\n );\n assert.ok(\n navigationIndex !== -1,\n `Expected a navigation call (${NAVIGATION_TOOLS.join(' or ')}), got: ${calls.map(c => c.name).join(', ')}`,\n );\n const afterNavigation = calls.slice(navigationIndex + 1);\n const inspectionCalls = afterNavigation.filter(c =>\n INSPECTION_TOOLS.includes(c.name),\n );\n assert.ok(\n inspectionCalls.length >= 1,\n `Expected at least one inspection tool (${INSPECTION_TOOLS.join(', ')}) after navigation, got: ${calls.map(c => c.name).join(', ')}`,\n );\n },\n};\n" }, { "path": "scripts/eval_scenarios/frontend_snapshot_test.ts", "content": "/**\n * @license\n * Copyright 2026 Google LLC\n * SPDX-License-Identifier: Apache-2.0\n *\n * Eval scenario using \"website\"/\"webpage\" wording to verify the model invokes\n * the right tools when users ask to open a site and read its content.\n */\n\nimport assert from 'node:assert';\n\nimport type {TestScenario} from '../eval_gemini.ts';\n\nexport const scenario: TestScenario = {\n prompt:\n 'Open the website at and tell me what content is on the page.',\n maxTurns: 3,\n htmlRoute: {\n path: '/frontend_snapshot.html',\n htmlContent: '

Frontend Test

This is a test webpage.

',\n },\n expectations: calls => {\n assert.strictEqual(calls.length, 2);\n assert.ok(\n calls[0].name === 'navigate_page' || calls[0].name === 'new_page',\n 'First call should be navigation',\n );\n assert.strictEqual(\n calls[1].name,\n 'take_snapshot',\n 'Second call should be take_snapshot to read page content',\n );\n },\n};\n" }, { "path": "scripts/eval_scenarios/input_parallel_test.ts", "content": "/**\n * @license\n * Copyright 2026 Google LLC\n * SPDX-License-Identifier: Apache-2.0\n */\n\nimport assert from 'node:assert';\n\nimport type {TestScenario} from '../eval_gemini.ts';\n\nexport const scenario: TestScenario = {\n prompt:\n 'Go to , fill the input with \"hello world\" and click the button five times in parallel.',\n maxTurns: 10,\n htmlRoute: {\n path: '/input_test.html',\n htmlContent: `\n \n \n `,\n },\n expectations: calls => {\n assert.strictEqual(calls.length, 8);\n assert.ok(\n calls[0].name === 'navigate_page' || calls[0].name === 'new_page',\n );\n assert.ok(calls[1].name === 'take_snapshot');\n assert.ok(calls[2].name === 'fill');\n for (let i = 3; i < 8; i++) {\n assert.ok(calls[i].name === 'click');\n assert.strictEqual(Boolean(calls[i].args.includeSnapshot), false);\n }\n },\n};\n" }, { "path": "scripts/eval_scenarios/input_test.ts", "content": "/**\n * @license\n * Copyright 2026 Google LLC\n * SPDX-License-Identifier: Apache-2.0\n */\n\nimport assert from 'node:assert';\n\nimport type {TestScenario} from '../eval_gemini.ts';\n\nexport const scenario: TestScenario = {\n prompt:\n 'Go to , fill the input with \"hello world\" and click the button.',\n maxTurns: 4,\n htmlRoute: {\n path: '/input_test.html',\n htmlContent: `\n \n \n `,\n },\n expectations: calls => {\n assert.strictEqual(calls.length, 4);\n assert.ok(\n calls[0].name === 'navigate_page' || calls[0].name === 'new_page',\n );\n assert.ok(calls[1].name === 'take_snapshot');\n assert.ok(calls[2].name === 'fill');\n assert.ok(calls[3].name === 'click');\n },\n};\n" }, { "path": "scripts/eval_scenarios/isolated_context_test.ts", "content": "/**\n * @license\n * Copyright 2026 Google LLC\n * SPDX-License-Identifier: Apache-2.0\n */\n\nimport assert from 'node:assert';\n\nimport type {TestScenario} from '../eval_gemini.ts';\n\nexport const scenario: TestScenario = {\n prompt:\n 'Create a new page in an isolated context called contextB. Take a screenshot there.',\n maxTurns: 3,\n htmlRoute: {\n path: '/test.html',\n htmlContent: `\n

test

\n `,\n },\n expectations: calls => {\n console.log(JSON.stringify(calls, null, 2));\n assert.strictEqual(calls.length, 2);\n assert.ok(calls[0].name === 'new_page', 'First call should be navigation');\n assert.deepStrictEqual(calls[0].args.isolatedContext, 'contextB');\n assert.ok(\n calls[1].name === 'take_screenshot',\n 'Second call should be a screenshot',\n );\n },\n};\n" }, { "path": "scripts/eval_scenarios/lighthouse_a11y_test.ts", "content": "/**\n * @license\n * Copyright 2026 Google LLC\n * SPDX-License-Identifier: Apache-2.0\n */\n\nimport assert from 'node:assert';\n\nimport type {TestScenario} from '../eval_gemini.ts';\n\nexport const scenario: TestScenario = {\n prompt: 'Check a11y issues on the current page',\n maxTurns: 1,\n expectations: calls => {\n assert.strictEqual(calls.length, 1);\n assert.ok(\n calls[0].name === 'lighthouse_audit',\n 'First call should be lighthouse_audit',\n );\n },\n};\n" }, { "path": "scripts/eval_scenarios/lighthouse_best_practices_test.ts", "content": "/**\n * @license\n * Copyright 2026 Google LLC\n * SPDX-License-Identifier: Apache-2.0\n */\n\nimport assert from 'node:assert';\n\nimport type {TestScenario} from '../eval_gemini.ts';\n\nexport const scenario: TestScenario = {\n prompt: 'Check for best practices on the current page',\n maxTurns: 1,\n expectations: calls => {\n assert.strictEqual(calls.length, 1);\n assert.ok(\n calls[0].name === 'lighthouse_audit',\n 'First call should be lighthouse_audit',\n );\n },\n};\n" }, { "path": "scripts/eval_scenarios/navigation_test.ts", "content": "/**\n * @license\n * Copyright 2026 Google LLC\n * SPDX-License-Identifier: Apache-2.0\n */\n\nimport assert from 'node:assert';\n\nimport type {TestScenario} from '../eval_gemini.ts';\n\nexport const scenario: TestScenario = {\n prompt: 'Navigate to https://developers.chrome.com and tell me if it worked.',\n maxTurns: 1,\n expectations: calls => {\n assert.deepStrictEqual(calls, [\n {\n name: 'navigate_page',\n args: {url: 'https://developers.chrome.com'},\n },\n ]);\n },\n};\n" }, { "path": "scripts/eval_scenarios/network_test.ts", "content": "/**\n * @license\n * Copyright 2026 Google LLC\n * SPDX-License-Identifier: Apache-2.0\n */\n\nimport assert from 'node:assert';\n\nimport type {TestScenario} from '../eval_gemini.ts';\n\nexport const scenario: TestScenario = {\n prompt: 'Navigate to and list all network requests.',\n maxTurns: 2,\n htmlRoute: {\n path: '/network_test.html',\n htmlContent: `\n

Network Test

\n \n `,\n },\n expectations: calls => {\n assert.strictEqual(calls.length, 2);\n assert.ok(\n calls[0].name === 'navigate_page' || calls[0].name === 'new_page',\n 'First call should be navigation',\n );\n assert.strictEqual(\n calls[1].name,\n 'list_network_requests',\n 'Second call should be list_network_requests',\n );\n },\n};\n" }, { "path": "scripts/eval_scenarios/page_focus_keyboard_test.ts", "content": "/**\n * @license\n * Copyright 2026 Google LLC\n * SPDX-License-Identifier: Apache-2.0\n */\n\nimport assert from 'node:assert';\n\nimport type {TestScenario} from '../eval_gemini.ts';\n\nexport const scenario: TestScenario = {\n serverArgs: ['--experimental-page-id-routing'],\n prompt: `Open two pages in the same isolated context \"session\":\n- Page 1 at data:text/html,\n- Page 2 at data:text/html,

Other

\n\nNow use the press_key tool to type \"a\" on Page 1 without selecting it first. You must use press_key, not fill or type_text. If you encounter any errors, recover from them.`,\n maxTurns: 10,\n expectations: calls => {\n // Should open 2 pages in the same context.\n const newPages = calls.filter(c => c.name === 'new_page');\n assert.strictEqual(newPages.length, 2, 'Should open 2 pages');\n assert.strictEqual(newPages[0].args.isolatedContext, 'session');\n assert.strictEqual(newPages[1].args.isolatedContext, 'session');\n\n // Should attempt press_key at least once.\n const pressKeys = calls.filter(c => c.name === 'press_key');\n assert.ok(pressKeys.length >= 1, 'Should attempt press_key at least once');\n\n const selectPages = calls.filter(c => c.name === 'select_page');\n\n if (selectPages.length > 0) {\n const firstPressKeyIndex = calls.indexOf(pressKeys[0]);\n const firstSelectPageIndex = calls.indexOf(selectPages[0]);\n\n if (firstPressKeyIndex < firstSelectPageIndex) {\n // Error path: press_key was attempted first and failed.\n // Verify recovery: must have a second press_key after select_page.\n assert.ok(\n pressKeys.length >= 2,\n 'Should retry press_key after error recovery',\n );\n const lastPressKeyIndex = calls.lastIndexOf(pressKeys.at(-1)!);\n assert.ok(\n firstSelectPageIndex < lastPressKeyIndex,\n 'select_page should precede the successful press_key',\n );\n } else {\n // Proactive path: model selected page first.\n assert.ok(\n firstSelectPageIndex < firstPressKeyIndex,\n 'select_page should precede press_key',\n );\n }\n }\n // If no select_page was called, the model found another recovery path.\n // This is acceptable as long as press_key was attempted.\n },\n};\n" }, { "path": "scripts/eval_scenarios/page_id_routing_test.ts", "content": "/**\n * @license\n * Copyright 2026 Google LLC\n * SPDX-License-Identifier: Apache-2.0\n */\n\nimport assert from 'node:assert';\n\nimport type {TestScenario} from '../eval_gemini.ts';\n\nexport const scenario: TestScenario = {\n serverArgs: ['--experimental-page-id-routing'],\n prompt: `Open two new pages in isolated contexts:\n- Page A (isolatedContext \"contextA\") at data:text/html,\n- Page B (isolatedContext \"contextB\") at data:text/html,\nThen take a snapshot of Page A, take a snapshot of Page B, and then click the button on Page A.`,\n maxTurns: 12,\n expectations: calls => {\n // Should have 2 new_page calls with isolatedContext.\n const newPages = calls.filter(c => c.name === 'new_page');\n assert.strictEqual(newPages.length, 2, 'Should open 2 pages');\n for (const np of newPages) {\n assert.strictEqual(\n typeof np.args.isolatedContext,\n 'string',\n 'new_page should use isolatedContext',\n );\n }\n\n // Should have at least 2 take_snapshot calls (one per page).\n // The model may use pageId directly or select_page before each snapshot.\n const snapshots = calls.filter(c => c.name === 'take_snapshot');\n assert.ok(snapshots.length >= 2, 'Should take at least 2 snapshots');\n\n // Should have a click call (resolving uid from Page A's snapshot\n // even though Page B was snapshotted after).\n const clicks = calls.filter(c => c.name === 'click');\n assert.ok(clicks.length >= 1, 'Should click the button on Page A');\n },\n};\n" }, { "path": "scripts/eval_scenarios/performance_test.ts", "content": "/**\n * @license\n * Copyright 2026 Google LLC\n * SPDX-License-Identifier: Apache-2.0\n */\n\nimport assert from 'node:assert';\n\nimport type {TestScenario} from '../eval_gemini.ts';\n\nexport const scenario: TestScenario = {\n prompt: 'Check the performance of https://developers.chrome.com',\n maxTurns: 2,\n expectations: calls => {\n assert.strictEqual(calls.length, 2);\n assert.ok(\n calls[0].name === 'navigate_page' || calls[0].name === 'new_page',\n );\n assert.ok(calls[1].name === 'performance_start_trace');\n },\n};\n" }, { "path": "scripts/eval_scenarios/select_page_test.ts", "content": "/**\n * @license\n * Copyright 2026 Google LLC\n * SPDX-License-Identifier: Apache-2.0\n */\n\nimport assert from 'node:assert';\n\nimport type {TestScenario} from '../eval_gemini.ts';\n\nexport const scenario: TestScenario = {\n prompt:\n 'Open new page and then open new page https://developers.chrome.com. Select the page.',\n maxTurns: 3,\n htmlRoute: {\n path: '/test.html',\n htmlContent: `\n

test

\n `,\n },\n expectations: calls => {\n assert.strictEqual(calls.length, 3);\n assert.ok(calls[0].name === 'new_page', 'First call should be navigation');\n assert.ok(calls[1].name === 'new_page', 'Second call should be navigation');\n assert.ok(\n calls[2].name === 'select_page',\n 'Third call should be select_page',\n );\n assert.strictEqual(\n calls[2].args.pageId,\n 2,\n 'PageId has to be set to 2. about:blank is 1, is 2, https://developers.chrome.com is 3.',\n );\n assert.strictEqual(\n calls[2].args.bringToFront,\n undefined,\n 'bringToFront should use the default value.',\n );\n },\n};\n" }, { "path": "scripts/eval_scenarios/snapshot_test.ts", "content": "/**\n * @license\n * Copyright 2026 Google LLC\n * SPDX-License-Identifier: Apache-2.0\n */\n\nimport assert from 'node:assert';\n\nimport type {TestScenario} from '../eval_gemini.ts';\n\nexport const scenario: TestScenario = {\n prompt: 'Read the content of ',\n maxTurns: 3,\n htmlRoute: {\n path: '/test.html',\n htmlContent: '

Hello World

This is a test.

',\n },\n expectations: calls => {\n assert.strictEqual(calls.length, 2);\n assert.ok(\n calls[0].name === 'navigate_page' || calls[0].name === 'new_page',\n );\n assert.ok(calls[1].name === 'take_snapshot');\n },\n};\n" }, { "path": "scripts/generate-cli.ts", "content": "/**\n * @license\n * Copyright 2026 Google LLC\n * SPDX-License-Identifier: Apache-2.0\n */\n\nimport fs from 'node:fs';\nimport path from 'node:path';\n\nimport {Client} from '@modelcontextprotocol/sdk/client/index.js';\nimport {StdioClientTransport} from '@modelcontextprotocol/sdk/client/stdio.js';\n\nimport {parseArguments} from '../build/src/bin/chrome-devtools-mcp-cli-options.js';\nimport {labels} from '../build/src/tools/categories.js';\nimport {createTools} from '../build/src/tools/tools.js';\n\nconst OUTPUT_PATH = path.join(\n import.meta.dirname,\n '../src/bin/cliDefinitions.ts',\n);\n\nasync function fetchTools() {\n console.log('Connecting to chrome-devtools-mcp to fetch tools...');\n // Use the local build of the server\n const serverPath = path.join(\n import.meta.dirname,\n '../build/src/bin/chrome-devtools-mcp.js',\n );\n\n const transport = new StdioClientTransport({\n command: 'node',\n args: [serverPath],\n env: {...process.env, CHROME_DEVTOOLS_MCP_NO_USAGE_STATISTICS: 'true'},\n });\n\n const client = new Client(\n {\n name: 'chrome-devtools-cli-generator',\n version: '0.1.0',\n },\n {\n capabilities: {},\n },\n );\n\n await client.connect(transport);\n try {\n const toolsResponse = await client.listTools();\n if (!toolsResponse.tools?.length) {\n throw new Error(`No tools were fetched`);\n }\n const tools = toolsResponse.tools || [];\n console.log(`Fetched ${tools.length} tools`);\n return tools;\n } finally {\n await client.close();\n }\n}\n\ninterface CliOption {\n name: string;\n type: string;\n description: string;\n required: boolean;\n default?: unknown;\n enum?: unknown[];\n}\n\ninterface JsonSchema {\n type?: string | string[];\n description?: string;\n properties?: Record;\n required?: string[];\n default?: unknown;\n enum?: unknown[];\n}\n\nfunction schemaToCLIOptions(schema: JsonSchema): CliOption[] {\n if (!schema || !schema.properties) {\n return [];\n }\n const required = schema.required || [];\n const properties = schema.properties;\n return Object.entries(properties).map(([name, prop]) => {\n const isRequired = required.includes(name);\n const description = prop.description || '';\n if (typeof prop.type !== 'string') {\n throw new Error(\n `Property ${name} has a complex type not supported by CLI.`,\n );\n }\n return {\n name,\n type: prop.type,\n description,\n required: isRequired,\n default: prop.default,\n enum: prop.enum,\n };\n });\n}\n\nasync function generateCli() {\n const tools = await fetchTools();\n\n // Sort tools by name\n const sortedTools = tools\n .sort((a, b) => a.name.localeCompare(b.name))\n .filter(tool => {\n // Skipping fill_form because it is not relevant in shell scripts\n // and CLI does not handle array/JSON args well.\n if (tool.name === 'fill_form') {\n return false;\n }\n // Skipping wait_for because CLI does not handle array/JSON args well\n // and shell scripts have many mechanisms for waiting.\n if (tool.name === 'wait_for') {\n return false;\n }\n return true;\n });\n\n const staticTools = createTools(parseArguments());\n const toolNameToCategory = new Map();\n for (const tool of staticTools) {\n toolNameToCategory.set(\n tool.name,\n labels[tool.annotations.category as keyof typeof labels],\n );\n }\n\n const commands: Record<\n string,\n {description: string; category: string; args: Record}\n > = {};\n\n for (const tool of sortedTools) {\n const options = schemaToCLIOptions(tool.inputSchema);\n const args: Record = {};\n for (const opt of options) {\n args[opt.name] = opt;\n }\n const category = toolNameToCategory.get(tool.name);\n if (!category) {\n throw new Error(`Tool ${tool.name} has no category.`);\n }\n if (!tool.description) {\n throw new Error(`Tool ${tool.name} is missing descripttion`);\n }\n commands[tool.name] = {\n description: tool.description,\n category,\n args,\n };\n }\n\n const lines: string[] = [];\n lines.push(`/**\n * @license\n * Copyright ${new Date().getFullYear()} Google LLC\n * SPDX-License-Identifier: Apache-2.0\n */\n\n// NOTE: do not edit manually. Auto-generated by 'npm run cli:generate'.\n\nexport interface ArgDef {\n name: string;\n type: string;\n description: string;\n required: boolean;\n default?: string | number | boolean;\n enum?: ReadonlyArray;\n}\nexport type Commands = Record<\n string,\n {\n description: string;\n category: string;\n args: Record\n }\n>;\nexport const commands: Commands = ${JSON.stringify(commands, null, 2)} as const;\n`);\n\n fs.mkdirSync(path.dirname(OUTPUT_PATH), {recursive: true});\n fs.writeFileSync(OUTPUT_PATH, lines.join(''));\n console.log(`Generated CLI at ${OUTPUT_PATH}`);\n}\n\ngenerateCli().catch(err => {\n console.error('Error during generation:', err);\n process.exit(1);\n});\n" }, { "path": "scripts/generate-docs.ts", "content": "/**\n * @license\n * Copyright 2025 Google LLC\n * SPDX-License-Identifier: Apache-2.0\n */\n\nimport fs from 'node:fs';\n\nimport {Client} from '@modelcontextprotocol/sdk/client/index.js';\nimport {StdioClientTransport} from '@modelcontextprotocol/sdk/client/stdio.js';\nimport type {Tool} from '@modelcontextprotocol/sdk/types.js';\nimport {get_encoding} from 'tiktoken';\n\nimport {cliOptions} from '../build/src/bin/chrome-devtools-mcp-cli-options.js';\nimport type {ParsedArguments} from '../build/src/bin/chrome-devtools-mcp-cli-options.js';\nimport {ToolCategory, labels} from '../build/src/tools/categories.js';\nimport {createTools} from '../build/src/tools/tools.js';\n\nconst OUTPUT_PATH = './docs/tool-reference.md';\nconst SLIM_OUTPUT_PATH = './docs/slim-tool-reference.md';\nconst README_PATH = './README.md';\n\nasync function measureServer(args: string[]) {\n // 1. Connect to your actual MCP server\n const transport = new StdioClientTransport({\n command: 'node',\n args: ['./build/src/bin/chrome-devtools-mcp.js', ...args], // Point to your built MCP server\n });\n\n const client = new Client(\n {name: 'measurer', version: '1.0.0'},\n {capabilities: {}},\n );\n await client.connect(transport);\n\n // 2. Fetch all tools\n const toolsList = await client.listTools();\n\n // 3. Serialize exactly how an LLM would see it (JSON)\n const jsonString = JSON.stringify(toolsList.tools, null, 2);\n\n // 4. Count tokens (using cl100k_base which is standard for GPT-4/Claude-3.5 approximation)\n const enc = get_encoding('cl100k_base');\n const tokenCount = enc.encode(jsonString).length;\n\n console.log(`--- Measurement Results ---`);\n console.log(`Total Tools: ${toolsList.tools.length}`);\n console.log(`JSON Character Count: ${jsonString.length}`);\n console.log(`Estimated Token Count: ~${tokenCount}`);\n\n // Clean up\n enc.free();\n await client.close();\n return {\n tokenCount,\n };\n}\n\n// Extend the MCP Tool type to include our annotations\ninterface ToolWithAnnotations extends Tool {\n annotations?: {\n title?: string;\n category?: typeof ToolCategory;\n conditions?: string[];\n };\n}\n\ninterface ZodCheck {\n kind: string;\n}\n\ninterface ZodDef {\n typeName: string;\n checks?: ZodCheck[];\n values?: string[];\n type?: ZodSchema;\n innerType?: ZodSchema;\n schema?: ZodSchema;\n defaultValue?: () => unknown;\n}\n\ninterface ZodSchema {\n _def: ZodDef;\n description?: string;\n}\n\ninterface TypeInfo {\n type: string;\n enum?: string[];\n items?: TypeInfo;\n description?: string;\n default?: unknown;\n}\n\nfunction escapeHtmlTags(text: string): string {\n return text\n .replace(/&(?![a-zA-Z]+;)/g, '&')\n .replace(/<([a-zA-Z][^>]*)>/g, '<$1>');\n}\n\nfunction addCrossLinks(text: string, tools: ToolWithAnnotations[]): string {\n let result = text;\n\n // Create a set of all tool names for efficient lookup\n const toolNames = new Set(tools.map(tool => tool.name));\n\n // Sort tool names by length (descending) to match longer names first\n const sortedToolNames = Array.from(toolNames).sort(\n (a, b) => b.length - a.length,\n );\n\n for (const toolName of sortedToolNames) {\n // Create regex to match tool name (case insensitive, word boundaries)\n const regex = new RegExp(`\\\\b${toolName}\\\\b`, 'gi');\n\n result = result.replace(regex, match => {\n // Only create link if the match isn't already inside a link\n if (result.indexOf(`[${match}]`) !== -1) {\n return match; // Already linked\n }\n const anchorLink = toolName.toLowerCase();\n return `[\\`${match}\\`](#${anchorLink})`;\n });\n }\n\n return result;\n}\n\nfunction generateToolsTOC(\n categories: Record,\n sortedCategories: string[],\n): string {\n let toc = '';\n\n for (const category of sortedCategories) {\n const categoryTools = categories[category];\n const categoryName = labels[category];\n toc += `- **${categoryName}** (${categoryTools.length} tools)\\n`;\n\n // Sort tools within category for TOC\n categoryTools.sort((a: Tool, b: Tool) => a.name.localeCompare(b.name));\n for (const tool of categoryTools) {\n const anchorLink = tool.name.toLowerCase();\n toc += ` - [\\`${tool.name}\\`](docs/tool-reference.md#${anchorLink})\\n`;\n }\n }\n\n return toc;\n}\n\nfunction updateReadmeWithToolsTOC(toolsTOC: string): void {\n const readmeContent = fs.readFileSync(README_PATH, 'utf8');\n\n const beginMarker = '';\n const endMarker = '';\n\n const beginIndex = readmeContent.indexOf(beginMarker);\n const endIndex = readmeContent.indexOf(endMarker);\n\n if (beginIndex === -1 || endIndex === -1) {\n console.warn('Could not find auto-generated tools markers in README.md');\n return;\n }\n\n const before = readmeContent.substring(0, beginIndex + beginMarker.length);\n const after = readmeContent.substring(endIndex);\n\n const updatedContent = before + '\\n\\n' + toolsTOC + '\\n' + after;\n\n fs.writeFileSync(README_PATH, updatedContent);\n console.log('Updated README.md with tools table of contents');\n}\n\nfunction generateConfigOptionsMarkdown(): string {\n let markdown = '';\n\n for (const [optionName, optionConfig] of Object.entries(cliOptions)) {\n // Skip hidden options\n if (optionConfig.hidden) {\n continue;\n }\n\n const aliasText = optionConfig.alias ? `, \\`-${optionConfig.alias}\\`` : '';\n const description = optionConfig.description || optionConfig.describe || '';\n\n // Convert camelCase to dash-case\n const dashCaseName = optionName\n .replace(/([a-z])([A-Z])/g, '$1-$2')\n .toLowerCase();\n const nameDisplay =\n dashCaseName !== optionName\n ? `\\`--${optionName}\\`/ \\`--${dashCaseName}\\``\n : `\\`--${optionName}\\``;\n\n // Start with option name and description\n markdown += `- **${nameDisplay}${aliasText}**\\n`;\n markdown += ` ${description}\\n`;\n\n // Add type information\n markdown += ` - **Type:** ${optionConfig.type}\\n`;\n\n // Add choices if available\n if (optionConfig.choices) {\n markdown += ` - **Choices:** ${optionConfig.choices.map(c => `\\`${c}\\``).join(', ')}\\n`;\n }\n\n // Add default if available\n if (optionConfig.default !== undefined) {\n markdown += ` - **Default:** \\`${optionConfig.default}\\`\\n`;\n }\n\n markdown += '\\n';\n }\n\n return markdown.trim();\n}\n\nfunction updateReadmeWithOptionsMarkdown(optionsMarkdown: string): void {\n const readmeContent = fs.readFileSync(README_PATH, 'utf8');\n\n const beginMarker = '';\n const endMarker = '';\n\n const beginIndex = readmeContent.indexOf(beginMarker);\n const endIndex = readmeContent.indexOf(endMarker);\n\n if (beginIndex === -1 || endIndex === -1) {\n console.warn('Could not find auto-generated options markers in README.md');\n return;\n }\n\n const before = readmeContent.substring(0, beginIndex + beginMarker.length);\n const after = readmeContent.substring(endIndex);\n\n const updatedContent = before + '\\n\\n' + optionsMarkdown + '\\n\\n' + after;\n\n fs.writeFileSync(README_PATH, updatedContent);\n console.log('Updated README.md with options markdown');\n}\n\n// Helper to convert Zod schema to JSON schema-like object for docs\nfunction getZodTypeInfo(schema: ZodSchema): TypeInfo {\n let description = schema.description;\n let def = schema._def;\n let defaultValue: unknown;\n\n // Unwrap optional/default/effects\n while (\n def.typeName === 'ZodOptional' ||\n def.typeName === 'ZodDefault' ||\n def.typeName === 'ZodEffects'\n ) {\n if (def.typeName === 'ZodDefault' && def.defaultValue) {\n defaultValue = def.defaultValue();\n }\n const next = def.innerType || def.schema;\n if (!next) {\n break;\n }\n schema = next;\n def = schema._def;\n if (!description && schema.description) {\n description = schema.description;\n }\n }\n\n const result: TypeInfo = {type: 'unknown'};\n if (description) {\n result.description = description;\n }\n if (defaultValue !== undefined) {\n result.default = defaultValue;\n }\n\n switch (def.typeName) {\n case 'ZodString':\n result.type = 'string';\n break;\n case 'ZodNumber':\n result.type = def.checks?.some((c: ZodCheck) => c.kind === 'int')\n ? 'integer'\n : 'number';\n break;\n case 'ZodBoolean':\n result.type = 'boolean';\n break;\n case 'ZodEnum':\n result.type = 'string';\n result.enum = def.values;\n break;\n case 'ZodArray':\n result.type = 'array';\n if (def.type) {\n result.items = getZodTypeInfo(def.type);\n }\n break;\n default:\n result.type = 'unknown';\n }\n return result;\n}\n\nfunction isRequired(schema: ZodSchema): boolean {\n let def = schema._def;\n while (def.typeName === 'ZodEffects') {\n if (!def.schema) {\n break;\n }\n schema = def.schema;\n def = schema._def;\n }\n return def.typeName !== 'ZodOptional' && def.typeName !== 'ZodDefault';\n}\n\nasync function generateReference(\n title: string,\n outputPath: string,\n toolsWithAnnotations: ToolWithAnnotations[],\n categories: Record,\n sortedCategories: string[],\n serverArgs: string[],\n) {\n console.log(`Found ${toolsWithAnnotations.length} tools`);\n\n // Generate markdown documentation\n let markdown = `\n\n# ${title} (~${(await measureServer(serverArgs)).tokenCount} cl100k_base tokens)\n\n`;\n // Generate table of contents\n for (const category of sortedCategories) {\n const categoryTools = categories[category];\n const categoryName = labels[category];\n const anchorName = categoryName.toLowerCase().replace(/\\s+/g, '-');\n markdown += `- **[${categoryName}](#${anchorName})** (${categoryTools.length} tools)\\n`;\n\n // Sort tools within category for TOC\n categoryTools.sort((a: Tool, b: Tool) => a.name.localeCompare(b.name));\n for (const tool of categoryTools) {\n // Generate proper markdown anchor link: backticks are removed, keep underscores, lowercase\n const anchorLink = tool.name.toLowerCase();\n markdown += ` - [\\`${tool.name}\\`](#${anchorLink})\\n`;\n }\n }\n markdown += '\\n';\n\n for (const category of sortedCategories) {\n const categoryTools = categories[category];\n const categoryName = labels[category];\n\n markdown += `## ${categoryName}\\n\\n`;\n\n // Sort tools within category\n categoryTools.sort((a: Tool, b: Tool) => a.name.localeCompare(b.name));\n\n for (const tool of categoryTools) {\n markdown += `### \\`${tool.name}\\`\\n\\n`;\n\n if (tool.description) {\n // Escape HTML tags but preserve JS function syntax\n let escapedDescription = escapeHtmlTags(tool.description);\n\n // Add cross-links to mentioned tools\n escapedDescription = addCrossLinks(\n escapedDescription,\n toolsWithAnnotations,\n );\n markdown += `**Description:** ${escapedDescription}\\n\\n`;\n }\n\n // Handle input schema\n if (\n tool.inputSchema &&\n tool.inputSchema.properties &&\n Object.keys(tool.inputSchema.properties).length > 0\n ) {\n const properties = tool.inputSchema.properties;\n const required = tool.inputSchema.required || [];\n\n markdown += '**Parameters:**\\n\\n';\n\n const propertyNames = Object.keys(properties).sort((a, b) => {\n const aRequired = required.includes(a);\n const bRequired = required.includes(b);\n if (aRequired && !bRequired) {\n return -1;\n }\n if (!aRequired && bRequired) {\n return 1;\n }\n return a.localeCompare(b);\n });\n for (const propName of propertyNames) {\n const prop = properties[propName] as TypeInfo;\n const isRequired = required.includes(propName);\n const requiredText = isRequired ? ' **(required)**' : ' _(optional)_';\n\n let typeInfo = prop.type || 'unknown';\n if (prop.enum) {\n typeInfo = `enum: ${prop.enum.map((v: string) => `\"${v}\"`).join(', ')}`;\n }\n\n markdown += `- **${propName}** (${typeInfo})${requiredText}`;\n if (prop.description) {\n let escapedParamDesc = escapeHtmlTags(prop.description);\n\n // Add cross-links to mentioned tools\n escapedParamDesc = addCrossLinks(\n escapedParamDesc,\n toolsWithAnnotations,\n );\n markdown += `: ${escapedParamDesc}`;\n }\n markdown += '\\n';\n }\n markdown += '\\n';\n } else {\n markdown += '**Parameters:** None\\n\\n';\n }\n\n markdown += '---\\n\\n';\n }\n }\n\n // Write the documentation to file\n fs.writeFileSync(outputPath, markdown.trim() + '\\n');\n\n console.log(\n `Generated documentation for ${toolsWithAnnotations.length} tools in ${outputPath}`,\n );\n}\n\n// eslint-disable-next-line @typescript-eslint/no-explicit-any\nfunction getToolsAndCategories(tools: any) {\n // Convert ToolDefinitions to ToolWithAnnotations\n const toolsWithAnnotations: ToolWithAnnotations[] = tools\n .filter(tool => {\n if (!tool.annotations.conditions) {\n return true;\n }\n\n // Only include unconditional tools.\n return tool.annotations.conditions.length === 0;\n })\n .map(tool => {\n const properties: Record = {};\n const required: string[] = [];\n\n for (const [key, schema] of Object.entries(\n tool.schema as unknown as Record,\n )) {\n const info = getZodTypeInfo(schema);\n properties[key] = info;\n if (isRequired(schema)) {\n required.push(key);\n }\n }\n\n return {\n name: tool.name,\n description: tool.description,\n inputSchema: {\n type: 'object',\n properties,\n required,\n },\n annotations: tool.annotations,\n };\n });\n // Group tools by category (based on annotations)\n const categories: Record = {};\n toolsWithAnnotations.forEach((tool: ToolWithAnnotations) => {\n const category = tool.annotations?.category || 'Uncategorized';\n if (!categories[category]) {\n categories[category] = [];\n }\n categories[category].push(tool);\n });\n\n // Sort categories using the enum order\n const categoryOrder = Object.values(ToolCategory);\n const sortedCategories = Object.keys(categories).sort((a, b) => {\n const aIndex = categoryOrder.indexOf(a);\n const bIndex = categoryOrder.indexOf(b);\n // Put known categories first, unknown categories last\n if (aIndex === -1 && bIndex === -1) {\n return a.localeCompare(b);\n }\n if (aIndex === -1) {\n return 1;\n }\n if (bIndex === -1) {\n return -1;\n }\n return aIndex - bIndex;\n });\n return {toolsWithAnnotations, categories, sortedCategories};\n}\n\nasync function generateToolDocumentation(): Promise {\n try {\n console.log('Generating tool documentation from definitions...');\n\n {\n const {toolsWithAnnotations, categories, sortedCategories} =\n getToolsAndCategories(createTools({slim: false} as ParsedArguments));\n await generateReference(\n 'Chrome DevTools MCP Tool Reference',\n OUTPUT_PATH,\n toolsWithAnnotations,\n categories,\n sortedCategories,\n [],\n );\n\n // Generate tools TOC and update README\n const toolsTOC = generateToolsTOC(categories, sortedCategories);\n updateReadmeWithToolsTOC(toolsTOC);\n }\n\n {\n const {toolsWithAnnotations, categories, sortedCategories} =\n getToolsAndCategories(createTools({slim: true} as ParsedArguments));\n await generateReference(\n 'Chrome DevTools MCP Slim Tool Reference',\n SLIM_OUTPUT_PATH,\n toolsWithAnnotations,\n categories,\n sortedCategories,\n ['--slim'],\n );\n }\n\n // Generate and update configuration options\n const optionsMarkdown = generateConfigOptionsMarkdown();\n updateReadmeWithOptionsMarkdown(optionsMarkdown);\n process.exit(0);\n } catch (error) {\n console.error('Error generating documentation:', error);\n process.exit(1);\n }\n}\n\n// Run the documentation generator\ngenerateToolDocumentation().catch(console.error);\n" }, { "path": "scripts/post-build.ts", "content": "/**\n * @license\n * Copyright 2025 Google LLC\n * SPDX-License-Identifier: Apache-2.0\n */\n\nimport * as fs from 'node:fs';\nimport * as path from 'node:path';\n\nconst BUILD_DIR = path.join(process.cwd(), 'build');\n\n/**\n * Writes content to a file.\n * @param filePath The path to the file.\n * @param content The content to write.\n */\nfunction writeFile(filePath: string, content: string): void {\n fs.writeFileSync(filePath, content, 'utf-8');\n}\n\nfunction main(): void {\n const devtoolsThirdPartyPath =\n 'node_modules/chrome-devtools-frontend/front_end/third_party';\n const devtoolsFrontEndCorePath =\n 'node_modules/chrome-devtools-frontend/front_end/core';\n\n // Create i18n mock\n const i18nDir = path.join(BUILD_DIR, devtoolsFrontEndCorePath, 'i18n');\n const localesFile = path.join(i18nDir, 'locales.js');\n const localesContent = `\nexport const LOCALES = [\n 'en-US',\n];\n\nexport const BUNDLED_LOCALES = [\n 'en-US',\n];\n\nexport const DEFAULT_LOCALE = 'en-US';\n\nexport const REMOTE_FETCH_PATTERN = '@HOST@/remote/serve_file/@VERSION@/core/i18n/locales/@LOCALE@.json';\n\nexport const LOCAL_FETCH_PATTERN = './locales/@LOCALE@.json';`;\n writeFile(localesFile, localesContent);\n\n // Create codemirror.next mock.\n const codeMirrorDir = path.join(\n BUILD_DIR,\n devtoolsThirdPartyPath,\n 'codemirror.next',\n );\n fs.mkdirSync(codeMirrorDir, {recursive: true});\n const codeMirrorFile = path.join(codeMirrorDir, 'codemirror.next.js');\n const codeMirrorContent = `export default {}`;\n writeFile(codeMirrorFile, codeMirrorContent);\n\n // Create root mock\n const rootDir = path.join(BUILD_DIR, devtoolsFrontEndCorePath, 'root');\n fs.mkdirSync(rootDir, {recursive: true});\n const runtimeFile = path.join(rootDir, 'Runtime.js');\n const runtimeContent = `\nexport function getChromeVersion() { return ''; };\nexport const hostConfig = {};\nexport const Runtime = {\n isDescriptorEnabled: () => true,\n queryParam: () => null,\n}\nexport const experiments = {\n isEnabled: () => false,\n}\nexport const ExperimentName = {\n ALL: '*',\n CAPTURE_NODE_CREATION_STACKS: 'capture-node-creation-stacks',\n LIVE_HEAP_PROFILE: 'live-heap-profile',\n PROTOCOL_MONITOR: 'protocol-monitor',\n SAMPLING_HEAP_PROFILER_TIMELINE: 'sampling-heap-profiler-timeline',\n SHOW_OPTION_TO_EXPOSE_INTERNALS_IN_HEAP_SNAPSHOT: 'show-option-to-expose-internals-in-heap-snapshot',\n TIMELINE_INVALIDATION_TRACKING: 'timeline-invalidation-tracking',\n TIMELINE_SHOW_ALL_EVENTS: 'timeline-show-all-events',\n TIMELINE_V8_RUNTIME_CALL_STATS: 'timeline-v8-runtime-call-stats',\n APCA: 'apca',\n FONT_EDITOR: 'font-editor',\n FULL_ACCESSIBILITY_TREE: 'full-accessibility-tree',\n CONTRAST_ISSUES: 'contrast-issues',\n EXPERIMENTAL_COOKIE_FEATURES: 'experimental-cookie-features',\n INSTRUMENTATION_BREAKPOINTS: 'instrumentation-breakpoints',\n AUTHORED_DEPLOYED_GROUPING: 'authored-deployed-grouping',\n JUST_MY_CODE: 'just-my-code',\n USE_SOURCE_MAP_SCOPES: 'use-source-map-scopes',\n TIMELINE_SHOW_POST_MESSAGE_EVENTS: 'timeline-show-postmessage-events',\n TIMELINE_DEBUG_MODE: 'timeline-debug-mode',\n}\n `;\n writeFile(runtimeFile, runtimeContent);\n\n copyDevToolsDescriptionFiles();\n}\n\nfunction copyDevToolsDescriptionFiles() {\n const devtoolsIssuesDescriptionPath =\n 'node_modules/chrome-devtools-frontend/front_end/models/issues_manager/descriptions';\n const sourceDir = path.join(process.cwd(), devtoolsIssuesDescriptionPath);\n const destDir = path.join(\n BUILD_DIR,\n 'src',\n 'third_party',\n 'issue-descriptions',\n );\n fs.cpSync(sourceDir, destDir, {recursive: true});\n}\n\nmain();\n" }, { "path": "scripts/prepare.ts", "content": "/**\n * @license\n * Copyright 2025 Google LLC\n * SPDX-License-Identifier: Apache-2.0\n */\n\nimport {readFileSync, writeFileSync} from 'node:fs';\nimport {rm} from 'node:fs/promises';\nimport {resolve} from 'node:path';\n\nconst projectRoot = process.cwd();\n\nconst filesToRemove = [\n 'node_modules/chrome-devtools-frontend/package.json',\n 'node_modules/chrome-devtools-frontend/front_end/models/trace/lantern/testing',\n 'node_modules/chrome-devtools-frontend/front_end/third_party/intl-messageformat/package/package.json',\n];\n\n/**\n * Removes the conflicting global HTMLElementEventMap declaration from\n * @paulirish/trace_engine/models/trace/ModelImpl.d.ts to avoid TS2717 error\n * when both chrome-devtools-frontend and @paulirish/trace_engine declare\n * the same property.\n */\nfunction removeConflictingGlobalDeclaration(): void {\n const filePath = resolve(\n projectRoot,\n 'node_modules/@paulirish/trace_engine/models/trace/ModelImpl.d.ts',\n );\n console.log(\n 'Removing conflicting global declaration from @paulirish/trace_engine...',\n );\n const content = readFileSync(filePath, 'utf-8');\n // Remove the declare global block using regex\n // Matches: declare global { ... interface HTMLElementEventMap { ... } ... }\n const newContent = content.replace(\n /declare global\\s*\\{\\s*interface HTMLElementEventMap\\s*\\{[^}]*\\[ModelUpdateEvent\\.eventName\\]:\\s*ModelUpdateEvent;\\s*\\}\\s*\\}/s,\n '',\n );\n writeFileSync(filePath, newContent, 'utf-8');\n console.log('Successfully removed conflicting global declaration.');\n}\n\nasync function main() {\n console.log('Running prepare script to clean up chrome-devtools-frontend...');\n for (const file of filesToRemove) {\n const fullPath = resolve(projectRoot, file);\n console.log(`Removing: ${file}`);\n try {\n await rm(fullPath, {recursive: true, force: true});\n } catch (error) {\n console.error(`Failed to remove ${file}:`, error);\n process.exit(1);\n }\n }\n console.log('Clean up of chrome-devtools-frontend complete.');\n\n removeConflictingGlobalDeclaration();\n}\n\nvoid main();\n" }, { "path": "scripts/test.mjs", "content": "/**\n * @license\n * Copyright 2026 Google LLC\n * SPDX-License-Identifier: Apache-2.0\n */\n\n// Note: can be converted to ts file once node 20 support is dropped.\n// Node 20 does not support --experimental-strip-types flag.\n\nimport {spawn, execSync} from 'node:child_process';\nimport path from 'node:path';\nimport process from 'node:process';\n\nconst args = process.argv.slice(2);\nconst userArgs = args.filter(arg => !arg.startsWith('-'));\nconst flags = args.filter(arg => arg.startsWith('-'));\n\nconst files = [];\n\nlet shouldRetry = false;\nconst retryIndex = flags.indexOf('--retry');\nif (retryIndex !== -1) {\n shouldRetry = true;\n flags.splice(retryIndex, 1);\n}\n\nif (userArgs.length > 0) {\n for (const arg of userArgs) {\n // Map .ts files to build/ .js files\n let testPath = arg;\n if (testPath.endsWith('.ts')) {\n testPath = testPath.replace(/\\.ts$/, '.js');\n if (!testPath.startsWith('build/')) {\n testPath = path.join('build', testPath);\n }\n }\n files.push(testPath);\n }\n} else {\n const isNode20 = process.version.startsWith('v20.');\n if (isNode20) {\n files.push('build/tests');\n } else {\n files.push('build/tests/**/*.test.js');\n }\n}\n\nconst nodeArgs = [\n '--import',\n './build/tests/setup.js',\n '--no-warnings=ExperimentalWarning',\n '--test-reporter',\n (process.env['NODE_TEST_REPORTER'] ?? process.env['CI']) ? 'spec' : 'dot',\n '--test-force-exit',\n '--test-concurrency=1',\n '--test',\n '--test-timeout=60000',\n ...flags,\n ...files,\n];\n\nfunction installChrome(version) {\n try {\n return execSync(\n `npx puppeteer browsers install chrome@${version} --format \"{{path}}\"`,\n )\n .toString()\n .trim();\n } catch (e) {\n console.error(`Failed to install Chrome ${version}:`, e);\n process.exit(1);\n }\n}\n\nasync function runTests(attempt) {\n if (attempt > 1) {\n console.log(`\\nRun attempt ${attempt}...\\n`);\n }\n return new Promise(resolve => {\n const child = spawn('node', nodeArgs, {\n stdio: 'inherit',\n env: {\n ...process.env,\n CHROME_DEVTOOLS_MCP_NO_USAGE_STATISTICS: true,\n CHROME_DEVTOOLS_MCP_CRASH_ON_UNCAUGHT: true,\n },\n });\n\n child.on('close', code => {\n resolve(code);\n });\n });\n}\n\nconst chromePath = installChrome('146.0.7680.31');\nprocess.env.CHROME_M146_EXECUTABLE_PATH = chromePath;\n\nconst maxAttempts = shouldRetry ? 3 : 1;\nlet exitCode = 1;\n\nfor (let i = 1; i <= maxAttempts; i++) {\n exitCode = await runTests(i);\n if (exitCode === 0) {\n break;\n }\n}\n\nprocess.exit(exitCode ?? 1);\n" }, { "path": "scripts/tsconfig.json", "content": "{\n \"extends\": \"../tsconfig.json\",\n \"compilerOptions\": {\n \"target\": \"esnext\",\n \"module\": \"nodenext\",\n \"moduleResolution\": \"nodenext\",\n \"outDir\": \"./ignored\",\n \"rootDir\": \".\",\n \"strict\": true,\n \"esModuleInterop\": true,\n \"skipLibCheck\": true,\n \"forceConsistentCasingInFileNames\": true,\n \"noImplicitReturns\": true,\n \"noImplicitOverride\": true,\n \"noFallthroughCasesInSwitch\": true,\n \"incremental\": true,\n \"allowJs\": true,\n \"allowImportingTsExtensions\": true,\n \"noEmit\": true,\n \"useUnknownInCatchVariables\": false\n },\n \"include\": [\"./**/*.ts\", \"./**/*.js\", \"./**/*.mjs\"]\n}\n" }, { "path": "scripts/update-lighthouse.ts", "content": "/**\n * @license\n * Copyright 2026 Google LLC\n * SPDX-License-Identifier: Apache-2.0\n */\n\nimport {execSync} from 'node:child_process';\nimport fs from 'node:fs';\nimport path from 'node:path';\n\nconst ROOT_DIR = process.cwd();\nconst LIGHTHOUSE_DIR = path.resolve(ROOT_DIR, '../lighthouse');\nconst DEST_DIR = path.join(ROOT_DIR, 'src/third_party');\n\nfunction main() {\n if (!fs.existsSync(LIGHTHOUSE_DIR)) {\n console.error(`Lighthouse directory not found at ${LIGHTHOUSE_DIR}`);\n process.exit(1);\n }\n\n console.log('Running yarn in lighthouse directory...');\n execSync('yarn', {cwd: LIGHTHOUSE_DIR, stdio: 'inherit'});\n\n console.log('Building lighthouse-devtools-mcp bundle...');\n execSync('yarn build-devtools-mcp', {cwd: LIGHTHOUSE_DIR, stdio: 'inherit'});\n\n const bundlePath = path.join(\n LIGHTHOUSE_DIR,\n 'dist',\n 'lighthouse-devtools-mcp-bundle.js',\n );\n\n console.log(`Copying bundle from ${bundlePath} to ${DEST_DIR}...`);\n fs.copyFileSync(\n bundlePath,\n path.join(DEST_DIR, 'lighthouse-devtools-mcp-bundle.js'),\n );\n\n const noticesPath = path.join(\n LIGHTHOUSE_DIR,\n 'dist',\n 'LIGHTHOUSE_MCP_BUNDLE_THIRD_PARTY_NOTICES',\n );\n\n console.log(`Copying notices from ${noticesPath} to ${DEST_DIR}...`);\n fs.copyFileSync(\n noticesPath,\n path.join(DEST_DIR, 'LIGHTHOUSE_MCP_BUNDLE_THIRD_PARTY_NOTICES'),\n );\n\n console.log('Done.');\n}\n\nmain();\n" }, { "path": "scripts/verify-npm-package.mjs", "content": "/**\n * @license\n * Copyright 2026 Google LLC\n * SPDX-License-Identifier: Apache-2.0\n */\n\nimport {execSync} from 'node:child_process';\n\n// Checks that the select build files are present using `npm publish --dry-run`.\nfunction verifyPackageContents() {\n try {\n const output = execSync('npm publish --dry-run --json --silent', {\n encoding: 'utf8',\n });\n // skip non-JSON output from prepare.\n const data = JSON.parse(output.substring(output.indexOf('{')));\n const files = data.files.map(f => f.path);\n // Check some important files.\n const requiredPaths = [\n 'build/src/index.js',\n 'build/src/third_party/index.js',\n ];\n for (const requiredPath of requiredPaths) {\n const hasBuildFolder = files.some(path => path.startsWith(requiredPath));\n if (!hasBuildFolder) {\n console.error(\n `Assertion Failed: \"${requiredPath}\" not found in tarball.`,\n );\n process.exit(1);\n }\n }\n console.log(\n `npm publish --dry-run contained ${JSON.stringify(requiredPaths)}`,\n );\n } catch (err) {\n console.error('failed to parse npm publish output', err);\n process.exit(1);\n }\n}\n\nverifyPackageContents();\n" }, { "path": "scripts/verify-server-json-version.ts", "content": "/**\n * @license\n * Copyright 2025 Google LLC\n * SPDX-License-Identifier: Apache-2.0\n */\n\nimport {execSync} from 'node:child_process';\nimport fs from 'node:fs';\nimport os from 'node:os';\nimport path from 'node:path';\n\nconst serverJsonFilePath = path.join(process.cwd(), 'server.json');\nconst serverJson = JSON.parse(fs.readFileSync(serverJsonFilePath, 'utf-8'));\n\nconst tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'mcp-verify-'));\n\ntry {\n const osName = os.platform();\n const arch = os.arch();\n let platform = '';\n if (osName === 'darwin') {\n platform = 'darwin';\n } else if (osName === 'linux') {\n platform = 'linux';\n }\n // mcp-publisher does not support windows\n else {\n throw new Error(`Unsupported platform: ${osName}`);\n }\n\n let archName = '';\n if (arch === 'x64') {\n archName = 'amd64';\n } else if (arch === 'arm64') {\n archName = 'arm64';\n } else {\n throw new Error(`Unsupported architecture: ${arch}`);\n }\n\n const osArch = `${platform}_${archName}`;\n const binName = 'mcp-publisher';\n const downloadUrl = `https://github.com/modelcontextprotocol/registry/releases/latest/download/${binName}_${osArch}.tar.gz`;\n\n console.log(`Downloading ${binName} from ${downloadUrl}`);\n const downloadCmd = `curl -L \"${downloadUrl}\" | tar xz -C \"${tmpDir}\" ${binName}`;\n execSync(downloadCmd, {stdio: 'inherit'});\n\n const publisherPath = path.join(tmpDir, binName);\n fs.chmodSync(publisherPath, 0o755);\n console.log(`Downloaded to ${publisherPath}`);\n\n // Create the new server.json in the temporary directory\n execSync(`${publisherPath} init`, {cwd: tmpDir, stdio: 'inherit'});\n\n const newServerJsonPath = path.join(tmpDir, 'server.json');\n const newServerJson = JSON.parse(fs.readFileSync(newServerJsonPath, 'utf-8'));\n\n const propertyToVerify = ['$schema'];\n const diffProps = [];\n\n for (const prop of propertyToVerify) {\n if (serverJson[prop] !== newServerJson[prop]) {\n diffProps.push(prop);\n }\n }\n\n if (diffProps.length) {\n throw new Error(\n `The following props in ${serverJsonFilePath} did not match the latest init value:\\n${diffProps.map(\n prop =>\n `- \"${prop}\": expected \"${newServerJson[prop]}\", got \"${serverJson[prop]}\"`,\n )}`,\n );\n }\n} finally {\n fs.rmSync(tmpDir, {recursive: true, force: true});\n}\n" }, { "path": "server.json", "content": "{\n \"$schema\": \"https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json\",\n \"name\": \"io.github.ChromeDevTools/chrome-devtools-mcp\",\n \"title\": \"Chrome DevTools MCP\",\n \"description\": \"MCP server for Chrome DevTools\",\n \"repository\": {\n \"url\": \"https://github.com/ChromeDevTools/chrome-devtools-mcp\",\n \"source\": \"github\"\n },\n \"version\": \"0.20.2\",\n \"packages\": [\n {\n \"registryType\": \"npm\",\n \"registryBaseUrl\": \"https://registry.npmjs.org\",\n \"identifier\": \"chrome-devtools-mcp\",\n \"version\": \"0.20.2\",\n \"transport\": {\n \"type\": \"stdio\"\n },\n \"environmentVariables\": []\n }\n ]\n}\n" }, { "path": "skills/a11y-debugging/SKILL.md", "content": "---\nname: a11y-debugging\ndescription: Uses Chrome DevTools MCP for accessibility (a11y) debugging and auditing based on web.dev guidelines. Use when testing semantic HTML, ARIA labels, focus states, keyboard navigation, tap targets, and color contrast.\n---\n\n## Core Concepts\n\n**Accessibility Tree vs DOM**: Visually hiding an element (e.g., `CSS opacity: 0`) behaves differently for screen readers than `display: none` or `aria-hidden=\"true\"`. The `take_snapshot` tool returns the accessibility tree of the page, which represents what assistive technologies \"see\", making it the most reliable source of truth for semantic structure.\n\n**Reading web.dev documentation**: If you need to research specific accessibility guidelines (like `https://web.dev/articles/accessible-tap-targets`), you can append `.md.txt` to the URL (e.g., `https://web.dev/articles/accessible-tap-targets.md.txt`) to fetch the clean, raw markdown version. This is much easier to read!\n\n## Workflow Patterns\n\n### 1. Automated Audit (Lighthouse)\n\nStart by running a Lighthouse accessibility audit to get a comprehensive baseline. This tool provides a high-level score and lists specific failing elements with remediation advice.\n\n1. Run the audit:\n - Set `mode` to `\"navigation\"` to refresh the page and capture load issues.\n - Set `outputDirPath` (e.g., `/tmp/lh-report`) to save the full JSON report.\n2. **Analyze the Summary**:\n - Check `scores` (0-1 scale). A score < 1 indicates violations.\n - Review `audits.failed` count.\n3. **Review the Report (CRITICAL)**:\n - **Parsing**: Do not read the entire file line-by-line. Use a CLI tool like `jq` or a Node.js one-liner to filter for failures:\n ```bash\n # Extract failing audits with their details\n node -e \"const r=require('./report.json'); Object.values(r.audits).filter(a=>a.score!==null && a.score<1).forEach(a=>console.log(JSON.stringify({id:a.id, title:a.title, items:a.details?.items})))\"\n ```\n - This efficiently extracts the `selector` and `snippet` of failing elements without loading the full report into context.\n\n### 2. Browser Issues & Audits\n\nChrome automatically checks for common accessibility problems. Use `list_console_messages` to check for these native audits:\n\n- `types`: `[\"issue\"]`\n- `includePreservedMessages`: `true` (to catch issues that occurred during page load)\n\nThis often reveals missing labels, invalid ARIA attributes, and other critical errors without manual investigation.\n\n### 3. Semantics & Structure\n\nThe accessibility tree exposes the heading hierarchy and semantic landmarks.\n\n1. Navigate to the page.\n2. Use `take_snapshot` to capture the accessibility tree.\n3. **Check Heading Levels**: Ensure heading levels (`h1`, `h2`, `h3`, etc.) are logical and do not skip levels. The snapshot will include heading roles.\n4. **Content Reordering**: Verify that the DOM order (which drives the accessibility tree) matches the visual reading order. Use `take_screenshot` to inspect the visual layout and compare it against the snapshot structure to catch CSS floats or absolute positioning that jumbles the logical flow.\n\n### 4. Labels, Forms & Text Alternatives\n\n1. Locate buttons, inputs, and images in the `take_snapshot` output.\n2. Ensure interactive elements have an accessible name (e.g., a button should not just say `\"\"` if it only contains an icon).\n3. **Orphaned Inputs**: Verify that all form inputs have associated labels. Use `evaluate_script` with the **\"Find Orphaned Form Inputs\" snippet** found in [references/a11y-snippets.md](references/a11y-snippets.md).\n4. Check images for `alt` text.\n\n### 5. Focus & Keyboard Navigation\n\nTesting \"keyboard traps\" and proper focus management without visual feedback relies on tracking the focused element.\n\n1. Use the `press_key` tool with `\"Tab\"` or `\"Shift+Tab\"` to move focus.\n2. Use `take_snapshot` to capture the updated accessibility tree.\n3. Locate the element marked as focused in the snapshot to verify focus moved to the expected interactive element.\n4. If a modal opens, focus must move into the modal and \"trap\" within it until closed.\n\n### 6. Tap Targets and Visuals\n\nAccording to web.dev, tap targets should be at least 48x48 pixels with sufficient spacing. Since the accessibility tree doesn't show sizes, use `evaluate_script` with the **\"Measure Tap Target Size\" snippet** found in [references/a11y-snippets.md](references/a11y-snippets.md).\n\n_Pass the element's `uid` from the snapshot as an argument to `evaluate_script`._\n\n### 7. Color Contrast\n\nTo verify color contrast ratios, start by checking for native accessibility issues:\n\n1. Call `list_console_messages` with `types: [\"issue\"]`.\n2. Look for \"Low Contrast\" issues in the output.\n\nIf native audits do not report issues (which may happen in some headless environments) or if you need to check a specific element manually, use `evaluate_script` with the **\"Check Color Contrast\" snippet** found in [references/a11y-snippets.md](references/a11y-snippets.md).\n\n### 8. Global Page Checks\n\nVerify document-level accessibility settings often missed in component testing using the **\"Global Page Checks\" snippet** found in [references/a11y-snippets.md](references/a11y-snippets.md).\n\n## Troubleshooting\n\nIf standard a11y queries fail or the `evaluate_script` snippets return unexpected results:\n\n- **Visual Inspection**: If automated scripts cannot determine contrast (e.g., text over gradient images or complex backgrounds), use `take_screenshot` to capture the element. While models cannot measure exact contrast ratios from images, they can visually assess legibility and identify obvious issues.\n" }, { "path": "skills/a11y-debugging/references/a11y-snippets.md", "content": "# Accessibility Debugging Snippets\n\nUse these JavaScript snippets with the `evaluate_script` tool.\n\n## 1. Find Orphaned Form Inputs\n\nFinds form inputs that lack an associated label (no `label[for]`, `aria-label`, `aria-labelledby`, or wrapping `