概述

chrome-devtools-mcp 是一个基于 Model Context Protocol (MCP) 的 Chrome DevTools 服务器和命令行工具。该项目由 Google Chrome 团队维护，提供了一套完整的浏览器自动化、调试和性能分析能力。资料来源：AGENTS.md

项目的主要目标是让开发者能够通过 MCP 协议与 Chrome 浏览器进行交互，实现网页自动化、元素操作、性能分析、无障碍调试等功能。资料来源：skills/chrome-devtools/SKILL.md

核心架构

技术栈

资料来源：package.json

架构图

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)

资料来源：skills/chrome-devtools-cli/SKILL.md

性能工具 (Performance)

资料来源：skills/debug-optimize-lcp/SKILL.md

无障碍调试工具 (Accessibility)

资料来源：skills/a11y-debugging/SKILL.md

元素交互工具 (Interaction)

资料来源：skills/chrome-devtools/SKILL.md

网络工具 (Network)

WebMCP 工具

WebMCP 允许与网页暴露的工具进行交互：

资料来源：src/tools/webmcp.ts

模拟工具 (Emulation)

资料来源：skills/chrome-devtools-cli/SKILL.md

核心概念

页面作用域 (Page Scoped)

工具分为两类：

1. 页面作用域工具：需要先选择目标页面才能使用
2. 全局工具：可随时调用，不需要选择页面

export function definePageTool<Schema extends zod.ZodRawShape>(
  definition: PageToolDefinition<Schema>,
): DefinedPageTool<Schema>;

资料来源：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

快速开始

安装

npm i chrome-devtools-mcp@latest -g
chrome-devtools status  # 验证安装

资料来源：skills/chrome-devtools-cli/references/installation.md

常用命令

资料来源：AGENTS.md

基本工作流程

graph LR
    A[导航页面] --> B[等待内容加载]
    B --> C[获取快照]
    C --> D[获取元素 UID]
    D --> E[执行交互操作]

开发规范

TypeScript 规范

项目采用严格的 TypeScript 规范：

资料来源：AGENTS.md

工具定义模式

export function definePageTool<Schema extends zod.ZodRawShape>(
  definition: PageToolDefinition<Schema>,
): DefinedPageTool<Schema> {
  return {
    ...definition,
    pageScoped: true,
  } as DefinedPageTool<Schema>;
}

资料来源：src/tools/ToolDefinition.ts

技能系统

项目包含多个专业技能模块：

扩展机制

MCP 服务器扩展

可以通过 CLI 参数扩展 MCP 服务器功能：

npx chrome-devtools-mcp@latest --categoryExtensions

WebMCP 扩展

网页可以暴露自定义工具供 MCP 调用，实现双向通信。资料来源：src/tools/webmcp.ts

常见用例

自动化测试场景

// 场景：导航 -> 截图 -> 检查元素
const calls = [
  { name: 'navigate_page', url: 'https://example.com' },
  { name: 'take_screenshot' },
  { name: 'take_snapshot' }
];

资料来源：scripts/eval_scenarios/snapshot_test.ts

性能分析场景

// 场景：导航 -> 开始性能追踪
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 机制

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 参数

工具注解

工具可以通过注解系统标记元信息：

annotations: {
  category: ToolCategory.WEBMCP,
  readOnlyHint: true,
  conditions: ['networkIdle']
}

资料来源：scripts/generate-docs.ts

总结

chrome-devtools-mcp 项目提供了一套完整的 Chrome DevTools 自动化解决方案，通过 MCP 协议实现了与 AI 模型的深度集成。项目具有以下特点：

• 模块化设计：工具按功能分类，易于扩展和维护
• 严格类型安全：TypeScript 规范确保代码质量
• 丰富的调试能力：支持性能分析、无障碍调试、LCP 优化等专业领域
• 灵活的工作流程：支持页面管理、元素交互、网络模拟等多种操作
• 双向扩展机制：既支持 MCP 协议扩展，也支持 WebMCP 网页扩展

概述

chrome-devtools-mcp 是一个 Chrome DevTools MCP（Model Context Protocol）服务器和命令行工具，提供对浏览器自动化、页面调试、性能分析和网络监控的全面控制。该项目允许开发者通过 MCP 协议与 Chrome DevTools Protocol 进行交互，实现高效的浏览器自动化和调试工作流。

本指南将帮助用户快速上手该工具，涵盖从安装配置到基本操作的全流程。

系统架构

组件关系

graph TD
    A[用户/Agent] --> B[MCP 客户端]
    B --> C[chrome-devtools-mcp 服务器]
    C --> D[Chrome DevTools Protocol]
    D --> E[浏览器实例]
    F[chrome-devtools CLI] --> C

核心模块

资料来源：AGENTS.md:1-5

环境要求

必要条件

• Node.js: 需要 Node.js 运行时环境
• npm: 用于包管理和脚本执行
• Chrome 浏览器: 支持本地安装的 Chrome 或 Chromium

安装步骤

#### 全局安装

npm i chrome-devtools-mcp@latest -g

安装完成后，chrome-devtools 命令将全局可用。

资料来源：skills/chrome-devtools-cli/references/installation.md:3-7

#### 验证安装

chrome-devtools status

该命令用于检查安装是否成功。

基本命令

启动 MCP 服务器

npx chrome-devtools-mcp@latest [选项]

查看帮助信息

chrome-devtools --help

工作流程模式

标准操作流程

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

常用工具

页面管理

元素交互

键盘操作

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

文件上传

chrome-devtools upload_file "element-id" "file.txt"
chrome-devtools upload_file "element-id" "file.txt" --includeSnapshot true

性能分析

性能追踪

graph TD
    A[开始追踪] --> B[performance_start_trace]
    B --> C[执行业务操作]
    C --> D[停止追踪]
    D --> E[performance_stop_trace]
    E --> F[分析结果]
    F --> G[LCPBreakdown]
    F --> H[其他指标]

性能工具

# 基础追踪
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"

网络监控

网络请求检查

chrome-devtools network_requests # 查看网络请求列表

网络请求工具可配置：

• include: 是否包含请求详情
• pagination: 分页配置（pageIdx, pageSize）

资料来源：src/McpResponse.ts:50-75

模拟与测试

网络模拟

chrome-devtools emulate --networkConditions "Offline"
chrome-devtools emulate --cpuThrottlingRate 4

设备模拟

# 模拟暗黑模式和全高清视口
chrome-devtools emulate --colorScheme "dark" --viewport "1920x1080"

# 重置页面尺寸
chrome-devtools resize_page 1920 1080

开发与测试

构建项目

npm run build

该命令执行 TypeScript 编译并测试构建结果。

运行测试

npm run test          # 运行所有测试
npm run test path-to-test.ts  # 运行单个测试文件

代码格式化

npm run format

该命令自动修复格式化问题并显示 linting 错误。

TypeScript 开发规范

项目制定了严格的 TypeScript 开发规范：

资料来源：AGENTS.md:15-25

故障排除

常见问题

重启终端

安装后可能需要重启终端或 source 配置文件（.bashrc、.zshrc）以使命令生效。

资料来源：skills/chrome-devtools-cli/references/installation.md:10-18

扩展功能

扩展支持

如需使用浏览器扩展功能，在 MCP 服务器配置中添加 --categoryExtensions 参数：

npx chrome-devtools-mcp@latest --categoryExtensions

WebMCP 工具

页面可暴露自定义 WebMCP 工具：

chrome-devtools list_webmcp_tools
chrome-devtools execute_webmcp_tool "toolName" --input '{"key": "value"}'

资料来源：src/tools/webmcp.ts:10-40

下一步

• 阅读完整的工具参考文档
• 查看 LCP 优化指南
• 学习无障碍调试技巧

1. 概述

chrome-devtools-mcp 是一个基于 Model Context Protocol (MCP) 的服务器实现，通过 Chrome DevTools Protocol 与 Chrome 浏览器进行交互。该项目为 AI 助手提供了一套完整的浏览器自动化工具集，涵盖页面导航、快照采集、性能分析、网络监控、无障碍审计等功能。

核心设计理念是将复杂的 CDP 操作封装为声明式的工具定义，并支持按需启用或禁用特定工具类别。

资料来源：skills/chrome-devtools/SKILL.md

2. 架构层次

项目采用分层架构，从底层到顶层依次为：

graph TD
    A[MCP 客户端] --> B[MCP 服务器层<br/>src/index.ts]
    B --> C[工具路由层<br/>src/ToolHandler.ts]
    C --> D[页面管理层<br/>src/McpPage.ts<br/>src/McpContext.ts]
    D --> E[浏览器抽象层<br/>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 工厂函数声明式定义，支持条件化生成和参数化扩展：

export function defineTool<
  Schema extends zod.ZodRawShape,
  Args extends ParsedArguments = ParsedArguments,
>(
  definition:
    | ToolDefinition<Schema>
    | ((args?: Args) => ToolDefinition<Schema>),
) {
  if (typeof definition === 'function') {
    const factory = definition;
    return (args: Args) => {
      return factory(args);
    };
  }
  return definition;
}

资料来源：src/tools/ToolDefinition.ts:1-20

3.2 工具定义结构

每个工具定义包含以下关键字段：

interface ToolDefinition<
  Schema extends zod.ZodRawShape = zod.ZodRawShape,
> extends BaseToolDefinition<Schema> {
  handler: (
    request: Request<Schema>,
    response: Response,
    context: Context,
  ) => Promise<void>;
}

资料来源：src/tools/ToolDefinition.ts:1-20

3.3 页面上下文管理

页面上下文通过 McpContext 管理，支持多页面并发操作：

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 浏览器生命周期

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 枚举定义：

资料来源：src/tools/categories.ts、src/tools/webmcp.ts

5. 页面收集器 (PageCollector)

PageCollector 是一个通用的事件收集器，用于监听浏览器目标事件：

export class PageCollector<T> {
  #browser: Browser;
  #listenersInitializer: (
    collector: (item: T) => void,
  ) => ListenerMap<PageEvents>;
  protected storage = new WeakMap<Page, Array<Array<WithSymbolId<T>>>>();
  
  async init(pages: Page[]) { /* ... */ }
  dispose() { /* ... */ }
}

资料来源：src/PageCollector.ts:1-30

5.1 事件流

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 允许页面主动暴露自定义工具，实现双向通信：

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<string, unknown> = {};
    if (request.params.input) {
      const parsed = JSON.parse(request.params.input);
      // ...
    }
  },
});

资料来源：src/tools/webmcp.ts:1-50

7. 请求处理流程

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. 工具依赖关系

部分工具需要特定的前置条件，例如对话框阻塞：

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 条件化工具生成

工具支持函数式定义，可根据参数动态生成：

export function definePageTool<
  Schema extends zod.ZodRawShape,
  Args extends ParsedArguments = ParsedArguments,
>(
  definition: (args?: Args) => PageToolDefinition<Schema>,
): (args?: Args) => DefinedPageTool<Schema> {
  return (args?: Args): DefinedPageTool<Schema> => {
    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 机制支持页面主动暴露能力，拓展了应用边界

概述

守护进程系统（Daemon System）是 chrome-devtools-mcp 项目中负责管理和维护 Chrome DevTools 协议通信后端服务的核心模块。该系统确保 MCP 服务器与浏览器实例之间的长期稳定连接，并提供进程生命周期管理、状态监控和资源清理等功能。

在 chrome-devtools-mcp 架构中，守护进程扮演着后台服务的角色，使得客户端能够通过 MCP 协议与浏览器进行交互，而无需关心底层连接管理的复杂性。

系统架构

整体架构图

graph TD
    subgraph 客户端层
        A[MCP 客户端]
        B[CLI 工具<br/>chrome-devtools]
    end
    
    subgraph 守护进程层
        C[Daemon Manager]
        D[Chrome Browser<br/>实例]
    end
    
    subgraph 协议层
        E[CDP 协议<br/>Chrome DevTools Protocol]
    end
    
    A --> C
    B --> C
    C <--> E
    E <--> D
    
    style C fill:#e1f5fe
    style D fill:#fff3e0

核心组件

守护进程管理器

进程启动流程

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. 配置管理

守护进程支持多种启动配置参数：

客户端通信接口

连接建立

graph LR
    A[CLI 命令] --> B[Client.connect]
    B --> C{连接状态}
    C -->|成功| D[返回连接句柄]
    C -->|失败| E[错误处理]
    D --> F[发送 CDP 命令]
    F --> G[接收响应]

API 接口

守护进程客户端提供以下核心方法：

interface DaemonClient {
  // 建立连接
  connect(options: ConnectOptions): Promise<Connection>;
  
  // 断开连接
  disconnect(): Promise<void>;
  
  // 发送命令
  sendCommand<T>(method: string, params?: object): Promise<T>;
  
  // 获取状态
  getStatus(): DaemonStatus;
}

类型系统

核心类型定义

// 守护进程状态枚举
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

工具模块

错误处理

工具模块提供统一的错误处理机制：

// 自定义错误类型
class DaemonError extends Error {
  constructor(
    message: string,
    public code: DaemonErrorCode,
    public details?: object
  ) {
    super(message);
  }
}

日志记录

interface LogOptions {
  level: 'debug' | 'info' | 'warn' | 'error';
  timestamp?: boolean;
  prefix?: string;
}

状态流转

stateDiagram-v2
    [*] --> STOPPED: 初始化
    STOPPED --> STARTING: 启动请求
    STARTING --> RUNNING: 连接成功
    STARTING --> ERROR: 连接失败
    RUNNING --> STOPPING: 停止请求
    RUNNING --> ERROR: 连接断开
    STOPPING --> STOPPED: 进程已关闭
    ERROR --> STARTING: 重试
    ERROR --> STOPPED: 放弃
    STOPPED --> [*]: 销毁

使用场景

1. MCP 服务器集成

守护进程系统被 MCP 服务器直接使用：

import { DaemonManager } from './daemon/daemon';

const daemon = new DaemonManager({
  port: 9222,
  headless: true
});

await daemon.start();

2. CLI 工具调用

命令行工具通过守护进程客户端与服务交互：

chrome-devtools start
chrome-devtools status
chrome-devtools stop

3. 测试环境

在测试场景中，守护进程提供隔离的浏览器环境：

const testDaemon = new DaemonManager({
  userDataDir: '/tmp/test-profile',
  headless: true
});

配置与调试

环境变量

日志级别

# 启用所有调试日志
DEBUG=* chrome-devtools start

# 输出到文件
npx chrome-devtools-mcp@latest --log-file=/tmp/daemon.log

最佳实践

1. 启动顺序：先启动守护进程，再建立客户端连接
2. 资源清理：使用完毕及时调用 stop() 方法释放资源
3. 超时处理：设置合理的 startupTimeout 避免无限等待
4. 错误恢复：实现重连机制处理临时性网络故障
5. 端口管理：确保调试端口未被其他进程占用

相关文档

• 安装指南
• 故障排除
• 工具参考

概述

工具系统是 chrome-devtools-mcp 的核心组件，它将 Chrome DevTools Protocol (CDP) 的能力封装为可通过 MCP (Model Context Protocol) 调用的接口。该系统支持两类工具：

• 全局工具 (Tool)：不依赖于特定页面的工具，如浏览器管理、网络控制等
• 页面作用域工具 (PageTool)：需要绑定到特定页面的工具，如元素交互、表单填充等

资料来源：src/tools/ToolDefinition.ts:1-50

工具架构

类型层级

工具系统采用 TypeScript 类型安全的设计，通过泛型约束确保工具定义的正确性。

graph TD
    A[BaseToolDefinition] --> B[ToolDefinition]
    A --> C[PageToolDefinition]
    B --> D[DefinedTool]
    C --> E[DefinedPageTool]

资料来源：src/tools/ToolDefinition.ts:50-80

工具结构

每个工具定义包含以下核心字段：

资料来源：src/tools/ToolDefinition.ts:80-120

工具定义函数

defineTool - 全局工具定义

defineTool 用于定义不依赖特定页面的工具，如浏览器管理、性能分析等。

export function defineTool<Schema extends zod.ZodRawShape>(
  definition: ToolDefinition<Schema>,
): DefinedTool<Schema>;

使用示例：

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 参数。

export function definePageTool<Schema extends zod.ZodRawShape>(
  definition: PageToolDefinition<Schema>,
): DefinedPageTool<Schema>;

使用示例：

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

工厂模式支持

两个定义函数都支持传入工厂函数，用于动态生成工具定义：

export function definePageTool<
  Schema extends zod.ZodRawShape,
  Args extends ParsedArguments = ParsedArguments,
>(
  definition: (args?: Args) => PageToolDefinition<Schema>,
): (args?: Args) => DefinedPageTool<Schema>;

这允许工具定义根据传入参数进行条件性配置。

资料来源：src/tools/ToolDefinition.ts:220-240

工具分类体系

分类枚举

工具按功能域划分为多个分类，便于管理和文档生成：

资料来源：src/tools/categories.ts

分类标签映射

文档生成系统使用标签映射将分类标识转换为可读名称：

const labels: Record<string, string> = {
  [ToolCategory.NAVIGATION]: 'Navigation',
  [ToolCategory.INPUT]: 'Input Automation',
  [ToolCategory.INSPECTION]: 'Inspection',
  // ...
};

资料来源：scripts/generate-docs.ts:30-50

工具注解系统

注解结构

annotations 字段提供工具的额外元数据：

interface ToolAnnotations {
  category: ToolCategory;           // 工具所属分类
  readOnlyHint?: boolean;            // 是否为只读操作
  conditions?: string[];            // 需要的实验性标志
  docsLink?: string;                // 文档链接
}

资料来源：src/tools/ToolDefinition.ts:40-48

条件激活机制

某些工具需要特定标志才能使用，条件在 conditions 数组中声明：

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 定义：

schema: {
  paramName: zod.string().describe('Parameter description'),
  optionalParam: zod.number().optional().describe('Optional parameter'),
  enumParam: zod.enum(['option1', 'option2']).describe('Enum parameter'),
}

常用 Schema 组件

预定义 Schema

系统提供常用 schema 组件：

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：

handler: (
  request: Request<Schema> & { page?: ContextPage },
  response: Response,
  context: Context,
) => Promise<void>

页面作用域工具 Handler：

handler: (
  request: Request<Schema> & { page: ContextPage },
  response: Response,
  context: Context,
) => Promise<void>

请求生命周期

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 类进行格式化，支持多种输出格式：

response.setListWebMcpTools();                    // 设置 WebMCP 工具列表
response.setText(content: string);                // 设置文本内容
response.setScreenshot(filePath: string);        // 设置截图路径
response.setSnapshot(snapshot: string);          // 设置快照内容

响应数据结构

interface ToolResponse {
  content: ContentBlock[];        // 内容块列表
  structuredContent?: {           // 结构化内容
    webmcpTools?: WebMcpTool[];    // WebMCP 工具信息
    networkRequests?: NetworkRequest[];
    pagination?: PaginationData;
  };
}

资料来源：src/McpResponse.ts:1-50

工具注册与发现

工具列表生成

文档生成脚本自动扫描所有工具定义并生成参考文档：

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

工具列表输出格式

## 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 工具：

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 工具：

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 使用有严格的类型安全要求：

资料来源：AGENTS.md:20-35

总结

工具系统是 chrome-devtools-mcp 实现浏览器自动化和调试能力的基础架构。通过：

• 类型安全的工具定义：利用 TypeScript 泛型和 Zod schema 确保编译期和运行期类型正确
• 分层架构：区分全局工具和页面作用域工具，适配不同的使用场景
• 注解驱动：通过 annotations 提供元数据，支持文档生成和 AI 决策
• 统一处理流程：标准化工具的注册、调用、响应流程

开发者可以基于 defineTool 和 definePageTool 快速扩展新的工具能力，同时保持代码的一致性和可维护性。

概述

输入自动化工具是 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

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 工具

press_key 工具用于模拟键盘按键操作，支持单键、修饰键组合以及特殊键序列。

参数定义：

支持的修饰键：

• Control
• Shift
• Alt
• Meta

特殊键示例：

• Enter - 回车键
• Tab - 制表符
• Escape - 退出键
• ArrowUp / ArrowDown - 方向键
• Control++ - Ctrl 加号（缩放）
• Control+Shift+R - 强制刷新

实现原理：

该工具使用 parseKey 函数解析按键字符串，将修饰键与主键分离。执行时按照修饰键按下 → 主键按下 → 修饰键释放的顺序进行操作，确保组合键的正确性。资料来源：src/tools/input.ts:1-100

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 工具用于向当前聚焦的输入元素输入文本内容。

参数定义：

使用场景：

• 在文本框中输入搜索关键词
• 填写表单字段
• 在富文本编辑器中输入内容

执行流程：

graph LR
    A[聚焦输入框] --> B[逐字符输入文本]
    B --> C{指定了 submitKey?}
    C -->|是| D[按下提交键]
    C -->|否| E[操作完成]
    D --> E

元素交互工具

click 工具

click 工具通过元素 ID 执行点击操作，支持单击和双击模式。

参数定义：

hover 工具

hover 工具将鼠标移动到指定元素上方，常用于触发 CSS 悬浮效果或显示下拉菜单。

drag 工具

drag 工具执行拖拽操作，将源元素拖拽到目标元素位置。

参数定义：

fill 工具

fill 工具用于快速填充表单输入框或选择下拉选项，相比 type_text 更加高效。

参数定义：

文件上传工具

upload_file 工具

upload_file 工具通过已存在的文件输入元素（<input type="file">）上传本地文件。

参数定义：

使用限制：

• 目标元素必须是 <input type="file"> 或具有 contenteditable 属性的元素
• 文件路径必须是服务器可访问的本地路径
• 不支持拖拽上传区域（需使用 drag 工具模拟拖拽）

通用参数与配置

快照参数

所有交互工具都支持 includeSnapshot 可选参数，用于控制在操作执行后是否返回页面的可访问性树快照。

建议在以下场景启用快照返回：

• 验证表单提交后的页面状态
• 检查下拉菜单或弹窗是否正确显示
• 确认异步操作完成后的 DOM 变化

页面选择

交互工具执行前必须通过 select_page 选择目标页面：

chrome-devtools select_page 1  # 选择索引为 1 的页面
chrome-devtools select_page 1 --bringToFront true  # 选择并切换到前台

未选择页面的直接调用将导致错误。

工作流程

典型交互流程

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 工具进行响应

chrome-devtools handle_dialog accept  # 接受对话框
chrome-devtools handle_dialog dismiss --promptText "取消"  # 拒绝并填写提示文本

错误处理

常见错误场景

最佳实践

1. 始终获取最新快照：页面状态可能因异步操作变化，建议每次交互前重新调用 take_snapshot
2. 使用 appropriate 的超时设置：对于慢速网络或复杂页面，适当增加超时时间
3. 验证操作结果：使用快照对比验证交互是否成功执行
4. 避免并行冲突：多个工具同时操作同一页面可能导致不可预期行为

命令行使用示例

# 点击按钮
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 验证

概述

性能分析工具是 chrome-devtools-mcp 提供的核心功能集，用于监控、测量和优化网页性能。该工具集涵盖性能追踪、性能洞察分析、内存快照捕获以及 Lighthouse 审计等多个维度，为开发者提供全面的性能诊断能力。

工具采用 Chrome DevTools Protocol (CDP) 与浏览器内核深度交互，支持性能追踪录制、追踪文件保存与加载、性能指标解析以及自动化 Lighthouse 审计等功能。

资料来源：src/tools/performance.ts src/tools/lighthouse.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 开发者工具的性能录制功能，能够捕获页面在加载和运行过程中的详细执行轨迹数据。

工作流程

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 设置为 true 时，工具会重新加载页面并录制完整的加载过程，这对于分析页面首次加载性能至关重要。

资料来源：src/tools/performance.ts 资料来源：skills/chrome-devtools/SKILL.md

#### performance_stop_trace

停止当前正在进行的性能追踪录制，并将追踪数据保存到指定文件或返回 JSON 数据。

追踪数据格式

追踪数据采用 JSON 格式，包含以下核心部分：

• traceEvents：Chrome 追踪格式的事件数组
• metadata：追踪元数据，包括浏览器版本、录制时间等
• screenshots：如果启用截屏，则包含 Base64 编码的截屏数据

性能洞察分析 (Performance Insights)

功能描述

Performance Insights 是 Chrome DevTools 中比传统 Performance 面板更现代的性能分析界面，提供以用户为中心的性能指标解读。工具 performance_analyze_insight 用于获取这些洞察数据。

支持的洞察类型

工具参数

#### performance_analyze_insight

LCP 优化指南

根据 LCPBreakdown 洞察数据，可按以下目标进行优化：

资料来源：skills/debug-optimize-lcp/SKILL.md 资料来源：skills/debug-optimize-lcp/references/optimization-strategies.md

内存快照 (Memory Snapshot)

功能描述

内存快照工具用于捕获 V8 JavaScript 引擎的堆内存状态，帮助开发者分析内存泄漏和内存使用情况。

工具参数

#### take_memory_snapshot

快照文件格式为 .heapsnapshot，可使用 Chrome DevTools 的 Memory 面板加载分析。

工作原理

1. 调用 CDP 的 HeapProfiler.takeHeapSnapshot 方法
2. 将快照数据序列化为 Chrome 支持的堆快照格式
3. 保存到指定文件路径或返回数据

Lighthouse 审计

功能描述

Lighthouse 审计工具提供基于 Chromium 内置 Lighthouse 的自动化网站质量审计，覆盖无障碍访问（Accessibility）、搜索引擎优化（SEO）、最佳实践等多个维度。

与性能追踪的区别

工具参数

#### lighthouse_audit

审计类别

Lighthouse 审计默认包含以下类别：

审计结果结构

审计结果为 JSON 格式，包含：

• scores：各审计类别的分数（0-1 范围）
• audits：详细审计结果，包含通过/失败状态和建议
• timing：审计执行时间

资料来源：src/tools/lighthouse.ts

LCP 调试与优化工作流

诊断流程

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 元素

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});
  });
};

#### 审计常见问题

() => {
  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：

资料来源：scripts/eval_scenarios/performance_test.ts

使用限制与注意事项

1. 对话处理：性能追踪工具（performance_start_trace）在有对话框打开时会被阻塞
2. 超时配置：使用 timeout 参数控制操作超时时间，避免长时间等待
3. 文件路径：建议为追踪文件和快照指定明确的文件路径，便于后续分析
4. 页面选择：Lighthouse 审计等页面工具需要先选择目标页面

相关工具链接

• 导航工具：navigate_page - 页面导航
• 快照工具：take_snapshot - 页面结构快照
• 模拟工具：emulate - 网络和设备模拟

概述

内存调试工具是 chrome-devtools-mcp 提供的核心功能集之一，用于分析和诊断浏览器页面中的内存问题。这些工具通过 Chrome DevTools Protocol 与 Chromium 的堆快照引擎交互，帮助开发者识别内存泄漏、追踪对象增长，并理解 JavaScript 运行时的内存分布情况。

内存调试工具的主要职责包括：

• 捕获页面的堆快照（Heap Snapshot）文件
• 加载和分析堆快照数据
• 提供快照摘要统计信息
• 支持与外部内存分析工具（如 Memlab）的集成
• 包含用于手动比较快照的回退脚本

资料来源：src/tools/memory.ts:1-15

架构设计

核心组件

内存调试工具的架构由以下核心组件构成：

工具定义架构

内存工具使用统一的工具定义框架，该框架基于 definePageTool 工厂函数构建。每个工具定义包含以下结构：

export interface BaseToolDefinition<Schema extends zod.ZodRawShape> {
  name: string;
  description: string;
  annotations: {
    category: ToolCategory;
    readOnlyHint: boolean;
    conditions?: string[];
  };
  schema: Schema;
  blockedByDialog: boolean;
}

资料来源：src/tools/ToolDefinition.ts:20-35

工具 API

takeMemorySnapshot

功能：捕获当前选中页面的堆快照。

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

参数说明：

执行流程：

graph TD
    A[调用 take_memory_snapshot] --> B[验证文件路径]
    B --> C[执行 pptrPage.captureHeapSnapshot]
    C --> D[保存 .heapsnapshot 文件]
    D --> E[返回成功消息]

使用示例：

chrome-devtools take_memory_snapshot "./baseline.heapsnapshot"
chrome-devtools take_memory_snapshot "./target.heapsnapshot" --includeSnapshot true

loadMemorySnapshot

功能：加载堆快照文件并返回摘要统计信息。

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

参数说明：

注意：此工具需要 experimentalMemory 条件满足方可使用。

工作流程

基本内存调试流程

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：建立基线快照

在执行任何操作之前，捕获页面的初始内存状态：

chrome-devtools take_memory_snapshot "./baseline.heapsnapshot"

资料来源：skills/memory-leak-debugging/SKILL.md:1-20

#### 步骤 2：操作并捕获目标快照

执行可能存在内存泄漏的操作（如重复用户交互），然后再次捕获快照：

chrome-devtools take_memory_snapshot "./target.heapsnapshot"

#### 步骤 3：恢复页面状态

将页面恢复到原始状态，验证内存是否被正确释放：

使用 click、fill 等工具将页面操作回原始状态，观察内存是否释放。

资料来源：skills/memory-leak-debugging/SKILL.md:21-35

#### 步骤 4：捕获最终快照

恢复操作后再次捕获快照：

chrome-devtools take_memory_snapshot "./final.heapsnapshot"

#### 步骤 5：分析对比

使用 Memlab 或回退脚本分析三个快照文件。

快照比较脚本

compare_snapshots.js

当 Memlab 不可用时，可以使用项目提供的回退脚本进行快照比较。

位置：skills/memory-leak-debugging/references/compare_snapshots.js

使用方法：

node skills/memory-leak-debugging/references/compare_snapshots.js <baseline.heapsnapshot> <target.heapsnapshot>

资料来源：skills/memory-leak-debugging/references/compare_snapshots.js:1-50

输出内容：

检测的常见泄漏类型：

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

常见内存泄漏类型

根据项目文档，堆快照分析中最常见的泄漏类型包括：

资料来源：skills/memory-leak-debugging/references/compare_snapshots.js:43-49

使用限制与注意事项

工具阻塞条件

takeMemorySnapshot 工具配置了 blockedByDialog: true，这意味着当页面上存在对话框时，该工具将被阻塞：

blockedByDialog: 如果设置为 true，则工具在页面存在对话框时无法执行。

资料来源：src/tools/memory.ts:38-39

路径验证

所有文件路径在执行前都会经过验证，确保快照文件能够正确保存到指定位置：

context.validatePath(request.params.filePath);

资料来源：src/tools/memory.ts:41

文件扩展名强制

脚本会自动为文件路径添加 .heapsnapshot 扩展名：

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

命令行使用

基本命令

# 捕获堆快照
chrome-devtools take_memory_snapshot "./snap.heapsnapshot"

# 加载并分析快照
chrome-devtools load_memory_snapshot "./snap.heapsnapshot"

完整示例

# 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

相关文件索引

概述

chrome-devtools-mcp 提供了完整的命令行界面（CLI）和灵活的配置系统，支持通过命令行参数启动 MCP 服务器、管理浏览器生命周期、以及自动化浏览器操作。该项目采用 TypeScript 开发，使用 Puppeteer 作为底层浏览器自动化引擎，并通过 MCP（Model Context Protocol）协议与 AI 代理进行通信。资料来源：AGENTS.md

架构设计

组件关系

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]

启动流程

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: 暴露工具列表

命令行接口

全局命令

资料来源：skills/chrome-devtools-cli/SKILL.md:50-53

工具命令

CLI 支持直接调用 MCP 工具进行浏览器自动化操作，基本语法如下：

chrome-devtools <tool> [arguments] [flags]

资料来源：skills/chrome-devtools-cli/SKILL.md:21

输出格式

默认输出为 Markdown 格式，可通过 --output-format 参数切换：

chrome-devtools take_snapshot --output-format=json

资料来源：skills/chrome-devtools-cli/SKILL.md:23

命令行参数配置

参数解析模块

参数解析由 chrome-devtools-mcp-cli-options.ts 实现，核心类型定义如下：

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

工具类别配置

工具按功能分类管理，通过 --category-* 标志启用：

资料来源：skills/chrome-devtools-cli/SKILL.md:49-51

必需标志构建

工具类别标志通过 buildFlag 函数动态构建：

import {buildFlag} from '../build/src/index.js';

// 生成标志名
const categoryFlag = buildFlag(category);
const flagName = `--${categoryFlag}`;

资料来源：scripts/generate-docs.ts:72-76

默认关闭的类别

部分工具类别默认不启用，需要显式启用：

export const OFF_BY_DEFAULT_CATEGORIES = [
  ToolCategory.WEBMCP,
  ToolCategory.EXTENSION,
  ToolCategory.EXPERIMENTAL,
];

资料来源：scripts/generate-docs.ts:24-28

工具分类体系

分类定义

graph LR
    A[ToolCategory] --> B[NAVIGATION]
    A --> C[INPUT]
    A --> D[PERFORMANCE]
    A --> E[NETWORK]
    A --> F[EXTENSION]
    A --> G[WEBMCP]
    A --> H[EXPERIMENTAL]

分类标签映射

资料来源：scripts/generate-docs.ts:29-40

浏览器配置

Puppeteer 配置

通过 puppeteer.config.cjs 配置文件管理浏览器实例：

module.exports = {
  puppeteer: {
    // 浏览器启动参数
    args: [
      '--no-sandbox',
      '--disable-setuid-sandbox',
      '--disable-dev-shm-usage',
    ],
    // 用户数据目录（持久化配置）
    userDataDir: './chrome-profile',
    // 调试端口
    debugPort: 9222,
  },
};

资料来源：puppeteer.config.cjs

浏览器生命周期

浏览器使用持久化 Chrome 配置文件，首次调用工具时自动启动：

stateDiagram-v2
    [*] --> 未启动: 程序初始化
    未启动 --> 运行中: 首次工具调用
    运行中 --> 运行中: 工具操作
    运行中 --> 已停止: stop命令
    已停止 --> 运行中: start命令
    已停止 --> [*]: 程序退出

资料来源：skills/chrome-devtools/SKILL.md:8-9

页面管理

工具操作作用于当前选中的页面，支持多页面管理：

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

网络与模拟配置

网络条件模拟

# 离线模拟
chrome-devtools emulate --networkConditions "Offline"

# 自定义网络节流
chrome-devtools emulate --networkConditions "Slow 3G"

资料来源：skills/chrome-devtools-cli/SKILL.md:41-44

设备模拟

资料来源：skills/chrome-devtools-cli/SKILL.md:44-48

使用示例

# 模拟暗黑模式和全高清视口
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

实验性功能

启用方式

实验性功能默认禁用，需通过相应标志启用：

chrome-devtools-mcp --experimentalVision=true --experimentalScreencast=true

资料来源：skills/chrome-devtools-cli/SKILL.md:49-51

实验性工具列表

资料来源：skills/chrome-devtools-cli/SKILL.md:49-55

CLI 选项自动生成

生成流程

项目使用脚本自动从运行时工具定义生成 CLI 选项：

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

生成的代码结构

生成的 chrome-devtools-cli-options.ts 包含所有工具的 CLI 接口定义：

// 通过 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

构建与测试

构建命令

npm run build    # 运行 tsc 编译并测试构建

资料来源：AGENTS.md:5

测试命令

npm run test                    # 构建并运行所有测试
npm run test path-to-test.ts    # 构建并运行单个测试文件

资料来源：AGENTS.md:6-8

代码格式

npm run format    # 修复格式问题和 linting 错误

资料来源：AGENTS.md:11

扩展管理配置

扩展操作命令

资料来源：skills/chrome-devtools-cli/SKILL.md:48-50

启用扩展支持

扩展功能默认关闭，需要通过 --categoryExtensions 标志启用：

chrome-devtools-mcp --categoryExtensions=true

资料来源：skills/chrome-devtools/SKILL.md:8-9

性能追踪配置

追踪命令

# 开始追踪
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

内存快照

chrome-devtools take_memory_snapshot "./snap.heapsnapshot"

资料来源：skills/chrome-devtools-cli/SKILL.md:41-42

环境变量

资料来源：skills/chrome-devtools-cli/references/installation.md:13

常见配置问题排查

问题诊断步骤

1. 检查服务状态：chrome-devtools status
2. 查看详细日志：启动时添加 --logFile=/tmp/cdm-test.log
3. 分析日志输出中的错误信息

资料来源：skills/troubleshooting/SKILL.md

权限错误处理

遇到 EACCES 权限错误时，建议：

• 使用 nvm 管理 Node.js 版本
• 配置 npm 使用不同的全局目录
• 避免使用 sudo 安装全局包

资料来源：skills/chrome-devtools-cli/references/installation.md:16-18

概述

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 助手与浏览器自动化之间的桥梁。

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

核心组件

客户端配置

.mcp.json 配置格式

MCP 客户端通过 .mcp.json 配置文件声明服务器连接。配置文件采用 JSON 格式定义服务器路径和可选参数。

{
  "mcpServers": {
    "chrome-devtools": {
      "command": "node",
      "args": ["path/to/cli.js", "--headless"]
    }
  }
}

资料来源：.mcp.json

Gemini 扩展配置

针对 Google Gemini 平台的特殊集成配置：

{
  "name": "chrome-devtools",
  "description": "...",
  "entry_point": "...",
  "runtime": "...",
  "permissions": ["browser"]
}

资料来源：gemini-extension.json

运行时环境要求

项目对 Node.js 版本有明确的兼容性要求：

资料来源：package.json:48-51

WebMCP 工具接口

WebMCP 是项目定义的扩展协议，允许网页向 MCP 客户端暴露自定义工具。核心接口包含两个工具：

list_webmcp_tools

列出当前页面暴露的所有 WebMCP 工具。

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 工具。

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 枚举进行分类管理：

工具定义函数

项目使用工厂函数模式定义工具：

export function definePageTool<Schema extends zod.ZodRawShape>(
  definition: PageToolDefinition<Schema>
): DefinedPageTool<Schema> {
  return {
    ...definition,
    pageScoped: true,
  };
}

关键特性包括：

• pageScoped: 标记工具是否需要页面上下文
• blockedByDialog: 标记对话框是否阻止工具执行
• readOnlyHint: 提示工具是否仅读取数据

资料来源：src/tools/ToolDefinition.ts:38-50

通用模式定义

项目提供可复用的参数模式：

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 协议兼容的响应：

if (this.#listWebMcpTools && data.webmcpTools) {
  structuredContent.webmcpTools = data.webmcpTools.map(
    ({name, description, inputSchema, annotations}) => ({
      name,
      description,
      inputSchema,
      annotations,
    }),
  );
}

资料来源：src/McpResponse.ts:45-54

响应格式化

响应消息包含结构化内容与文本描述：

资料来源：src/McpResponse.ts:55-68

集成工作流

典型执行流程

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: 响应数据

页面工具调用示例

``bash chrome-devtools take_snapshot ``

1. 获取页面快照：

``bash chrome-devtools evaluate_script "document.title" ``

1. 执行 JavaScript：

``bash chrome-devtools navigate_page --url "https://example.com" ``

1. 页面导航：

工具分类参考

输入自动化工具

资料来源：skills/chrome-devtools-cli/SKILL.md:14-28

导航工具

资料来源：skills/chrome-devtools-cli/SKILL.md:1-13

检查工具

类型系统

Schema 定义规范

项目强制使用 Zod 进行运行时类型验证，禁止使用 any 类型：

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 泛型处理参数转换：

type ParsedArguments = {
  [key: string]: unknown;
};

扩展与定制

自定义工具开发

1. 在 src/tools/ 目录创建新工具文件
2. 使用 definePageTool 工厂函数定义工具
3. 实现 handler 异步函数处理逻辑
4. 导出工具并注册到相应类别

类别扩展

工具类别在 ToolCategory 枚举中定义：

export enum ToolCategory {
  WEBMCP = 'webmcp',
  INPUT = 'input',
  NAVIGATION = 'navigation',
  INSPECTION = 'inspection',
}

测试与验证

集成测试场景

项目包含多个评估场景用于验证客户端集成：

资料来源：scripts/eval_scenarios/performance_test.ts:1-22

测试执行命令

npm run test                    # 运行所有测试
npm run test tests/McpContext.test.ts  # 运行单个测试文件

资料来源：AGENTS.md:5-7

安全考虑

对话框阻塞机制

某些工具设置 blockedByDialog: true，在浏览器对话框出现时会被阻塞：

{
  blockedByDialog: true,  // 对话框会阻止此工具执行
}

只读操作提示

readOnlyHint 注解用于提示工具是否修改浏览器状态：

{
  readOnlyHint: true,  // 提示此工具仅读取数据
}

相关文档

• 安装指南 - CLI 安装与配置
• 工具参考 - 所有工具完整文档
• 无障碍调试 - 可访问性检查集成
• 性能优化 - LCP 调试集成

Pitfall Log / 踩坑日志

项目：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