\n
\n\n# Installation and Setup\n\nThis page covers all methods for installing and configuring the **chrome-devtools-mcp** project, including global CLI usage, local development setup, and MCP server integration.\n\n## Overview\n\nThe chrome-devtools-mcp project provides two primary interfaces:\n\n1. **CLI Tool** (`chrome-devtools`) - A command-line interface for terminal-based browser automation\n2. **MCP Server** - A Model Context Protocol server for integrating Chrome DevTools into AI assistants\n\nThe installation approach depends on your use case:\n\n| Use Case | Recommended Method | Installation Command |\n|----------|-------------------|---------------------|\n| Terminal automation | Global CLI | `npm i chrome-devtools-mcp@latest -g` |\n| AI assistant integration | MCP Server | Clone and build from source |\n| Development contribution | Local development | Clone, install dependencies, build |\n\n资料来源：[skills/chrome-devtools-cli/references/installation.md:1-5]()\n\n## Prerequisites\n\n### Node.js Version Requirement\n\nThe project requires a specific Node.js version defined in `.nvmrc`. Before installation, ensure you have the correct version:\n\n```bash\n# Check the required Node.js version\ncat .nvmrc\n```\n\nUsing a Node version manager (such as nvm) is strongly recommended to avoid permission errors and manage multiple Node versions.\n\n资料来源：[CONTRIBUTING.md:31-35]()\n\n### System Requirements\n\n- **Operating System**: macOS, Linux, or Windows with WSL\n- **Chrome/Chromium**: Chrome browser must be installed on the system\n- **npm**: Node Package Manager (included with Node.js)\n- **Optional**: ffmpeg (required only for experimental screencast feature)\n\n## Method 1: Global CLI Installation\n\n### Installation\n\nInstall the package globally to make the `chrome-devtools` command available system-wide:\n\n```bash\nnpm i chrome-devtools-mcp@latest -g\n```\n\n资料来源：[skills/chrome-devtools-cli/references/installation.md:5]()\n\n### Verification\n\nAfter installation, verify the setup:\n\n```bash\nchrome-devtools status\n```\n\nA successful output indicates the CLI is properly installed and accessible.\n\n资料来源：[skills/chrome-devtools-cli/references/installation.md:7]()\n\n## Method 2: Local Development Setup\n\nFor contributing to the project or running the latest development version:\n\n### Workflow Diagram\n\n```mermaid\ngraph TD\n A[Clone Repository] --> B[Check Node.js Version]\n B --> C{nvm installed?}\n C -->|No| D[Install nvm]\n C -->|Yes| E[Run nvm use]\n D --> E\n E --> F[Run npm ci]\n F --> G[Run npm run build]\n G --> H[Verify with npm run test]\n H --> I[Setup Complete]\n```\n\n### Step-by-Step Instructions\n\n#### 1. Clone the Repository\n\n```bash\ngit clone https://github.com/ChromeDevTools/chrome-devtools-mcp.git\ncd chrome-devtools-mcp\n```\n\n资料来源：[CONTRIBUTING.md:33-36]()\n\n#### 2. Set Node.js Version\n\n```bash\nnvm use\n```\n\nThis reads the version from `.nvmrc` and switches to the correct Node.js version.\n\n#### 3. Install Dependencies\n\n```bash\nnpm ci\n```\n\nThe `npm ci` command performs a clean install using the exact versions from `package-lock.json`, ensuring consistency across environments.\n\n资料来源：[CONTRIBUTING.md:36]()\n\n#### 4. Build the Project\n\n```bash\nnpm run build\n```\n\nThis command runs TypeScript compilation (`tsc`) and verifies the build succeeds. The build output is placed in the `build/` directory.\n\n资料来源：[AGENTS.md:5]()\n\n### Available npm Scripts\n\n| Script | Purpose |\n|--------|---------|\n| `npm run build` | Compile TypeScript and test build |\n| `npm run test` | Build and run all tests |\n| `npm run test 相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [AGENTS.md](https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/AGENTS.md)\n- [CONTRIBUTING.md](https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/CONTRIBUTING.md)\n- [skills/chrome-devtools-cli/references/installation.md](https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/skills/chrome-devtools-cli/references/installation.md)\n- [skills/chrome-devtools-cli/SKILL.md](https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/skills/chrome-devtools-cli/SKILL.md)\n- [package.json](https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/package.json)\n\n
\n\n# Configuration Reference\n\nThis page documents all configuration options available for the `chrome-devtools-mcp` project, covering CLI arguments, MCP server initialization, Puppeteer browser settings, and MCP client configuration files.\n\n## Overview\n\nThe `chrome-devtools-mcp` project supports multiple layers of configuration:\n\n1. **CLI Arguments** - Command-line flags passed when starting the MCP server or CLI\n2. **Puppeteer Configuration** - Browser launch and connection settings\n3. **MCP Client Configuration** - JSON configuration for connecting MCP clients\n\nConfiguration flows through the application as follows:\n\n```mermaid\ngraph TD\n A[CLI Arguments] --> B[chrome-devtools-mcp-cli-options.ts]\n B --> C[ParsedArguments Type]\n C --> D[chrome-devtools-mcp-main.ts]\n D --> E[Puppeteer Launch]\n F[.mcp.json] --> G[MCP Client]\n G --> H[MCP Server Connection]\n```\n\n## CLI Configuration\n\nThe MCP server accepts numerous command-line arguments for customization. These are defined in `src/bin/chrome-devtools-mcp-cli-options.ts` and typed via the `ParsedArguments` interface.\n\n### General Options\n\n| Option | Type | Default | Description |\n|--------|------|---------|-------------|\n| `--port` | `number` | `6274` | Port for the MCP server to listen on |\n| `--host` | `string` | `\"127.0.0.1\"` | Host address to bind |\n| `--log-file` | `string` | `undefined` | Path to write debug logs |\n| `--help` | `boolean` | `false` | Show help message |\n\n资料来源：[src/bin/chrome-devtools-mcp-cli-options.ts](src/bin/chrome-devtools-mcp-cli-options.ts)\n\n### Browser Connection Options\n\n| Option | Type | Default | Description |\n|--------|------|---------|-------------|\n| `--browserUrl` | `string` | `undefined` | Connect to an existing Chrome instance at this URL |\n| `--autoConnect` | `boolean` | `true` | Automatically connect to existing Chrome |\n| `--browserPath` | `string` | `undefined` | Custom path to Chrome executable |\n| `--userDataDir` | `string` | `undefined` | Chrome profile directory path |\n\n资料来源：[src/bin/chrome-devtools-mcp-cli-options.ts](src/bin/chrome-devtools-mcp-cli-options.ts)\n\n### Browser Launch Options\n\n| Option | Type | Default | Description |\n|--------|------|---------|-------------|\n| `--headless` | `boolean` | `true` | Run Chrome in headless mode |\n| `--sandbox` | `boolean` | `true` | Enable Chrome sandbox mode |\n| `--noFirstRun` | `boolean` | `true` | Skip first-run dialogs |\n| `--windowSize` | `string` | `\"1920x1080\"` | Default window dimensions |\n\n资料来源：[src/bin/chrome-devtools-mcp-cli-options.ts](src/bin/chrome-devtools-mcp-cli-options.ts)\n\n### MCP Server Categories\n\nThe MCP server organizes tools into categories. Categories can be enabled or disabled using `--category*` flags:\n\n| Option | Type | Default | Description |\n|--------|------|---------|-------------|\n| `--categoryNavigation` | `boolean` | `true` | Navigation tools (navigate_page, new_page) |\n| `--categoryInteraction` | `boolean` | `true` | Interaction tools (click, fill, type) |\n| `--categoryInspection` | `boolean` | `true` | Inspection tools (take_snapshot, take_screenshot) |\n| `--categoryPerformance` | `boolean` | `true` | Performance tools (traces, profiles) |\n| `--categoryNetwork` | `boolean` | `true` | Network tools (network_interceptor) |\n| `--categoryExtensions` | `boolean` | `false` | Chrome extension management |\n| `--categoryExperimental` | `boolean` | `false` | Experimental tools |\n| `--categoryExperimentalWebmcp` | `boolean` | `false` | WebMCP integration tools |\n| `--categoryDebugging` | `boolean` | `false` | Debugging utilities |\n\n```bash\n# Enable extension support\nchrome-devtools-mcp --categoryExtensions=true\n\n# Enable experimental features\nchrome-devtools-mcp --categoryExperimental=true --experimentalVision=true\n```\n\n资料来源：[src/tools/categories.ts](src/tools/categories.ts) 资料来源：[skills/chrome-devtools/SKILL.md](skills/chrome-devtools/SKILL.md)\n\n### Experimental Features\n\nExperimental features require explicit enabling via CLI flags:\n\n| Option | Type | Default | Description |\n|--------|------|---------|-------------|\n| `--experimentalVision` | `boolean` | `false` | Enable coordinate-based clicking (click_at) |\n| `--experimentalScreencast` | `boolean` | `false` | Enable screencast recording |\n\n```bash\n# Start with experimental vision mode\nchrome-devtools-mcp --experimentalVision=true\n```\n\n资料来源：[skills/chrome-devtools-cli/SKILL.md](skills/chrome-devtools-cli/SKILL.md)\n\n### Debugging Options\n\n| Option | Type | Default | Description |\n|--------|------|---------|-------------|\n| `--verbose` | `boolean` | `false` | Enable verbose logging |\n| `DEBUG` | `env` | `undefined` | Debug categories filter |\n\n```sh\n# Run with debug logging to log.txt\nnpx @modelcontextprotocol/inspector node /build/src/bin/chrome-devtools-mcp.js --log-file=/path/to/log.txt\n```\n\n资料来源：[CONTRIBUTING.md](CONTRIBUTING.md)\n\n## Puppeteer Configuration\n\nThe project uses Puppeteer for browser automation. Configuration is defined in `puppeteer.config.cjs` and can be overridden via CLI arguments.\n\n### Configuration File Structure\n\n```javascript\n// puppeteer.config.cjs\nmodule.exports = {\n puppeteer: {\n // Browser launch arguments\n args: [\n '--no-sandbox',\n '--disable-setuid-sandbox',\n '--disable-dev-shm-usage',\n ],\n // Default launch settings\n headless: true,\n }\n};\n```\n\n### Default Browser Arguments\n\nThe following Chromium arguments are passed by default:\n\n| Argument | Purpose |\n|----------|---------|\n| `--no-sandbox` | Disable sandbox (may be overridden by `--sandbox`) |\n| `--disable-setuid-sandbox` | Prevent setuid complications |\n| `--disable-dev-shm-usage` | Avoid shared memory issues in containers |\n| `--disable-web-security` | Disable web security for testing |\n| `--ash-no-nudges` | Disable Ash nudges |\n\n### Connection Modes\n\nThe MCP server supports two browser connection modes:\n\n```mermaid\ngraph TD\n A[Start chrome-devtools-mcp] --> B{--browserUrl provided?}\n B -->|Yes| C[Remote Connection Mode]\n B -->|No| D[Launch Mode]\n D --> E{--userDataDir provided?}\n E -->|Yes| F[Use existing profile]\n E -->|No| G[Create temporary profile]\n C --> H[Connect via CDP WebSocket]\n F --> I[Puppeteer.launch]\n G --> I\n```\n\n1. **Launch Mode** (default): Puppeteer launches a new Chrome instance\n2. **Remote Connection Mode**: Connect to an existing Chrome via `--browserUrl`\n\n资料来源：[src/bin/chrome-devtools-mcp-main.ts](src/bin/chrome-devtools-mcp-main.ts)\n\n## MCP Client Configuration\n\nThe `.mcp.json` file provides configuration for MCP clients connecting to the server.\n\n### Example Configuration\n\n```json\n{\n \"mcpServers\": {\n \"chrome-devtools\": {\n \"command\": \"npx\",\n \"args\": [\"chrome-devtools-mcp@latest\"],\n \"env\": {}\n }\n }\n}\n```\n\n### Extended Configuration Example\n\n```json\n{\n \"mcpServers\": {\n \"chrome-devtools\": {\n \"command\": \"node\",\n \"args\": [\n \"/path/to/chrome-devtools-mcp/build/src/bin/chrome-devtools-mcp.js\",\n \"--port\", \"6274\",\n \"--headless\", \"false\",\n \"--categoryExtensions\", \"true\"\n ],\n \"env\": {}\n }\n }\n}\n```\n\n### Configuration for Remote Connection\n\nTo connect to a specific Chrome instance:\n\n```json\n{\n \"mcpServers\": {\n \"chrome-devtools\": {\n \"command\": \"npx\",\n \"args\": [\n \"chrome-devtools-mcp@latest\",\n \"--browserUrl\", \"http://localhost:9222\",\n \"--autoConnect\", \"true\"\n ]\n }\n }\n}\n```\n\n资料来源：[.mcp.json](.mcp.json)\n\n## Tool Categories and Annotations\n\nTools are annotated with metadata that affects their availability based on configuration:\n\n### Category Reference\n\n| Category | Flag | Description |\n|----------|------|-------------|\n| `NAVIGATION` | `--categoryNavigation` | Page navigation and management |\n| `INTERACTION` | `--categoryInteraction` | User interaction (clicks, fills) |\n| `INSPECTION` | `--categoryInspection` | Page inspection (snapshots, screenshots) |\n| `PERFORMANCE` | `--categoryPerformance` | Performance profiling |\n| `NETWORK` | `--categoryNetwork` | Network request handling |\n| `EXTENSIONS` | `--categoryExtensions` | Chrome extension management |\n| `EXPERIMENTAL` | `--categoryExperimental` | Experimental tools |\n| `EXPERIMENTAL_WEBMCP` | `--categoryExperimentalWebmcp` | WebMCP integration |\n| `DEBUGGING` | `--categoryDebugging` | Debug utilities |\n\n### Tool Annotation Schema\n\n```typescript\ninterface ToolAnnotation {\n title?: string;\n category?: ToolCategory;\n conditions?: string[]; // Required flags for tool availability\n readOnlyHint?: boolean; // Indicates if tool modifies browser state\n}\n```\n\nTools marked with `readOnlyHint: false` may be blocked in read-only MCP modes.\n\n```mermaid\ngraph LR\n A[Tool Annotation] --> B[readOnlyHint]\n A --> C[category]\n A --> D[conditions]\n B --> E{Client Mode}\n C --> F[Category Filter]\n D --> G[Flag Check]\n E -->|Plan/ReadOnly| H[Only readOnlyHint=true]\n E -->|Normal| I[All tools]\n```\n\n资料来源：[src/tools/ToolDefinition.ts](src/tools/ToolDefinition.ts) 资料来源：[skills/troubleshooting/SKILL.md](skills/troubleshooting/SKILL.md)\n\n## Environment Variables\n\n| Variable | Description |\n|----------|-------------|\n| `DEBUG` | Controls debug logging categories (e.g., `DEBUG=*`) |\n| `PUPPETEER_SKIP_DOWNLOAD` | Skip Puppeteer browser download |\n| `PUPPETEER_EXECUTABLE_PATH` | Custom Chrome executable path |\n\n## Configuration Precedence\n\nConfiguration values are resolved in the following order (highest to lowest):\n\n1. **CLI Arguments** - Explicit flags passed at runtime\n2. **Environment Variables** - Set in shell or `.env` files\n3. **Configuration Files** - `.mcp.json`, `puppeteer.config.cjs`\n4. **Default Values** - Built-in defaults in source code\n\n```mermaid\ngraph TD\n A[Configuration Resolution] --> B[CLI Arguments]\n A --> C[Environment Variables]\n A --> D[Config Files]\n A --> E[Defaults]\n B --> F[Final Config]\n C --> F\n D --> F\n E --> F\n style B fill:#ff9999\n style F fill:#99ff99\n```\n\n## Quick Reference\n\n### Minimal Configuration\n\n```bash\n# Default settings (headless, localhost:6274)\nnpx chrome-devtools-mcp@latest\n```\n\n### Common Configurations\n\n```bash\n# Visible browser with extensions\nchrome-devtools-mcp --headless=false --categoryExtensions=true\n\n# Remote Chrome connection\nchrome-devtools-mcp --browserUrl=http://localhost:9222\n\n# Custom port\nchrome-devtools-mcp --port=9000\n```\n\n## Troubleshooting Configuration Issues\n\n| Symptom | Likely Cause | Solution |\n|---------|--------------|----------|\n| Only 9 tools available | Read-only mode enforced by MCP client | Disable read-only/Plan mode in client |\n| Extension tools missing | `--categoryExtensions` not enabled | Add `--categoryExtensions=true` |\n| New profile created instead of connecting | Incorrect `--browserUrl` or typo in flags | Verify URL and check for flag typos like `--autoBronnect` |\n| `chrome-devtools` command not found | PATH not configured | Ensure npm global bin is in PATH |\n\n资料来源：[skills/troubleshooting/SKILL.md](skills/troubleshooting/SKILL.md)\n\n---\n\n\n\n## System Architecture\n\n### 相关页面\n\n相关主题：[Project Overview](#overview), [MCP Protocol Integration](#mcp-protocol), [Telemetry and Monitoring](#telemetry)\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [src/bin/chrome-devtools-mcp-cli-options.ts](https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/src/bin/chrome-devtools-mcp-cli-options.ts)\n- [src/bin/chrome-devtools-mcp-main.ts](https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/src/bin/chrome-devtools-mcp-main.ts)\n- [puppeteer.config.cjs](https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/puppeteer.config.cjs)\n- [.mcp.json](https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/.mcp.json)\n\n
\n\n# System Architecture\n\n## Overview\n\nThe `chrome-devtools-mcp` project implements a Model Context Protocol (MCP) server that provides programmatic control over Chrome DevTools through a well-defined architecture of interconnected components. The system enables AI assistants and CLI tools to interact with a headless Chrome browser instance by exposing browser operations as typed tools with schema validation.\n\nThe architecture follows a layered design pattern with clear separation between the protocol layer (MCP), the tool definition system, browser management, and page-level interactions. This modular approach allows for extensibility while maintaining type safety and consistent behavior across all exposed functionality.\n\n资料来源：[AGENTS.md]()\n\n## High-Level Architecture\n\n```mermaid\ngraph TD\n subgraph \"Client Layer\"\n CLI[CLI ToolRelevant Source Files
\n\n以下源码文件用于生成本页说明：\n\n- [src/tools/ToolDefinition.ts](https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/src/tools/ToolDefinition.ts)\n- [src/PageCollector.ts](https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/src/PageCollector.ts)\n- [src/tools/webmcp.ts](https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/src/tools/webmcp.ts)\n- [src/tools/categories.ts](https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/src/tools/categories.ts)\n- [src/browser.ts](https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/src/browser.ts)\n- [AGENTS.md](https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/AGENTS.md)\nchrome-devtools]\n AI[AI Assistant
MCP Client]\n end\n\n subgraph \"MCP Protocol Layer\"\n MCP[MCP Server
Protocol Handler]\n TDEF[Tool Definitions
Registry]\n end\n\n subgraph \"Tool System\"\n PAGES[Page Tools
Context-Aware]\n GLOB[Global Tools
Browser-Level]\n end\n\n subgraph \"Browser Layer\"\n CHROME[Chrome Browser
Puppeteer/CDP]\n PAGES_BROWSER[Pages
Target Management]\n end\n\n CLI --> MCP\n AI --> MCP\n MCP --> TDEF\n TDEF --> PAGES\n TDEF --> GLOB\n MCP --> CHROME\n CHROME --> PAGES_BROWSER\n```\n\n## Core Components\n\n### 1. Tool Definition System\n\nThe tool definition system is the foundation of the MCP server's extensibility. It provides factory functions for creating both page-scoped and global tools with automatic schema validation.\n\n| Component | File | Purpose |\n|-----------|------|---------|\n| `defineTool` | `src/tools/ToolDefinition.ts:11-30` | Factory for global tools |\n| `definePageTool` | `src/tools/ToolDefinition.ts:52-90` | Factory for page-scoped tools |\n| `ToolCategory` | `src/tools/categories.ts` | Tool categorization enum |\n\nThe `defineTool` function supports two invocation patterns:\n\n```typescript\n// Direct tool definition\ndefineTool({\n name: 'tool_name',\n schema: { /* zod schema */ },\n handler: async (request, response, context) => { /* ... */ }\n});\n\n// Factory pattern with arguments\ndefineTool((args?: Args) => ({\n name: 'tool_name',\n schema: { /* zod schema using args */ },\n handler: async (request, response, context) => { /* ... */ }\n}));\n```\n\n资料来源：[src/tools/ToolDefinition.ts:11-30]()\n\n### 2. Page Scoped Tools\n\nPage-scoped tools are tools that operate within the context of a specific browser page. They receive an additional `page` property in the request object and have access to the page's DOM, JavaScript context, and rendering state.\n\n```typescript\nexport function definePageTool<\n Schema extends zod.ZodRawShape,\n Args extends ParsedArguments = ParsedArguments,\n>(\n definition:\n | PageToolDefinition
Event]\n DESTROYED[targetdestroyed
Event]\n end\n\n subgraph \"Storage\"\n STORAGE[(WeakMap<Page,
Array<Array<WithSymbolId<T>>>>)]\n end\n\n INIT --> ADD\n ADD --> LISTEN\n CREATED --> ADD\n LISTEN --> STORAGE\n```\n\nKey characteristics of the `PageCollector`:\n\n| Property | Description |\n|----------|-------------|\n| `#browser` | Reference to the Puppeteer Browser instance |\n| `#listenersInitializer` | Factory function for creating event listeners |\n| `#listeners` | WeakMap tracking active listeners per page |\n| `maxNavigationSaved` | Maximum navigations to retain (default: 3) |\n| `storage` | WeakMap storing collected data per page |\n\n资料来源：[src/PageCollector.ts]()\n\n### 4. Browser Management\n\nThe browser module (`src/browser.ts`) handles the initialization and lifecycle of the Puppeteer-based Chrome browser instance. It provides the foundation for all page operations and CDP (Chrome DevTools Protocol) interactions.\n\nThe browser layer is responsible for:\n\n- Launching headless Chrome with appropriate flags\n- Managing browser context and isolated worlds\n- Coordinating page creation and destruction\n- Providing access to CDP sessions for advanced operations\n\n资料来源：[src/browser.ts]()\n\n### 5. WebMCP Tool System\n\nThe WebMCP system allows pages to expose their own tools to the MCP server, enabling dynamic tool discovery and execution from web applications.\n\n```mermaid\ngraph LR\n WEB[Web Application
Exposes Tools]\n MCP[MCP Server]\n EXEC[execute_webmcp_tool]\n LIST[list_webmcp_tools]\n\n WEB --> LIST\n LIST --> WEB\n WEB --> EXEC\n EXEC --> WEB\n```\n\nTwo primary tools manage WebMCP functionality:\n\n| Tool | Purpose |\n|------|---------|\n| `list_webmcp_tools` | Enumerates all WebMCP tools exposed by the current page |\n| `execute_webmcp_tool` | Invokes a named WebMCP tool with optional parameters |\n\n```typescript\nexport const listWebMcpTools = definePageTool({\n name: 'list_webmcp_tools',\n description: `Lists all WebMCP tools the page exposes.`,\n annotations: {\n category: ToolCategory.WEBMCP,\n readOnlyHint: true,\n },\n schema: {},\n blockedByDialog: false,\n handler: async (_request, response, _context) => {\n response.setListWebMcpTools();\n },\n});\n```\n\n资料来源：[src/tools/webmcp.ts]()\n\n## Tool Categories\n\nTools are organized into categories for logical grouping and documentation purposes. The category system enables documentation generation and tool discovery.\n\n| Category | Description |\n|----------|-------------|\n| `WEBMCP` | Tools exposed by web pages themselves |\n| Navigation | Page navigation and history operations |\n| Input | Form filling, clicking, keyboard input |\n| Capture | Screenshots, snapshots, memory profiling |\n| Network | Network request inspection and manipulation |\n| Performance | Tracing, profiling, performance insights |\n\n资料来源：[src/tools/categories.ts]()\n\n## Request/Response Flow\n\n```mermaid\nsequenceDiagram\n participant Client\n participant MCP as MCP Server\n participant TDEF as Tool Definitions\n participant HANDLER as Tool Handler\n participant BROWSER as Browser/Page\n\n Client->>MCP: Tool Request (with args)\n MCP->>TDEF: Lookup Tool Definition\n TDEF-->>MCP: Schema + Handler Reference\n MCP->>MCP: Validate Arguments (Zod)\n MCP->>HANDLER: Invoke Handler(request, response, context)\n HANDLER->>BROWSER: CDP Commands / Puppeteer API\n BROWSER-->>HANDLER: Result\n HANDLER-->>MCP: Update Response\n MCP-->>Client: JSON-RPC Response\n```\n\n## Tool Schema System\n\nAll tool parameters are validated using Zod schemas, ensuring type safety and providing automatic OpenAPI-style documentation.\n\n```typescript\n// Schema definition example\nschema: {\n toolName: zod.string().describe('The name of the WebMCP tool to execute'),\n input: zod\n .string()\n .optional()\n .describe('The JSON-stringified parameters to pass to the WebMCP tool'),\n}\n```\n\nThe schema system supports:\n\n- **Required/Optional detection**: Automatically determines if fields are required based on Zod type\n- **Type transformations**: Applied via `.transform()` for input normalization\n- **Descriptions**: Extracted for documentation generation\n- **Enumerations**: Validated against allowed values\n\nCommon schema utilities include:\n\n| Schema | File | Purpose |\n|--------|------|---------|\n| `pageIdSchema` | `ToolDefinition.ts:95-97` | Optional page targeting |\n| `timeoutSchema` | `ToolDefinition.ts:99-107` | Timeout with zero-to-undefined transform |\n| `viewportTransform` | `ToolDefinition.ts` | Viewport dimension parsing |\n\n资料来源：[src/tools/ToolDefinition.ts:95-107]()\n\n## Error Handling Patterns\n\nThe architecture defines specific error constants for expected failure conditions:\n\n```typescript\nexport const CLOSE_PAGE_ERROR =\n 'The last open page cannot be closed. It is fine to keep it open.';\n```\n\nThis error message indicates that the MCP server intentionally allows users to keep the final browser page open rather than forcing closure, which is a deliberate UX decision for browser automation workflows.\n\n## Type Safety Guarantees\n\nThe codebase enforces strict TypeScript practices to maintain type safety:\n\n| Rule | Rationale |\n|------|-----------|\n| No `any` type | Prevents untyped data flow |\n| No `as` casting | Avoids bypass of type checking |\n| No `!` assertions | Prevents unsafe assumptions |\n| No `// @ts-ignore` | Maintains full type coverage |\n| Prefer `for..of` over `forEach` | Better async/await compatibility |\n\n资料来源：[AGENTS.md]()\n\n## Build and Test Infrastructure\n\n```mermaid\ngraph LR\n subgraph \"Build Commands\"\n BUILD[npm run build
tsc compilation]\n TEST[npm run test
Build + Run Tests]\n FORMAT[npm run format
Fix linting]\n GEN[npm run gen
Generate Docs]\n end\n\n subgraph \"Output Artifacts\"\n JS[JavaScript
/build/src]\n TYPES[Type Declarations
/build/src]\n DOCS[Markdown Docs
/skills/*]\n end\n\n BUILD --> JS\n BUILD --> TYPES\n TEST --> JS\n GEN --> DOCS\n```\n\nThe project uses a standardized build pipeline that ensures type correctness at compile time and provides consistent tooling for development tasks.\n\n## Summary\n\nThe chrome-devtools-mcp system architecture provides:\n\n1. **Extensible Tool System**: Factory functions for creating typed, validated tools\n2. **Page Context Awareness**: Automatic injection of page context into tool handlers\n3. **Event-Driven Page Management**: Observer pattern for tracking browser page lifecycle\n4. **Schema Validation**: Zod-based runtime validation with compile-time type inference\n5. **WebMCP Integration**: Bidirectional tool exposure between server and web pages\n6. **Strict Type Safety**: No escape hatches for type checking, ensuring reliability\n\nThis architecture enables reliable browser automation while maintaining the flexibility needed for diverse use cases ranging from simple navigation to complex performance profiling and accessibility debugging.\n\n---\n\n\n\n## MCP Protocol Integration\n\n### 相关页面\n\n相关主题：[System Architecture](#system-architecture), [Input and Navigation Automation Tools](#automation-tools), [Debugging and Inspection Tools](#debugging-tools)\n\n
\n
\n\n# MCP Protocol Integration\n\n## Overview\n\nThe `chrome-devtools-mcp` project implements a Model Context Protocol (MCP) server that enables AI assistants and MCP clients to interact with Chrome DevTools programmatically. This integration provides a standardized interface for browser automation, debugging, and performance analysis through a collection of well-defined tools.\n\nThe MCP protocol serves as the communication layer between AI assistants and the Chrome browser, allowing tools to be discovered, invoked, and executed remotely. The server handles tool registration, request routing, response formatting, and maintains state across multiple browser pages.\n\n资料来源：[src/index.ts:1-50](https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/src/index.ts)\n\n## Architecture\n\n### High-Level System Design\n\n```mermaid\ngraph TD\n MCP_CLIENT[\"MCP Client / AI Assistant\"]\n MCP_SERVER[\"MCP ServerRelevant Source Files
\n\n以下源码文件用于生成本页说明：\n\n- [src/index.ts](https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/src/index.ts)\n- [src/McpResponse.ts](https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/src/McpResponse.ts)\n- [src/tools/ToolDefinition.ts](https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/src/tools/ToolDefinition.ts)\n- [src/tools/webmcp.ts](https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/src/tools/webmcp.ts)\n- [src/tools/categories.ts](https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/src/tools/categories.ts)\n- [scripts/generate-docs.ts](https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/scripts/generate-docs.ts)\n(chrome-devtools-mcp)\"]\n TOOL_REGISTRY[\"Tool Registry\"]\n BROWSER[\"Chrome Browser\"]\n CDP[\"Chrome DevTools Protocol\"]\n \n MCP_CLIENT -->|\"Call Tool Request\"| MCP_SERVER\n MCP_SERVER -->|\"Tool Definitions\"| MCP_CLIENT\n MCP_SERVER --> TOOL_REGISTRY\n TOOL_REGISTRY -->|\"Handler Execution\"| MCP_SERVER\n MCP_SERVER -->|\"CDP Commands\"| BROWSER\n BROWSER --> CDP\n```\n\n### Tool Registration Flow\n\n```mermaid\ngraph TD\n START[\"Server Initialization\"] --> CREATE_TOOLS[\"createTools()\"]\n CREATE_TOOLS --> REGISTER[\"registerTool()\"]\n REGISTER --> DEFINE[\"definePageTool()\"]\n DEFINE --> SCHEMA[\"Schema Validation\"]\n SCHEMA --> HANDLER[\"Handler Mapping\"]\n HANDLER --> READY[\"Tool Available\"]\n \n STYLE REGISTER fill:#90EE90\n STYLE READY fill:#98FB98\n```\n\nThe MCP server initializes by invoking `createTools()` which returns an array of tool definitions. Each tool is then registered with the MCP server using the protocol's `setRequestHandler()` method. Tools are defined using `definePageTool()` which establishes the tool name, description, input schema, annotations, and handler function.\n\n资料来源：[src/index.ts:40-65](https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/src/index.ts)\n\n## Tool Definition System\n\n### ToolDefinition.ts Pattern\n\nTools are defined using the `definePageTool()` function which creates a structured tool definition with type-safe schemas. The definition includes metadata, validation rules, and the execution handler.\n\n```typescript\nexport const listWebMcpTools = definePageTool({\n name: 'list_webmcp_tools',\n description: `Lists all WebMCP tools the page exposes.`,\n annotations: {\n category: ToolCategory.WEBMCP,\n readOnlyHint: true,\n },\n schema: {},\n blockedByDialog: false,\n handler: async (_request, response, _context) => {\n response.setListWebMcpTools();\n },\n});\n```\n\n资料来源：[src/tools/webmcp.ts:15-27](https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/src/tools/webmcp.ts)\n\n### Tool Definition Structure\n\n| Property | Type | Description |\n|----------|------|-------------|\n| `name` | `string` | Unique identifier for the tool |\n| `description` | `string` | Human-readable description for the MCP client |\n| `annotations` | `ToolAnnotations` | Metadata about the tool's behavior |\n| `schema` | `ZodSchema` | Input validation schema |\n| `blockedByDialog` | `boolean` | Whether the tool waits for dialog dismissal |\n| `handler` | `AsyncHandler` | Function that executes the tool |\n\n### Tool Annotations\n\nThe annotation system provides additional metadata about tools that MCP clients can use for tool selection, permission handling, and UI display.\n\n```typescript\ninterface ToolAnnotations {\n category?: ToolCategory;\n readOnlyHint?: boolean;\n conditions?: string[];\n // Additional annotation properties...\n}\n```\n\n| Annotation | Type | Purpose |\n|------------|------|---------|\n| `category` | `ToolCategory` | Groups tools into logical categories |\n| `readOnlyHint` | `boolean` | Indicates if tool doesn't modify browser state |\n| `conditions` | `string[]` | Flags required for this tool to execute |\n\n资料来源：[src/tools/ToolDefinition.ts](https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/src/tools/ToolDefinition.ts)\n\n## Tool Categories\n\nTools are organized into categories that help MCP clients understand their purpose and scope.\n\n```mermaid\ngraph TD\n TOOLS[\"All Tools\"]\n NAV[\"Navigation
(navigate, new_page, close)\"]\n INPUT[\"Input Automation
(click, fill, type_text)\"]\n EMULATE[\"Emulation
(viewport, userAgent)\"]\n PERFORMANCE[\"Performance
(trace, analyze)\"]\n NETWORK[\"Network
(requests, cookies)\"]\n WEBMCP[\"WebMCP
(page-exposed tools)\"]\n \n TOOLS --> NAV\n TOOLS --> INPUT\n TOOLS --> EMULATE\n TOOLS --> PERFORMANCE\n TOOLS --> NETWORK\n TOOLS --> WEBMCP\n```\n\n### Available Categories\n\n| Category | Enum Value | Description |\n|----------|-------------|-------------|\n| Navigation | `ToolCategory.NAVIGATION` | Page navigation and management |\n| Input Automation | `ToolCategory.INPUT` | Element interaction and form input |\n| Emulation | `ToolCategory.EMULATION` | Browser environment simulation |\n| Performance | `ToolCategory.PERFORMANCE` | Tracing and performance analysis |\n| Network | `ToolCategory.NETWORK` | Network request inspection |\n| WebMCP | `ToolCategory.WEBMCP` | Tools exposed by the web page |\n| Accessibility | `ToolCategory.A11Y` | Accessibility auditing |\n| Debug | `ToolCategory.DEBUG` | JavaScript debugging tools |\n\n资料来源：[src/tools/categories.ts](https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/src/tools/categories.ts)\n\n## Response System\n\n### McpResponse Architecture\n\nThe response system formats tool execution results into structured MCP responses that include both human-readable markdown and machine-parseable structured content.\n\n```mermaid\ngraph LR\n REQUEST[\"Tool Request\"] --> HANDLER[\"Tool Handler\"]\n HANDLER --> RESPONSE[\"McpResponse\"]\n RESPONSE -->|Text Content| MARKDOWN[\"Markdown Output\"]\n RESPONSE -->|Structured Data| JSON[\"JSON / Structured\"]\n \n subgraph Response Components\n TOOL_DEFS[\"Tool Definitions\"]\n NETWORK[\"Network Requests\"]\n PAGINATION[\"Pagination Info\"]\n WEBMCP_TOOLS[\"WebMCP Tools\"]\n end\n \n RESPONSE --> TOOL_DEFS\n RESPONSE --> NETWORK\n RESPONSE --> PAGINATION\n RESPONSE --> WEBMCP_TOOLS\n```\n\n### Response Formatting Features\n\n| Feature | Description |\n|---------|-------------|\n| **Tool Definitions** | Lists all available tools with their schemas |\n| **Network Requests** | Includes network waterfall data when requested |\n| **Pagination** | Handles large result sets with pagination info |\n| **WebMCP Tools** | Lists tools exposed by the current web page |\n| **Structured Content** | Provides machine-readable data alongside text |\n\n资料来源：[src/McpResponse.ts:50-120](https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/src/McpResponse.ts)\n\n### Structured Content Model\n\nThe `structuredContent` object provides programmatic access to response data:\n\n```typescript\ninterface StructuredContent {\n webmcpTools?: WebMcpToolInfo[];\n networkRequests?: NetworkRequest[];\n pagination?: PaginationInfo;\n [key: string]: unknown;\n}\n```\n\n### Pagination Support\n\nWhen handling large datasets (e.g., network requests), the response includes pagination metadata:\n\n```typescript\nconst paginationData = this.#dataWithPagination(\n requests,\n this.#networkRequestsOptions.pagination,\n);\nstructuredContent.pagination = paginationData.pagination;\n```\n\n资料来源：[src/McpResponse.ts:150-180](https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/src/McpResponse.ts)\n\n## WebMCP Integration\n\nWebMCP enables web pages to expose custom tools that MCP clients can discover and invoke. This creates a two-way communication channel where the browser can extend its capabilities based on the loaded page.\n\n```mermaid\ngraph TD\n MCP_CLIENT[\"MCP Client\"]\n SERVER[\"MCP Server\"]\n CHROME[\"Chrome Browser\"]\n WEB_PAGE[\"Web Page\"]\n \n subgraph Discovery Flow\n CLIENT_LIST[\"list_webmcp_tools\"]\n SERVER -->|\"Query\"| CHROME\n CHROME --> WEB_PAGE\n WEB_PAGE -->|\"Exposes tools\"| CHROME\n CHROME -->|\"Tool list\"| SERVER\n SERVER -->|\"Tool names\"| CLIENT_LIST\n end\n \n subgraph Execution Flow\n EXEC[\"execute_webmcp_tool\"]\n CLIENT -->|\"toolName + input\"| SERVER\n SERVER -->|\"Forward\"| CHROME\n CHROME --> WEB_PAGE\n WEB_PAGE -->|\"Execute\"| RESULT[\"Result\"]\n end\n```\n\n### WebMCP Tools\n\n| Tool | Description | Parameters |\n|------|-------------|------------|\n| `list_webmcp_tools` | Lists all tools exposed by the current page | None |\n| `execute_webmcp_tool` | Invokes a WebMCP tool exposed by the page | `toolName`, `input` (JSON string) |\n\nThe `execute_webmcp_tool` accepts input as a JSON string which is parsed and passed to the page-exposed tool:\n\n```typescript\nlet input: Record
\n
\n\n# Input and Navigation Automation Tools\n\n## Overview\n\nThe Input and Navigation Automation Tools constitute the core interaction layer of the `chrome-devtools-mcp` project, enabling programmatic control over browser pages through the Chrome DevTools Protocol (CDP). These tools allow AI agents and automated scripts to simulate real user interactions including keyboard input, mouse actions, page navigation, and environment emulation.\n\n**资料来源:** [skills/chrome-devtools/SKILL.md](https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/skills/chrome-devtools/SKILL.md)\n\n## Architecture\n\nThe automation system is organized into three primary tool categories that work in concert to provide comprehensive browser control:\n\n```mermaid\ngraph TD\n A[chrome-devtools-mcp Tools] --> B[Input Tools]\n A --> C[Navigation Tools]\n A --> D[Emulation Tools]\n \n B --> B1[click]\n B --> B2[fill]\n B --> B3[type_text]\n B --> B4[press_key]\n B --> B5[hover]\n B --> B6[drag]\n B --> B7[upload_file]\n \n C --> C1[navigate_page]\n C --> C2[new_page]\n C --> C3[select_page]\n C --> C4[close_page]\n C --> C5[list_pages]\n \n D --> D1[emulate]\n D --> D2[resize_page]\n \n E[WaitForHelper] --> B\n E --> C\n```\n\n**资料来源:** [src/tools/ToolDefinition.ts](https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/src/tools/ToolDefinition.ts)\n\n## Input Tools\n\nInput tools provide the capability to simulate user interactions with page elements. All input operations require a valid element `uid` obtained from a previous `take_snapshot` call.\n\n**资料来源:** [skills/chrome-devtools-cli/SKILL.md](https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/skills/chrome-devtools-cli/SKILL.md)\n\n### Core Input Operations\n\n| Tool | Purpose | Key Parameters |\n|------|---------|----------------|\n| `click` | Click on an element | `uid` (required), `dblClick`, `includeSnapshot` |\n| `fill` | Fill text into input/select | `uid` (required), `value` (required), `includeSnapshot` |\n| `type_text` | Type text character by character | `text` (required), `submitKey`, `includeSnapshot` |\n| `press_key` | Press a key or combination | `key` (required), `includeSnapshot` |\n| `hover` | Hover over an element | `uid` (required), `includeSnapshot` |\n| `drag` | Drag element to destination | `src` (required), `dst` (required), `includeSnapshot` |\n| `upload_file` | Upload file via input element | `uid` (required), `filePath` (required), `includeSnapshot` |\n\n**资料来源:** [src/tools/input.ts](https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/src/tools/input.ts)\n\n### Keyboard Handling\n\nThe keyboard system supports complex key combinations through a modifier parsing mechanism defined in `src/utils/keyboard.ts`:\n\n```typescript\n// Key format: \"Control+A\", \"Control+Shift+R\", \"Alt+F4\"\nconst tokens = parseKey(request.params.key);\nconst [key, ...modifiers] = tokens;\n```\n\n**资料来源:** [src/utils/keyboard.ts](https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/src/utils/keyboard.ts)\n\nSupported modifiers:\n- `Control`\n- `Shift`\n- `Alt`\n- `Meta`\n\n### Interaction Workflow\n\n```mermaid\nsequenceDiagram\n participant Agent as AI Agent\n participant Snapshot as take_snapshot\n participant Input as Input Tool\n participant Page as Chrome Page\n \n Agent->>Page: navigate_page / new_page\n Agent->>Snapshot: take_snapshot\n Snapshot-->>Agent: Element UIDs\n Agent->>Input: click uid=\"1_5\"\n Input->>Page: CDP Input.dispatchMouseEvent\n Page-->>Input: Mouse click confirmed\n Input-->>Agent: Result response\n```\n\n**资料来源:** [skills/chrome-devtools/SKILL.md](https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/skills/chrome-devtools/SKILL.md)\n\n### Common Input Patterns\n\n**Typing with Submit:**\n```bash\nchrome-devtools type_text \"hello\" --submitKey \"Enter\"\n```\n\n**Click with Snapshot:**\n```bash\nchrome-devtools click \"uid\" --includeSnapshot true\n```\n\n**Pressing Key Combinations:**\n```bash\nchrome-devtools press_key \"Control+A\" --includeSnapshot true\n```\n\n**资料来源:** [skills/chrome-devtools-cli/SKILL.md](https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/skills/chrome-devtools-cli/SKILL.md)\n\n## Navigation Tools\n\nNavigation tools manage page lifecycle and context within the browser instance.\n\n**资料来源:** [src/tools/pages.ts](https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/src/tools/pages.ts)\n\n### Page Management Operations\n\n| Tool | Purpose | Key Parameters |\n|------|---------|----------------|\n| `navigate_page` | Navigate current page to URL | `url` (required), `type`, `ignoreCache`, `timeout`, `handleBeforeUnload`, `initScript` |\n| `new_page` | Create new page/tab | `url`, `background`, `timeout`, `isolatedContext` |\n| `select_page` | Set active page context | `pageId` (required), `bringToFront` |\n| `close_page` | Close page by index | `pageId` (optional) |\n| `list_pages` | List all open pages | - |\n\n**资料来源:** [src/tools/pages.ts](https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/src/tools/pages.ts)\n\n### Navigation Types\n\nThe `navigate_page` tool supports multiple navigation types:\n\n```typescript\ntype: \"navigate\" | \"reload\" | \"back\" | \"forward\"\n```\n\n| Type | Behavior |\n|------|----------|\n| `navigate` | Default navigation to specified URL |\n| `reload` | Reload current page (supports `ignoreCache`) |\n| `back` | Navigate to previous page in history |\n| `forward` | Navigate to next page in history |\n\n**资料来源:** [src/tools/pages.ts](https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/src/tools/pages.ts)\n\n### Before Unload Handling\n\nWhen navigating away from a page with pending changes, the browser may display a \"before unload\" dialog:\n\n```bash\nchrome-devtools navigate_page --url \"https://example.com\" --handleBeforeUnload \"accept\"\n```\n\n| Option | Behavior |\n|--------|----------|\n| `accept` | Proceed with navigation, dismiss dialog |\n| `dismiss` | Cancel navigation |\n\n**资料来源:** [skills/chrome-devtools-cli/SKILL.md](https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/skills/chrome-devtools-cli/SKILL.md)\n\n### Multi-Page Context Management\n\nPages are managed with a zero-based index system. The `select_page` tool changes the active page context for subsequent tool calls:\n\n```bash\n# List pages to see available pages\nchrome-devtools list_pages\n\n# Select page by index\nchrome-devtools select_page 1 --bringToFront true\n```\n\n**资料来源:** [skills/chrome-devtools/SKILL.md](https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/skills/chrome-devtools/SKILL.md)\n\n### Isolated Contexts\n\nNew pages can be created with isolated JavaScript contexts, useful for testing extensions or isolated scripts:\n\n```bash\nchrome-devtools new_page \"https://example.com\" --isolatedContext \"ctx\"\n```\n\n**资料来源:** [src/tools/pages.ts](https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/src/tools/pages.ts)\n\n### Page Lifecycle\n\n```mermaid\nstateDiagram-v2\n [*] --> created: new_page\n created --> active: select_page\n active --> background: select_page (other)\n background --> active: select_page (bringToFront)\n active --> closed: close_page\n closed --> [*]\n \n active --> navigating: navigate_page\n navigating --> active: Load complete\n```\n\n**资料来源:** [src/PageCollector.ts](https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/src/PageCollector.ts)\n\n## Emulation Tools\n\nEmulation tools control browser environment settings including network conditions, CPU throttling, geolocation, viewport, and user agent.\n\n**资料来源:** [src/tools/emulation.ts](https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/src/tools/emulation.ts)\n\n### Emulation Capabilities\n\n| Capability | Parameters | Description |\n|------------|------------|-------------|\n| Network Conditions | `networkConditions` | Preset: \"Offline\", \"Slow 3G\", \"Fast 3G\", etc. |\n| CPU Throttling | `cpuThrottlingRate` | Multiplier (e.g., 4 = 4x slowdown) |\n| Geolocation | `geolocation` | Coordinates in format \"lat,lng\" |\n| Color Scheme | `colorScheme` | \"light\" or \"dark\" |\n| Viewport | `viewport` | Format: \"WIDTHxHEIGHT\" (e.g., \"1920x1080\") |\n| User Agent | `userAgent` | Custom UA string |\n\n**资料来源:** [src/tools/emulation.ts](https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/src/tools/emulation.ts)\n\n### Emulation Commands\n\n**Network Emulation:**\n```bash\nchrome-devtools emulate --networkConditions \"Offline\"\n```\n\n**Multiple Emulations:**\n```bash\nchrome-devtools emulate --cpuThrottlingRate 4 --geolocation \"0x0\"\n```\n\n**Visual Emulation:**\n```bash\nchrome-devtools emulate --colorScheme \"dark\" --viewport \"1920x1080\"\n```\n\n**User Agent Spoofing:**\n```bash\nchrome-devtools emulate --userAgent \"Mozilla/5.0...\"\n```\n\n**资料来源:** [skills/chrome-devtools-cli/SKILL.md](https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/skills/chrome-devtools-cli/SKILL.md)\n\n### Page Resize\n\nThe `resize_page` tool resizes the selected page's window:\n\n```bash\nchrome-devtools resize_page 1920 1080\n```\n\n**资料来源:** [src/tools/emulation.ts](https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/src/tools/emulation.ts)\n\n## WaitForHelper\n\nThe `WaitForHelper` module provides synchronization mechanisms to ensure page elements are ready before interactions occur.\n\n**资料来源:** [src/WaitForHelper.ts](https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/src/WaitForHelper.ts)\n\n### Wait Strategies\n\n| Strategy | Description |\n|----------|-------------|\n| `wait_for` | Generic wait for specified duration or condition |\n| Event-based | Wait for navigation, network idle, or element state |\n| Timeout handling | Configurable timeout with default fallback |\n\n**资料来源:** [skills/chrome-devtools/SKILL.md](https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/skills/chrome-devtools/SKILL.md)\n\n### Recommended Workflow\n\nThe official workflow ensures reliable automation:\n\n1. **Navigate**: Use `navigate_page` or `new_page`\n2. **Wait**: Use `wait_for` if you know what to look for\n3. **Snapshot**: Use `take_snapshot` to understand page structure\n4. **Interact**: Use element `uid`s from snapshot for `click`, `fill`, etc.\n\n**资料来源:** [skills/chrome-devtools/SKILL.md](https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/skills/chrome-devtools/SKILL.md)\n\n## Tool Configuration Schema\n\nAll tools follow a consistent schema pattern defined in `src/tools/ToolDefinition.ts`:\n\n```typescript\nexport const timeoutSchema = {\n timeout: zod\n .number()\n .int()\n .optional()\n .describe(\n `Maximum wait time in milliseconds. If set to 0, the default timeout will be used.`,\n )\n .transform(value => {\n return value && value <= 0 ? undefined : value;\n }),\n};\n\nexport const pageIdSchema = {\n pageId: zod.number().optional().describe('Targets a specific page by ID.'),\n};\n```\n\n**资料来源:** [src/tools/ToolDefinition.ts](https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/src/tools/ToolDefinition.ts)\n\n### IncludeSnapshot Pattern\n\nMany input tools support the `includeSnapshot` flag to return an updated page snapshot after the action:\n\n```bash\nchrome-devtools click \"id\" --includeSnapshot true\n```\n\nWhen `true`, the response includes the full accessibility tree, allowing chaining without an explicit `take_snapshot` call.\n\n**资料来源:** [skills/chrome-devtools-cli/SKILL.md](https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/skills/chrome-devtools-cli/SKILL.md)\n\n## Error Handling\n\n### Dialog Blocking\n\nSome input tools are blocked when a dialog is present:\n\n```typescript\nblockedByDialog: true,\n```\n\nIn such cases, use `handle_dialog` first:\n\n```bash\nchrome-devtools handle_dialog accept\nchrome-devtools handle_dialog dismiss --promptText \"hi\"\n```\n\n**资料来源:** [src/tools/input.ts](https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/src/tools/input.ts)\n\n### Page Closure Restrictions\n\nThe last open page cannot be closed:\n\n```typescript\nexport const CLOSE_PAGE_ERROR =\n 'The last open page cannot be closed. It is fine to keep it open.';\n```\n\n**资料来源:** [src/tools/ToolDefinition.ts](https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/src/tools/ToolDefinition.ts)\n\n## CLI Usage\n\nAll tools are accessible via the `chrome-devtools` CLI:\n\n```bash\nchrome-devtools 相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [src/tools/input.ts](https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/src/tools/input.ts)\n- [src/tools/pages.ts](https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/src/tools/pages.ts)\n- [src/tools/emulation.ts](https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/src/tools/emulation.ts)\n- [src/WaitForHelper.ts](https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/src/WaitForHelper.ts)\n- [src/utils/keyboard.ts](https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/src/utils/keyboard.ts)\n- [docs/tool-reference.md](https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/docs/tool-reference.md)\n- [skills/chrome-devtools-cli/SKILL.md](https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/skills/chrome-devtools-cli/SKILL.md)\n- [skills/chrome-devtools/SKILL.md](https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/skills/chrome-devtools/SKILL.md)\n\n
\n\n# Debugging and Inspection Tools\n\n## Overview\n\nThe Debugging and Inspection Tools in chrome-devtools-mcp provide comprehensive capabilities for examining browser page state, accessibility trees, console output, network activity, and memory usage. These tools serve as the primary interface for automated debugging, accessibility auditing, and performance analysis workflows.\n\nThe inspection layer is built on Chrome DevTools Protocol (CDP) and exposes both programmatic and visual inspection capabilities through a unified MCP (Model Context Protocol) interface. All tools operate on the currently selected page context, enabling sequential inspection workflows.\n\n## Architecture\n\n```mermaid\ngraph TD\n subgraph \"Inspection Layer\"\n SNAP[Snapshot Tools]\n SCR[Screen Tools]\n NET[Network Tools]\n CON[Console Tools]\n MEM[Memory Tools]\n end\n \n subgraph \"Formatting Layer\"\n SF[SnapshotFormatter]\n NF[NetworkFormatter]\n CF[ConsoleFormatter]\n end\n \n subgraph \"CDP Integration\"\n CDP[Chrome DevTools Protocol]\n PUP[CDP Puppeteer Bridge]\n end\n \n SNAP --> SF\n SCR --> CDP\n NET --> NF\n CON --> CF\n MEM --> CDP\n \n SF --> PUP\n NF --> PUP\n CF --> PUP\n PUP --> CDP\n \n style SNAP fill:#e1f5fe\n style SCR fill:#e1f5fe\n style NET fill:#e1f5fe\n style CON fill:#e1f5fe\n style MEM fill:#e1f5fe\n```\n\n## Page Snapshot Tools\n\n### take_snapshot\n\nThe primary inspection tool that captures the accessibility tree of the currently selected page. The snapshot provides a text-based representation of page structure with unique element identifiers (UIDs) used for subsequent interaction.\n\n**Parameters:**\n\n| Parameter | Type | Required | Description |\n|-----------|------|----------|-------------|\n| `verbose` | boolean | No | Include all available information from the full a11y tree. Default: `false` |\n| `filePath` | string | No | Absolute or relative path to save snapshot output instead of attaching to response |\n\n**Key Features:**\n\n- Returns element hierarchy with unique `uid` identifiers\n- Indicates which element is selected in DevTools Elements panel\n- Supports output to file for large snapshots\n- Based on accessibility tree, not raw DOM (reflects what assistive technologies perceive)\n- Marked as `blockedByDialog: true` to handle browser dialogs gracefully\n\n**Source:** [src/tools/snapshot.ts:17-43]()\n\n### wait_for\n\nSuspends execution until a specified condition is met on the page, enabling synchronization with dynamic content loading.\n\n**Source:** [src/tools/snapshot.ts:45+]()\n\n## Console Tools\n\n### list_console_messages\n\nRetrieves console output and browser-issued accessibility audits from the current page. This tool captures both developer-initiated logs and automatic Chrome accessibility checks.\n\n**Use Cases:**\n\n- Capturing `console.log`, `console.error`, and other console methods\n- Detecting browser-issued accessibility issues\n- Preserving messages from page load that occurred before inspection\n- Filtering by message types (`log`, `warn`, `error`, `info`, `debug`, `issue`)\n\n**Source:** [src/tools/console.ts]()\n\n### Console Output Types\n\n| Type | Description | Typical Use |\n|------|-------------|-------------|\n| `log` | General information | Debug output |\n| `warn` | Warning messages | Non-critical issues |\n| `error` | Error messages | Failures and exceptions |\n| `info` | Informational messages | Status updates |\n| `debug` | Debug-level details | Verbose debugging |\n| `issue` | Browser a11y audits | Accessibility violations |\n\nThe console formatter (`ConsoleFormatter.ts`) processes raw CDP messages into structured, human-readable output with proper formatting of objects and arrays.\n\n**Source:** [src/formatters/ConsoleFormatter.ts]()\n\n## Network Inspection Tools\n\n### Network Monitoring\n\nThe network inspection subsystem captures HTTP traffic, WebSocket communications, and resource loading timing. Network tools are essential for debugging API calls, identifying slow resources, and analyzing request/response patterns.\n\n**Source:** [src/tools/network.ts]()\n\n**Network Formatter:** [src/formatters/NetworkFormatter.ts]()\n\n### Network Parameters\n\n| Parameter | Type | Description |\n|-----------|------|-------------|\n| `pageIdx` | number | Page index for pagination |\n| `pageSize` | number | Number of items per page |\n| `types` | string[] | Filter by resource types (document, stylesheet, image, script, xhr, etc.) |\n| `includePreservedMessages` | boolean | Include messages from before tool invocation |\n\n## Memory Inspection Tools\n\n### take_memory_snapshot\n\nCaptures V8 heap memory snapshots for debugging memory leaks and analyzing memory consumption patterns. Heap snapshots are saved in Chrome's standard `.heapsnapshot` format.\n\n**Parameters:**\n\n| Parameter | Type | Required | Description |\n|-----------|------|----------|-------------|\n| `filePath` | string | Yes | Target path for the snapshot file |\n\n**Use Cases:**\n\n- Identifying memory leaks\n- Analyzing object retention paths\n- Comparing heap states before/after operations\n- Finding detached DOM trees\n\n**Source:** [src/tools/memory.ts]()\n\n## Screenshot Tools\n\n### take_screenshot\n\nCaptures visual representation of the current page state. Unlike snapshots, screenshots provide pixel-level fidelity for visual inspection when accessibility tree information is insufficient.\n\n**Use Cases:**\n\n- Visual debugging when structure is unclear\n- Capturing rendered UI state\n- Documenting bug reproductions\n- Inspecting CSS-dependent layouts\n\n**Source:** [src/tools/screenshot.ts]()\n\n## Snapshot Formatting\n\nThe SnapshotFormatter (`SnapshotFormatter.ts`) transforms raw accessibility tree data into human-readable hierarchical text format.\n\n**Output Structure:**\n\n```\nuid=1_0 RootWebArea \"Example Domain\" url=\"https://example.com/\"\n uid=1_1 heading \"Example Domain\" level=\"1\"\n uid=1_2 paragraph \"Some content text\"\n```\n\n**Key Formatting Features:**\n\n- Hierarchical indentation reflecting DOM tree structure\n- UID assignment following CDP node IDs\n- Role-based element classification (heading, paragraph, button, etc.)\n- Attribute inclusion for semantic details\n- ARIA property preservation\n\n**Source:** [src/formatters/SnapshotFormatter.ts]()\n\n## Workflow Patterns\n\n### Standard Inspection Workflow\n\n```mermaid\ngraph LR\n A[Navigate to Page] --> B[wait_for Condition]\n B --> C[take_snapshot]\n C --> D{Issue Found?}\n D -->|Yes| E[Take Screenshot]\n E --> F[Check Console Logs]\n F --> G[Document Findings]\n D -->|No| H[Continue Testing]\n \n style A fill:#c8e6c9\n style C fill:#bbdefb\n style F fill:#fff9c4\n```\n\n### Accessibility Audit Workflow\n\n1. **Lighthouse Audit**: Run comprehensive accessibility audit via MCP tools\n2. **Console Inspection**: Check for browser-issued `issue` type messages\n3. **Snapshot Analysis**: Verify heading hierarchy, ARIA labels, semantic landmarks\n4. **Form Input Verification**: Ensure all inputs have associated labels\n5. **Focus Navigation**: Test keyboard navigation with `press_key` tool\n\n**Source:** [skills/a11y-debugging/SKILL.md]()\n\n## Tool Categories\n\nAll inspection tools are categorized under `ToolCategory.DEBUGGING` for organizational purposes and MCP tool discovery.\n\n**Source:** [src/tools/snapshot.ts:10]()\n\n### Category Matrix\n\n| Tool | Category | Read-Only | Blocked by Dialog |\n|------|----------|-----------|-------------------|\n| `take_snapshot` | DEBUGGING | false* | true |\n| `wait_for` | DEBUGGING | true | true |\n| `list_console_messages` | DEBUGGING | true | false |\n| `take_memory_snapshot` | DEBUGGING | true | true |\n| `take_screenshot` | DEBUGGING | true | true |\n\n*Note: `take_snapshot` is not read-only due to the `filePath` parameter allowing file system writes.\n\n## Integration with Input Automation\n\nInspection tools work in conjunction with input automation tools to enable test-verify workflows:\n\n```mermaid\ngraph TD\n INSPECT[Inspection Tools] <-->|UID feedback| INTERACT[Input Automation]\n \n INSPECT --> SNAP[Snapshot with UIDs]\n INTERACT --> CLICK[click uid]\n INTERACT --> FILL[fill uid \"text\"]\n INTERACT --> HOVER[hover uid]\n \n SNAP --> ELEM[Element UIDs]\n ELEM --> CLICK\n ELEM --> FILL\n ELEM --> HOVER\n```\n\n**Source:** [skills/chrome-devtools/SKILL.md]()\n\n## Best Practices\n\n1. **Prefer Snapshots over Screenshots**: Text snapshots are faster, machine-parseable, and more reliable for automation\n2. **Use File Output for Large Data**: Specify `filePath` parameter when capturing large snapshots or traces\n3. **Wait Before Inspecting**: Always use `wait_for` when content loads dynamically\n4. **Check Console First**: Browser-issued issues often reveal accessibility problems without manual investigation\n5. **Keep Snapshots Current**: Element UIDs may change after page mutations—take fresh snapshots before interactions\n\n## Output Formats\n\nAll inspection tools support multiple output formats via the `--output-format` flag:\n\n| Format | Use Case |\n|--------|----------|\n| `markdown` (default) | Human-readable output with formatting |\n| `json` | Structured data for programmatic processing |\n\n**Source:** [skills/chrome-devtools-cli/SKILL.md]()\n\n## Error Handling\n\nInspection tools handle common failure scenarios:\n\n- **Dialog Blocking**: Tools with `blockedByDialog: true` will wait if a browser dialog appears\n- **Page Context Missing**: Operations fail gracefully if no page is selected\n- **Path Validation**: File operations validate paths before writing\n- **Timeout Handling**: Configurable timeouts prevent indefinite waits\n\n**Source:** [src/tools/snapshot.ts:28-31]()\n\n---\n\n\n\n## Performance Analysis Tools\n\n### 相关页面\n\n相关主题：[Debugging and Inspection Tools](#debugging-tools), [Telemetry and Monitoring](#telemetry)\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [src/tools/snapshot.ts](https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/src/tools/snapshot.ts)\n- [src/tools/screenshot.ts](https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/src/tools/screenshot.ts)\n- [src/tools/network.ts](https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/src/tools/network.ts)\n- [src/tools/console.ts](https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/src/tools/console.ts)\n- [src/tools/memory.ts](https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/src/tools/memory.ts)\n- [src/formatters/ConsoleFormatter.ts](https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/src/formatters/ConsoleFormatter.ts)\n- [src/formatters/NetworkFormatter.ts](https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/src/formatters/NetworkFormatter.ts)\n- [src/formatters/SnapshotFormatter.ts](https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/src/formatters/SnapshotFormatter.ts)\n\n
\n\n# Performance Analysis Tools\n\nThe chrome-devtools-mcp repository provides a comprehensive suite of performance analysis tools through the Chrome DevTools Protocol integration. These tools enable automated performance auditing, runtime tracing, memory profiling, and network condition emulation.\n\n## Overview\n\nPerformance Analysis Tools in chrome-devtools-mcp encompass four primary domains:\n\n| Domain | Primary Tools | Purpose |\n|--------|---------------|---------|\n| **Lighthouse Auditing** | `lighthouse_audit` | Accessibility, SEO, best practices scoring |\n| **Performance Tracing** | `performance_start_trace`, `performance_stop_trace` | Chrome tracing with DevTools performance data |\n| **Memory Profiling** | `take_memory_snapshot`, `HeapSnapshotManager` | JavaScript heap analysis |\n| **Trace Processing** | `parse.ts` | Processing and parsing of trace events |\n\n资料来源：[src/tools/lighthouse.ts:1-20]()\n\n## Architecture\n\nThe performance analysis system follows a layered architecture:\n\n```mermaid\ngraph TD\n subgraph \"CLI Layer\"\n CLI[CLI CommandsRelated Source Files
\n\nThe following source files were used to generate this documentation:\n\n- [src/tools/lighthouse.ts](https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/src/tools/lighthouse.ts)\n- [src/tools/performance.ts](https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/src/tools/performance.ts)\n- [src/HeapSnapshotManager.ts](https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/src/HeapSnapshotManager.ts)\n- [src/formatters/HeapSnapshotFormatter.ts](https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/src/formatters/HeapSnapshotFormatter.ts)\n- [src/trace-processing/parse.ts](https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/src/trace-processing/parse.ts)\n- [skills/debug-optimize-lcp/SKILL.md](https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/skills/debug-optimize-lcp/SKILL.md)\n- [skills/chrome-devtools-cli/SKILL.md](https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/skills/chrome-devtools-cli/SKILL.md)\nchrome-devtools CLI]\n end\n \n subgraph \"Tool Layer\"\n LH[Lighthouse Audit Tool]\n PT[Performance Trace Tools]\n MS[Memory Snapshot Tools]\n end\n \n subgraph \"Protocol Layer\"\n CDP[Chrome DevTools Protocol]\n end\n \n subgraph \"Processing Layer\"\n HSP[Heap Snapshot Parser]\n TRP[Trace Event Parser]\n FMT[Result Formatters]\n end\n \n subgraph \"Output Layer\"\n JSON[JSON Reports]\n HTML[HTML Reports]\n SNAP[Heap Snapshots]\n end\n \n CLI --> LH\n CLI --> PT\n CLI --> MS\n \n LH --> CDP\n PT --> CDP\n MS --> CDP\n \n MS --> HSP\n PT --> TRP\n \n HSP --> FMT\n TRP --> FMT\n \n FMT --> JSON\n FMT --> HTML\n HSP --> SNAP\n```\n\n## Lighthouse Audit Tool\n\nThe `lighthouse_audit` tool provides automated accessibility, SEO, and best practices auditing.\n\n### Tool Definition\n\n```typescript\nexport const lighthouseAudit = definePageTool({\n name: 'lighthouse_audit',\n description: `Get Lighthouse score and reports for accessibility, SEO, best practices, and agentic browsing. This excludes performance.`,\n schema: {\n mode: zod.enum(['navigation', 'snapshot']).default('navigation'),\n device: zod.enum(['desktop', 'mobile']).default('desktop'),\n outputDirPath: zod.string().optional(),\n },\n});\n```\n\n资料来源：[src/tools/lighthouse.ts:19-40]()\n\n### Audit Categories\n\n| Category | Description | Default Enabled |\n|----------|-------------|-----------------|\n| `accessibility` | WCAG compliance, ARIA labels, color contrast | Yes |\n| `seo` | Meta tags, crawlability, mobile friendliness | Yes |\n| `best-practices` | HTTPS usage, no deprecated APIs | Yes |\n| `agentic-browsing` | AI agent compatibility checks | Yes |\n\n### Parameters\n\n| Parameter | Type | Required | Default | Description |\n|-----------|------|----------|---------|-------------|\n| `mode` | `navigation` \\| `snapshot` | No | `navigation` | `navigation` reloads & audits; `snapshot` analyzes current state |\n| `device` | `desktop` \\| `mobile` | No | `desktop` | Device emulation type |\n| `outputDirPath` | string | No | temp file | Directory for JSON reports |\n\n### Usage Workflow\n\n```mermaid\ngraph LR\n A[Start Audit] --> B{Mode?}\n B -->|navigation| C[Reload Page]\n B -->|snapshot| D[Analyze Current State]\n C --> E[Run Lighthouse]\n D --> E\n E --> F[Generate JSON Report]\n F --> G[Parse Results]\n G --> H[Return Scores & Failed Audits]\n```\n\n资料来源：[src/tools/lighthouse.ts:40-60]()\n\n## Performance Tracing\n\nThe performance tracing system captures Chrome DevTools performance data for deep analysis.\n\n### Available Tools\n\n| Tool | Purpose |\n|------|---------|\n| `performance_start_trace` | Begin recording performance trace |\n| `performance_stop_trace` | Stop recording and return trace data |\n| `performance_analyze_insight` | Get details on specific Performance Insights |\n\n### Trace Configuration\n\n| Parameter | Type | Description |\n|-----------|------|-------------|\n| `filePath` | string | Optional path to save trace file (`.gz` format) |\n| `reload` | boolean | Whether to reload the page before tracing |\n\n### LCP Analysis\n\nThe trace system integrates with LCP (Largest Contentful Paint) debugging:\n\n```javascript\nasync () => {\n return await new Promise(resolve => {\n new PerformanceObserver(list => {\n const entries = list.getEntries();\n const last = entries[entries.length - 1];\n resolve({\n element: last.element?.tagName,\n id: last.element?.id,\n className: last.element?.className,\n url: last.url,\n startTime: last.startTime,\n renderTime: last.renderTime,\n loadTime: last.loadTime,\n size: last.size,\n });\n }).observe({type: 'largest-contentful-paint', buffered: true});\n });\n};\n```\n\n资料来源：[skills/debug-optimize-lcp/references/lcp-snippets.md:1-30]()\n\n### LCP Subpart Breakdown\n\nLCP is measured across four subparts that sum to 100%:\n\n| Subpart | Target | Root Cause | Fixes |\n|---------|--------|------------|-------|\n| TTFB | ~40% | Slow server response | Minimize redirects, CDN caching, bfcache eligibility |\n| Resource Load Delay | ~10% | Late discovery | Remove lazy-loading, add preload/fetchpriority |\n| Resource Load Duration | ~40% | Large/slow resource | WebP/AVIF formats, CDN, compression |\n| Element Render Delay | <10% | Render blocking | Inline critical CSS, defer JS, break long tasks |\n\n资料来源：[skills/debug-optimize-lcp/SKILL.md:1-50]()\n\n## Memory Profiling\n\nThe memory profiling system captures and analyzes JavaScript heap snapshots.\n\n### Heap Snapshot Manager\n\nThe `HeapSnapshotManager` class handles snapshot lifecycle:\n\n```typescript\nexport class PageCollector
\n
\n\n# CLI Reference\n\nThe `chrome-devtools-mcp` CLI provides a command-line interface for interacting with Chrome DevTools, enabling browser automation, page manipulation, performance analysis, and network inspection directly from the terminal.\n\n## Overview\n\nThe CLI is built on top of the Model Context Protocol (MCP) and serves as the primary interface for users who prefer terminal-based workflows over programmatic SDK integration. It wraps the MCP server functionality into a user-friendly command structure.\n\n```mermaid\ngraph TD\n A[User Terminal] -->|chrome-devtools command| B[CLI Entry Point]\n B --> C[chrome-devtools-cli-options.ts]\n C --> D[Argument Parsing]\n D --> E[chrome-devtools-mcp Server]\n E --> F[Chrome Browser Instance]\n F --> G[Page Context]\n G --> H[Tool Execution]\n H --> I[Response Output]\n```\n\n资料来源：[skills/chrome-devtools-cli/SKILL.md]()\n\n## Command Structure\n\nThe general command syntax follows:\n\n```bash\nchrome-devtools 相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [src/bin/chrome-devtools.ts](https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/src/bin/chrome-devtools.ts)\n- [src/bin/chrome-devtools-cli-options.ts](https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/src/bin/chrome-devtools-cli-options.ts)\n- [src/tools/slim/tools.ts](https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/src/tools/slim/tools.ts)\n- [docs/cli.md](https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/docs/cli.md)\n- [docs/slim-tool-reference.md](https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/docs/slim-tool-reference.md)\n\n
\n\n# Project Overview\n\n## Introduction\n\nThe **chrome-devtools-mcp** project is a Model Context Protocol (MCP) server and command-line interface (CLI) for Chrome DevTools. It provides a comprehensive bridge that enables AI assistants, automated testing systems, and developer tools to programmatically control and interact with Chrome browser instances through Chrome DevTools Protocol (CDP).\n\n资料来源：[AGENTS.md](https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/AGENTS.md)\n\n## Core Purpose and Scope\n\nThe project serves as an abstraction layer that exposes Chrome DevTools capabilities as MCP tools, making browser automation accessible through a standardized protocol. This enables use cases including:\n\n- **AI-Powered Browser Automation**: Allowing language models to control browsers for research, testing, and data extraction\n- **Performance Analysis**: Capturing traces, analyzing Largest Contentful Paint (LCP), and measuring page load metrics\n- **Accessibility Auditing**: Running automated accessibility checks and inspecting the accessibility tree\n- **End-to-End Testing**: Automating user interactions including navigation, form filling, and element inspection\n- **WebMCP Tool Execution**: Running custom tools exposed by web pages through the WebMCP protocol\n\n资料来源：[skills/chrome-devtools-cli/SKILL.md](https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/skills/chrome-devtools-cli/SKILL.md)\n\n## Architecture Overview\n\nThe system follows a layered architecture with distinct components:\n\n```mermaid\ngraph TD\n A[CLI / AI Agent] --> B[MCP Server]\n B --> C[Tool Registry]\n C --> D[CDP Client]\n D --> E[Chrome Browser]\n F[WebMCP Tools] -.-> B\n G[PageCollector] --> H[Event Listeners]\n H --> E\n```\n\n### Component Layers\n\n| Layer | Purpose | Key Files |\n|-------|---------|-----------|\n| **MCP Protocol** | Standardized communication interface | `src/McpResponse.ts` |\n| **Tool System** | Tool definitions and schema validation | `src/tools/ToolDefinition.ts` |\n| **CDP Bridge** | Chrome DevTools Protocol communication | `src/PageCollector.ts` |\n| **Skills Layer** | Domain-specific tool groupings | `skills/*/SKILL.md` |\n\n资料来源：[src/McpResponse.ts](https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/src/McpResponse.ts) and [src/PageCollector.ts](https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/src/PageCollector.ts)\n\n## Tool Categories\n\nThe project organizes tools into the following categories:\n\n| Category | Description | Example Tools |\n|----------|-------------|---------------|\n| **Navigation** | Page navigation and management | `navigate_page`, `new_page`, `close_page`, `select_page` |\n| **Inspection** | Page content and state inspection | `take_snapshot`, `take_screenshot`, `evaluate_script` |\n| **Interaction** | User simulation | `type_text`, `press_key`, `fill_form`, `upload_file` |\n| **Performance** | Performance measurement and tracing | `performance_start_trace`, `performance_stop_trace`, `take_memory_snapshot` |\n| **Emulation** | Browser environment simulation | `emulate`, `resize_page` |\n| **Network** | Network request inspection | (Network-related tools) |\n| **Accessibility** | A11y auditing | Lighthouse-based accessibility audits |\n| **WEBMCP** | Dynamic page-exposed tools | `list_webmcp_tools`, `execute_webmcp_tool` |\n\n资料来源：[skills/chrome-devtools-cli/SKILL.md](https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/skills/chrome-devtools-cli/SKILL.md)\n\n## Page Management System\n\nThe `PageCollector` class manages multiple browser pages using Chrome's target lifecycle:\n\n```mermaid\ngraph LR\n A[Browser Instance] -->|targetcreated| B[PageCollector]\n A -->|targetdestroyed| B\n B --> C[WeakMap Storage]\n C --> D[Navigation History]\n D --> E[Resource Tracking]\n```\n\nKey characteristics:\n- **Multiple Page Support**: Manages several open pages simultaneously\n- **Navigation History**: Stores up to 3 recent navigations per page (`maxNavigationSaved = 3`)\n- **Resource Tracking**: Collects resources per navigation sub-list\n- **Event-Driven**: Listens to Chrome target lifecycle events\n\n资料来源：[src/PageCollector.ts](https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/src/PageCollector.ts)\n\n## Tool Definition System\n\nThe tool system uses TypeScript and Zod for schema validation. Two primary tool types exist:\n\n### Global Tools\n\nTools that operate independently of page context:\n\n```typescript\nexport function defineTool相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [AGENTS.md](https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/AGENTS.md)\n- [skills/chrome-devtools-cli/SKILL.md](https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/skills/chrome-devtools-cli/SKILL.md)\n- [skills/debug-optimize-lcp/SKILL.md](https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/skills/debug-optimize-lcp/SKILL.md)\n- [skills/a11y-debugging/SKILL.md](https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/skills/a11y-debugging/SKILL.md)\n- [skills/debug-optimize-lcp/references/optimization-strategies.md](https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/skills/debug-optimize-lcp/references/optimization-strategies.md)\n- [scripts/eval_scenarios/snapshot_test.ts](https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/scripts/eval_scenarios/snapshot_test.ts)\n- [scripts/eval_scenarios/performance_test.ts](https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/scripts/eval_scenarios/performance_test.ts)\n- [src/tools/ToolDefinition.ts](https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/src/tools/ToolDefinition.ts)\n- [src/McpResponse.ts](https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/src/McpResponse.ts)\n- [src/tools/webmcp.ts](https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/src/tools/webmcp.ts)\n- [src/PageCollector.ts](https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/src/PageCollector.ts)\n\n
\n\n# Installation and Setup\n\nThis page covers all methods for installing and configuring the **chrome-devtools-mcp** project, including global CLI usage, local development setup, and MCP server integration.\n\n## Overview\n\nThe chrome-devtools-mcp project provides two primary interfaces:\n\n1. **CLI Tool** (`chrome-devtools`) - A command-line interface for terminal-based browser automation\n2. **MCP Server** - A Model Context Protocol server for integrating Chrome DevTools into AI assistants\n\nThe installation approach depends on your use case:\n\n| Use Case | Recommended Method | Installation Command |\n|----------|-------------------|---------------------|\n| Terminal automation | Global CLI | `npm i chrome-devtools-mcp@latest -g` |\n| AI assistant integration | MCP Server | Clone and build from source |\n| Development contribution | Local development | Clone, install dependencies, build |\n\n资料来源：[skills/chrome-devtools-cli/references/installation.md:1-5]()\n\n## Prerequisites\n\n### Node.js Version Requirement\n\nThe project requires a specific Node.js version defined in `.nvmrc`. Before installation, ensure you have the correct version:\n\n```bash\n# Check the required Node.js version\ncat .nvmrc\n```\n\nUsing a Node version manager (such as nvm) is strongly recommended to avoid permission errors and manage multiple Node versions.\n\n资料来源：[CONTRIBUTING.md:31-35]()\n\n### System Requirements\n\n- **Operating System**: macOS, Linux, or Windows with WSL\n- **Chrome/Chromium**: Chrome browser must be installed on the system\n- **npm**: Node Package Manager (included with Node.js)\n- **Optional**: ffmpeg (required only for experimental screencast feature)\n\n## Method 1: Global CLI Installation\n\n### Installation\n\nInstall the package globally to make the `chrome-devtools` command available system-wide:\n\n```bash\nnpm i chrome-devtools-mcp@latest -g\n```\n\n资料来源：[skills/chrome-devtools-cli/references/installation.md:5]()\n\n### Verification\n\nAfter installation, verify the setup:\n\n```bash\nchrome-devtools status\n```\n\nA successful output indicates the CLI is properly installed and accessible.\n\n资料来源：[skills/chrome-devtools-cli/references/installation.md:7]()\n\n## Method 2: Local Development Setup\n\nFor contributing to the project or running the latest development version:\n\n### Workflow Diagram\n\n```mermaid\ngraph TD\n A[Clone Repository] --> B[Check Node.js Version]\n B --> C{nvm installed?}\n C -->|No| D[Install nvm]\n C -->|Yes| E[Run nvm use]\n D --> E\n E --> F[Run npm ci]\n F --> G[Run npm run build]\n G --> H[Verify with npm run test]\n H --> I[Setup Complete]\n```\n\n### Step-by-Step Instructions\n\n#### 1. Clone the Repository\n\n```bash\ngit clone https://github.com/ChromeDevTools/chrome-devtools-mcp.git\ncd chrome-devtools-mcp\n```\n\n资料来源：[CONTRIBUTING.md:33-36]()\n\n#### 2. Set Node.js Version\n\n```bash\nnvm use\n```\n\nThis reads the version from `.nvmrc` and switches to the correct Node.js version.\n\n#### 3. Install Dependencies\n\n```bash\nnpm ci\n```\n\nThe `npm ci` command performs a clean install using the exact versions from `package-lock.json`, ensuring consistency across environments.\n\n资料来源：[CONTRIBUTING.md:36]()\n\n#### 4. Build the Project\n\n```bash\nnpm run build\n```\n\nThis command runs TypeScript compilation (`tsc`) and verifies the build succeeds. The build output is placed in the `build/` directory.\n\n资料来源：[AGENTS.md:5]()\n\n### Available npm Scripts\n\n| Script | Purpose |\n|--------|---------|\n| `npm run build` | Compile TypeScript and test build |\n| `npm run test` | Build and run all tests |\n| `npm run test 相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [AGENTS.md](https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/AGENTS.md)\n- [CONTRIBUTING.md](https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/CONTRIBUTING.md)\n- [skills/chrome-devtools-cli/references/installation.md](https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/skills/chrome-devtools-cli/references/installation.md)\n- [skills/chrome-devtools-cli/SKILL.md](https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/skills/chrome-devtools-cli/SKILL.md)\n- [package.json](https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/package.json)\n\n
\n\n# Configuration Reference\n\nThis page documents all configuration options available for the `chrome-devtools-mcp` project, covering CLI arguments, MCP server initialization, Puppeteer browser settings, and MCP client configuration files.\n\n## Overview\n\nThe `chrome-devtools-mcp` project supports multiple layers of configuration:\n\n1. **CLI Arguments** - Command-line flags passed when starting the MCP server or CLI\n2. **Puppeteer Configuration** - Browser launch and connection settings\n3. **MCP Client Configuration** - JSON configuration for connecting MCP clients\n\nConfiguration flows through the application as follows:\n\n```mermaid\ngraph TD\n A[CLI Arguments] --> B[chrome-devtools-mcp-cli-options.ts]\n B --> C[ParsedArguments Type]\n C --> D[chrome-devtools-mcp-main.ts]\n D --> E[Puppeteer Launch]\n F[.mcp.json] --> G[MCP Client]\n G --> H[MCP Server Connection]\n```\n\n## CLI Configuration\n\nThe MCP server accepts numerous command-line arguments for customization. These are defined in `src/bin/chrome-devtools-mcp-cli-options.ts` and typed via the `ParsedArguments` interface.\n\n### General Options\n\n| Option | Type | Default | Description |\n|--------|------|---------|-------------|\n| `--port` | `number` | `6274` | Port for the MCP server to listen on |\n| `--host` | `string` | `\"127.0.0.1\"` | Host address to bind |\n| `--log-file` | `string` | `undefined` | Path to write debug logs |\n| `--help` | `boolean` | `false` | Show help message |\n\n资料来源：[src/bin/chrome-devtools-mcp-cli-options.ts](src/bin/chrome-devtools-mcp-cli-options.ts)\n\n### Browser Connection Options\n\n| Option | Type | Default | Description |\n|--------|------|---------|-------------|\n| `--browserUrl` | `string` | `undefined` | Connect to an existing Chrome instance at this URL |\n| `--autoConnect` | `boolean` | `true` | Automatically connect to existing Chrome |\n| `--browserPath` | `string` | `undefined` | Custom path to Chrome executable |\n| `--userDataDir` | `string` | `undefined` | Chrome profile directory path |\n\n资料来源：[src/bin/chrome-devtools-mcp-cli-options.ts](src/bin/chrome-devtools-mcp-cli-options.ts)\n\n### Browser Launch Options\n\n| Option | Type | Default | Description |\n|--------|------|---------|-------------|\n| `--headless` | `boolean` | `true` | Run Chrome in headless mode |\n| `--sandbox` | `boolean` | `true` | Enable Chrome sandbox mode |\n| `--noFirstRun` | `boolean` | `true` | Skip first-run dialogs |\n| `--windowSize` | `string` | `\"1920x1080\"` | Default window dimensions |\n\n资料来源：[src/bin/chrome-devtools-mcp-cli-options.ts](src/bin/chrome-devtools-mcp-cli-options.ts)\n\n### MCP Server Categories\n\nThe MCP server organizes tools into categories. Categories can be enabled or disabled using `--category*` flags:\n\n| Option | Type | Default | Description |\n|--------|------|---------|-------------|\n| `--categoryNavigation` | `boolean` | `true` | Navigation tools (navigate_page, new_page) |\n| `--categoryInteraction` | `boolean` | `true` | Interaction tools (click, fill, type) |\n| `--categoryInspection` | `boolean` | `true` | Inspection tools (take_snapshot, take_screenshot) |\n| `--categoryPerformance` | `boolean` | `true` | Performance tools (traces, profiles) |\n| `--categoryNetwork` | `boolean` | `true` | Network tools (network_interceptor) |\n| `--categoryExtensions` | `boolean` | `false` | Chrome extension management |\n| `--categoryExperimental` | `boolean` | `false` | Experimental tools |\n| `--categoryExperimentalWebmcp` | `boolean` | `false` | WebMCP integration tools |\n| `--categoryDebugging` | `boolean` | `false` | Debugging utilities |\n\n```bash\n# Enable extension support\nchrome-devtools-mcp --categoryExtensions=true\n\n# Enable experimental features\nchrome-devtools-mcp --categoryExperimental=true --experimentalVision=true\n```\n\n资料来源：[src/tools/categories.ts](src/tools/categories.ts) 资料来源：[skills/chrome-devtools/SKILL.md](skills/chrome-devtools/SKILL.md)\n\n### Experimental Features\n\nExperimental features require explicit enabling via CLI flags:\n\n| Option | Type | Default | Description |\n|--------|------|---------|-------------|\n| `--experimentalVision` | `boolean` | `false` | Enable coordinate-based clicking (click_at) |\n| `--experimentalScreencast` | `boolean` | `false` | Enable screencast recording |\n\n```bash\n# Start with experimental vision mode\nchrome-devtools-mcp --experimentalVision=true\n```\n\n资料来源：[skills/chrome-devtools-cli/SKILL.md](skills/chrome-devtools-cli/SKILL.md)\n\n### Debugging Options\n\n| Option | Type | Default | Description |\n|--------|------|---------|-------------|\n| `--verbose` | `boolean` | `false` | Enable verbose logging |\n| `DEBUG` | `env` | `undefined` | Debug categories filter |\n\n```sh\n# Run with debug logging to log.txt\nnpx @modelcontextprotocol/inspector node /build/src/bin/chrome-devtools-mcp.js --log-file=/path/to/log.txt\n```\n\n资料来源：[CONTRIBUTING.md](CONTRIBUTING.md)\n\n## Puppeteer Configuration\n\nThe project uses Puppeteer for browser automation. Configuration is defined in `puppeteer.config.cjs` and can be overridden via CLI arguments.\n\n### Configuration File Structure\n\n```javascript\n// puppeteer.config.cjs\nmodule.exports = {\n puppeteer: {\n // Browser launch arguments\n args: [\n '--no-sandbox',\n '--disable-setuid-sandbox',\n '--disable-dev-shm-usage',\n ],\n // Default launch settings\n headless: true,\n }\n};\n```\n\n### Default Browser Arguments\n\nThe following Chromium arguments are passed by default:\n\n| Argument | Purpose |\n|----------|---------|\n| `--no-sandbox` | Disable sandbox (may be overridden by `--sandbox`) |\n| `--disable-setuid-sandbox` | Prevent setuid complications |\n| `--disable-dev-shm-usage` | Avoid shared memory issues in containers |\n| `--disable-web-security` | Disable web security for testing |\n| `--ash-no-nudges` | Disable Ash nudges |\n\n### Connection Modes\n\nThe MCP server supports two browser connection modes:\n\n```mermaid\ngraph TD\n A[Start chrome-devtools-mcp] --> B{--browserUrl provided?}\n B -->|Yes| C[Remote Connection Mode]\n B -->|No| D[Launch Mode]\n D --> E{--userDataDir provided?}\n E -->|Yes| F[Use existing profile]\n E -->|No| G[Create temporary profile]\n C --> H[Connect via CDP WebSocket]\n F --> I[Puppeteer.launch]\n G --> I\n```\n\n1. **Launch Mode** (default): Puppeteer launches a new Chrome instance\n2. **Remote Connection Mode**: Connect to an existing Chrome via `--browserUrl`\n\n资料来源：[src/bin/chrome-devtools-mcp-main.ts](src/bin/chrome-devtools-mcp-main.ts)\n\n## MCP Client Configuration\n\nThe `.mcp.json` file provides configuration for MCP clients connecting to the server.\n\n### Example Configuration\n\n```json\n{\n \"mcpServers\": {\n \"chrome-devtools\": {\n \"command\": \"npx\",\n \"args\": [\"chrome-devtools-mcp@latest\"],\n \"env\": {}\n }\n }\n}\n```\n\n### Extended Configuration Example\n\n```json\n{\n \"mcpServers\": {\n \"chrome-devtools\": {\n \"command\": \"node\",\n \"args\": [\n \"/path/to/chrome-devtools-mcp/build/src/bin/chrome-devtools-mcp.js\",\n \"--port\", \"6274\",\n \"--headless\", \"false\",\n \"--categoryExtensions\", \"true\"\n ],\n \"env\": {}\n }\n }\n}\n```\n\n### Configuration for Remote Connection\n\nTo connect to a specific Chrome instance:\n\n```json\n{\n \"mcpServers\": {\n \"chrome-devtools\": {\n \"command\": \"npx\",\n \"args\": [\n \"chrome-devtools-mcp@latest\",\n \"--browserUrl\", \"http://localhost:9222\",\n \"--autoConnect\", \"true\"\n ]\n }\n }\n}\n```\n\n资料来源：[.mcp.json](.mcp.json)\n\n## Tool Categories and Annotations\n\nTools are annotated with metadata that affects their availability based on configuration:\n\n### Category Reference\n\n| Category | Flag | Description |\n|----------|------|-------------|\n| `NAVIGATION` | `--categoryNavigation` | Page navigation and management |\n| `INTERACTION` | `--categoryInteraction` | User interaction (clicks, fills) |\n| `INSPECTION` | `--categoryInspection` | Page inspection (snapshots, screenshots) |\n| `PERFORMANCE` | `--categoryPerformance` | Performance profiling |\n| `NETWORK` | `--categoryNetwork` | Network request handling |\n| `EXTENSIONS` | `--categoryExtensions` | Chrome extension management |\n| `EXPERIMENTAL` | `--categoryExperimental` | Experimental tools |\n| `EXPERIMENTAL_WEBMCP` | `--categoryExperimentalWebmcp` | WebMCP integration |\n| `DEBUGGING` | `--categoryDebugging` | Debug utilities |\n\n### Tool Annotation Schema\n\n```typescript\ninterface ToolAnnotation {\n title?: string;\n category?: ToolCategory;\n conditions?: string[]; // Required flags for tool availability\n readOnlyHint?: boolean; // Indicates if tool modifies browser state\n}\n```\n\nTools marked with `readOnlyHint: false` may be blocked in read-only MCP modes.\n\n```mermaid\ngraph LR\n A[Tool Annotation] --> B[readOnlyHint]\n A --> C[category]\n A --> D[conditions]\n B --> E{Client Mode}\n C --> F[Category Filter]\n D --> G[Flag Check]\n E -->|Plan/ReadOnly| H[Only readOnlyHint=true]\n E -->|Normal| I[All tools]\n```\n\n资料来源：[src/tools/ToolDefinition.ts](src/tools/ToolDefinition.ts) 资料来源：[skills/troubleshooting/SKILL.md](skills/troubleshooting/SKILL.md)\n\n## Environment Variables\n\n| Variable | Description |\n|----------|-------------|\n| `DEBUG` | Controls debug logging categories (e.g., `DEBUG=*`) |\n| `PUPPETEER_SKIP_DOWNLOAD` | Skip Puppeteer browser download |\n| `PUPPETEER_EXECUTABLE_PATH` | Custom Chrome executable path |\n\n## Configuration Precedence\n\nConfiguration values are resolved in the following order (highest to lowest):\n\n1. **CLI Arguments** - Explicit flags passed at runtime\n2. **Environment Variables** - Set in shell or `.env` files\n3. **Configuration Files** - `.mcp.json`, `puppeteer.config.cjs`\n4. **Default Values** - Built-in defaults in source code\n\n```mermaid\ngraph TD\n A[Configuration Resolution] --> B[CLI Arguments]\n A --> C[Environment Variables]\n A --> D[Config Files]\n A --> E[Defaults]\n B --> F[Final Config]\n C --> F\n D --> F\n E --> F\n style B fill:#ff9999\n style F fill:#99ff99\n```\n\n## Quick Reference\n\n### Minimal Configuration\n\n```bash\n# Default settings (headless, localhost:6274)\nnpx chrome-devtools-mcp@latest\n```\n\n### Common Configurations\n\n```bash\n# Visible browser with extensions\nchrome-devtools-mcp --headless=false --categoryExtensions=true\n\n# Remote Chrome connection\nchrome-devtools-mcp --browserUrl=http://localhost:9222\n\n# Custom port\nchrome-devtools-mcp --port=9000\n```\n\n## Troubleshooting Configuration Issues\n\n| Symptom | Likely Cause | Solution |\n|---------|--------------|----------|\n| Only 9 tools available | Read-only mode enforced by MCP client | Disable read-only/Plan mode in client |\n| Extension tools missing | `--categoryExtensions` not enabled | Add `--categoryExtensions=true` |\n| New profile created instead of connecting | Incorrect `--browserUrl` or typo in flags | Verify URL and check for flag typos like `--autoBronnect` |\n| `chrome-devtools` command not found | PATH not configured | Ensure npm global bin is in PATH |\n\n资料来源：[skills/troubleshooting/SKILL.md](skills/troubleshooting/SKILL.md)\n\n---\n\n\n\n## System Architecture\n\n### 相关页面\n\n相关主题：[Project Overview](#overview), [MCP Protocol Integration](#mcp-protocol), [Telemetry and Monitoring](#telemetry)\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [src/bin/chrome-devtools-mcp-cli-options.ts](https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/src/bin/chrome-devtools-mcp-cli-options.ts)\n- [src/bin/chrome-devtools-mcp-main.ts](https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/src/bin/chrome-devtools-mcp-main.ts)\n- [puppeteer.config.cjs](https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/puppeteer.config.cjs)\n- [.mcp.json](https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/.mcp.json)\n\n
\n\n# System Architecture\n\n## Overview\n\nThe `chrome-devtools-mcp` project implements a Model Context Protocol (MCP) server that provides programmatic control over Chrome DevTools through a well-defined architecture of interconnected components. The system enables AI assistants and CLI tools to interact with a headless Chrome browser instance by exposing browser operations as typed tools with schema validation.\n\nThe architecture follows a layered design pattern with clear separation between the protocol layer (MCP), the tool definition system, browser management, and page-level interactions. This modular approach allows for extensibility while maintaining type safety and consistent behavior across all exposed functionality.\n\n资料来源：[AGENTS.md]()\n\n## High-Level Architecture\n\n```mermaid\ngraph TD\n subgraph \"Client Layer\"\n CLI[CLI ToolRelevant Source Files
\n\n以下源码文件用于生成本页说明：\n\n- [src/tools/ToolDefinition.ts](https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/src/tools/ToolDefinition.ts)\n- [src/PageCollector.ts](https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/src/PageCollector.ts)\n- [src/tools/webmcp.ts](https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/src/tools/webmcp.ts)\n- [src/tools/categories.ts](https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/src/tools/categories.ts)\n- [src/browser.ts](https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/src/browser.ts)\n- [AGENTS.md](https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/AGENTS.md)\nchrome-devtools]\n AI[AI Assistant
MCP Client]\n end\n\n subgraph \"MCP Protocol Layer\"\n MCP[MCP Server
Protocol Handler]\n TDEF[Tool Definitions
Registry]\n end\n\n subgraph \"Tool System\"\n PAGES[Page Tools
Context-Aware]\n GLOB[Global Tools
Browser-Level]\n end\n\n subgraph \"Browser Layer\"\n CHROME[Chrome Browser
Puppeteer/CDP]\n PAGES_BROWSER[Pages
Target Management]\n end\n\n CLI --> MCP\n AI --> MCP\n MCP --> TDEF\n TDEF --> PAGES\n TDEF --> GLOB\n MCP --> CHROME\n CHROME --> PAGES_BROWSER\n```\n\n## Core Components\n\n### 1. Tool Definition System\n\nThe tool definition system is the foundation of the MCP server's extensibility. It provides factory functions for creating both page-scoped and global tools with automatic schema validation.\n\n| Component | File | Purpose |\n|-----------|------|---------|\n| `defineTool` | `src/tools/ToolDefinition.ts:11-30` | Factory for global tools |\n| `definePageTool` | `src/tools/ToolDefinition.ts:52-90` | Factory for page-scoped tools |\n| `ToolCategory` | `src/tools/categories.ts` | Tool categorization enum |\n\nThe `defineTool` function supports two invocation patterns:\n\n```typescript\n// Direct tool definition\ndefineTool({\n name: 'tool_name',\n schema: { /* zod schema */ },\n handler: async (request, response, context) => { /* ... */ }\n});\n\n// Factory pattern with arguments\ndefineTool((args?: Args) => ({\n name: 'tool_name',\n schema: { /* zod schema using args */ },\n handler: async (request, response, context) => { /* ... */ }\n}));\n```\n\n资料来源：[src/tools/ToolDefinition.ts:11-30]()\n\n### 2. Page Scoped Tools\n\nPage-scoped tools are tools that operate within the context of a specific browser page. They receive an additional `page` property in the request object and have access to the page's DOM, JavaScript context, and rendering state.\n\n```typescript\nexport function definePageTool<\n Schema extends zod.ZodRawShape,\n Args extends ParsedArguments = ParsedArguments,\n>(\n definition:\n | PageToolDefinition
Event]\n DESTROYED[targetdestroyed
Event]\n end\n\n subgraph \"Storage\"\n STORAGE[(WeakMap<Page,
Array<Array<WithSymbolId<T>>>>)]\n end\n\n INIT --> ADD\n ADD --> LISTEN\n CREATED --> ADD\n LISTEN --> STORAGE\n```\n\nKey characteristics of the `PageCollector`:\n\n| Property | Description |\n|----------|-------------|\n| `#browser` | Reference to the Puppeteer Browser instance |\n| `#listenersInitializer` | Factory function for creating event listeners |\n| `#listeners` | WeakMap tracking active listeners per page |\n| `maxNavigationSaved` | Maximum navigations to retain (default: 3) |\n| `storage` | WeakMap storing collected data per page |\n\n资料来源：[src/PageCollector.ts]()\n\n### 4. Browser Management\n\nThe browser module (`src/browser.ts`) handles the initialization and lifecycle of the Puppeteer-based Chrome browser instance. It provides the foundation for all page operations and CDP (Chrome DevTools Protocol) interactions.\n\nThe browser layer is responsible for:\n\n- Launching headless Chrome with appropriate flags\n- Managing browser context and isolated worlds\n- Coordinating page creation and destruction\n- Providing access to CDP sessions for advanced operations\n\n资料来源：[src/browser.ts]()\n\n### 5. WebMCP Tool System\n\nThe WebMCP system allows pages to expose their own tools to the MCP server, enabling dynamic tool discovery and execution from web applications.\n\n```mermaid\ngraph LR\n WEB[Web Application
Exposes Tools]\n MCP[MCP Server]\n EXEC[execute_webmcp_tool]\n LIST[list_webmcp_tools]\n\n WEB --> LIST\n LIST --> WEB\n WEB --> EXEC\n EXEC --> WEB\n```\n\nTwo primary tools manage WebMCP functionality:\n\n| Tool | Purpose |\n|------|---------|\n| `list_webmcp_tools` | Enumerates all WebMCP tools exposed by the current page |\n| `execute_webmcp_tool` | Invokes a named WebMCP tool with optional parameters |\n\n```typescript\nexport const listWebMcpTools = definePageTool({\n name: 'list_webmcp_tools',\n description: `Lists all WebMCP tools the page exposes.`,\n annotations: {\n category: ToolCategory.WEBMCP,\n readOnlyHint: true,\n },\n schema: {},\n blockedByDialog: false,\n handler: async (_request, response, _context) => {\n response.setListWebMcpTools();\n },\n});\n```\n\n资料来源：[src/tools/webmcp.ts]()\n\n## Tool Categories\n\nTools are organized into categories for logical grouping and documentation purposes. The category system enables documentation generation and tool discovery.\n\n| Category | Description |\n|----------|-------------|\n| `WEBMCP` | Tools exposed by web pages themselves |\n| Navigation | Page navigation and history operations |\n| Input | Form filling, clicking, keyboard input |\n| Capture | Screenshots, snapshots, memory profiling |\n| Network | Network request inspection and manipulation |\n| Performance | Tracing, profiling, performance insights |\n\n资料来源：[src/tools/categories.ts]()\n\n## Request/Response Flow\n\n```mermaid\nsequenceDiagram\n participant Client\n participant MCP as MCP Server\n participant TDEF as Tool Definitions\n participant HANDLER as Tool Handler\n participant BROWSER as Browser/Page\n\n Client->>MCP: Tool Request (with args)\n MCP->>TDEF: Lookup Tool Definition\n TDEF-->>MCP: Schema + Handler Reference\n MCP->>MCP: Validate Arguments (Zod)\n MCP->>HANDLER: Invoke Handler(request, response, context)\n HANDLER->>BROWSER: CDP Commands / Puppeteer API\n BROWSER-->>HANDLER: Result\n HANDLER-->>MCP: Update Response\n MCP-->>Client: JSON-RPC Response\n```\n\n## Tool Schema System\n\nAll tool parameters are validated using Zod schemas, ensuring type safety and providing automatic OpenAPI-style documentation.\n\n```typescript\n// Schema definition example\nschema: {\n toolName: zod.string().describe('The name of the WebMCP tool to execute'),\n input: zod\n .string()\n .optional()\n .describe('The JSON-stringified parameters to pass to the WebMCP tool'),\n}\n```\n\nThe schema system supports:\n\n- **Required/Optional detection**: Automatically determines if fields are required based on Zod type\n- **Type transformations**: Applied via `.transform()` for input normalization\n- **Descriptions**: Extracted for documentation generation\n- **Enumerations**: Validated against allowed values\n\nCommon schema utilities include:\n\n| Schema | File | Purpose |\n|--------|------|---------|\n| `pageIdSchema` | `ToolDefinition.ts:95-97` | Optional page targeting |\n| `timeoutSchema` | `ToolDefinition.ts:99-107` | Timeout with zero-to-undefined transform |\n| `viewportTransform` | `ToolDefinition.ts` | Viewport dimension parsing |\n\n资料来源：[src/tools/ToolDefinition.ts:95-107]()\n\n## Error Handling Patterns\n\nThe architecture defines specific error constants for expected failure conditions:\n\n```typescript\nexport const CLOSE_PAGE_ERROR =\n 'The last open page cannot be closed. It is fine to keep it open.';\n```\n\nThis error message indicates that the MCP server intentionally allows users to keep the final browser page open rather than forcing closure, which is a deliberate UX decision for browser automation workflows.\n\n## Type Safety Guarantees\n\nThe codebase enforces strict TypeScript practices to maintain type safety:\n\n| Rule | Rationale |\n|------|-----------|\n| No `any` type | Prevents untyped data flow |\n| No `as` casting | Avoids bypass of type checking |\n| No `!` assertions | Prevents unsafe assumptions |\n| No `// @ts-ignore` | Maintains full type coverage |\n| Prefer `for..of` over `forEach` | Better async/await compatibility |\n\n资料来源：[AGENTS.md]()\n\n## Build and Test Infrastructure\n\n```mermaid\ngraph LR\n subgraph \"Build Commands\"\n BUILD[npm run build
tsc compilation]\n TEST[npm run test
Build + Run Tests]\n FORMAT[npm run format
Fix linting]\n GEN[npm run gen
Generate Docs]\n end\n\n subgraph \"Output Artifacts\"\n JS[JavaScript
/build/src]\n TYPES[Type Declarations
/build/src]\n DOCS[Markdown Docs
/skills/*]\n end\n\n BUILD --> JS\n BUILD --> TYPES\n TEST --> JS\n GEN --> DOCS\n```\n\nThe project uses a standardized build pipeline that ensures type correctness at compile time and provides consistent tooling for development tasks.\n\n## Summary\n\nThe chrome-devtools-mcp system architecture provides:\n\n1. **Extensible Tool System**: Factory functions for creating typed, validated tools\n2. **Page Context Awareness**: Automatic injection of page context into tool handlers\n3. **Event-Driven Page Management**: Observer pattern for tracking browser page lifecycle\n4. **Schema Validation**: Zod-based runtime validation with compile-time type inference\n5. **WebMCP Integration**: Bidirectional tool exposure between server and web pages\n6. **Strict Type Safety**: No escape hatches for type checking, ensuring reliability\n\nThis architecture enables reliable browser automation while maintaining the flexibility needed for diverse use cases ranging from simple navigation to complex performance profiling and accessibility debugging.\n\n---\n\n\n\n## MCP Protocol Integration\n\n### 相关页面\n\n相关主题：[System Architecture](#system-architecture), [Input and Navigation Automation Tools](#automation-tools), [Debugging and Inspection Tools](#debugging-tools)\n\n
\n
\n\n# MCP Protocol Integration\n\n## Overview\n\nThe `chrome-devtools-mcp` project implements a Model Context Protocol (MCP) server that enables AI assistants and MCP clients to interact with Chrome DevTools programmatically. This integration provides a standardized interface for browser automation, debugging, and performance analysis through a collection of well-defined tools.\n\nThe MCP protocol serves as the communication layer between AI assistants and the Chrome browser, allowing tools to be discovered, invoked, and executed remotely. The server handles tool registration, request routing, response formatting, and maintains state across multiple browser pages.\n\n资料来源：[src/index.ts:1-50](https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/src/index.ts)\n\n## Architecture\n\n### High-Level System Design\n\n```mermaid\ngraph TD\n MCP_CLIENT[\"MCP Client / AI Assistant\"]\n MCP_SERVER[\"MCP ServerRelevant Source Files
\n\n以下源码文件用于生成本页说明：\n\n- [src/index.ts](https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/src/index.ts)\n- [src/McpResponse.ts](https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/src/McpResponse.ts)\n- [src/tools/ToolDefinition.ts](https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/src/tools/ToolDefinition.ts)\n- [src/tools/webmcp.ts](https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/src/tools/webmcp.ts)\n- [src/tools/categories.ts](https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/src/tools/categories.ts)\n- [scripts/generate-docs.ts](https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/scripts/generate-docs.ts)\n(chrome-devtools-mcp)\"]\n TOOL_REGISTRY[\"Tool Registry\"]\n BROWSER[\"Chrome Browser\"]\n CDP[\"Chrome DevTools Protocol\"]\n \n MCP_CLIENT -->|\"Call Tool Request\"| MCP_SERVER\n MCP_SERVER -->|\"Tool Definitions\"| MCP_CLIENT\n MCP_SERVER --> TOOL_REGISTRY\n TOOL_REGISTRY -->|\"Handler Execution\"| MCP_SERVER\n MCP_SERVER -->|\"CDP Commands\"| BROWSER\n BROWSER --> CDP\n```\n\n### Tool Registration Flow\n\n```mermaid\ngraph TD\n START[\"Server Initialization\"] --> CREATE_TOOLS[\"createTools()\"]\n CREATE_TOOLS --> REGISTER[\"registerTool()\"]\n REGISTER --> DEFINE[\"definePageTool()\"]\n DEFINE --> SCHEMA[\"Schema Validation\"]\n SCHEMA --> HANDLER[\"Handler Mapping\"]\n HANDLER --> READY[\"Tool Available\"]\n \n STYLE REGISTER fill:#90EE90\n STYLE READY fill:#98FB98\n```\n\nThe MCP server initializes by invoking `createTools()` which returns an array of tool definitions. Each tool is then registered with the MCP server using the protocol's `setRequestHandler()` method. Tools are defined using `definePageTool()` which establishes the tool name, description, input schema, annotations, and handler function.\n\n资料来源：[src/index.ts:40-65](https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/src/index.ts)\n\n## Tool Definition System\n\n### ToolDefinition.ts Pattern\n\nTools are defined using the `definePageTool()` function which creates a structured tool definition with type-safe schemas. The definition includes metadata, validation rules, and the execution handler.\n\n```typescript\nexport const listWebMcpTools = definePageTool({\n name: 'list_webmcp_tools',\n description: `Lists all WebMCP tools the page exposes.`,\n annotations: {\n category: ToolCategory.WEBMCP,\n readOnlyHint: true,\n },\n schema: {},\n blockedByDialog: false,\n handler: async (_request, response, _context) => {\n response.setListWebMcpTools();\n },\n});\n```\n\n资料来源：[src/tools/webmcp.ts:15-27](https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/src/tools/webmcp.ts)\n\n### Tool Definition Structure\n\n| Property | Type | Description |\n|----------|------|-------------|\n| `name` | `string` | Unique identifier for the tool |\n| `description` | `string` | Human-readable description for the MCP client |\n| `annotations` | `ToolAnnotations` | Metadata about the tool's behavior |\n| `schema` | `ZodSchema` | Input validation schema |\n| `blockedByDialog` | `boolean` | Whether the tool waits for dialog dismissal |\n| `handler` | `AsyncHandler` | Function that executes the tool |\n\n### Tool Annotations\n\nThe annotation system provides additional metadata about tools that MCP clients can use for tool selection, permission handling, and UI display.\n\n```typescript\ninterface ToolAnnotations {\n category?: ToolCategory;\n readOnlyHint?: boolean;\n conditions?: string[];\n // Additional annotation properties...\n}\n```\n\n| Annotation | Type | Purpose |\n|------------|------|---------|\n| `category` | `ToolCategory` | Groups tools into logical categories |\n| `readOnlyHint` | `boolean` | Indicates if tool doesn't modify browser state |\n| `conditions` | `string[]` | Flags required for this tool to execute |\n\n资料来源：[src/tools/ToolDefinition.ts](https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/src/tools/ToolDefinition.ts)\n\n## Tool Categories\n\nTools are organized into categories that help MCP clients understand their purpose and scope.\n\n```mermaid\ngraph TD\n TOOLS[\"All Tools\"]\n NAV[\"Navigation
(navigate, new_page, close)\"]\n INPUT[\"Input Automation
(click, fill, type_text)\"]\n EMULATE[\"Emulation
(viewport, userAgent)\"]\n PERFORMANCE[\"Performance
(trace, analyze)\"]\n NETWORK[\"Network
(requests, cookies)\"]\n WEBMCP[\"WebMCP
(page-exposed tools)\"]\n \n TOOLS --> NAV\n TOOLS --> INPUT\n TOOLS --> EMULATE\n TOOLS --> PERFORMANCE\n TOOLS --> NETWORK\n TOOLS --> WEBMCP\n```\n\n### Available Categories\n\n| Category | Enum Value | Description |\n|----------|-------------|-------------|\n| Navigation | `ToolCategory.NAVIGATION` | Page navigation and management |\n| Input Automation | `ToolCategory.INPUT` | Element interaction and form input |\n| Emulation | `ToolCategory.EMULATION` | Browser environment simulation |\n| Performance | `ToolCategory.PERFORMANCE` | Tracing and performance analysis |\n| Network | `ToolCategory.NETWORK` | Network request inspection |\n| WebMCP | `ToolCategory.WEBMCP` | Tools exposed by the web page |\n| Accessibility | `ToolCategory.A11Y` | Accessibility auditing |\n| Debug | `ToolCategory.DEBUG` | JavaScript debugging tools |\n\n资料来源：[src/tools/categories.ts](https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/src/tools/categories.ts)\n\n## Response System\n\n### McpResponse Architecture\n\nThe response system formats tool execution results into structured MCP responses that include both human-readable markdown and machine-parseable structured content.\n\n```mermaid\ngraph LR\n REQUEST[\"Tool Request\"] --> HANDLER[\"Tool Handler\"]\n HANDLER --> RESPONSE[\"McpResponse\"]\n RESPONSE -->|Text Content| MARKDOWN[\"Markdown Output\"]\n RESPONSE -->|Structured Data| JSON[\"JSON / Structured\"]\n \n subgraph Response Components\n TOOL_DEFS[\"Tool Definitions\"]\n NETWORK[\"Network Requests\"]\n PAGINATION[\"Pagination Info\"]\n WEBMCP_TOOLS[\"WebMCP Tools\"]\n end\n \n RESPONSE --> TOOL_DEFS\n RESPONSE --> NETWORK\n RESPONSE --> PAGINATION\n RESPONSE --> WEBMCP_TOOLS\n```\n\n### Response Formatting Features\n\n| Feature | Description |\n|---------|-------------|\n| **Tool Definitions** | Lists all available tools with their schemas |\n| **Network Requests** | Includes network waterfall data when requested |\n| **Pagination** | Handles large result sets with pagination info |\n| **WebMCP Tools** | Lists tools exposed by the current web page |\n| **Structured Content** | Provides machine-readable data alongside text |\n\n资料来源：[src/McpResponse.ts:50-120](https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/src/McpResponse.ts)\n\n### Structured Content Model\n\nThe `structuredContent` object provides programmatic access to response data:\n\n```typescript\ninterface StructuredContent {\n webmcpTools?: WebMcpToolInfo[];\n networkRequests?: NetworkRequest[];\n pagination?: PaginationInfo;\n [key: string]: unknown;\n}\n```\n\n### Pagination Support\n\nWhen handling large datasets (e.g., network requests), the response includes pagination metadata:\n\n```typescript\nconst paginationData = this.#dataWithPagination(\n requests,\n this.#networkRequestsOptions.pagination,\n);\nstructuredContent.pagination = paginationData.pagination;\n```\n\n资料来源：[src/McpResponse.ts:150-180](https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/src/McpResponse.ts)\n\n## WebMCP Integration\n\nWebMCP enables web pages to expose custom tools that MCP clients can discover and invoke. This creates a two-way communication channel where the browser can extend its capabilities based on the loaded page.\n\n```mermaid\ngraph TD\n MCP_CLIENT[\"MCP Client\"]\n SERVER[\"MCP Server\"]\n CHROME[\"Chrome Browser\"]\n WEB_PAGE[\"Web Page\"]\n \n subgraph Discovery Flow\n CLIENT_LIST[\"list_webmcp_tools\"]\n SERVER -->|\"Query\"| CHROME\n CHROME --> WEB_PAGE\n WEB_PAGE -->|\"Exposes tools\"| CHROME\n CHROME -->|\"Tool list\"| SERVER\n SERVER -->|\"Tool names\"| CLIENT_LIST\n end\n \n subgraph Execution Flow\n EXEC[\"execute_webmcp_tool\"]\n CLIENT -->|\"toolName + input\"| SERVER\n SERVER -->|\"Forward\"| CHROME\n CHROME --> WEB_PAGE\n WEB_PAGE -->|\"Execute\"| RESULT[\"Result\"]\n end\n```\n\n### WebMCP Tools\n\n| Tool | Description | Parameters |\n|------|-------------|------------|\n| `list_webmcp_tools` | Lists all tools exposed by the current page | None |\n| `execute_webmcp_tool` | Invokes a WebMCP tool exposed by the page | `toolName`, `input` (JSON string) |\n\nThe `execute_webmcp_tool` accepts input as a JSON string which is parsed and passed to the page-exposed tool:\n\n```typescript\nlet input: Record
\n
\n\n# Input and Navigation Automation Tools\n\n## Overview\n\nThe Input and Navigation Automation Tools constitute the core interaction layer of the `chrome-devtools-mcp` project, enabling programmatic control over browser pages through the Chrome DevTools Protocol (CDP). These tools allow AI agents and automated scripts to simulate real user interactions including keyboard input, mouse actions, page navigation, and environment emulation.\n\n**资料来源:** [skills/chrome-devtools/SKILL.md](https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/skills/chrome-devtools/SKILL.md)\n\n## Architecture\n\nThe automation system is organized into three primary tool categories that work in concert to provide comprehensive browser control:\n\n```mermaid\ngraph TD\n A[chrome-devtools-mcp Tools] --> B[Input Tools]\n A --> C[Navigation Tools]\n A --> D[Emulation Tools]\n \n B --> B1[click]\n B --> B2[fill]\n B --> B3[type_text]\n B --> B4[press_key]\n B --> B5[hover]\n B --> B6[drag]\n B --> B7[upload_file]\n \n C --> C1[navigate_page]\n C --> C2[new_page]\n C --> C3[select_page]\n C --> C4[close_page]\n C --> C5[list_pages]\n \n D --> D1[emulate]\n D --> D2[resize_page]\n \n E[WaitForHelper] --> B\n E --> C\n```\n\n**资料来源:** [src/tools/ToolDefinition.ts](https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/src/tools/ToolDefinition.ts)\n\n## Input Tools\n\nInput tools provide the capability to simulate user interactions with page elements. All input operations require a valid element `uid` obtained from a previous `take_snapshot` call.\n\n**资料来源:** [skills/chrome-devtools-cli/SKILL.md](https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/skills/chrome-devtools-cli/SKILL.md)\n\n### Core Input Operations\n\n| Tool | Purpose | Key Parameters |\n|------|---------|----------------|\n| `click` | Click on an element | `uid` (required), `dblClick`, `includeSnapshot` |\n| `fill` | Fill text into input/select | `uid` (required), `value` (required), `includeSnapshot` |\n| `type_text` | Type text character by character | `text` (required), `submitKey`, `includeSnapshot` |\n| `press_key` | Press a key or combination | `key` (required), `includeSnapshot` |\n| `hover` | Hover over an element | `uid` (required), `includeSnapshot` |\n| `drag` | Drag element to destination | `src` (required), `dst` (required), `includeSnapshot` |\n| `upload_file` | Upload file via input element | `uid` (required), `filePath` (required), `includeSnapshot` |\n\n**资料来源:** [src/tools/input.ts](https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/src/tools/input.ts)\n\n### Keyboard Handling\n\nThe keyboard system supports complex key combinations through a modifier parsing mechanism defined in `src/utils/keyboard.ts`:\n\n```typescript\n// Key format: \"Control+A\", \"Control+Shift+R\", \"Alt+F4\"\nconst tokens = parseKey(request.params.key);\nconst [key, ...modifiers] = tokens;\n```\n\n**资料来源:** [src/utils/keyboard.ts](https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/src/utils/keyboard.ts)\n\nSupported modifiers:\n- `Control`\n- `Shift`\n- `Alt`\n- `Meta`\n\n### Interaction Workflow\n\n```mermaid\nsequenceDiagram\n participant Agent as AI Agent\n participant Snapshot as take_snapshot\n participant Input as Input Tool\n participant Page as Chrome Page\n \n Agent->>Page: navigate_page / new_page\n Agent->>Snapshot: take_snapshot\n Snapshot-->>Agent: Element UIDs\n Agent->>Input: click uid=\"1_5\"\n Input->>Page: CDP Input.dispatchMouseEvent\n Page-->>Input: Mouse click confirmed\n Input-->>Agent: Result response\n```\n\n**资料来源:** [skills/chrome-devtools/SKILL.md](https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/skills/chrome-devtools/SKILL.md)\n\n### Common Input Patterns\n\n**Typing with Submit:**\n```bash\nchrome-devtools type_text \"hello\" --submitKey \"Enter\"\n```\n\n**Click with Snapshot:**\n```bash\nchrome-devtools click \"uid\" --includeSnapshot true\n```\n\n**Pressing Key Combinations:**\n```bash\nchrome-devtools press_key \"Control+A\" --includeSnapshot true\n```\n\n**资料来源:** [skills/chrome-devtools-cli/SKILL.md](https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/skills/chrome-devtools-cli/SKILL.md)\n\n## Navigation Tools\n\nNavigation tools manage page lifecycle and context within the browser instance.\n\n**资料来源:** [src/tools/pages.ts](https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/src/tools/pages.ts)\n\n### Page Management Operations\n\n| Tool | Purpose | Key Parameters |\n|------|---------|----------------|\n| `navigate_page` | Navigate current page to URL | `url` (required), `type`, `ignoreCache`, `timeout`, `handleBeforeUnload`, `initScript` |\n| `new_page` | Create new page/tab | `url`, `background`, `timeout`, `isolatedContext` |\n| `select_page` | Set active page context | `pageId` (required), `bringToFront` |\n| `close_page` | Close page by index | `pageId` (optional) |\n| `list_pages` | List all open pages | - |\n\n**资料来源:** [src/tools/pages.ts](https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/src/tools/pages.ts)\n\n### Navigation Types\n\nThe `navigate_page` tool supports multiple navigation types:\n\n```typescript\ntype: \"navigate\" | \"reload\" | \"back\" | \"forward\"\n```\n\n| Type | Behavior |\n|------|----------|\n| `navigate` | Default navigation to specified URL |\n| `reload` | Reload current page (supports `ignoreCache`) |\n| `back` | Navigate to previous page in history |\n| `forward` | Navigate to next page in history |\n\n**资料来源:** [src/tools/pages.ts](https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/src/tools/pages.ts)\n\n### Before Unload Handling\n\nWhen navigating away from a page with pending changes, the browser may display a \"before unload\" dialog:\n\n```bash\nchrome-devtools navigate_page --url \"https://example.com\" --handleBeforeUnload \"accept\"\n```\n\n| Option | Behavior |\n|--------|----------|\n| `accept` | Proceed with navigation, dismiss dialog |\n| `dismiss` | Cancel navigation |\n\n**资料来源:** [skills/chrome-devtools-cli/SKILL.md](https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/skills/chrome-devtools-cli/SKILL.md)\n\n### Multi-Page Context Management\n\nPages are managed with a zero-based index system. The `select_page` tool changes the active page context for subsequent tool calls:\n\n```bash\n# List pages to see available pages\nchrome-devtools list_pages\n\n# Select page by index\nchrome-devtools select_page 1 --bringToFront true\n```\n\n**资料来源:** [skills/chrome-devtools/SKILL.md](https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/skills/chrome-devtools/SKILL.md)\n\n### Isolated Contexts\n\nNew pages can be created with isolated JavaScript contexts, useful for testing extensions or isolated scripts:\n\n```bash\nchrome-devtools new_page \"https://example.com\" --isolatedContext \"ctx\"\n```\n\n**资料来源:** [src/tools/pages.ts](https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/src/tools/pages.ts)\n\n### Page Lifecycle\n\n```mermaid\nstateDiagram-v2\n [*] --> created: new_page\n created --> active: select_page\n active --> background: select_page (other)\n background --> active: select_page (bringToFront)\n active --> closed: close_page\n closed --> [*]\n \n active --> navigating: navigate_page\n navigating --> active: Load complete\n```\n\n**资料来源:** [src/PageCollector.ts](https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/src/PageCollector.ts)\n\n## Emulation Tools\n\nEmulation tools control browser environment settings including network conditions, CPU throttling, geolocation, viewport, and user agent.\n\n**资料来源:** [src/tools/emulation.ts](https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/src/tools/emulation.ts)\n\n### Emulation Capabilities\n\n| Capability | Parameters | Description |\n|------------|------------|-------------|\n| Network Conditions | `networkConditions` | Preset: \"Offline\", \"Slow 3G\", \"Fast 3G\", etc. |\n| CPU Throttling | `cpuThrottlingRate` | Multiplier (e.g., 4 = 4x slowdown) |\n| Geolocation | `geolocation` | Coordinates in format \"lat,lng\" |\n| Color Scheme | `colorScheme` | \"light\" or \"dark\" |\n| Viewport | `viewport` | Format: \"WIDTHxHEIGHT\" (e.g., \"1920x1080\") |\n| User Agent | `userAgent` | Custom UA string |\n\n**资料来源:** [src/tools/emulation.ts](https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/src/tools/emulation.ts)\n\n### Emulation Commands\n\n**Network Emulation:**\n```bash\nchrome-devtools emulate --networkConditions \"Offline\"\n```\n\n**Multiple Emulations:**\n```bash\nchrome-devtools emulate --cpuThrottlingRate 4 --geolocation \"0x0\"\n```\n\n**Visual Emulation:**\n```bash\nchrome-devtools emulate --colorScheme \"dark\" --viewport \"1920x1080\"\n```\n\n**User Agent Spoofing:**\n```bash\nchrome-devtools emulate --userAgent \"Mozilla/5.0...\"\n```\n\n**资料来源:** [skills/chrome-devtools-cli/SKILL.md](https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/skills/chrome-devtools-cli/SKILL.md)\n\n### Page Resize\n\nThe `resize_page` tool resizes the selected page's window:\n\n```bash\nchrome-devtools resize_page 1920 1080\n```\n\n**资料来源:** [src/tools/emulation.ts](https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/src/tools/emulation.ts)\n\n## WaitForHelper\n\nThe `WaitForHelper` module provides synchronization mechanisms to ensure page elements are ready before interactions occur.\n\n**资料来源:** [src/WaitForHelper.ts](https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/src/WaitForHelper.ts)\n\n### Wait Strategies\n\n| Strategy | Description |\n|----------|-------------|\n| `wait_for` | Generic wait for specified duration or condition |\n| Event-based | Wait for navigation, network idle, or element state |\n| Timeout handling | Configurable timeout with default fallback |\n\n**资料来源:** [skills/chrome-devtools/SKILL.md](https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/skills/chrome-devtools/SKILL.md)\n\n### Recommended Workflow\n\nThe official workflow ensures reliable automation:\n\n1. **Navigate**: Use `navigate_page` or `new_page`\n2. **Wait**: Use `wait_for` if you know what to look for\n3. **Snapshot**: Use `take_snapshot` to understand page structure\n4. **Interact**: Use element `uid`s from snapshot for `click`, `fill`, etc.\n\n**资料来源:** [skills/chrome-devtools/SKILL.md](https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/skills/chrome-devtools/SKILL.md)\n\n## Tool Configuration Schema\n\nAll tools follow a consistent schema pattern defined in `src/tools/ToolDefinition.ts`:\n\n```typescript\nexport const timeoutSchema = {\n timeout: zod\n .number()\n .int()\n .optional()\n .describe(\n `Maximum wait time in milliseconds. If set to 0, the default timeout will be used.`,\n )\n .transform(value => {\n return value && value <= 0 ? undefined : value;\n }),\n};\n\nexport const pageIdSchema = {\n pageId: zod.number().optional().describe('Targets a specific page by ID.'),\n};\n```\n\n**资料来源:** [src/tools/ToolDefinition.ts](https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/src/tools/ToolDefinition.ts)\n\n### IncludeSnapshot Pattern\n\nMany input tools support the `includeSnapshot` flag to return an updated page snapshot after the action:\n\n```bash\nchrome-devtools click \"id\" --includeSnapshot true\n```\n\nWhen `true`, the response includes the full accessibility tree, allowing chaining without an explicit `take_snapshot` call.\n\n**资料来源:** [skills/chrome-devtools-cli/SKILL.md](https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/skills/chrome-devtools-cli/SKILL.md)\n\n## Error Handling\n\n### Dialog Blocking\n\nSome input tools are blocked when a dialog is present:\n\n```typescript\nblockedByDialog: true,\n```\n\nIn such cases, use `handle_dialog` first:\n\n```bash\nchrome-devtools handle_dialog accept\nchrome-devtools handle_dialog dismiss --promptText \"hi\"\n```\n\n**资料来源:** [src/tools/input.ts](https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/src/tools/input.ts)\n\n### Page Closure Restrictions\n\nThe last open page cannot be closed:\n\n```typescript\nexport const CLOSE_PAGE_ERROR =\n 'The last open page cannot be closed. It is fine to keep it open.';\n```\n\n**资料来源:** [src/tools/ToolDefinition.ts](https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/src/tools/ToolDefinition.ts)\n\n## CLI Usage\n\nAll tools are accessible via the `chrome-devtools` CLI:\n\n```bash\nchrome-devtools 相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [src/tools/input.ts](https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/src/tools/input.ts)\n- [src/tools/pages.ts](https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/src/tools/pages.ts)\n- [src/tools/emulation.ts](https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/src/tools/emulation.ts)\n- [src/WaitForHelper.ts](https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/src/WaitForHelper.ts)\n- [src/utils/keyboard.ts](https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/src/utils/keyboard.ts)\n- [docs/tool-reference.md](https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/docs/tool-reference.md)\n- [skills/chrome-devtools-cli/SKILL.md](https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/skills/chrome-devtools-cli/SKILL.md)\n- [skills/chrome-devtools/SKILL.md](https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/skills/chrome-devtools/SKILL.md)\n\n
\n\n# Debugging and Inspection Tools\n\n## Overview\n\nThe Debugging and Inspection Tools in chrome-devtools-mcp provide comprehensive capabilities for examining browser page state, accessibility trees, console output, network activity, and memory usage. These tools serve as the primary interface for automated debugging, accessibility auditing, and performance analysis workflows.\n\nThe inspection layer is built on Chrome DevTools Protocol (CDP) and exposes both programmatic and visual inspection capabilities through a unified MCP (Model Context Protocol) interface. All tools operate on the currently selected page context, enabling sequential inspection workflows.\n\n## Architecture\n\n```mermaid\ngraph TD\n subgraph \"Inspection Layer\"\n SNAP[Snapshot Tools]\n SCR[Screen Tools]\n NET[Network Tools]\n CON[Console Tools]\n MEM[Memory Tools]\n end\n \n subgraph \"Formatting Layer\"\n SF[SnapshotFormatter]\n NF[NetworkFormatter]\n CF[ConsoleFormatter]\n end\n \n subgraph \"CDP Integration\"\n CDP[Chrome DevTools Protocol]\n PUP[CDP Puppeteer Bridge]\n end\n \n SNAP --> SF\n SCR --> CDP\n NET --> NF\n CON --> CF\n MEM --> CDP\n \n SF --> PUP\n NF --> PUP\n CF --> PUP\n PUP --> CDP\n \n style SNAP fill:#e1f5fe\n style SCR fill:#e1f5fe\n style NET fill:#e1f5fe\n style CON fill:#e1f5fe\n style MEM fill:#e1f5fe\n```\n\n## Page Snapshot Tools\n\n### take_snapshot\n\nThe primary inspection tool that captures the accessibility tree of the currently selected page. The snapshot provides a text-based representation of page structure with unique element identifiers (UIDs) used for subsequent interaction.\n\n**Parameters:**\n\n| Parameter | Type | Required | Description |\n|-----------|------|----------|-------------|\n| `verbose` | boolean | No | Include all available information from the full a11y tree. Default: `false` |\n| `filePath` | string | No | Absolute or relative path to save snapshot output instead of attaching to response |\n\n**Key Features:**\n\n- Returns element hierarchy with unique `uid` identifiers\n- Indicates which element is selected in DevTools Elements panel\n- Supports output to file for large snapshots\n- Based on accessibility tree, not raw DOM (reflects what assistive technologies perceive)\n- Marked as `blockedByDialog: true` to handle browser dialogs gracefully\n\n**Source:** [src/tools/snapshot.ts:17-43]()\n\n### wait_for\n\nSuspends execution until a specified condition is met on the page, enabling synchronization with dynamic content loading.\n\n**Source:** [src/tools/snapshot.ts:45+]()\n\n## Console Tools\n\n### list_console_messages\n\nRetrieves console output and browser-issued accessibility audits from the current page. This tool captures both developer-initiated logs and automatic Chrome accessibility checks.\n\n**Use Cases:**\n\n- Capturing `console.log`, `console.error`, and other console methods\n- Detecting browser-issued accessibility issues\n- Preserving messages from page load that occurred before inspection\n- Filtering by message types (`log`, `warn`, `error`, `info`, `debug`, `issue`)\n\n**Source:** [src/tools/console.ts]()\n\n### Console Output Types\n\n| Type | Description | Typical Use |\n|------|-------------|-------------|\n| `log` | General information | Debug output |\n| `warn` | Warning messages | Non-critical issues |\n| `error` | Error messages | Failures and exceptions |\n| `info` | Informational messages | Status updates |\n| `debug` | Debug-level details | Verbose debugging |\n| `issue` | Browser a11y audits | Accessibility violations |\n\nThe console formatter (`ConsoleFormatter.ts`) processes raw CDP messages into structured, human-readable output with proper formatting of objects and arrays.\n\n**Source:** [src/formatters/ConsoleFormatter.ts]()\n\n## Network Inspection Tools\n\n### Network Monitoring\n\nThe network inspection subsystem captures HTTP traffic, WebSocket communications, and resource loading timing. Network tools are essential for debugging API calls, identifying slow resources, and analyzing request/response patterns.\n\n**Source:** [src/tools/network.ts]()\n\n**Network Formatter:** [src/formatters/NetworkFormatter.ts]()\n\n### Network Parameters\n\n| Parameter | Type | Description |\n|-----------|------|-------------|\n| `pageIdx` | number | Page index for pagination |\n| `pageSize` | number | Number of items per page |\n| `types` | string[] | Filter by resource types (document, stylesheet, image, script, xhr, etc.) |\n| `includePreservedMessages` | boolean | Include messages from before tool invocation |\n\n## Memory Inspection Tools\n\n### take_memory_snapshot\n\nCaptures V8 heap memory snapshots for debugging memory leaks and analyzing memory consumption patterns. Heap snapshots are saved in Chrome's standard `.heapsnapshot` format.\n\n**Parameters:**\n\n| Parameter | Type | Required | Description |\n|-----------|------|----------|-------------|\n| `filePath` | string | Yes | Target path for the snapshot file |\n\n**Use Cases:**\n\n- Identifying memory leaks\n- Analyzing object retention paths\n- Comparing heap states before/after operations\n- Finding detached DOM trees\n\n**Source:** [src/tools/memory.ts]()\n\n## Screenshot Tools\n\n### take_screenshot\n\nCaptures visual representation of the current page state. Unlike snapshots, screenshots provide pixel-level fidelity for visual inspection when accessibility tree information is insufficient.\n\n**Use Cases:**\n\n- Visual debugging when structure is unclear\n- Capturing rendered UI state\n- Documenting bug reproductions\n- Inspecting CSS-dependent layouts\n\n**Source:** [src/tools/screenshot.ts]()\n\n## Snapshot Formatting\n\nThe SnapshotFormatter (`SnapshotFormatter.ts`) transforms raw accessibility tree data into human-readable hierarchical text format.\n\n**Output Structure:**\n\n```\nuid=1_0 RootWebArea \"Example Domain\" url=\"https://example.com/\"\n uid=1_1 heading \"Example Domain\" level=\"1\"\n uid=1_2 paragraph \"Some content text\"\n```\n\n**Key Formatting Features:**\n\n- Hierarchical indentation reflecting DOM tree structure\n- UID assignment following CDP node IDs\n- Role-based element classification (heading, paragraph, button, etc.)\n- Attribute inclusion for semantic details\n- ARIA property preservation\n\n**Source:** [src/formatters/SnapshotFormatter.ts]()\n\n## Workflow Patterns\n\n### Standard Inspection Workflow\n\n```mermaid\ngraph LR\n A[Navigate to Page] --> B[wait_for Condition]\n B --> C[take_snapshot]\n C --> D{Issue Found?}\n D -->|Yes| E[Take Screenshot]\n E --> F[Check Console Logs]\n F --> G[Document Findings]\n D -->|No| H[Continue Testing]\n \n style A fill:#c8e6c9\n style C fill:#bbdefb\n style F fill:#fff9c4\n```\n\n### Accessibility Audit Workflow\n\n1. **Lighthouse Audit**: Run comprehensive accessibility audit via MCP tools\n2. **Console Inspection**: Check for browser-issued `issue` type messages\n3. **Snapshot Analysis**: Verify heading hierarchy, ARIA labels, semantic landmarks\n4. **Form Input Verification**: Ensure all inputs have associated labels\n5. **Focus Navigation**: Test keyboard navigation with `press_key` tool\n\n**Source:** [skills/a11y-debugging/SKILL.md]()\n\n## Tool Categories\n\nAll inspection tools are categorized under `ToolCategory.DEBUGGING` for organizational purposes and MCP tool discovery.\n\n**Source:** [src/tools/snapshot.ts:10]()\n\n### Category Matrix\n\n| Tool | Category | Read-Only | Blocked by Dialog |\n|------|----------|-----------|-------------------|\n| `take_snapshot` | DEBUGGING | false* | true |\n| `wait_for` | DEBUGGING | true | true |\n| `list_console_messages` | DEBUGGING | true | false |\n| `take_memory_snapshot` | DEBUGGING | true | true |\n| `take_screenshot` | DEBUGGING | true | true |\n\n*Note: `take_snapshot` is not read-only due to the `filePath` parameter allowing file system writes.\n\n## Integration with Input Automation\n\nInspection tools work in conjunction with input automation tools to enable test-verify workflows:\n\n```mermaid\ngraph TD\n INSPECT[Inspection Tools] <-->|UID feedback| INTERACT[Input Automation]\n \n INSPECT --> SNAP[Snapshot with UIDs]\n INTERACT --> CLICK[click uid]\n INTERACT --> FILL[fill uid \"text\"]\n INTERACT --> HOVER[hover uid]\n \n SNAP --> ELEM[Element UIDs]\n ELEM --> CLICK\n ELEM --> FILL\n ELEM --> HOVER\n```\n\n**Source:** [skills/chrome-devtools/SKILL.md]()\n\n## Best Practices\n\n1. **Prefer Snapshots over Screenshots**: Text snapshots are faster, machine-parseable, and more reliable for automation\n2. **Use File Output for Large Data**: Specify `filePath` parameter when capturing large snapshots or traces\n3. **Wait Before Inspecting**: Always use `wait_for` when content loads dynamically\n4. **Check Console First**: Browser-issued issues often reveal accessibility problems without manual investigation\n5. **Keep Snapshots Current**: Element UIDs may change after page mutations—take fresh snapshots before interactions\n\n## Output Formats\n\nAll inspection tools support multiple output formats via the `--output-format` flag:\n\n| Format | Use Case |\n|--------|----------|\n| `markdown` (default) | Human-readable output with formatting |\n| `json` | Structured data for programmatic processing |\n\n**Source:** [skills/chrome-devtools-cli/SKILL.md]()\n\n## Error Handling\n\nInspection tools handle common failure scenarios:\n\n- **Dialog Blocking**: Tools with `blockedByDialog: true` will wait if a browser dialog appears\n- **Page Context Missing**: Operations fail gracefully if no page is selected\n- **Path Validation**: File operations validate paths before writing\n- **Timeout Handling**: Configurable timeouts prevent indefinite waits\n\n**Source:** [src/tools/snapshot.ts:28-31]()\n\n---\n\n\n\n## Performance Analysis Tools\n\n### 相关页面\n\n相关主题：[Debugging and Inspection Tools](#debugging-tools), [Telemetry and Monitoring](#telemetry)\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [src/tools/snapshot.ts](https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/src/tools/snapshot.ts)\n- [src/tools/screenshot.ts](https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/src/tools/screenshot.ts)\n- [src/tools/network.ts](https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/src/tools/network.ts)\n- [src/tools/console.ts](https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/src/tools/console.ts)\n- [src/tools/memory.ts](https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/src/tools/memory.ts)\n- [src/formatters/ConsoleFormatter.ts](https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/src/formatters/ConsoleFormatter.ts)\n- [src/formatters/NetworkFormatter.ts](https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/src/formatters/NetworkFormatter.ts)\n- [src/formatters/SnapshotFormatter.ts](https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/src/formatters/SnapshotFormatter.ts)\n\n
\n\n# Performance Analysis Tools\n\nThe chrome-devtools-mcp repository provides a comprehensive suite of performance analysis tools through the Chrome DevTools Protocol integration. These tools enable automated performance auditing, runtime tracing, memory profiling, and network condition emulation.\n\n## Overview\n\nPerformance Analysis Tools in chrome-devtools-mcp encompass four primary domains:\n\n| Domain | Primary Tools | Purpose |\n|--------|---------------|---------|\n| **Lighthouse Auditing** | `lighthouse_audit` | Accessibility, SEO, best practices scoring |\n| **Performance Tracing** | `performance_start_trace`, `performance_stop_trace` | Chrome tracing with DevTools performance data |\n| **Memory Profiling** | `take_memory_snapshot`, `HeapSnapshotManager` | JavaScript heap analysis |\n| **Trace Processing** | `parse.ts` | Processing and parsing of trace events |\n\n资料来源：[src/tools/lighthouse.ts:1-20]()\n\n## Architecture\n\nThe performance analysis system follows a layered architecture:\n\n```mermaid\ngraph TD\n subgraph \"CLI Layer\"\n CLI[CLI CommandsRelated Source Files
\n\nThe following source files were used to generate this documentation:\n\n- [src/tools/lighthouse.ts](https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/src/tools/lighthouse.ts)\n- [src/tools/performance.ts](https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/src/tools/performance.ts)\n- [src/HeapSnapshotManager.ts](https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/src/HeapSnapshotManager.ts)\n- [src/formatters/HeapSnapshotFormatter.ts](https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/src/formatters/HeapSnapshotFormatter.ts)\n- [src/trace-processing/parse.ts](https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/src/trace-processing/parse.ts)\n- [skills/debug-optimize-lcp/SKILL.md](https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/skills/debug-optimize-lcp/SKILL.md)\n- [skills/chrome-devtools-cli/SKILL.md](https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/skills/chrome-devtools-cli/SKILL.md)\nchrome-devtools CLI]\n end\n \n subgraph \"Tool Layer\"\n LH[Lighthouse Audit Tool]\n PT[Performance Trace Tools]\n MS[Memory Snapshot Tools]\n end\n \n subgraph \"Protocol Layer\"\n CDP[Chrome DevTools Protocol]\n end\n \n subgraph \"Processing Layer\"\n HSP[Heap Snapshot Parser]\n TRP[Trace Event Parser]\n FMT[Result Formatters]\n end\n \n subgraph \"Output Layer\"\n JSON[JSON Reports]\n HTML[HTML Reports]\n SNAP[Heap Snapshots]\n end\n \n CLI --> LH\n CLI --> PT\n CLI --> MS\n \n LH --> CDP\n PT --> CDP\n MS --> CDP\n \n MS --> HSP\n PT --> TRP\n \n HSP --> FMT\n TRP --> FMT\n \n FMT --> JSON\n FMT --> HTML\n HSP --> SNAP\n```\n\n## Lighthouse Audit Tool\n\nThe `lighthouse_audit` tool provides automated accessibility, SEO, and best practices auditing.\n\n### Tool Definition\n\n```typescript\nexport const lighthouseAudit = definePageTool({\n name: 'lighthouse_audit',\n description: `Get Lighthouse score and reports for accessibility, SEO, best practices, and agentic browsing. This excludes performance.`,\n schema: {\n mode: zod.enum(['navigation', 'snapshot']).default('navigation'),\n device: zod.enum(['desktop', 'mobile']).default('desktop'),\n outputDirPath: zod.string().optional(),\n },\n});\n```\n\n资料来源：[src/tools/lighthouse.ts:19-40]()\n\n### Audit Categories\n\n| Category | Description | Default Enabled |\n|----------|-------------|-----------------|\n| `accessibility` | WCAG compliance, ARIA labels, color contrast | Yes |\n| `seo` | Meta tags, crawlability, mobile friendliness | Yes |\n| `best-practices` | HTTPS usage, no deprecated APIs | Yes |\n| `agentic-browsing` | AI agent compatibility checks | Yes |\n\n### Parameters\n\n| Parameter | Type | Required | Default | Description |\n|-----------|------|----------|---------|-------------|\n| `mode` | `navigation` \\| `snapshot` | No | `navigation` | `navigation` reloads & audits; `snapshot` analyzes current state |\n| `device` | `desktop` \\| `mobile` | No | `desktop` | Device emulation type |\n| `outputDirPath` | string | No | temp file | Directory for JSON reports |\n\n### Usage Workflow\n\n```mermaid\ngraph LR\n A[Start Audit] --> B{Mode?}\n B -->|navigation| C[Reload Page]\n B -->|snapshot| D[Analyze Current State]\n C --> E[Run Lighthouse]\n D --> E\n E --> F[Generate JSON Report]\n F --> G[Parse Results]\n G --> H[Return Scores & Failed Audits]\n```\n\n资料来源：[src/tools/lighthouse.ts:40-60]()\n\n## Performance Tracing\n\nThe performance tracing system captures Chrome DevTools performance data for deep analysis.\n\n### Available Tools\n\n| Tool | Purpose |\n|------|---------|\n| `performance_start_trace` | Begin recording performance trace |\n| `performance_stop_trace` | Stop recording and return trace data |\n| `performance_analyze_insight` | Get details on specific Performance Insights |\n\n### Trace Configuration\n\n| Parameter | Type | Description |\n|-----------|------|-------------|\n| `filePath` | string | Optional path to save trace file (`.gz` format) |\n| `reload` | boolean | Whether to reload the page before tracing |\n\n### LCP Analysis\n\nThe trace system integrates with LCP (Largest Contentful Paint) debugging:\n\n```javascript\nasync () => {\n return await new Promise(resolve => {\n new PerformanceObserver(list => {\n const entries = list.getEntries();\n const last = entries[entries.length - 1];\n resolve({\n element: last.element?.tagName,\n id: last.element?.id,\n className: last.element?.className,\n url: last.url,\n startTime: last.startTime,\n renderTime: last.renderTime,\n loadTime: last.loadTime,\n size: last.size,\n });\n }).observe({type: 'largest-contentful-paint', buffered: true});\n });\n};\n```\n\n资料来源：[skills/debug-optimize-lcp/references/lcp-snippets.md:1-30]()\n\n### LCP Subpart Breakdown\n\nLCP is measured across four subparts that sum to 100%:\n\n| Subpart | Target | Root Cause | Fixes |\n|---------|--------|------------|-------|\n| TTFB | ~40% | Slow server response | Minimize redirects, CDN caching, bfcache eligibility |\n| Resource Load Delay | ~10% | Late discovery | Remove lazy-loading, add preload/fetchpriority |\n| Resource Load Duration | ~40% | Large/slow resource | WebP/AVIF formats, CDN, compression |\n| Element Render Delay | <10% | Render blocking | Inline critical CSS, defer JS, break long tasks |\n\n资料来源：[skills/debug-optimize-lcp/SKILL.md:1-50]()\n\n## Memory Profiling\n\nThe memory profiling system captures and analyzes JavaScript heap snapshots.\n\n### Heap Snapshot Manager\n\nThe `HeapSnapshotManager` class handles snapshot lifecycle:\n\n```typescript\nexport class PageCollector
\n
\n\n# CLI Reference\n\nThe `chrome-devtools-mcp` CLI provides a command-line interface for interacting with Chrome DevTools, enabling browser automation, page manipulation, performance analysis, and network inspection directly from the terminal.\n\n## Overview\n\nThe CLI is built on top of the Model Context Protocol (MCP) and serves as the primary interface for users who prefer terminal-based workflows over programmatic SDK integration. It wraps the MCP server functionality into a user-friendly command structure.\n\n```mermaid\ngraph TD\n A[User Terminal] -->|chrome-devtools command| B[CLI Entry Point]\n B --> C[chrome-devtools-cli-options.ts]\n C --> D[Argument Parsing]\n D --> E[chrome-devtools-mcp Server]\n E --> F[Chrome Browser Instance]\n F --> G[Page Context]\n G --> H[Tool Execution]\n H --> I[Response Output]\n```\n\n资料来源：[skills/chrome-devtools-cli/SKILL.md]()\n\n## Command Structure\n\nThe general command syntax follows:\n\n```bash\nchrome-devtools