# https://github.com/ChromeDevTools/chrome-devtools-mcp 项目说明书
生成时间：2026-05-13 09:07:08 UTC
## 目录
- [项目介绍](#project-introduction)
- [快速开始指南](#quick-start)
- [系统架构](#system-architecture)
- [守护进程系统](#daemon-system)
- [工具参考](#tool-reference)
- [输入自动化工具](#input-automation)
- [性能分析工具](#performance-tools)
- [内存调试工具](#memory-debugging)
- [CLI与配置](#cli-configuration)
- [MCP客户端集成](#mcp-client-integration)
## 项目介绍
### 相关页面
相关主题：[系统架构](#system-architecture), [快速开始指南](#quick-start)
相关源码文件
以下源码文件用于生成本页说明：
- [README.md](https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/README.md)
- [AGENTS.md](https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/AGENTS.md)
- [package.json](https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/package.json)
- [src/index.ts](https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/src/index.ts)
- [src/tools/ToolDefinition.ts](https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/src/tools/ToolDefinition.ts)
- [src/tools/webmcp.ts](https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/src/tools/webmcp.ts)
- [src/PageCollector.ts](https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/src/PageCollector.ts)
- [skills/chrome-devtools/SKILL.md](https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/skills/chrome-devtools/SKILL.md)
- [skills/chrome-devtools-cli/SKILL.md](https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/skills/chrome-devtools-cli/SKILL.md)
- [skills/a11y-debugging/SKILL.md](https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/skills/a11y-debugging/SKILL.md)
# 项目介绍
## 概述
chrome-devtools-mcp 是一个基于 Model Context Protocol (MCP) 的 Chrome DevTools 服务器和命令行工具。该项目由 Google Chrome 团队维护，提供了一套完整的浏览器自动化、调试和性能分析能力。资料来源：[AGENTS.md]()
项目的主要目标是让开发者能够通过 MCP 协议与 Chrome 浏览器进行交互，实现网页自动化、元素操作、性能分析、无障碍调试等功能。资料来源：[skills/chrome-devtools/SKILL.md]()
## 核心架构
### 技术栈
| 组件 | 技术 | 说明 |
|------|------|------|
| 运行时 | Node.js / TypeScript | 使用严格类型检查 |
| 协议 | MCP (Model Context Protocol) | 与 AI 模型交互的标准协议 |
| 浏览器控制 | Puppeteer | Chrome DevTools Protocol 封装 |
| 验证 | Zod | Schema 验证库 |
资料来源：[package.json]()
### 架构图
```mermaid
graph TB
subgraph "客户端层"
AI[AI 模型 / Claude]
CLI[CLI 工具]
end
subgraph "MCP 协议层"
MCPServer[MCP Server]
Protocol[MCP Protocol]
end
subgraph "工具层"
Navigation[导航工具]
Performance[性能工具]
A11y[无障碍工具]
Interaction[交互工具]
Network[网络工具]
WebMCP[WebMCP 工具]
end
subgraph "浏览器层"
CDP[Chrome DevTools Protocol]
Chrome[Chrome Browser]
end
AI --> MCPServer
CLI --> MCPServer
MCPServer --> Protocol
Protocol --> Navigation
Protocol --> Performance
Protocol --> A11y
Protocol --> Interaction
Protocol --> Network
Protocol --> WebMCP
Navigation --> CDP
Performance --> CDP
A11y --> CDP
Interaction --> CDP
Network --> CDP
WebMCP --> CDP
CDP --> Chrome
```
## 工具分类
### 导航工具 (Navigation)
| 工具名称 | 功能 | 页面作用域 |
|---------|------|-----------|
| `new_page` | 创建新页面 | 是 |
| `navigate_page` | 导航到指定 URL | 是 |
| `select_page` | 选择目标页面作为上下文 | 是 |
| `close_page` | 关闭指定页面 | 是 |
| `list_pages` | 列出所有打开的页面 | 否 |
资料来源：[skills/chrome-devtools-cli/SKILL.md]()
### 性能工具 (Performance)
| 工具名称 | 功能 |
|---------|------|
| `performance_start_trace` | 开始性能追踪录制 |
| `performance_stop_trace` | 停止性能追踪录制 |
| `take_memory_snapshot` | 捕获内存堆快照 |
| `performance_analyze_insight` | 获取性能洞察详情 |
资料来源：[skills/debug-optimize-lcp/SKILL.md]()
### 无障碍调试工具 (Accessibility)
| 工具名称 | 功能 |
|---------|------|
| `take_snapshot` | 获取页面快照和可访问性树 |
| `lighthouse_audit` | 运行 Lighthouse 无障碍审计 |
| `evaluate_script` | 执行 JavaScript 脚本 |
资料来源：[skills/a11y-debugging/SKILL.md]()
### 元素交互工具 (Interaction)
| 工具名称 | 功能 |
|---------|------|
| `click` | 点击元素 |
| `fill` / `fill_form` | 填充表单 |
| `type_text` | 键盘输入文本 |
| `press_key` | 按下按键 |
| `upload_file` | 上传文件 |
| `take_screenshot` | 截图 |
资料来源：[skills/chrome-devtools/SKILL.md]()
### 网络工具 (Network)
| 工具名称 | 功能 |
|---------|------|
| `network_start_monitoring` | 开始网络监控 |
| `network_stop_monitoring` | 停止网络监控 |
| `get_network_requests` | 获取网络请求列表 |
### WebMCP 工具
WebMCP 允许与网页暴露的工具进行交互：
| 工具名称 | 功能 |
|---------|------|
| `list_webmcp_tools` | 列出页面暴露的所有 WebMCP 工具 |
| `execute_webmcp_tool` | 执行指定的 WebMCP 工具 |
资料来源：[src/tools/webmcp.ts]()
### 模拟工具 (Emulation)
| 工具名称 | 功能 |
|---------|------|
| `emulate` | 模拟网络条件、CPU 节流、地理位置、配色方案、视口大小 |
| `resize_page` | 调整页面窗口大小 |
| `emulate_user_agent` | 模拟用户代理 |
资料来源：[skills/chrome-devtools-cli/SKILL.md]()
## 核心概念
### 页面作用域 (Page Scoped)
工具分为两类：
1. **页面作用域工具**：需要先选择目标页面才能使用
2. **全局工具**：可随时调用，不需要选择页面
```typescript
export function definePageTool(
definition: PageToolDefinition,
): DefinedPageTool;
```
资料来源：[src/tools/ToolDefinition.ts:1-100]()
### 浏览器生命周期
浏览器会在第一次工具调用时自动启动，使用持久化的 Chrome 配置文件。要启用扩展支持，需要在 MCP 服务器配置中添加 `--categoryExtensions` 参数。资料来源：[skills/chrome-devtools/SKILL.md]()
### 元素唯一标识 (UID)
每个页面元素都有唯一的 `uid` 标识符，用于交互操作。获取 UID 的方式是使用 `take_snapshot` 工具获取页面结构。资料来源：[skills/chrome-devtools/SKILL.md]()
## 项目结构
```
chrome-devtools-mcp/
├── src/
│ ├── index.ts # 入口文件
│ ├── tools/ # 工具定义
│ │ ├── ToolDefinition.ts # 基础工具定义
│ │ ├── webmcp.ts # WebMCP 工具
│ │ └── ...
│ ├── PageCollector.ts # 页面收集器
│ └── ...
├── skills/ # 技能文档
│ ├── chrome-devtools/ # 核心 DevTools 技能
│ ├── chrome-devtools-cli/ # CLI 技能
│ ├── a11y-debugging/ # 无障碍调试技能
│ └── debug-optimize-lcp/ # LCP 优化技能
├── scripts/ # 脚本
│ └── generate-docs.ts # 文档生成
└── package.json
```
## 快速开始
### 安装
```bash
npm i chrome-devtools-mcp@latest -g
chrome-devtools status # 验证安装
```
资料来源：[skills/chrome-devtools-cli/references/installation.md]()
### 常用命令
| 命令 | 说明 |
|------|------|
| `npm run build` | 编译 TypeScript 并测试构建 |
| `npm run test` | 运行所有测试 |
| `npm run test ` | 运行单个测试文件 |
| `npm run format` | 修复格式和获取 linting 错误 |
| `npm run gen` | 生成文档 |
资料来源：[AGENTS.md]()
### 基本工作流程
```mermaid
graph LR
A[导航页面] --> B[等待内容加载]
B --> C[获取快照]
C --> D[获取元素 UID]
D --> E[执行交互操作]
```
## 开发规范
### TypeScript 规范
项目采用严格的 TypeScript 规范：
| 规则 | 说明 |
|------|------|
| 禁止使用 `any` 类型 | 必须使用具体类型 |
| 禁止使用 `as` 类型转换 | 使用类型守卫或泛型 |
| 禁止使用 `!` 断言 | 使用显式检查 |
| 禁止使用 `// @ts-ignore` | 必须修复类型问题 |
| 优先使用 `for..of` | 避免使用 `forEach` |
资料来源：[AGENTS.md]()
### 工具定义模式
```typescript
export function definePageTool(
definition: PageToolDefinition,
): DefinedPageTool {
return {
...definition,
pageScoped: true,
} as DefinedPageTool;
}
```
资料来源：[src/tools/ToolDefinition.ts]()
## 技能系统
项目包含多个专业技能模块：
| 技能名称 | 用途 | 使用场景 |
|---------|------|---------|
| `chrome-devtools` | 核心浏览器操作 | 调试网页、自动化交互、性能分析 |
| `chrome-devtools-cli` | 命令行操作 | 页面导航、网络模拟、元素操作 |
| `a11y-debugging` | 无障碍调试 | 检测 ARIA 标签、焦点管理、键盘导航 |
| `debug-optimize-lcp` | LCP 优化 | 优化最大内容绘制性能 |
## 扩展机制
### MCP 服务器扩展
可以通过 CLI 参数扩展 MCP 服务器功能：
```bash
npx chrome-devtools-mcp@latest --categoryExtensions
```
### WebMCP 扩展
网页可以暴露自定义工具供 MCP 调用，实现双向通信。资料来源：[src/tools/webmcp.ts]()
## 常见用例
### 自动化测试场景
```typescript
// 场景：导航 -> 截图 -> 检查元素
const calls = [
{ name: 'navigate_page', url: 'https://example.com' },
{ name: 'take_screenshot' },
{ name: 'take_snapshot' }
];
```
资料来源：[scripts/eval_scenarios/snapshot_test.ts]()
### 性能分析场景
```typescript
// 场景：导航 -> 开始性能追踪
const calls = [
{ name: 'navigate_page', url: 'https://developers.chrome.com' },
{ name: 'performance_start_trace' }
];
```
资料来源：[scripts/eval_scenarios/performance_test.ts]()
### LCP 优化场景
LCP (最大内容绘制) 优化包括以下关键策略：
1. **消除资源加载延迟**：使用预加载、避免懒加载、设置 fetchpriority
2. **消除元素渲染延迟**：内联关键 CSS、拆分长任务、减少渲染阻塞
3. **减少资源加载时长**：使用现代图片格式、CDN 加速
4. **降低 TTFB**：减少重定向、优化服务器响应、使用边缘缓存
资料来源：[skills/debug-optimize-lcp/SKILL.md]()
## 页面管理
### PageCollector 机制
```mermaid
graph TB
subgraph "PageCollector"
Storage[(WeakMap<Page, Array<NavigationData>>)]
end
subgraph "事件监听"
Created[targetcreated]
Destroyed[targetdestroyed]
end
Created -->|新页面| Add[addPage]
Destroyed -->|页面关闭| Remove[removePage]
Add --> Storage
Remove --> Storage
```
`PageCollector` 使用 `WeakMap` 存储每个页面的导航历史和资源数据，较新的导航记录排在前面。资料来源：[src/PageCollector.ts]()
## 配置与扩展
### CLI 参数
| 参数 | 说明 |
|------|------|
| `--help` | 显示帮助信息 |
| `--categoryExtensions` | 启用扩展支持 |
| `--port` | 指定端口号 |
### 工具注解
工具可以通过注解系统标记元信息：
```typescript
annotations: {
category: ToolCategory.WEBMCP,
readOnlyHint: true,
conditions: ['networkIdle']
}
```
资料来源：[scripts/generate-docs.ts]()
## 总结
chrome-devtools-mcp 项目提供了一套完整的 Chrome DevTools 自动化解决方案，通过 MCP 协议实现了与 AI 模型的深度集成。项目具有以下特点：
- **模块化设计**：工具按功能分类，易于扩展和维护
- **严格类型安全**：TypeScript 规范确保代码质量
- **丰富的调试能力**：支持性能分析、无障碍调试、LCP 优化等专业领域
- **灵活的工作流程**：支持页面管理、元素交互、网络模拟等多种操作
- **双向扩展机制**：既支持 MCP 协议扩展，也支持 WebMCP 网页扩展
---
## 快速开始指南
### 相关页面
相关主题：[MCP客户端集成](#mcp-client-integration), [CLI与配置](#cli-configuration)
相关源码文件
以下源码文件用于生成本页说明：
- [README.md](https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/README.md)
- [AGENTS.md](https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/AGENTS.md)
- [skills/chrome-devtools-cli/SKILL.md](https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/skills/chrome-devtools-cli/SKILL.md)
- [skills/chrome-devtools/SKILL.md](https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/skills/chrome-devtools/SKILL.md)
- [skills/chrome-devtools-cli/references/installation.md](https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/skills/chrome-devtools-cli/references/installation.md)
# 快速开始指南
## 概述
chrome-devtools-mcp 是一个 Chrome DevTools MCP（Model Context Protocol）服务器和命令行工具，提供对浏览器自动化、页面调试、性能分析和网络监控的全面控制。该项目允许开发者通过 MCP 协议与 Chrome DevTools Protocol 进行交互，实现高效的浏览器自动化和调试工作流。
本指南将帮助用户快速上手该工具，涵盖从安装配置到基本操作的全流程。
## 系统架构
### 组件关系
```mermaid
graph TD
A[用户/Agent] --> B[MCP 客户端]
B --> C[chrome-devtools-mcp 服务器]
C --> D[Chrome DevTools Protocol]
D --> E[浏览器实例]
F[chrome-devtools CLI] --> C
```
### 核心模块
| 模块 | 路径 | 功能描述 |
|------|------|----------|
| MCP 服务器 | `src/bin/chrome-devtools-mcp.ts` | 核心服务进程，处理 MCP 协议通信 |
| 工具定义 | `src/tools/` | 各类浏览器操作工具的实现 |
| 响应处理 | `src/McpResponse.ts` | MCP 响应格式化与数据处理 |
资料来源：[AGENTS.md:1-5]()
## 环境要求
### 必要条件
- **Node.js**: 需要 Node.js 运行时环境
- **npm**: 用于包管理和脚本执行
- **Chrome 浏览器**: 支持本地安装的 Chrome 或 Chromium
### 安装步骤
#### 全局安装
```bash
npm i chrome-devtools-mcp@latest -g
```
安装完成后，`chrome-devtools` 命令将全局可用。
资料来源：[skills/chrome-devtools-cli/references/installation.md:3-7]()
#### 验证安装
```bash
chrome-devtools status
```
该命令用于检查安装是否成功。
## 基本命令
### 启动 MCP 服务器
```bash
npx chrome-devtools-mcp@latest [选项]
```
### 查看帮助信息
```bash
chrome-devtools --help
```
## 工作流程模式
### 标准操作流程
```mermaid
graph LR
A[导航页面] --> B[等待加载]
B --> C[获取快照]
C --> D[元素交互]
D --> E{是否完成}
E -->|否| B
E -->|是| F[结束]
```
### 页面交互前准备
1. **导航**: 使用 `navigate_page` 或 `new_page` 访问目标页面
2. **等待**: 使用 `wait_for` 确保内容加载完成
3. **快照**: 使用 `take_snapshot` 获取页面结构
4. **交互**: 使用快照中的元素 `uid` 进行操作
资料来源：[skills/chrome-devtools/SKILL.md:14-24]()
## 常用工具
### 页面管理
| 工具 | 功能 | 参数 |
|------|------|------|
| `new_page` | 创建新页面 | `url`, `--background`, `--timeout`, `--isolatedContext` |
| `navigate_page` | 导航到 URL | `url`, `--type`, `--timeout`, `--initScript` |
| `list_pages` | 列出所有页面 | 无 |
| `select_page` | 选择目标页面 | `pageId`, `--bringToFront` |
| `close_page` | 关闭页面 | `pageId` |
### 元素交互
| 工具 | 功能 | 常用参数 |
|------|------|----------|
| `click` | 点击元素 | `uid`, `--includeSnapshot` |
| `fill` | 填充输入框 | `uid`, `text`, `--submitKey` |
| `hover` | 悬停元素 | `uid` |
| `take_snapshot` | 获取页面快照 | `--filePath`, `--includeSnapshot` |
| `take_screenshot` | 截图 | `--filePath` |
### 键盘操作
```bash
chrome-devtools press_key "Enter" # 按下指定按键
chrome-devtools type_text "hello" # 输入文本
chrome-devtools type_text "hello" --submitKey "Enter" # 输入并提交
```
资料来源：[skills/chrome-devtools-cli/SKILL.md:1-35]()
### 文件上传
```bash
chrome-devtools upload_file "element-id" "file.txt"
chrome-devtools upload_file "element-id" "file.txt" --includeSnapshot true
```
## 性能分析
### 性能追踪
```mermaid
graph TD
A[开始追踪] --> B[performance_start_trace]
B --> C[执行业务操作]
C --> D[停止追踪]
D --> E[performance_stop_trace]
E --> F[分析结果]
F --> G[LCPBreakdown]
F --> H[其他指标]
```
### 性能工具
| 工具 | 功能 |
|------|------|
| `performance_start_trace` | 开始性能追踪 |
| `performance_stop_trace` | 停止追踪并保存 |
| `performance_analyze_insight` | 分析具体性能指标 |
| `take_memory_snapshot` | 捕获内存堆快照 |
```bash
# 基础追踪
chrome-devtools performance_start_trace true false
# 带文件保存的追踪
chrome-devtools performance_start_trace true true --filePath trace.gz
# 停止并保存
chrome-devtools performance_stop_trace --filePath "result.json"
```
## 网络监控
### 网络请求检查
```bash
chrome-devtools network_requests # 查看网络请求列表
```
网络请求工具可配置：
- `include`: 是否包含请求详情
- `pagination`: 分页配置（`pageIdx`, `pageSize`）
资料来源：[src/McpResponse.ts:50-75]()
## 模拟与测试
### 网络模拟
```bash
chrome-devtools emulate --networkConditions "Offline"
chrome-devtools emulate --cpuThrottlingRate 4
```
### 设备模拟
| 参数 | 功能 | 示例值 |
|------|------|--------|
| `--colorScheme` | 颜色方案 | `dark`, `light` |
| `--viewport` | 视口尺寸 | `1920x1080` |
| `--userAgent` | 用户代理字符串 | 自定义 UA |
| `--geolocation` | 地理位置 | `0x0` |
```bash
# 模拟暗黑模式和全高清视口
chrome-devtools emulate --colorScheme "dark" --viewport "1920x1080"
# 重置页面尺寸
chrome-devtools resize_page 1920 1080
```
## 开发与测试
### 构建项目
```bash
npm run build
```
该命令执行 TypeScript 编译并测试构建结果。
### 运行测试
```bash
npm run test # 运行所有测试
npm run test path-to-test.ts # 运行单个测试文件
```
### 代码格式化
```bash
npm run format
```
该命令自动修复格式化问题并显示 linting 错误。
## TypeScript 开发规范
项目制定了严格的 TypeScript 开发规范：
| 规范 | 说明 |
|------|------|
| 禁用 `any` 类型 | 必须使用具体类型 |
| 禁用 `as` 类型转换 | 使用类型守卫或泛型 |
| 禁用 `!` 断言 | 使用显式类型检查 |
| 禁用 `// @ts-ignore` | 必须修复类型问题 |
| 优先使用 `for..of` | 避免使用 `forEach` |
资料来源：[AGENTS.md:15-25]()
## 故障排除
### 常见问题
| 问题 | 解决方案 |
|------|----------|
| 命令未识别 | 确保全局 npm `bin` 目录在 PATH 中 |
| 权限错误 | 避免使用 `sudo`，使用 nvm 管理 Node.js |
| 旧版本运行 | 运行 `chrome-devtools stop && npm uninstall -g chrome-devtools-mcp` |
### 重启终端
安装后可能需要重启终端或 source 配置文件（`.bashrc`、`.zshrc`）以使命令生效。
资料来源：[skills/chrome-devtools-cli/references/installation.md:10-18]()
## 扩展功能
### 扩展支持
如需使用浏览器扩展功能，在 MCP 服务器配置中添加 `--categoryExtensions` 参数：
```bash
npx chrome-devtools-mcp@latest --categoryExtensions
```
### WebMCP 工具
页面可暴露自定义 WebMCP 工具：
| 工具 | 功能 |
|------|------|
| `list_webmcp_tools` | 列出页面暴露的所有 WebMCP 工具 |
| `execute_webmcp_tool` | 执行指定的 WebMCP 工具 |
```bash
chrome-devtools list_webmcp_tools
chrome-devtools execute_webmcp_tool "toolName" --input '{"key": "value"}'
```
资料来源：[src/tools/webmcp.ts:10-40]()
## 下一步
- 阅读完整的[工具参考文档](./tool-reference.md)
- 查看 [LCP 优化指南](./debug-optimize-lcp/index.md)
- 学习[无障碍调试](./a11y-debugging/index.md)技巧
---
## 系统架构
### 相关页面
相关主题：[守护进程系统](#daemon-system), [工具参考](#tool-reference)
相关源码文件
以下源码文件用于生成本页说明：
- [src/index.ts](https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/src/index.ts)
- [src/McpPage.ts](https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/src/McpPage.ts)
- [src/McpContext.ts](https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/src/McpContext.ts)
- [src/ToolHandler.ts](https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/src/ToolHandler.ts)
- [src/browser.ts](https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/src/browser.ts)
# 系统架构
## 1. 概述
chrome-devtools-mcp 是一个基于 Model Context Protocol (MCP) 的服务器实现，通过 Chrome DevTools Protocol 与 Chrome 浏览器进行交互。该项目为 AI 助手提供了一套完整的浏览器自动化工具集，涵盖页面导航、快照采集、性能分析、网络监控、无障碍审计等功能。
核心设计理念是将复杂的 CDP 操作封装为声明式的工具定义，并支持按需启用或禁用特定工具类别。
资料来源：[skills/chrome-devtools/SKILL.md]()
## 2. 架构层次
项目采用分层架构，从底层到顶层依次为：
```mermaid
graph TD
A[MCP 客户端] --> B[MCP 服务器层
src/index.ts]
B --> C[工具路由层
src/ToolHandler.ts]
C --> D[页面管理层
src/McpPage.ts
src/McpContext.ts]
D --> E[浏览器抽象层
src/browser.ts]
E --> F[Puppeteer]
F --> G[Chrome DevTools Protocol]
G --> H[Chrome 浏览器]
I[PageCollector] -.->|事件收集| D
I -.->|依赖| E
```
### 2.1 MCP 服务器层 (src/index.ts)
作为整个系统的入口点，负责初始化 MCP 服务器并注册所有可用工具。该层处理 MCP 协议的请求/响应生命周期。
### 2.2 工具路由层 (src/ToolHandler.ts)
负责将 MCP 请求路由到对应的工具处理器，维护工具注册表并处理工具执行的生命周期。
### 2.3 页面管理层 (src/McpPage.ts, src/McpContext.ts)
管理多页面上下文，包括页面创建、销毁、切换，以及页面作用域内工具的隔离执行。
### 2.4 浏览器抽象层 (src/browser.ts)
封装 Puppeteer API，提供浏览器启动、页面管理、连接复用等底层能力。
## 3. 核心组件
### 3.1 工具定义系统
工具通过 `defineTool` 和 `definePageTool` 工厂函数声明式定义，支持条件化生成和参数化扩展：
```typescript
export function defineTool<
Schema extends zod.ZodRawShape,
Args extends ParsedArguments = ParsedArguments,
>(
definition:
| ToolDefinition
| ((args?: Args) => ToolDefinition),
) {
if (typeof definition === 'function') {
const factory = definition;
return (args: Args) => {
return factory(args);
};
}
return definition;
}
```
资料来源：[src/tools/ToolDefinition.ts:1-20]()
| 组件 | 作用 |
|------|------|
| `ToolDefinition` | 工具的基础定义接口 |
| `defineTool` | 创建全局工具的工厂函数 |
| `definePageTool` | 创建页面作用域工具的工厂函数 |
| `pageIdSchema` | 提供可选的页面 ID 参数 |
| `timeoutSchema` | 提供可选的超时配置 |
### 3.2 工具定义结构
每个工具定义包含以下关键字段：
| 字段 | 类型 | 说明 |
|------|------|------|
| `name` | string | 工具唯一标识符 |
| `description` | string | 工具功能描述 |
| `schema` | ZodSchema | 输入参数校验 schema |
| `handler` | Function | 实际执行的处理函数 |
| `pageScoped` | boolean | 是否为页面作用域工具 |
| `blockedByDialog` | boolean | 是否被对话框阻塞 |
| `annotations` | ToolAnnotations | 工具元数据（分类、只读提示等）|
```typescript
interface ToolDefinition<
Schema extends zod.ZodRawShape = zod.ZodRawShape,
> extends BaseToolDefinition {
handler: (
request: Request,
response: Response,
context: Context,
) => Promise;
}
```
资料来源：[src/tools/ToolDefinition.ts:1-20]()
### 3.3 页面上下文管理
页面上下文通过 `McpContext` 管理，支持多页面并发操作：
```mermaid
graph TD
A[McpContext] -->|管理| B[McpPage 1]
A -->|管理| C[McpPage 2]
A -->|管理| D[McpPage N]
B -->|操作| E[CDP Session 1]
C -->|操作| F[CDP Session 2]
D -->|操作| G[CDP Session N]
```
`McpPage` 封装了单个页面的 CDP 操作，提供统一的工具调用接口。
资料来源：[src/McpPage.ts]()
### 3.4 浏览器生命周期
```mermaid
graph LR
A[启动 Chrome] --> B[建立 CDP 连接]
B --> C[初始化页面]
C --> D[注册事件监听]
D --> E[PageCollector 收集数据]
E --> F[等待工具调用]
F --> G[执行工具]
G --> H[返回结果]
H -->|继续| F
```
资料来源：[src/browser.ts]()
## 4. 工具分类体系
工具按功能分类，通过 `ToolCategory` 枚举定义：
| 分类 | 说明 | 示例工具 |
|------|------|----------|
| `NAVIGATION` | 页面导航与控制 | navigate_page, new_page, close_page |
| `INSPECTION` | 页面状态检查 | take_snapshot, take_screenshot |
| `INTERACTION` | 用户交互模拟 | click, fill_form, press_key |
| `PERFORMANCE` | 性能分析与追踪 | performance_start_trace, take_memory_snapshot |
| `NETWORK` | 网络请求监控 | network_intercept_request |
| `EMULATION` | 环境模拟 | emulate, resize_page |
| `ACCESSIBILITY` | 无障碍审计 | run_lighthouse |
| `WEBMCP` | 页面暴露的工具 | list_webmcp_tools, execute_webmcp_tool |
资料来源：[src/tools/categories.ts]()、[src/tools/webmcp.ts]()
## 5. 页面收集器 (PageCollector)
`PageCollector` 是一个通用的事件收集器，用于监听浏览器目标事件：
```typescript
export class PageCollector {
#browser: Browser;
#listenersInitializer: (
collector: (item: T) => void,
) => ListenerMap;
protected storage = new WeakMap>>>();
async init(pages: Page[]) { /* ... */ }
dispose() { /* ... */ }
}
```
资料来源：[src/PageCollector.ts:1-30]()
### 5.1 事件流
```mermaid
graph TD
A[targetcreated 事件] --> B{获取 Page}
B -->|成功| C[addPage]
B -->|失败| D[记录日志]
C --> E[targetdestroyed 事件]
E --> F[removePage]
G[页面事件] --> H[触发监听器]
H --> I[收集数据到 storage]
I --> J[WeakMap 存储]
```
## 6. WebMCP 工具机制
WebMCP 允许页面主动暴露自定义工具，实现双向通信：
```typescript
export const listWebMcpTools = definePageTool({
name: 'list_webmcp_tools',
description: `Lists all WebMCP tools the page exposes.`,
annotations: {
category: ToolCategory.WEBMCP,
readOnlyHint: true,
},
schema: {},
blockedByDialog: false,
handler: async (_request, response, _context) => {
response.setListWebMcpTools();
},
});
export const executeWebMcpTool = definePageTool({
name: 'execute_webmcp_tool',
description: `Executes a WebMCP tool exposed by the page.`,
annotations: {
category: ToolCategory.WEBMCP,
readOnlyHint: false,
},
schema: {
toolName: zod.string().describe('The name of the WebMCP tool to execute'),
input: zod.string().optional().describe('The JSON-stringified parameters'),
},
blockedByDialog: false,
handler: async (request, response) => {
const toolName = request.params.toolName;
let input: Record = {};
if (request.params.input) {
const parsed = JSON.parse(request.params.input);
// ...
}
},
});
```
资料来源：[src/tools/webmcp.ts:1-50]()
## 7. 请求处理流程
```mermaid
sequenceDiagram
participant Client as MCP 客户端
participant Server as MCP 服务器
participant Handler as ToolHandler
participant Context as McpContext
participant Page as McpPage
participant CDP as Chrome CDP
Client->>Server: 工具调用请求
Server->>Handler: 路由到对应工具
Handler->>Context: 获取当前页面上下文
Context->>Page: 执行页面操作
Page->>CDP: 发送 CDP 命令
CDP-->>Page: 返回执行结果
Page-->>Context: 返回结果
Context-->>Handler: 格式化响应
Handler-->>Server: 返回工具响应
Server-->>Client: MCP 响应
```
## 8. 工具依赖关系
部分工具需要特定的前置条件，例如对话框阻塞：
| 工具类型 | blockedByDialog | 说明 |
|----------|-----------------|------|
| 导航工具 | false | 通常允许在对话框存在时执行 |
| 检查工具 | false | 快照和截图不受对话框影响 |
| 交互工具 | true | 点击、表单填写需等待对话框关闭 |
```typescript
export const CLOSE_PAGE_ERROR =
'The last open page cannot be closed. It is fine to keep it open.';
```
资料来源：[src/tools/ToolDefinition.ts:30-32]()
## 9. 扩展性设计
### 9.1 新增工具类别
在 `src/tools/categories.ts` 中扩展 `ToolCategory` 枚举，然后在对应的文件中使用 `defineTool` 或 `definePageTool` 注册工具。
### 9.2 条件化工具生成
工具支持函数式定义，可根据参数动态生成：
```typescript
export function definePageTool<
Schema extends zod.ZodRawShape,
Args extends ParsedArguments = ParsedArguments,
>(
definition: (args?: Args) => PageToolDefinition,
): (args?: Args) => DefinedPageTool {
return (args?: Args): DefinedPageTool => {
const tool = definition(args);
return {
...tool,
pageScoped: true,
};
};
}
```
资料来源：[src/tools/ToolDefinition.ts:40-60]()
## 10. 总结
chrome-devtools-mcp 的架构设计体现了以下原则：
1. **分层解耦**：通过明确的层次划分，实现关注点分离
2. **声明式定义**：工具通过结构化的 schema 声明，简化了注册流程
3. **页面隔离**：每个页面维护独立的上下文，保证并发安全
4. **事件驱动**：通过 PageCollector 实现灵活的事件收集机制
5. **双向通信**：WebMCP 机制支持页面主动暴露能力，拓展了应用边界
---
## 守护进程系统
### 相关页面
相关主题：[系统架构](#system-architecture)
相关源码文件
以下源码文件用于生成本页说明：
- [src/daemon/daemon.ts](https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/src/daemon/daemon.ts)
- [src/daemon/client.ts](https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/src/daemon/client.ts)
- [src/daemon/types.ts](https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/src/daemon/types.ts)
- [src/daemon/utils.ts](https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/src/daemon/utils.ts)
# 守护进程系统
## 概述
守护进程系统（Daemon System）是 chrome-devtools-mcp 项目中负责管理和维护 Chrome DevTools 协议通信后端服务的核心模块。该系统确保 MCP 服务器与浏览器实例之间的长期稳定连接，并提供进程生命周期管理、状态监控和资源清理等功能。
在 chrome-devtools-mcp 架构中，守护进程扮演着后台服务的角色，使得客户端能够通过 MCP 协议与浏览器进行交互，而无需关心底层连接管理的复杂性。
## 系统架构
### 整体架构图
```mermaid
graph TD
subgraph 客户端层
A[MCP 客户端]
B[CLI 工具
chrome-devtools]
end
subgraph 守护进程层
C[Daemon Manager]
D[Chrome Browser
实例]
end
subgraph 协议层
E[CDP 协议
Chrome DevTools Protocol]
end
A --> C
B --> C
C <--> E
E <--> D
style C fill:#e1f5fe
style D fill:#fff3e0
```
### 核心组件
| 组件名称 | 文件位置 | 职责描述 |
|---------|---------|---------|
| Daemon Manager | `daemon.ts` | 进程生命周期管理、启动/停止控制 |
| Daemon Client | `client.ts` | 客户端通信接口、命令发送与接收 |
| 类型定义 | `types.ts` | 共享类型、接口、枚举定义 |
| 工具函数 | `utils.ts` | 通用工具函数、日志、错误处理 |
## 守护进程管理器
### 进程启动流程
```mermaid
sequenceDiagram
participant Client as MCP 客户端
participant Daemon as Daemon Manager
participant Chrome as Chrome 实例
participant CDP as CDP Protocol
Client->>Daemon: 启动请求
Daemon->>Chrome: 启动 Chrome 进程
Chrome-->>Daemon: 进程已启动
Daemon->>CDP: 建立 WebSocket 连接
CDP-->>Daemon: 连接就绪
Daemon-->>Client: 启动成功/状态就绪
```
### 核心功能
#### 1. 进程生命周期管理
守护进程管理器负责 Chrome 浏览器实例的完整生命周期：
- **启动**：初始化 Chrome 进程并建立调试连接
- **运行**：维护活跃的 CDP 会话
- **停止**：优雅关闭进程并清理资源
- **重启**：在故障时自动恢复服务
#### 2. 配置管理
守护进程支持多种启动配置参数：
| 参数名称 | 类型 | 默认值 | 说明 |
|---------|------|-------|------|
| port | number | 9222 | Chrome 调试端口 |
| userDataDir | string | - | 用户数据目录路径 |
| headless | boolean | true | 是否以无头模式运行 |
| startupTimeout | number | 30000 | 启动超时时间(毫秒) |
## 客户端通信接口
### 连接建立
```mermaid
graph LR
A[CLI 命令] --> B[Client.connect]
B --> C{连接状态}
C -->|成功| D[返回连接句柄]
C -->|失败| E[错误处理]
D --> F[发送 CDP 命令]
F --> G[接收响应]
```
### API 接口
守护进程客户端提供以下核心方法：
```typescript
interface DaemonClient {
// 建立连接
connect(options: ConnectOptions): Promise;
// 断开连接
disconnect(): Promise;
// 发送命令
sendCommand(method: string, params?: object): Promise;
// 获取状态
getStatus(): DaemonStatus;
}
```
## 类型系统
### 核心类型定义
```typescript
// 守护进程状态枚举
enum DaemonState {
STOPPED = 'stopped',
STARTING = 'starting',
RUNNING = 'running',
STOPPING = 'stopping',
ERROR = 'error'
}
// 连接配置
interface ConnectOptions {
port?: number;
autoReconnect?: boolean;
timeout?: number;
}
// 守护进程状态
interface DaemonStatus {
state: DaemonState;
uptime: number;
browserVersion?: string;
error?: string;
}
```
### 类型安全
守护进程系统采用 TypeScript 严格类型检查策略：
- 禁止使用 `any` 类型
- 禁止使用类型断言 `as` 关键字
- 禁止使用非空断言 `!` 操作符
- 优先使用 `for...of` 循环替代 `forEach`
## 工具模块
### 错误处理
工具模块提供统一的错误处理机制：
```typescript
// 自定义错误类型
class DaemonError extends Error {
constructor(
message: string,
public code: DaemonErrorCode,
public details?: object
) {
super(message);
}
}
```
### 日志记录
```typescript
interface LogOptions {
level: 'debug' | 'info' | 'warn' | 'error';
timestamp?: boolean;
prefix?: string;
}
```
## 状态流转
```mermaid
stateDiagram-v2
[*] --> STOPPED: 初始化
STOPPED --> STARTING: 启动请求
STARTING --> RUNNING: 连接成功
STARTING --> ERROR: 连接失败
RUNNING --> STOPPING: 停止请求
RUNNING --> ERROR: 连接断开
STOPPING --> STOPPED: 进程已关闭
ERROR --> STARTING: 重试
ERROR --> STOPPED: 放弃
STOPPED --> [*]: 销毁
```
## 使用场景
### 1. MCP 服务器集成
守护进程系统被 MCP 服务器直接使用：
```typescript
import { DaemonManager } from './daemon/daemon';
const daemon = new DaemonManager({
port: 9222,
headless: true
});
await daemon.start();
```
### 2. CLI 工具调用
命令行工具通过守护进程客户端与服务交互：
```bash
chrome-devtools start
chrome-devtools status
chrome-devtools stop
```
### 3. 测试环境
在测试场景中，守护进程提供隔离的浏览器环境：
```typescript
const testDaemon = new DaemonManager({
userDataDir: '/tmp/test-profile',
headless: true
});
```
## 配置与调试
### 环境变量
| 变量名称 | 说明 |
|---------|------|
| `CHROME_DEVTOOLS_MCP_NO_USAGE_STATISTICS` | 禁用使用统计 |
| `DEBUG` | 调试日志类别控制 |
| `LOG_FILE` | 日志输出文件路径 |
### 日志级别
```bash
# 启用所有调试日志
DEBUG=* chrome-devtools start
# 输出到文件
npx chrome-devtools-mcp@latest --log-file=/tmp/daemon.log
```
## 最佳实践
1. **启动顺序**：先启动守护进程，再建立客户端连接
2. **资源清理**：使用完毕及时调用 `stop()` 方法释放资源
3. **超时处理**：设置合理的 `startupTimeout` 避免无限等待
4. **错误恢复**：实现重连机制处理临时性网络故障
5. **端口管理**：确保调试端口未被其他进程占用
## 相关文档
- [安装指南](../skills/chrome-devtools-cli/references/installation.md)
- [故障排除](../skills/troubleshooting/SKILL.md)
- [工具参考](../src/tools/ToolDefinition.ts)
---
## 工具参考
### 相关页面
相关主题：[输入自动化工具](#input-automation), [性能分析工具](#performance-tools), [内存调试工具](#memory-debugging)
相关源码文件
以下源码文件用于生成本页说明：
- [src/tools/tools.ts](https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/src/tools/tools.ts)
- [src/tools/ToolDefinition.ts](https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/src/tools/ToolDefinition.ts)
- [src/tools/categories.ts](https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/src/tools/categories.ts)
- [src/tools/webmcp.ts](https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/src/tools/webmcp.ts)
- [src/McpResponse.ts](https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/src/McpResponse.ts)
- [scripts/generate-docs.ts](https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/scripts/generate-docs.ts)
# 工具参考
本页面详细描述 chrome-devtools-mcp 项目中的工具（Tool）系统架构、定义方式、分类体系以及运行时行为。
## 概述
工具系统是 chrome-devtools-mcp 的核心组件，它将 Chrome DevTools Protocol (CDP) 的能力封装为可通过 MCP (Model Context Protocol) 调用的接口。该系统支持两类工具：
- **全局工具 (Tool)**：不依赖于特定页面的工具，如浏览器管理、网络控制等
- **页面作用域工具 (PageTool)**：需要绑定到特定页面的工具，如元素交互、表单填充等
资料来源：[src/tools/ToolDefinition.ts:1-50]()
## 工具架构
### 类型层级
工具系统采用 TypeScript 类型安全的设计，通过泛型约束确保工具定义的正确性。
```mermaid
graph TD
A[BaseToolDefinition] --> B[ToolDefinition]
A --> C[PageToolDefinition]
B --> D[DefinedTool]
C --> E[DefinedPageTool]
```
| 类型名称 | 作用域 | 描述 |
|---------|--------|------|
| `BaseToolDefinition` | 基础 | 所有工具定义的基类 |
| `ToolDefinition` | 全局 | 不依赖页面的工具定义 |
| `PageToolDefinition` | 页面 | 依赖页面上下文工具定义 |
| `DefinedTool` | 全局 | 已解析的工具定义 |
| `DefinedPageTool` | 页面 | 已解析的页面作用域工具定义 |
资料来源：[src/tools/ToolDefinition.ts:50-80]()
### 工具结构
每个工具定义包含以下核心字段：
| 字段 | 类型 | 必填 | 描述 |
|------|------|------|------|
| `name` | `string` | 是 | 工具唯一标识名称 |
| `description` | `string` | 是 | 工具功能描述，用于 AI 理解用途 |
| `schema` | `zod.ZodRawShape` | 是 | 输入参数 schema 定义 |
| `handler` | `Function` | 是 | 工具执行逻辑 |
| `annotations` | `ToolAnnotations` | 否 | 工具元数据注解 |
| `blockedByDialog` | `boolean` | 否 | 是否被对话框阻塞 |
| `pageScoped` | `boolean` | 否 | 是否为页面作用域工具 |
资料来源：[src/tools/ToolDefinition.ts:80-120]()
## 工具定义函数
### defineTool - 全局工具定义
`defineTool` 用于定义不依赖特定页面的工具，如浏览器管理、性能分析等。
```typescript
export function defineTool(
definition: ToolDefinition,
): DefinedTool;
```
**使用示例**：
```typescript
export const myGlobalTool = defineTool({
name: 'my_global_tool',
description: 'A global tool that works without page context',
schema: {
param1: zod.string().describe('First parameter'),
},
annotations: {
category: ToolCategory.BROWSER,
readOnlyHint: true,
},
blockedByDialog: false,
handler: async (request, response, context) => {
// 工具执行逻辑
},
});
```
资料来源：[src/tools/ToolDefinition.ts:140-180]()
### definePageTool - 页面作用域工具定义
`definePageTool` 用于定义需要页面上下文的工具，handler 函数会自动接收 `page: ContextPage` 参数。
```typescript
export function definePageTool(
definition: PageToolDefinition,
): DefinedPageTool;
```
**使用示例**：
```typescript
export const clickTool = definePageTool({
name: 'click',
description: 'Clicks on an element identified by uid',
schema: {
uid: zod.string().describe('The uid of the element to click'),
},
annotations: {
category: ToolCategory.INPUT,
readOnlyHint: false,
},
blockedByDialog: true,
handler: async (request, response, context) => {
// request 包含 { page: ContextPage, params: { uid: string } }
},
});
```
资料来源：[src/tools/ToolDefinition.ts:180-220]()
### 工厂模式支持
两个定义函数都支持传入工厂函数，用于动态生成工具定义：
```typescript
export function definePageTool<
Schema extends zod.ZodRawShape,
Args extends ParsedArguments = ParsedArguments,
>(
definition: (args?: Args) => PageToolDefinition,
): (args?: Args) => DefinedPageTool;
```
这允许工具定义根据传入参数进行条件性配置。
资料来源：[src/tools/ToolDefinition.ts:220-240]()
## 工具分类体系
### 分类枚举
工具按功能域划分为多个分类，便于管理和文档生成：
| 分类标识 | 显示名称 | 描述 |
|---------|----------|------|
| `NAVIGATION` | Navigation | 页面导航相关工具 |
| `INPUT` | Input Automation | 用户输入和交互工具 |
| `INSPECTION` | Inspection | 页面元素检查和快照工具 |
| `EMULATION` | Emulation | 环境模拟工具 |
| `PERFORMANCE` | Performance | 性能分析工具 |
| `NETWORK` | Network | 网络请求相关工具 |
| `BROWSER` | Browser | 浏览器管理工具 |
| `EXTENSION` | Extensions | Chrome 扩展管理工具 |
| `WEBMCP` | WebMCP | WebMCP 协议工具 |
| `EXPERIMENTAL` | Experimental | 实验性功能工具 |
资料来源：[src/tools/categories.ts]()
### 分类标签映射
文档生成系统使用标签映射将分类标识转换为可读名称：
```typescript
const labels: Record = {
[ToolCategory.NAVIGATION]: 'Navigation',
[ToolCategory.INPUT]: 'Input Automation',
[ToolCategory.INSPECTION]: 'Inspection',
// ...
};
```
资料来源：[scripts/generate-docs.ts:30-50]()
## 工具注解系统
### 注解结构
`annotations` 字段提供工具的额外元数据：
```typescript
interface ToolAnnotations {
category: ToolCategory; // 工具所属分类
readOnlyHint?: boolean; // 是否为只读操作
conditions?: string[]; // 需要的实验性标志
docsLink?: string; // 文档链接
}
```
| 注解字段 | 类型 | 描述 |
|---------|------|------|
| `category` | `ToolCategory` | **必填** 工具分类 |
| `readOnlyHint` | `boolean` | 提示是否为只读操作，帮助 AI 决策是否需要确认 |
| `conditions` | `string[]` | 激活工具所需的实验性标志列表 |
| `docsLink` | `string` | 相关文档链接 |
资料来源：[src/tools/ToolDefinition.ts:40-48]()
### 条件激活机制
某些工具需要特定标志才能使用，条件在 `conditions` 数组中声明：
```typescript
const experimentalTool = definePageTool({
name: 'screencast_start',
description: 'Starts a screencast recording',
annotations: {
category: ToolCategory.EXPERIMENTAL,
conditions: ['experimentalScreencast'], // 需要 --experimentalScreencast=true
},
schema: {},
blockedByDialog: false,
handler: async (request, response, context) => {
// 处理屏幕录制
},
});
```
资料来源：[scripts/generate-docs.ts:60-80]()
## Schema 定义规范
### Zod Schema 结构
工具参数通过 Zod 进行类型安全的 schema 定义：
```typescript
schema: {
paramName: zod.string().describe('Parameter description'),
optionalParam: zod.number().optional().describe('Optional parameter'),
enumParam: zod.enum(['option1', 'option2']).describe('Enum parameter'),
}
```
### 常用 Schema 组件
| Schema 类型 | 用途 | 示例 |
|------------|------|------|
| `zod.string()` | 字符串参数 | 用户名、URL |
| `zod.number()` | 数字参数 | 坐标、超时值 |
| `zod.boolean()` | 布尔参数 | 开关选项 |
| `zod.enum()` | 枚举参数 | 类型选择 |
| `zod.array()` | 数组参数 | 多个值 |
| `zod.optional()` | 可选参数 | 标记为可选 |
### 预定义 Schema
系统提供常用 schema 组件：
```typescript
export const pageIdSchema = {
pageId: zod.number().optional().describe('Targets a specific page by ID.'),
};
export const timeoutSchema = {
timeout: zod
.number()
.int()
.optional()
.describe('Maximum wait time in milliseconds.'),
};
```
资料来源：[src/tools/ToolDefinition.ts:55-70]()
## 请求处理流程
### Handler 函数签名
**全局工具 Handler**：
```typescript
handler: (
request: Request & { page?: ContextPage },
response: Response,
context: Context,
) => Promise
```
**页面作用域工具 Handler**：
```typescript
handler: (
request: Request & { page: ContextPage },
response: Response,
context: Context,
) => Promise
```
### 请求生命周期
```mermaid
sequenceDiagram
participant Client as MCP Client
participant Server as MCP Server
participant Tool as Tool Handler
participant CDP as Chrome DevTools
Client->>Server: 工具调用请求
Server->>Tool: 解析参数 + 验证 Schema
alt 页面作用域工具
Tool->>Tool: 验证页面上下文
end
Tool->>CDP: CDP 协议命令
CDP-->>Tool: 执行结果
Tool->>Server: 格式化响应
Server-->>Client: MCP 响应
```
## MCP 响应集成
### 响应格式化
工具执行结果通过 `McpResponse` 类进行格式化，支持多种输出格式：
```typescript
response.setListWebMcpTools(); // 设置 WebMCP 工具列表
response.setText(content: string); // 设置文本内容
response.setScreenshot(filePath: string); // 设置截图路径
response.setSnapshot(snapshot: string); // 设置快照内容
```
### 响应数据结构
```typescript
interface ToolResponse {
content: ContentBlock[]; // 内容块列表
structuredContent?: { // 结构化内容
webmcpTools?: WebMcpTool[]; // WebMCP 工具信息
networkRequests?: NetworkRequest[];
pagination?: PaginationData;
};
}
```
资料来源：[src/McpResponse.ts:1-50]()
## 工具注册与发现
### 工具列表生成
文档生成脚本自动扫描所有工具定义并生成参考文档：
```mermaid
graph LR
A[工具源文件] --> B[generate-docs.ts]
B --> C[工具分类]
C --> D[Markdown 文档]
D --> E[docs/tool-reference.md]
B --> F[README TOC]
```
生成过程包括：
1. 扫描所有 `src/tools/` 目录下的工具定义
2. 按 `ToolCategory` 分组
3. 生成参数表格和描述
4. 输出到 `docs/tool-reference.md`
资料来源：[scripts/generate-docs.ts:100-150]()
### 工具列表输出格式
```markdown
## WebMCP tools
name="list_webmcp_tools", description="Lists all WebMCP tools...", inputSchema={}
name="execute_webmcp_tool", description="Executes a WebMCP tool...", inputSchema={"toolName": {...}, "input": {...}}
```
资料来源：[src/McpResponse.ts:60-80]()
## WebMCP 特殊工具
### list_webmcp_tools
列出页面暴露的所有 WebMCP 工具：
```typescript
export const listWebMcpTools = definePageTool({
name: 'list_webmcp_tools',
description: `Lists all WebMCP tools the page exposes.`,
annotations: {
category: ToolCategory.WEBMCP,
readOnlyHint: true,
},
schema: {},
blockedByDialog: false,
handler: async (_request, response, _context) => {
response.setListWebMcpTools();
},
});
```
资料来源：[src/tools/webmcp.ts:15-30]()
### execute_webmcp_tool
执行页面暴露的 WebMCP 工具：
```typescript
export const executeWebMcpTool = definePageTool({
name: 'execute_webmcp_tool',
description: `Executes a WebMCP tool exposed by the page.`,
annotations: {
category: ToolCategory.WEBMCP,
readOnlyHint: false,
},
schema: {
toolName: zod.string().describe('The name of the WebMCP tool to execute'),
input: zod.string().optional().describe('The JSON-stringified parameters'),
},
blockedByDialog: false,
handler: async (request, response) => {
// 解析输入并执行工具
},
});
```
资料来源：[src/tools/webmcp.ts:32-60]()
## 类型安全约束
项目对 TypeScript 使用有严格的类型安全要求：
| 规则 | 说明 | 违规处理 |
|------|------|----------|
| 禁止 `any` | 不允许使用 any 类型 | 使用具体类型替代 |
| 禁止 `as` | 不允许类型断言 | 使用类型守卫或验证 |
| 禁止 `!` | 不允许非空断言 | 使用显式检查 |
| 禁止 `@ts-ignore` | 不允许忽略类型检查 | 修复类型问题 |
| 推荐 `for..of` | 替代 `forEach` | 提高可读性 |
资料来源：[AGENTS.md:20-35]()
## 总结
工具系统是 chrome-devtools-mcp 实现浏览器自动化和调试能力的基础架构。通过：
- **类型安全的工具定义**：利用 TypeScript 泛型和 Zod schema 确保编译期和运行期类型正确
- **分层架构**：区分全局工具和页面作用域工具，适配不同的使用场景
- **注解驱动**：通过 annotations 提供元数据，支持文档生成和 AI 决策
- **统一处理流程**：标准化工具的注册、调用、响应流程
开发者可以基于 `defineTool` 和 `definePageTool` 快速扩展新的工具能力，同时保持代码的一致性和可维护性。
---
## 输入自动化工具
### 相关页面
相关主题：[工具参考](#tool-reference)
相关源码文件
以下源码文件用于生成本页说明：
- [src/tools/input.ts](https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/src/tools/input.ts)
- [src/tools/ToolDefinition.ts](https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/src/tools/ToolDefinition.ts)
- [skills/chrome-devtools-cli/SKILL.md](https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/skills/chrome-devtools-cli/SKILL.md)
- [skills/chrome-devtools/SKILL.md](https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/skills/chrome-devtools/SKILL.md)
# 输入自动化工具
## 概述
输入自动化工具是 chrome-devtools-mcp 项目的核心功能模块之一，提供了通过 Chrome DevTools Protocol 对网页进行自动化交互的能力。该模块允许通过 MCP（Model Context Protocol）协议向浏览器发送命令，实现模拟用户输入、元素交互和文件上传等操作。
这些工具位于 `src/tools/input.ts` 中，属于页面作用域工具（page-scoped tools），需要先选择一个活跃的页面上下文才能执行。工具集涵盖了从简单的按键操作到复杂的文本输入和文件上传等常见用户交互场景。
## 架构设计
### 工具定义模式
输入自动化工具采用统一的工厂函数模式进行定义，使用 TypeScript 和 Zod 进行类型安全和参数校验。核心工具通过 `definePageTool` 函数注册，该函数来源于 `ToolDefinition.ts` 模块。资料来源：[src/tools/ToolDefinition.ts:43-68]()
```mermaid
graph TD
A[用户请求] --> B[参数校验层 Zod Schema]
B --> C[Handler 处理函数]
C --> D[Playwright Page API]
D --> E[浏览器页面执行]
E --> F[响应构建]
F --> G[MCP 响应]
```
### 页面上下文依赖
所有输入自动化工具均为页面作用域工具，需要通过 `select_page` 选择目标页面后才能执行。这种设计确保了操作的上下文隔离性和安全性。资料来源：[src/tools/ToolDefinition.ts:55-67]()
## 工具分类
输入自动化工具按功能可分为以下三类：
| 类别 | 工具名称 | 功能描述 |
|------|----------|----------|
| 键盘操作 | `press_key` | 按下键盘按键或组合键 |
| 键盘操作 | `type_text` | 向聚焦的输入框输入文本 |
| 元素交互 | `click` | 点击指定元素 |
| 元素交互 | `drag` | 拖拽元素到目标位置 |
| 元素交互 | `fill` | 填充输入框或选择选项 |
| 元素交互 | `hover` | 鼠标悬停在元素上 |
| 文件操作 | `upload_file` | 通过文件输入元素上传文件 |
## 键盘操作工具
### press_key 工具
`press_key` 工具用于模拟键盘按键操作，支持单键、修饰键组合以及特殊键序列。
**参数定义：**
| 参数名 | 类型 | 必填 | 描述 |
|--------|------|------|------|
| `key` | string | 是 | 按键名称，支持组合键格式如 "Control+A"、"Control+Shift+R" |
| `includeSnapshot` | boolean | 否 | 是否在操作后返回页面快照 |
**支持的修饰键：**
- `Control`
- `Shift`
- `Alt`
- `Meta`
**特殊键示例：**
- `Enter` - 回车键
- `Tab` - 制表符
- `Escape` - 退出键
- `ArrowUp` / `ArrowDown` - 方向键
- `Control++` - Ctrl 加号（缩放）
- `Control+Shift+R` - 强制刷新
**实现原理：**
该工具使用 `parseKey` 函数解析按键字符串，将修饰键与主键分离。执行时按照修饰键按下 → 主键按下 → 修饰键释放的顺序进行操作，确保组合键的正确性。资料来源：[src/tools/input.ts:1-100]()
```typescript
const result = await page.waitForEventsAfterAction(async () => {
for (const modifier of modifiers) {
await page.pptrPage.keyboard.down(modifier);
}
await page.pptrPage.keyboard.press(key);
for (const modifier of modifiers.toReversed()) {
await page.pptrPage.keyboard.up(modifier);
}
});
```
### type_text 工具
`type_text` 工具用于向当前聚焦的输入元素输入文本内容。
**参数定义：**
| 参数名 | 类型 | 必填 | 描述 |
|--------|------|------|------|
| `text` | string | 是 | 要输入的文本内容 |
| `submitKey` | string | 否 | 输入完成后自动按下的提交键，如 "Enter" |
| `includeSnapshot` | boolean | 否 | 是否在操作后返回页面快照 |
**使用场景：**
- 在文本框中输入搜索关键词
- 填写表单字段
- 在富文本编辑器中输入内容
**执行流程：**
```mermaid
graph LR
A[聚焦输入框] --> B[逐字符输入文本]
B --> C{指定了 submitKey?}
C -->|是| D[按下提交键]
C -->|否| E[操作完成]
D --> E
```
## 元素交互工具
### click 工具
`click` 工具通过元素 ID 执行点击操作，支持单击和双击模式。
**参数定义：**
| 参数名 | 类型 | 必填 | 描述 |
|--------|------|------|------|
| `id` | string | 是 | 目标元素的 UID（从快照获取） |
| `dblClick` | boolean | 否 | 是否执行双击，默认为 false |
| `includeSnapshot` | boolean | 否 | 是否在操作后返回页面快照 |
### hover 工具
`hover` 工具将鼠标移动到指定元素上方，常用于触发 CSS 悬浮效果或显示下拉菜单。
### drag 工具
`drag` 工具执行拖拽操作，将源元素拖拽到目标元素位置。
**参数定义：**
| 参数名 | 类型 | 必填 | 描述 |
|--------|------|------|------|
| `src` | string | 是 | 源元素 ID |
| `dst` | string | 是 | 目标元素 ID |
| `includeSnapshot` | boolean | 否 | 是否在操作后返回页面快照 |
### fill 工具
`fill` 工具用于快速填充表单输入框或选择下拉选项，相比 `type_text` 更加高效。
**参数定义：**
| 参数名 | 类型 | 必填 | 描述 |
|--------|------|------|------|
| `id` | string | 是 | 目标输入框或选择框的 ID |
| `text` | string | 是 | 要填充的文本或选项值 |
| `includeSnapshot` | boolean | 否 | 是否在操作后返回页面快照 |
## 文件上传工具
### upload_file 工具
`upload_file` 工具通过已存在的文件输入元素（``）上传本地文件。
**参数定义：**
| 参数名 | 类型 | 必填 | 描述 |
|--------|------|------|------|
| `id` | string | 是 | 文件输入元素的 ID |
| `filePath` | string | 是 | 本地文件的绝对路径 |
| `includeSnapshot` | boolean | 否 | 是否在操作后返回页面快照 |
**使用限制：**
- 目标元素必须是 `` 或具有 `contenteditable` 属性的元素
- 文件路径必须是服务器可访问的本地路径
- 不支持拖拽上传区域（需使用 `drag` 工具模拟拖拽）
## 通用参数与配置
### 快照参数
所有交互工具都支持 `includeSnapshot` 可选参数，用于控制在操作执行后是否返回页面的可访问性树快照。
| 参数值 | 行为描述 |
|--------|----------|
| `true` | 操作完成后返回完整快照，可用于验证操作效果 |
| `false` 或未指定 | 仅返回操作结果文本，不返回快照 |
建议在以下场景启用快照返回：
- 验证表单提交后的页面状态
- 检查下拉菜单或弹窗是否正确显示
- 确认异步操作完成后的 DOM 变化
### 页面选择
交互工具执行前必须通过 `select_page` 选择目标页面：
```bash
chrome-devtools select_page 1 # 选择索引为 1 的页面
chrome-devtools select_page 1 --bringToFront true # 选择并切换到前台
```
未选择页面的直接调用将导致错误。
## 工作流程
### 典型交互流程
```mermaid
graph TD
A[初始化浏览器连接] --> B[选择目标页面]
B --> C[获取页面快照]
C --> D[识别目标元素 ID]
D --> E[执行交互操作]
E --> F{需要验证结果?}
F -->|是| G[获取更新后的快照]
F -->|否| H[完成]
G --> H
```
### 对话框处理
部分操作（如表单提交、文件上传确认）可能触发浏览器对话框。系统通过 `blockedByDialog` 属性控制工具是否等待对话框处理：
- `press_key` 等工具默认 `blockedByDialog: true`，会在对话框出现时阻塞
- 遇到对话框时，需使用 `handle_dialog` 工具进行响应
```bash
chrome-devtools handle_dialog accept # 接受对话框
chrome-devtools handle_dialog dismiss --promptText "取消" # 拒绝并填写提示文本
```
## 错误处理
### 常见错误场景
| 错误类型 | 原因 | 解决方案 |
|----------|------|----------|
| 元素未找到 | 提供的 ID 指向不存在的元素 | 使用 `take_snapshot` 重新获取最新页面状态 |
| 页面未选中 | 未先调用 `select_page` | 选择目标页面后重试 |
| 对话框阻塞 | 操作被对话框中断 | 使用 `handle_dialog` 处理后再重试 |
| 超时错误 | 元素等待超时 | 增加超时时间或检查元素是否存在 |
### 最佳实践
1. **始终获取最新快照**：页面状态可能因异步操作变化，建议每次交互前重新调用 `take_snapshot`
2. **使用 appropriate 的超时设置**：对于慢速网络或复杂页面，适当增加超时时间
3. **验证操作结果**：使用快照对比验证交互是否成功执行
4. **避免并行冲突**：多个工具同时操作同一页面可能导致不可预期行为
## 命令行使用示例
```bash
# 点击按钮
chrome-devtools click "btn-submit"
# 双击并获取快照
chrome-devtools click "btn-edit" --dblClick true --includeSnapshot true
# 输入文本并提交
chrome-devtools type_text "Hello World" --submitKey "Enter"
# 按下组合键
chrome-devtools press_key "Control+A" --includeSnapshot true
# 拖拽操作
chrome-devtools drag "source-id" "target-id"
# 文件上传
chrome-devtools upload_file "file-input" "/path/to/document.pdf"
```
## 相关资源
- 完整工具列表和参数说明：参考 `skills/chrome-devtools-cli/SKILL.md`
- 元素定位策略：使用 `take_snapshot` 获取可访问性树和元素 UID
- 高级调试：结合 `evaluate_script` 工具执行自定义 JavaScript 验证
---
## 性能分析工具
### 相关页面
相关主题：[工具参考](#tool-reference)
相关源码文件
以下源码文件用于生成本页说明：
- [src/tools/performance.ts](https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/src/tools/performance.ts)
- [src/tools/lighthouse.ts](https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/src/tools/lighthouse.ts)
- [src/trace-processing/parse.ts](https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/src/trace-processing/parse.ts)
- [skills/debug-optimize-lcp/SKILL.md](https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/skills/debug-optimize-lcp/SKILL.md)
- [skills/debug-optimize-lcp/references/lcp-snippets.md](https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/skills/debug-optimize-lcp/references/lcp-snippets.md)
- [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)
- [scripts/eval_scenarios/performance_test.ts](https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/scripts/eval_scenarios/performance_test.ts)
# 性能分析工具
## 概述
性能分析工具是 chrome-devtools-mcp 提供的核心功能集，用于监控、测量和优化网页性能。该工具集涵盖性能追踪、性能洞察分析、内存快照捕获以及 Lighthouse 审计等多个维度，为开发者提供全面的性能诊断能力。
工具采用 Chrome DevTools Protocol (CDP) 与浏览器内核深度交互，支持性能追踪录制、追踪文件保存与加载、性能指标解析以及自动化 Lighthouse 审计等功能。
资料来源：[src/tools/performance.ts]() [src/tools/lighthouse.ts]()
## 工具架构
### 模块组成
| 模块 | 文件路径 | 职责 |
|------|----------|------|
| 性能追踪 | `src/tools/performance.ts` | 启动/停止追踪录制，保存追踪文件 |
| 性能洞察 | `src/tools/performance.ts` | 分析 Performance Insight 数据 |
| 内存快照 | `src/tools/performance.ts` | 捕获 V8 堆内存快照 |
| Lighthouse 审计 | `src/tools/lighthouse.ts` | 执行无头性能审计 |
| 追踪解析 | `src/trace-processing/parse.ts` | 解析和处理追踪数据 |
### 工具分类
根据工具作用域可分为两类：
1. **全局工具 (Global Tools)**：独立于页面上下文，直接通过 CDP 与浏览器交互
2. **页面工具 (Page Tools)**：作用于当前选中的页面，需先选择页面
性能分析工具中，`performance_start_trace`、`performance_stop_trace` 和 `take_memory_snapshot` 属于全局工具，而 `performance_analyze_insight` 和 `lighthouse_audit` 属于页面工具。
资料来源：[src/tools/ToolDefinition.ts]()
## 性能追踪 (Performance Trace)
### 功能描述
性能追踪工具提供 Chrome 开发者工具的性能录制功能，能够捕获页面在加载和运行过程中的详细执行轨迹数据。
### 工作流程
```mermaid
graph TD
A[开始追踪] --> B[performance_start_trace]
B --> C{reload 参数}
C -->|true| D[重新加载页面并录制]
C -->|false| E[录制当前页面状态]
D --> F[CDP Performance.startTrace]
E --> F
F --> G[追踪数据缓存于内存]
G --> H[performance_stop_trace]
H --> I{filePath 参数}
I -->|提供| J[保存到文件]
I -->|未提供| K[返回 JSON 数据]
J --> L[追踪完成]
K --> L
```
### 工具参数
#### performance_start_trace
| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `reload` | `boolean` | `false` | 是否在开始追踪前重新加载页面 |
| `screenshot` | `boolean` | `false` | 是否捕获截屏 |
| `filePath` | `string` | 无 | 追踪文件的保存路径（可选） |
当 `reload` 设置为 `true` 时，工具会重新加载页面并录制完整的加载过程，这对于分析页面首次加载性能至关重要。
资料来源：[src/tools/performance.ts]()
资料来源：[skills/chrome-devtools/SKILL.md]()
#### performance_stop_trace
| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `filePath` | `string` | 无 | 导出追踪数据的文件路径（可选） |
停止当前正在进行的性能追踪录制，并将追踪数据保存到指定文件或返回 JSON 数据。
### 追踪数据格式
追踪数据采用 JSON 格式，包含以下核心部分：
- **traceEvents**：Chrome 追踪格式的事件数组
- **metadata**：追踪元数据，包括浏览器版本、录制时间等
- **screenshots**：如果启用截屏，则包含 Base64 编码的截屏数据
## 性能洞察分析 (Performance Insights)
### 功能描述
Performance Insights 是 Chrome DevTools 中比传统 Performance 面板更现代的性能分析界面，提供以用户为中心的性能指标解读。工具 `performance_analyze_insight` 用于获取这些洞察数据。
### 支持的洞察类型
| 洞察类型 | 说明 |
|----------|------|
| `LCPBreakdown` | Largest Contentful Paint 时间分解 |
| `FCPBreakdown` | First Contentful Paint 时间分解 |
| `CLSBreakdown` | Cumulative Layout Shift 变化分析 |
| `TTFBBreakdown` | Time To First Byte 时间分解 |
### 工具参数
#### performance_analyze_insight
| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `handle` | `string` | 是 | 追踪处理标识符 |
| `type` | `string` | 是 | 洞察类型（如 `LCPBreakdown`） |
### LCP 优化指南
根据 LCPBreakdown 洞察数据，可按以下目标进行优化：
| 瓶颈目标 | 占比目标 | 优化策略 |
|----------|----------|----------|
| TTFB | ~40% | 减少重定向，优化服务器响应时间，使用 CDN 缓存 HTML |
| 资源加载时间 | ~40% | 使用 WebP/AVIF 格式，启用压缩，设置缓存头 |
| 元素渲染延迟 | <10% | 内联关键 CSS，延迟非关键资源，打破长任务 |
| LCP 资源加载延迟 | ~40% | 使用 ``，避免懒加载 LCP 图片 |
资料来源：[skills/debug-optimize-lcp/SKILL.md]()
资料来源：[skills/debug-optimize-lcp/references/optimization-strategies.md]()
## 内存快照 (Memory Snapshot)
### 功能描述
内存快照工具用于捕获 V8 JavaScript 引擎的堆内存状态，帮助开发者分析内存泄漏和内存使用情况。
### 工具参数
#### take_memory_snapshot
| 参数 | 类型 | 说明 |
|------|------|------|
| `filePath` | `string` | 快照文件的保存路径 |
快照文件格式为 `.heapsnapshot`，可使用 Chrome DevTools 的 Memory 面板加载分析。
### 工作原理
1. 调用 CDP 的 `HeapProfiler.takeHeapSnapshot` 方法
2. 将快照数据序列化为 Chrome 支持的堆快照格式
3. 保存到指定文件路径或返回数据
## Lighthouse 审计
### 功能描述
Lighthouse 审计工具提供基于 Chromium 内置 Lighthouse 的自动化网站质量审计，覆盖无障碍访问（Accessibility）、搜索引擎优化（SEO）、最佳实践等多个维度。
### 与性能追踪的区别
| 维度 | Lighthouse 审计 | 性能追踪 |
|------|------------------|----------|
| 用途 | 网站质量综合评估 | 底层性能数据录制 |
| 输出 | 结构化审计报告 | 原始追踪事件数据 |
| 适用场景 | 快速评分、CI 集成 | 深度性能分析 |
### 工具参数
#### lighthouse_audit
| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `mode` | `navigation` \| `snapshot` | `navigation` | 审计模式：`navigation` 重新加载并审计，`snapshot` 分析当前状态 |
| `device` | `desktop` \| `mobile` | `desktop` | 模拟设备类型 |
| `outputDirPath` | `string` | 临时目录 | 报告文件的保存目录 |
| `pageId` | `number` | 当前选中页 | 指定审计的目标页面 |
### 审计类别
Lighthouse 审计默认包含以下类别：
| 类别 | 说明 |
|------|------|
| `accessibility` | 无障碍访问审计，检测缺失的标签、无效的 ARIA 属性等 |
| `seo` | 搜索引擎优化审计 |
| `best-practices` | Web 最佳实践审计 |
| `agentic-browsing` | 代理浏览能力审计 |
### 审计结果结构
审计结果为 JSON 格式，包含：
- `scores`：各审计类别的分数（0-1 范围）
- `audits`：详细审计结果，包含通过/失败状态和建议
- `timing`：审计执行时间
资料来源：[src/tools/lighthouse.ts]()
## LCP 调试与优化工作流
### 诊断流程
```mermaid
graph TD
A[开始 LCP 优化] --> B[performance_start_trace reload=true]
B --> C[录制页面加载追踪]
C --> D[performance_stop_trace]
D --> E[performance_analyze_insight LCPBreakdown]
E --> F{识别瓶颈}
F -->|TTFB 过高| G[优化服务器响应]
F -->|资源加载慢| H[优化资源大小和格式]
F -->|渲染延迟| I[消除阻塞资源]
G --> J[验证修复]
H --> J
I --> J
J --> K{重新录制}
K -->|需继续优化| B
K -->|达标| L[完成]
```
### JavaScript 诊断片段
#### 识别 LCP 元素
```javascript
async () => {
return await new Promise(resolve => {
new PerformanceObserver(list => {
const entries = list.getEntries();
const last = entries[entries.length - 1];
resolve({
element: last.element?.tagName,
id: last.element?.id,
url: last.url,
startTime: last.startTime,
renderTime: last.renderTime,
size: last.size,
});
}).observe({type: 'largest-contentful-paint', buffered: true});
});
};
```
#### 审计常见问题
```javascript
() => {
const issues = [];
// 检查视口内懒加载的图片
document.querySelectorAll('img[loading="lazy"]').forEach(img => {
const rect = img.getBoundingClientRect();
if (rect.top < window.innerHeight) {
issues.push({
issue: 'lazy-loaded image in viewport',
fix: 'Remove loading="lazy" from this image',
});
}
});
return issues;
};
```
资料来源：[skills/debug-optimize-lcp/references/lcp-snippets.md]()
## 测试场景
性能分析工具的自动化测试定义于 `scripts/eval_scenarios/performance_test.ts`：
| 场景 | 预期行为 |
|------|----------|
| 目标 URL | `https://developers.chrome.com` |
| 最大轮次 | 2 |
| 预期调用 | 第一轮：导航或新建页面；第二轮：启动性能追踪 |
资料来源：[scripts/eval_scenarios/performance_test.ts]()
## 使用限制与注意事项
1. **对话处理**：性能追踪工具（`performance_start_trace`）在有对话框打开时会被阻塞
2. **超时配置**：使用 `timeout` 参数控制操作超时时间，避免长时间等待
3. **文件路径**：建议为追踪文件和快照指定明确的文件路径，便于后续分析
4. **页面选择**：Lighthouse 审计等页面工具需要先选择目标页面
## 相关工具链接
- 导航工具：[navigate_page](skills/chrome-devtools/SKILL.md) - 页面导航
- 快照工具：[take_snapshot](skills/chrome-devtools/SKILL.md) - 页面结构快照
- 模拟工具：[emulate](skills/chrome-devtools-cli/SKILL.md) - 网络和设备模拟
---
## 内存调试工具
### 相关页面
相关主题：[工具参考](#tool-reference)
相关源码文件
以下源码文件用于生成本页说明：
- [src/tools/memory.ts](https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/src/tools/memory.ts)
- [src/HeapSnapshotManager.ts](https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/src/HeapSnapshotManager.ts)
- [src/formatters/HeapSnapshotFormatter.ts](https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/src/formatters/HeapSnapshotFormatter.ts)
- [skills/memory-leak-debugging/SKILL.md](https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/skills/memory-leak-debugging/SKILL.md)
- [skills/memory-leak-debugging/references/compare_snapshots.js](https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/skills/memory-leak-debugging/references/compare_snapshots.js)
- [src/tools/ToolDefinition.ts](https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/src/tools/ToolDefinition.ts)
# 内存调试工具
## 概述
内存调试工具是 chrome-devtools-mcp 提供的核心功能集之一，用于分析和诊断浏览器页面中的内存问题。这些工具通过 Chrome DevTools Protocol 与 Chromium 的堆快照引擎交互，帮助开发者识别内存泄漏、追踪对象增长，并理解 JavaScript 运行时的内存分布情况。
内存调试工具的主要职责包括：
- 捕获页面的堆快照（Heap Snapshot）文件
- 加载和分析堆快照数据
- 提供快照摘要统计信息
- 支持与外部内存分析工具（如 Memlab）的集成
- 包含用于手动比较快照的回退脚本
资料来源：[src/tools/memory.ts:1-15]()
## 架构设计
### 核心组件
内存调试工具的架构由以下核心组件构成：
| 组件 | 文件路径 | 职责描述 |
|------|----------|----------|
| MemoryToolDefinitions | `src/tools/memory.ts` | 定义所有内存相关的 MCP 工具 |
| HeapSnapshotManager | `src/HeapSnapshotManager.ts` | 管理堆快照的加载、解析和缓存 |
| HeapSnapshotFormatter | `src/formatters/HeapSnapshotFormatter.ts` | 格式化堆快照输出为可读格式 |
### 工具定义架构
内存工具使用统一的工具定义框架，该框架基于 `definePageTool` 工厂函数构建。每个工具定义包含以下结构：
```typescript
export interface BaseToolDefinition {
name: string;
description: string;
annotations: {
category: ToolCategory;
readOnlyHint: boolean;
conditions?: string[];
};
schema: Schema;
blockedByDialog: boolean;
}
```
资料来源：[src/tools/ToolDefinition.ts:20-35]()
## 工具 API
### takeMemorySnapshot
**功能**：捕获当前选中页面的堆快照。
```typescript
export const takeMemorySnapshot = definePageTool({
name: 'take_memory_snapshot',
description: `Capture a heap snapshot of the currently selected page. Use to analyze the memory distribution of JavaScript objects and debug memory leaks.`,
annotations: {
category: ToolCategory.MEMORY,
readOnlyHint: false,
},
schema: {
filePath: zod
.string()
.describe('A path to a .heapsnapshot file to save the heapsnapshot to.'),
},
blockedByDialog: true,
handler: async (request, response, context) => {
const page = request.page;
context.validatePath(request.params.filePath);
await page.pptrPage.captureHeapSnapshot({
path: ensureExtension(request.params.filePath, '.heapsnapshot'),
});
response.appendResponseLine(
`Heap snapshot saved to ${request.params.filePath}`,
);
},
});
```
资料来源：[src/tools/memory.ts:16-46]()
**参数说明**：
| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| filePath | string | 是 | 堆快照文件的保存路径，必须以 `.heapsnapshot` 结尾 |
**执行流程**：
```mermaid
graph TD
A[调用 take_memory_snapshot] --> B[验证文件路径]
B --> C[执行 pptrPage.captureHeapSnapshot]
C --> D[保存 .heapsnapshot 文件]
D --> E[返回成功消息]
```
**使用示例**：
```bash
chrome-devtools take_memory_snapshot "./baseline.heapsnapshot"
chrome-devtools take_memory_snapshot "./target.heapsnapshot" --includeSnapshot true
```
### loadMemorySnapshot
**功能**：加载堆快照文件并返回摘要统计信息。
```typescript
export const exploreMemorySnapshot = defineTool({
name: 'load_memory_snapshot',
description:
'Loads a memory heapsnapshot and returns snapshot summary stats.',
annotations: {
category: ToolCategory.MEMORY,
readOnlyHint: true,
conditions: ['experimentalMemory'],
},
schema: {
filePath: zod.string().describe('A path to a .heapsnapshot file to read.'),
},
blockedByDialog: false,
// ...
});
```
资料来源：[src/tools/memory.ts:48-68]()
**参数说明**：
| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| filePath | string | 是 | 要读取的堆快照文件路径 |
**注意**：此工具需要 `experimentalMemory` 条件满足方可使用。
## 工作流程
### 基本内存调试流程
```mermaid
graph TD
A[1. 创建新页面或导航到目标页面] --> B[2. 使用 take_memory_snapshot 捕获基线快照]
B --> C[3. 执行目标操作（如用户交互）]
C --> D[4. 使用 take_memory_snapshot 捕获目标快照]
D --> E[5. 使用 Memlab 或回退脚本分析快照]
E --> F[6. 识别泄漏并修复]
F --> G[7. 重复验证]
```
### 完整内存泄漏调试流程
根据 SKILL.md 文档，内存泄漏调试的标准工作流程如下：
#### 步骤 1：建立基线快照
在执行任何操作之前，捕获页面的初始内存状态：
```bash
chrome-devtools take_memory_snapshot "./baseline.heapsnapshot"
```
资料来源：[skills/memory-leak-debugging/SKILL.md:1-20]()
#### 步骤 2：操作并捕获目标快照
执行可能存在内存泄漏的操作（如重复用户交互），然后再次捕获快照：
```bash
chrome-devtools take_memory_snapshot "./target.heapsnapshot"
```
#### 步骤 3：恢复页面状态
将页面恢复到原始状态，验证内存是否被正确释放：
> 使用 `click`、`fill` 等工具将页面操作回原始状态，观察内存是否释放。
资料来源：[skills/memory-leak-debugging/SKILL.md:21-35]()
#### 步骤 4：捕获最终快照
恢复操作后再次捕获快照：
```bash
chrome-devtools take_memory_snapshot "./final.heapsnapshot"
```
#### 步骤 5：分析对比
使用 Memlab 或回退脚本分析三个快照文件。
## 快照比较脚本
### compare_snapshots.js
当 Memlab 不可用时，可以使用项目提供的回退脚本进行快照比较。
**位置**：`skills/memory-leak-debugging/references/compare_snapshots.js`
**使用方法**：
```bash
node skills/memory-leak-debugging/references/compare_snapshots.js
```
资料来源：[skills/memory-leak-debugging/references/compare_snapshots.js:1-50]()
**输出内容**：
| 输出部分 | 说明 |
|----------|------|
| Top 10 growing objects | 按大小增长排序的前 10 个对象 |
| Top 3 common leak types | 最常见的 3 种泄漏类型 |
**检测的常见泄漏类型**：
```javascript
const commonLeaks = diffs.filter(
d =>
d.key.toLowerCase().includes('detached') ||
d.key.toLowerCase().includes('html') ||
d.key.toLowerCase().includes('eventlistener') ||
d.key.toLowerCase().includes('context') ||
d.key.toLowerCase().includes('closure'),
);
```
资料来源：[skills/memory-leak-debugging/references/compare_snapshots.js:40-52]()
### 输出示例
脚本会输出类似以下格式的结果：
```
--- Top 10 growing objects by size ---
Detached HTMLDivElement: +5 objects, +2048 bytes
Closure: +12 objects, +1024 bytes
--- Top 3 most common types of memory leaks found ---
Detached HTMLDivElement: +5 objects, +2048 bytes
EventListener: +3 objects, +512 bytes
Context: +2 objects, +256 bytes
```
## 常见内存泄漏类型
根据项目文档，堆快照分析中最常见的泄漏类型包括：
| 泄漏类型 | 描述 | 检测关键词 |
|----------|------|------------|
| Detached DOM nodes | 已从 DOM 树移除但仍被 JavaScript 引用的 DOM 节点 | `detached`, `html` |
| Closures | 形成闭包并捕获外部变量的函数 | `closure` |
| Event Listeners | 未正确移除的事件监听器 | `eventlistener` |
| Contexts | JavaScript 执行上下文未正确释放 | `context` |
资料来源：[skills/memory-leak-debugging/references/compare_snapshots.js:43-49]()
## 使用限制与注意事项
### 工具阻塞条件
`takeMemorySnapshot` 工具配置了 `blockedByDialog: true`，这意味着当页面上存在对话框时，该工具将被阻塞：
> **blockedByDialog**: 如果设置为 `true`，则工具在页面存在对话框时无法执行。
资料来源：[src/tools/memory.ts:38-39]()
### 路径验证
所有文件路径在执行前都会经过验证，确保快照文件能够正确保存到指定位置：
```typescript
context.validatePath(request.params.filePath);
```
资料来源：[src/tools/memory.ts:41]()
### 文件扩展名强制
脚本会自动为文件路径添加 `.heapsnapshot` 扩展名：
```typescript
await page.pptrPage.captureHeapSnapshot({
path: ensureExtension(request.params.filePath, '.heapsnapshot'),
});
```
资料来源：[src/tools/memory.ts:43-45]()
## 集成外部工具
### Memlab 集成
项目推荐使用 Memlab 进行高级内存泄漏分析。使用 `take_memory_snapshot` 生成 `.heapsnapshot` 文件后，可参考 `references/memlab.md` 文档进行详细分析。
> **重要提示**：不要使用 `read_file` 或 `cat` 命令直接读取原始的 `.heapsnapshot` 文件。
资料来源：[skills/memory-leak-debugging/SKILL.md:36-50]()
## 命令行使用
### 基本命令
```bash
# 捕获堆快照
chrome-devtools take_memory_snapshot "./snap.heapsnapshot"
# 加载并分析快照
chrome-devtools load_memory_snapshot "./snap.heapsnapshot"
```
### 完整示例
```bash
# 1. 导航到目标页面
chrome-devtools navigate_page --url "https://example.com"
# 2. 捕获基线快照
chrome-devtools take_memory_snapshot "./baseline.heapsnapshot"
# 3. 执行测试操作（重复 10 次以放大泄漏）
chrome-devtools click "button" # 执行操作
chrome-devtools click "button" # 重复操作
# ... 重复 10 次
# 4. 捕获目标快照
chrome-devtools take_memory_snapshot "./target.heapsnapshot"
# 5. 恢复页面状态
# ... 执行恢复操作
# 6. 捕获最终快照
chrome-devtools take_memory_snapshot "./final.heapsnapshot"
# 7. 使用回退脚本分析
node skills/memory-leak-debugging/references/compare_snapshots.js ./baseline.heapsnapshot ./target.heapsnapshot
```
## 相关文件索引
| 文件 | 描述 |
|------|------|
| `src/tools/memory.ts` | 内存工具的核心定义文件 |
| `src/HeapSnapshotManager.ts` | 堆快照管理器实现 |
| `src/formatters/HeapSnapshotFormatter.ts` | 堆快照格式化器 |
| `skills/memory-leak-debugging/SKILL.md` | 内存泄漏调试技能文档 |
| `skills/memory-leak-debugging/references/compare_snapshots.js` | 快照比较回退脚本 |
| `skills/memory-leak-debugging/references/common-leaks.md` | 常见泄漏类型参考文档 |
---
## CLI与配置
### 相关页面
相关主题：[MCP客户端集成](#mcp-client-integration), [快速开始指南](#quick-start)
相关源码文件
以下源码文件用于生成本页说明：
- [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)
- [src/bin/chrome-devtools-mcp-main.ts](https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/src/bin/chrome-devtools-mcp-main.ts)
- [docs/cli.md](https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/docs/cli.md)
- [puppeteer.config.cjs](https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/puppeteer.config.cjs)
- [src/tools/categories.ts](https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/src/tools/categories.ts)
- [src/bin/chrome-devtools-cli-options.ts](https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/src/bin/chrome-devtools-cli-options.ts)
- [scripts/generate-cli.ts](https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/scripts/generate-cli.ts)
# CLI与配置
## 概述
chrome-devtools-mcp 提供了完整的命令行界面（CLI）和灵活的配置系统，支持通过命令行参数启动 MCP 服务器、管理浏览器生命周期、以及自动化浏览器操作。该项目采用 TypeScript 开发，使用 Puppeteer 作为底层浏览器自动化引擎，并通过 MCP（Model Context Protocol）协议与 AI 代理进行通信。资料来源：[AGENTS.md](https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/AGENTS.md)
## 架构设计
### 组件关系
```mermaid
graph TD
A[chrome-devtools-mcp CLI] --> B[chrome-devtools-mcp-main.ts]
A --> C[chrome-devtools-mcp-cli-options.ts]
B --> D[Puppeteer Browser]
C --> E[命令行参数解析]
F[puppeteer.config.cjs] --> D
G[MCP Server] --> H[工具层]
H --> I[Page Tools]
H --> J[Navigation Tools]
H --> K[Performance Tools]
H --> L[Network Tools]
```
### 启动流程
```mermaid
sequenceDiagram
participant User as 用户
participant CLI as CLI解析器
participant Main as 主程序
participant Browser as Puppeteer浏览器
participant MCP as MCP服务器
User->>CLI: 执行命令 + 参数
CLI->>CLI: parseArguments() 验证参数
CLI->>Main: 传递解析后的配置
Main->>Browser: 启动Chrome实例
Browser-->>Main: Browser实例就绪
Main->>MCP: 初始化MCP服务
MCP-->>User: 暴露工具列表
```
## 命令行接口
### 全局命令
| 命令 | 功能 | 说明 |
|------|------|------|
| `start` | 启动服务 | 启动或重启 chrome-devtools-mcp |
| `status` | 检查状态 | 检查 chrome-devtools-mcp 是否运行 |
| `stop` | 停止服务 | 停止正在运行的 chrome-devtools-mcp |
| `help` | 帮助信息 | 显示命令帮助和使用方法 |
资料来源：[skills/chrome-devtools-cli/SKILL.md:50-53](https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/skills/chrome-devtools-cli/SKILL.md)
### 工具命令
CLI 支持直接调用 MCP 工具进行浏览器自动化操作，基本语法如下：
```sh
chrome-devtools [arguments] [flags]
```
资料来源：[skills/chrome-devtools-cli/SKILL.md:21](https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/skills/chrome-devtools-cli/SKILL.md)
### 输出格式
默认输出为 Markdown 格式，可通过 `--output-format` 参数切换：
```sh
chrome-devtools take_snapshot --output-format=json
```
资料来源：[skills/chrome-devtools-cli/SKILL.md:23](https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/skills/chrome-devtools-cli/SKILL.md)
## 命令行参数配置
### 参数解析模块
参数解析由 `chrome-devtools-mcp-cli-options.ts` 实现，核心类型定义如下：
```typescript
interface ParsedArguments {
tool?: string;
args?: string[];
flags?: Flags;
}
interface Flags {
port?: number;
host?: string;
viaCli?: boolean;
experimentalVision?: boolean;
experimentalScreencast?: boolean;
categoryExtensions?: boolean;
categoryExperimentalWebmcp?: boolean;
// ... 其他配置项
}
```
资料来源：[scripts/generate-cli.ts:18-28](https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/scripts/generate-cli.ts)
### 工具类别配置
工具按功能分类管理，通过 `--category-*` 标志启用：
| 类别标志 | 功能 | 默认状态 |
|----------|------|----------|
| `--categoryExperimentalWebmcp` | WebMCP 实验性工具 | 关闭 |
| `--categoryExtensions` | Chrome 扩展管理 | 关闭 |
| `--experimentalVision` | 视觉坐标点击 | 关闭 |
| `--experimentalScreencast` | 屏幕录制功能 | 关闭 |
资料来源：[skills/chrome-devtools-cli/SKILL.md:49-51](https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/skills/chrome-devtools-cli/SKILL.md)
### 必需标志构建
工具类别标志通过 `buildFlag` 函数动态构建：
```typescript
import {buildFlag} from '../build/src/index.js';
// 生成标志名
const categoryFlag = buildFlag(category);
const flagName = `--${categoryFlag}`;
```
资料来源：[scripts/generate-docs.ts:72-76](https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/scripts/generate-docs.ts)
### 默认关闭的类别
部分工具类别默认不启用，需要显式启用：
```typescript
export const OFF_BY_DEFAULT_CATEGORIES = [
ToolCategory.WEBMCP,
ToolCategory.EXTENSION,
ToolCategory.EXPERIMENTAL,
];
```
资料来源：[scripts/generate-docs.ts:24-28](https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/scripts/generate-docs.ts)
## 工具分类体系
### 分类定义
```mermaid
graph LR
A[ToolCategory] --> B[NAVIGATION]
A --> C[INPUT]
A --> D[PERFORMANCE]
A --> E[NETWORK]
A --> F[EXTENSION]
A --> G[WEBMCP]
A --> H[EXPERIMENTAL]
```
### 分类标签映射
| 分类枚举 | 中文标签 | 说明 |
|----------|----------|------|
| `NAVIGATION` | 导航 | 页面导航和页面管理工具 |
| `INPUT` | 输入 | 用户交互和元素操作 |
| `PERFORMANCE` | 性能 | 性能分析和追踪 |
| `NETWORK` | 网络 | 网络请求监控 |
| `EXTENSION` | 扩展 | Chrome 扩展管理 |
| `WEBMCP` | WebMCP | 网页暴露的 MCP 工具 |
| `EXPERIMENTAL` | 实验性 | 实验功能 |
资料来源：[scripts/generate-docs.ts:29-40](https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/scripts/generate-docs.ts)
## 浏览器配置
### Puppeteer 配置
通过 `puppeteer.config.cjs` 配置文件管理浏览器实例：
```javascript
module.exports = {
puppeteer: {
// 浏览器启动参数
args: [
'--no-sandbox',
'--disable-setuid-sandbox',
'--disable-dev-shm-usage',
],
// 用户数据目录（持久化配置）
userDataDir: './chrome-profile',
// 调试端口
debugPort: 9222,
},
};
```
资料来源：[puppeteer.config.cjs](https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/puppeteer.config.cjs)
### 浏览器生命周期
浏览器使用持久化 Chrome 配置文件，首次调用工具时自动启动：
```mermaid
stateDiagram-v2
[*] --> 未启动: 程序初始化
未启动 --> 运行中: 首次工具调用
运行中 --> 运行中: 工具操作
运行中 --> 已停止: stop命令
已停止 --> 运行中: start命令
已停止 --> [*]: 程序退出
```
资料来源：[skills/chrome-devtools/SKILL.md:8-9](https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/skills/chrome-devtools/SKILL.md)
### 页面管理
工具操作作用于当前选中的页面，支持多页面管理：
```sh
chrome-devtools list_pages # 列出所有打开的页面
chrome-devtools select_page 1 # 选择页面作为上下文
chrome-devtools select_page 1 --bringToFront true # 选择并激活
chrome-devtools close_page 1 # 关闭指定页面
```
资料来源：[skills/chrome-devtools-cli/SKILL.md:27-38](https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/skills/chrome-devtools-cli/SKILL.md)
## 网络与模拟配置
### 网络条件模拟
```sh
# 离线模拟
chrome-devtools emulate --networkConditions "Offline"
# 自定义网络节流
chrome-devtools emulate --networkConditions "Slow 3G"
```
资料来源：[skills/chrome-devtools-cli/SKILL.md:41-44](https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/skills/chrome-devtools-cli/SKILL.md)
### 设备模拟
| 参数 | 说明 | 示例值 |
|------|------|--------|
| `--viewport` | 视口尺寸 | `1920x1080` |
| `--colorScheme` | 颜色方案 | `dark`, `light` |
| `--cpuThrottlingRate` | CPU 节流倍率 | `4` (4x) |
| `--geolocation` | 地理位置 | `0x0` |
| `--userAgent` | 用户代理字符串 | Mozilla/5.0... |
资料来源：[skills/chrome-devtools-cli/SKILL.md:44-48](https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/skills/chrome-devtools-cli/SKILL.md)
### 使用示例
```sh
# 模拟暗黑模式和全高清视口
chrome-devtools emulate --colorScheme "dark" --viewport "1920x1080"
# 模拟 CPU 节流和特定地理位置
chrome-devtools emulate --cpuThrottlingRate 4 --geolocation "0x0"
# 模拟自定义用户代理
chrome-devtools emulate --userAgent "Mozilla/5.0..."
# 调整页面窗口大小
chrome-devtools resize_page 1920 1080
```
## 实验性功能
### 启用方式
实验性功能默认禁用，需通过相应标志启用：
```sh
chrome-devtools-mcp --experimentalVision=true --experimentalScreencast=true
```
资料来源：[skills/chrome-devtools-cli/SKILL.md:49-51](https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/skills/chrome-devtools-cli/SKILL.md)
### 实验性工具列表
| 工具 | 功能 | 必需标志 |
|------|------|----------|
| `click_at` | 坐标点击 | `--experimentalVision=true` |
| `screencast_start` | 屏幕录制 | `--experimentalScreencast=true` |
| `screencast_stop` | 停止录制 | `--experimentalScreencast=true` |
| `list_webmcp_tools` | 列出 WebMCP 工具 | `--categoryExperimentalWebmcp=true` |
资料来源：[skills/chrome-devtools-cli/SKILL.md:49-55](https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/skills/chrome-devtools-cli/SKILL.md)
## CLI 选项自动生成
### 生成流程
项目使用脚本自动从运行时工具定义生成 CLI 选项：
```mermaid
graph TD
A[generate-cli.ts] --> B[启动 MCP 服务器]
B --> C[调用 listTools API]
C --> D[解析工具定义]
D --> E[生成 TypeScript 代码]
E --> F[输出到 chrome-devtools-cli-options.ts]
```
资料来源：[scripts/generate-cli.ts:30-55](https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/scripts/generate-cli.ts)
### 生成的代码结构
生成的 `chrome-devtools-cli-options.ts` 包含所有工具的 CLI 接口定义：
```typescript
// 通过 MCP 协议连接本地服务器获取工具定义
const transport = new StdioClientTransport({
command: 'node',
args: [serverPath, '--viaCli'],
env: {...process.env, CHROME_DEVTOOLS_MCP_NO_USAGE_STATISTICS: 'true'},
});
```
资料来源：[scripts/generate-cli.ts:36-42](https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/scripts/generate-cli.ts)
## 构建与测试
### 构建命令
```sh
npm run build # 运行 tsc 编译并测试构建
```
资料来源：[AGENTS.md:5](https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/AGENTS.md)
### 测试命令
```sh
npm run test # 构建并运行所有测试
npm run test path-to-test.ts # 构建并运行单个测试文件
```
资料来源：[AGENTS.md:6-8](https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/AGENTS.md)
### 代码格式
```sh
npm run format # 修复格式问题和 linting 错误
```
资料来源：[AGENTS.md:11](https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/AGENTS.md)
## 扩展管理配置
### 扩展操作命令
| 命令 | 功能 |
|------|------|
| `list_extensions` | 列出已安装的扩展 |
| `install_extension` | 安装扩展（需要路径） |
| `uninstall_extension` | 卸载扩展（需要 ID） |
| `reload_extension` | 重载扩展 |
| `trigger_extension_action` | 触发扩展默认操作 |
资料来源：[skills/chrome-devtools-cli/SKILL.md:48-50](https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/skills/chrome-devtools-cli/SKILL.md)
### 启用扩展支持
扩展功能默认关闭，需要通过 `--categoryExtensions` 标志启用：
```sh
chrome-devtools-mcp --categoryExtensions=true
```
资料来源：[skills/chrome-devtools/SKILL.md:8-9](https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/skills/chrome-devtools/SKILL.md)
## 性能追踪配置
### 追踪命令
```sh
# 开始追踪
chrome-devtools performance_start_trace true false
# 带文件输出
chrome-devtools performance_start_trace true true --filePath t.gz
# 停止追踪
chrome-devtools performance_stop_trace
# 保存到文件
chrome-devtools performance_stop_trace --filePath "t.json"
# 获取性能洞察
chrome-devtools performance_analyze_insight "1" "LCPBreakdown"
```
资料来源：[skills/chrome-devtools-cli/SKILL.md:32-40](https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/skills/chrome-devtools-cli/SKILL.md)
### 内存快照
```sh
chrome-devtools take_memory_snapshot "./snap.heapsnapshot"
```
资料来源：[skills/chrome-devtools-cli/SKILL.md:41-42](https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/skills/chrome-devtools-cli/SKILL.md)
## 环境变量
| 变量名 | 功能 | 说明 |
|--------|------|------|
| `CHROME_DEVTOOLS_MCP_NO_USAGE_STATISTICS` | 禁用使用统计 | 设为 `true` 可禁用遥测 |
| `PATH` | 系统路径 | 需包含全局 npm bin 目录 |
资料来源：[skills/chrome-devtools-cli/references/installation.md:13](https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/skills/chrome-devtools-cli/references/installation.md)
## 常见配置问题排查
### 问题诊断步骤
1. 检查服务状态：`chrome-devtools status`
2. 查看详细日志：启动时添加 `--logFile=/tmp/cdm-test.log`
3. 分析日志输出中的错误信息
资料来源：[skills/troubleshooting/SKILL.md](https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/skills/troubleshooting/SKILL.md)
### 权限错误处理
遇到 `EACCES` 权限错误时，建议：
- 使用 `nvm` 管理 Node.js 版本
- 配置 npm 使用不同的全局目录
- 避免使用 `sudo` 安装全局包
资料来源：[skills/chrome-devtools-cli/references/installation.md:16-18](https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/skills/chrome-devtools-cli/references/installation.md)
---
## MCP客户端集成
### 相关页面
相关主题：[快速开始指南](#quick-start), [CLI与配置](#cli-configuration)
相关源码文件
以下源码文件用于生成本页说明：
- [README.md](https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/README.md)
- [AGENTS.md](https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/AGENTS.md)
- [.mcp.json](https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/.mcp.json)
- [gemini-extension.json](https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/gemini-extension.json)
- [src/tools/webmcp.ts](https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/src/tools/webmcp.ts)
- [src/McpResponse.ts](https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/src/McpResponse.ts)
- [src/tools/ToolDefinition.ts](https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/src/tools/ToolDefinition.ts)
- [package.json](https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/package.json)
# MCP客户端集成
## 概述
MCP（Model Context Protocol）客户端集成是 chrome-devtools-mcp 项目的核心功能，它允许外部AI助手（如 Claude、Gemini 等）通过标准化的 MCP 协议与 Chrome DevTools 进行交互。该集成使得AI代理能够控制浏览器、执行自动化任务、采集页面快照以及进行性能调试。
本项目实现了一个 MCP 服务器，通过 WebMCP 工具接口扩展了标准的 DevTools 功能，使 AI 客户端能够以结构化的方式与浏览器进行双向通信。资料来源：[AGENTS.md:1-3]()
## 架构设计
### 整体架构
chrome-devtools-mcp 采用客户端-服务器架构，通过 MCP 协议实现 AI 助手与浏览器自动化之间的桥梁。
```mermaid
graph TD
subgraph AI客户端层
A[Claude / Gemini 等]
end
subgraph MCP协议层
B[MCP 客户端]
C[MCP 服务器]
end
subgraph 浏览器层
D[Chrome DevTools Protocol]
E[浏览器实例]
end
A -->|MCP 协议| B
B -->|MCP 请求| C
C -->|CDP 命令| D
D -->|CDP 响应| C
C -->|MCP 响应| B
B -->|MCP 响应| A
D -->|控制| E
E -->|反馈| D
```
### 核心组件
| 组件名称 | 文件位置 | 功能描述 |
|---------|---------|---------|
| MCPResponse | `src/McpResponse.ts` | 处理 MCP 协议响应序列化与格式化 |
| webmcp | `src/tools/webmcp.ts` | 定义 WebMCP 工具接口 |
| ToolDefinition | `src/tools/ToolDefinition.ts` | 工具定义与参数模式抽象 |
| 工具集合 | `src/tools/*.ts` | 具体工具实现（输入、导航、快照等）|
## 客户端配置
### .mcp.json 配置格式
MCP 客户端通过 `.mcp.json` 配置文件声明服务器连接。配置文件采用 JSON 格式定义服务器路径和可选参数。
```json
{
"mcpServers": {
"chrome-devtools": {
"command": "node",
"args": ["path/to/cli.js", "--headless"]
}
}
}
```
资料来源：[.mcp.json](https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/.mcp.json)
### Gemini 扩展配置
针对 Google Gemini 平台的特殊集成配置：
```json
{
"name": "chrome-devtools",
"description": "...",
"entry_point": "...",
"runtime": "...",
"permissions": ["browser"]
}
```
资料来源：[gemini-extension.json](https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/gemini-extension.json)
### 运行时环境要求
项目对 Node.js 版本有明确的兼容性要求：
| 版本范围 | 支持状态 |
|---------|---------|
| `^20.19.0` | 主要支持 |
| `^22.12.0` | 主要支持 |
| `>=23` | 兼容支持 |
资料来源：[package.json:48-51]()
## WebMCP 工具接口
WebMCP 是项目定义的扩展协议，允许网页向 MCP 客户端暴露自定义工具。核心接口包含两个工具：
### list_webmcp_tools
列出当前页面暴露的所有 WebMCP 工具。
```typescript
export const listWebMcpTools = definePageTool({
name: 'list_webmcp_tools',
description: `Lists all WebMCP tools the page exposes.`,
annotations: {
category: ToolCategory.WEBMCP,
readOnlyHint: true,
},
schema: {},
blockedByDialog: false,
handler: async (_request, response, _context) => {
response.setListWebMcpTools();
},
});
```
资料来源：[src/tools/webmcp.ts:14-24]()
### execute_webmcp_tool
执行页面暴露的 WebMCP 工具。
```typescript
export const executeWebMcpTool = definePageTool({
name: 'execute_webmcp_tool',
description: `Executes a WebMCP tool exposed by the page.`,
annotations: {
category: ToolCategory.WEBMCP,
readOnlyHint: false,
},
schema: {
toolName: zod.string().describe('The name of the WebMCP tool to execute'),
input: zod.string().optional().describe('The JSON-stringified parameters'),
},
blockedByDialog: false,
handler: async (request, response) => {
// 处理工具执行
},
});
```
资料来源：[src/tools/webmcp.ts:32-51]()
## 工具定义模式
### 工具类别
所有工具通过 `ToolCategory` 枚举进行分类管理：
| 类别标识 | 描述 |
|--------|------|
| `WEBMCP` | WebMCP 协议相关工具 |
| `INPUT` | 用户输入自动化工具 |
| `NAVIGATION` | 页面导航工具 |
| `INSPECTION` | 页面检查工具 |
### 工具定义函数
项目使用工厂函数模式定义工具：
```typescript
export function definePageTool(
definition: PageToolDefinition
): DefinedPageTool {
return {
...definition,
pageScoped: true,
};
}
```
关键特性包括：
- **pageScoped**: 标记工具是否需要页面上下文
- **blockedByDialog**: 标记对话框是否阻止工具执行
- **readOnlyHint**: 提示工具是否仅读取数据
资料来源：[src/tools/ToolDefinition.ts:38-50]()
### 通用模式定义
项目提供可复用的参数模式：
```typescript
export const timeoutSchema = {
timeout: zod
.number()
.int()
.optional()
.describe('Maximum wait time in milliseconds')
.transform(value => value && value <= 0 ? undefined : value),
};
export const pageIdSchema = {
pageId: zod.number().optional().describe('Targets a specific page by ID'),
};
```
资料来源：[src/tools/ToolDefinition.ts:53-68]()
## MCP 响应处理
### 响应数据结构
McpResponse 类负责将工具执行结果格式化为 MCP 协议兼容的响应：
```typescript
if (this.#listWebMcpTools && data.webmcpTools) {
structuredContent.webmcpTools = data.webmcpTools.map(
({name, description, inputSchema, annotations}) => ({
name,
description,
inputSchema,
annotations,
}),
);
}
```
资料来源：[src/McpResponse.ts:45-54]()
### 响应格式化
响应消息包含结构化内容与文本描述：
| 格式类型 | 用途 |
|---------|------|
| `structuredContent` | JSON 序列化数据 |
| `response` | 人类可读文本 |
| `annotations` | 元数据标记 |
资料来源：[src/McpResponse.ts:55-68]()
## 集成工作流
### 典型执行流程
```mermaid
sequenceDiagram
participant AI as AI 客户端
participant MCP as MCP 服务器
participant CDP as Chrome DevTools
AI->>MCP: 初始化连接
MCP-->>AI: 连接确认
AI->>MCP: list_webmcp_tools
MCP->>CDP: 获取页面工具
CDP-->>MCP: 工具列表
MCP-->>AI: 工具定义
AI->>MCP: execute_webmcp_tool
MCP->>CDP: 执行工具
CDP-->>MCP: 执行结果
MCP-->>AI: 响应数据
```
### 页面工具调用示例
1. **获取页面快照**：
```bash
chrome-devtools take_snapshot
```
2. **执行 JavaScript**：
```bash
chrome-devtools evaluate_script "document.title"
```
3. **页面导航**：
```bash
chrome-devtools navigate_page --url "https://example.com"
```
## 工具分类参考
### 输入自动化工具
| 工具名称 | 功能 | 参数 |
|---------|------|------|
| `type_text` | 模拟键盘输入 | `text`, `submitKey?` |
| `fill` | 填充表单字段 | `id`, `text` |
| `press_key` | 按下按键 | `key` |
| `upload_file` | 文件上传 | `id`, `path` |
| `drag` | 拖拽操作 | `src`, `dst` |
资料来源：[skills/chrome-devtools-cli/SKILL.md:14-28]()
### 导航工具
| 工具名称 | 功能 | 参数 |
|---------|------|------|
| `navigate_page` | 导航到URL | `url`, `type?`, `timeout?` |
| `new_page` | 打开新页面 | `url` |
| `close_page` | 关闭页面 | `index` |
| `select_page` | 选择页面上下文 | `pageId` |
| `list_pages` | 列出所有页面 | - |
资料来源：[skills/chrome-devtools-cli/SKILL.md:1-13]()
### 检查工具
| 工具名称 | 功能 | 参数 |
|---------|------|------|
| `take_snapshot` | 获取可访问性快照 | `includeSnapshot?` |
| `take_screenshot` | 截图 | - |
| `evaluate_script` | 执行脚本 | `script` |
## 类型系统
### Schema 定义规范
项目强制使用 Zod 进行运行时类型验证，禁止使用 `any` 类型：
```typescript
import {zod} from '../third_party/index.js';
// 正确做法
const schema = {
key: zod.string().describe('A key or key combination'),
};
// 禁止做法
// const bad: any = value;
// const bad = value as SomeType;
```
资料来源：[AGENTS.md:16-24]()
### 参数解析
使用 `ParsedArguments` 泛型处理参数转换：
```typescript
type ParsedArguments = {
[key: string]: unknown;
};
```
## 扩展与定制
### 自定义工具开发
1. 在 `src/tools/` 目录创建新工具文件
2. 使用 `definePageTool` 工厂函数定义工具
3. 实现 `handler` 异步函数处理逻辑
4. 导出工具并注册到相应类别
### 类别扩展
工具类别在 `ToolCategory` 枚举中定义：
```typescript
export enum ToolCategory {
WEBMCP = 'webmcp',
INPUT = 'input',
NAVIGATION = 'navigation',
INSPECTION = 'inspection',
}
```
## 测试与验证
### 集成测试场景
项目包含多个评估场景用于验证客户端集成：
| 测试场景 | 路径 | 验证内容 |
|---------|------|---------|
| 性能测试 | `scripts/eval_scenarios/performance_test.ts` | 性能追踪工具调用 |
| 快照测试 | `scripts/eval_scenarios/snapshot_test.ts` | 页面内容读取 |
| 页面选择测试 | `scripts/eval_scenarios/select_page_test.ts` | 多页面上下文切换 |
资料来源：[scripts/eval_scenarios/performance_test.ts:1-22]()
### 测试执行命令
```bash
npm run test # 运行所有测试
npm run test tests/McpContext.test.ts # 运行单个测试文件
```
资料来源：[AGENTS.md:5-7]()
## 安全考虑
### 对话框阻塞机制
某些工具设置 `blockedByDialog: true`，在浏览器对话框出现时会被阻塞：
```typescript
{
blockedByDialog: true, // 对话框会阻止此工具执行
}
```
### 只读操作提示
`readOnlyHint` 注解用于提示工具是否修改浏览器状态：
```typescript
{
readOnlyHint: true, // 提示此工具仅读取数据
}
```
## 相关文档
- [安装指南](../skills/chrome-devtools-cli/references/installation.md) - CLI 安装与配置
- [工具参考](../skills/chrome-devtools-cli/SKILL.md) - 所有工具完整文档
- [无障碍调试](../skills/a11y-debugging/SKILL.md) - 可访问性检查集成
- [性能优化](../skills/debug-optimize-lcp/SKILL.md) - LCP 调试集成
---
---
## Doramagic 踩坑日志
项目：ChromeDevTools/chrome-devtools-mcp
摘要：发现 18 个潜在踩坑项，其中 1 个为 high/blocking；最高优先级：配置坑 - 来源证据：performance_start_trace records 'CPU throttling: none / Network throttling: none' despite emulate setting throttling —…。
## 1. 配置坑 · 来源证据：performance_start_trace records 'CPU throttling: none / Network throttling: none' despite emulate setting throttling —…
- 严重度：high
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：performance_start_trace records 'CPU throttling: none / Network throttling: none' despite emulate setting throttling — measurements come back partially or full…
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_644cef1d4144424abe63f24528f5d082 | https://github.com/ChromeDevTools/chrome-devtools-mcp/issues/1955 | 来源讨论提到 macos 相关条件，需在安装/试用前复核。
## 2. 安装坑 · 来源证据：Auto-connect doesn't work on WSL with mirrored networking (Chrome on Windows host)
- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Auto-connect doesn't work on WSL with mirrored networking (Chrome on Windows host)
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_3275fc356e284918a94cf8c2c037caee | https://github.com/ChromeDevTools/chrome-devtools-mcp/issues/2004 | 来源讨论提到 windows 相关条件，需在安装/试用前复核。
## 3. 安装坑 · 来源证据：Update check hardcodes registry.npmjs.org, ignoring user's npm registry configuration
- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Update check hardcodes registry.npmjs.org, ignoring user's npm registry configuration
- 对用户的影响：可能阻塞安装或首次运行。
- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_1946d257bfb04c23a67250da4d584631 | https://github.com/ChromeDevTools/chrome-devtools-mcp/issues/1943 | 来源讨论提到 node 相关条件，需在安装/试用前复核。
## 4. 安装坑 · 来源证据：chrome-devtools-mcp: v0.20.1
- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：chrome-devtools-mcp: v0.20.1
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_11700367e17048138ab79571d751cec4 | https://github.com/ChromeDevTools/chrome-devtools-mcp/releases/tag/chrome-devtools-mcp-v0.20.1 | 来源类型 github_release 暴露的待验证使用条件。
## 5. 安装坑 · 来源证据：chrome-devtools-mcp: v0.22.0
- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：chrome-devtools-mcp: v0.22.0
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_6ff69eabdc334130b7b093706390c6c1 | https://github.com/ChromeDevTools/chrome-devtools-mcp/releases/tag/chrome-devtools-mcp-v0.22.0 | 来源类型 github_release 暴露的待验证使用条件。
## 6. 配置坑 · 来源证据：chrome-devtools-mcp: v0.21.0
- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：chrome-devtools-mcp: v0.21.0
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_41b2681dc7ae4bbabdb071511fdc0191 | https://github.com/ChromeDevTools/chrome-devtools-mcp/releases/tag/chrome-devtools-mcp-v0.21.0 | 来源类型 github_release 暴露的待验证使用条件。
## 7. 能力坑 · 能力判断依赖假设
- 严重度：medium
- 证据强度：source_linked
- 发现：README/documentation is current enough for a first validation pass.
- 对用户的影响：假设不成立时，用户拿不到承诺的能力。
- 建议检查：将假设转成下游验证清单。
- 防护动作：假设必须转成验证项；没有验证结果前不能写成事实。
- 证据：capability.assumptions | github_repo:1054793726 | https://github.com/ChromeDevTools/chrome-devtools-mcp | README/documentation is current enough for a first validation pass.
## 8. 运行坑 · 来源证据：chrome-devtools-mcp: v0.20.0
- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个运行相关的待验证问题：chrome-devtools-mcp: v0.20.0
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_8bef6b0b7a80406ab00a0576f82b35a7 | https://github.com/ChromeDevTools/chrome-devtools-mcp/releases/tag/chrome-devtools-mcp-v0.20.0 | 来源类型 github_release 暴露的待验证使用条件。
## 9. 运行坑 · 来源证据：chrome-devtools-mcp: v0.24.0
- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个运行相关的待验证问题：chrome-devtools-mcp: v0.24.0
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_e42176fdf7da4015ac82844a46f37c08 | https://github.com/ChromeDevTools/chrome-devtools-mcp/releases/tag/chrome-devtools-mcp-v0.24.0 | 来源类型 github_release 暴露的待验证使用条件。
## 10. 运行坑 · 来源证据：chrome-devtools-mcp: v0.26.0
- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个运行相关的待验证问题：chrome-devtools-mcp: v0.26.0
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_a6cf1fa6206f48e6a9e88a5d9d00fd64 | https://github.com/ChromeDevTools/chrome-devtools-mcp/releases/tag/chrome-devtools-mcp-v0.26.0 | 来源类型 github_release 暴露的待验证使用条件。
## 11. 维护坑 · 维护活跃度未知
- 严重度：medium
- 证据强度：source_linked
- 发现：未记录 last_activity_observed。
- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。
- 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。
- 防护动作：维护活跃度未知时，推荐强度不能标为高信任。
- 证据：evidence.maintainer_signals | github_repo:1054793726 | https://github.com/ChromeDevTools/chrome-devtools-mcp | last_activity_observed missing
## 12. 安全/权限坑 · 下游验证发现风险项
- 严重度：medium
- 证据强度：source_linked
- 发现：no_demo
- 对用户的影响：下游已经要求复核，不能在页面中弱化。
- 建议检查：进入安全/权限治理复核队列。
- 防护动作：下游风险存在时必须保持 review/recommendation 降级。
- 证据：downstream_validation.risk_items | github_repo:1054793726 | https://github.com/ChromeDevTools/chrome-devtools-mcp | no_demo; severity=medium
## 13. 安全/权限坑 · 存在安全注意事项
- 严重度：medium
- 证据强度：source_linked
- 发现：No sandbox install has been executed yet; downstream must verify before user use.
- 对用户的影响：用户安装前需要知道权限边界和敏感操作。
- 建议检查：转成明确权限清单和安全审查提示。
- 防护动作：安全注意事项必须面向用户前置展示。
- 证据：risks.safety_notes | github_repo:1054793726 | https://github.com/ChromeDevTools/chrome-devtools-mcp | No sandbox install has been executed yet; downstream must verify before user use.
## 14. 安全/权限坑 · 存在评分风险
- 严重度：medium
- 证据强度：source_linked
- 发现：no_demo
- 对用户的影响：风险会影响是否适合普通用户安装。
- 建议检查：把风险写入边界卡，并确认是否需要人工复核。
- 防护动作：评分风险必须进入边界卡，不能只作为内部分数。
- 证据：risks.scoring_risks | github_repo:1054793726 | https://github.com/ChromeDevTools/chrome-devtools-mcp | no_demo; severity=medium
## 15. 安全/权限坑 · 来源证据：Close empty-object tool schemas for stricter MCP client validation
- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Close empty-object tool schemas for stricter MCP client validation
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_2af67f120a9d4486998a92da71a92cb9 | https://github.com/ChromeDevTools/chrome-devtools-mcp/issues/2049 | 来源类型 github_issue 暴露的待验证使用条件。
## 16. 安全/权限坑 · 来源证据：chrome-devtools-mcp: v0.25.0
- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：chrome-devtools-mcp: v0.25.0
- 对用户的影响：可能影响授权、密钥配置或安全边界。
- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_51ee93809f08423dbc7b6c0d3eeddc77 | https://github.com/ChromeDevTools/chrome-devtools-mcp/releases/tag/chrome-devtools-mcp-v0.25.0 | 来源类型 github_release 暴露的待验证使用条件。
## 17. 维护坑 · issue/PR 响应质量未知
- 严重度：low
- 证据强度：source_linked
- 发现：issue_or_pr_quality=unknown。
- 对用户的影响：用户无法判断遇到问题后是否有人维护。
- 建议检查：抽样最近 issue/PR，判断是否长期无人处理。
- 防护动作：issue/PR 响应未知时，必须提示维护风险。
- 证据：evidence.maintainer_signals | github_repo:1054793726 | https://github.com/ChromeDevTools/chrome-devtools-mcp | issue_or_pr_quality=unknown
## 18. 维护坑 · 发布节奏不明确
- 严重度：low
- 证据强度：source_linked
- 发现：release_recency=unknown。
- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。
- 建议检查：确认最近 release/tag 和 README 安装命令是否一致。
- 防护动作：发布节奏未知或过期时，安装说明必须标注可能漂移。
- 证据：evidence.maintainer_signals | github_repo:1054793726 | https://github.com/ChromeDevTools/chrome-devtools-mcp | release_recency=unknown