chrome-devtools-mcp 是 Chrome DevTools 团队维护的 Model Context Protocol (MCP) 服务器。它把 Chrome 浏览器以结构化工具的形式暴露给 AI 代理（如 Claude Code、Cursor、Copilot CLI 等），使大模型可以像开发者打开 DevTools 那样直接操控浏览器：浏览页面、抓取证据、回放网络、跑 Lighthouse 与性能 trace。 资料来源：README.md:1-40

1. 项目角色与定位

项目自身并不实现浏览器自动化引擎，而是作为三层结构中的"翻译层"存在：

• MCP 协议层：通过 stdio 协议向客户端暴露工具列表、资源与提示模板；
• CDP 客户端层：以 WebSocket 与目标 Chrome 的 DevTools Protocol 通信；
• 浏览器管理：在未提供 --browserUrl 时，自行启动一个临时 Chrome 实例；提供时则接管已有远程实例。

资料来源：package.json:1-60 src/index.ts:1-80

该角色让"代理用自然语言完成前端任务"成为可能，是把 DevTools 控制台语义化的关键基础设施。

2. 核心能力

服务器围绕"页面（page）"这一抽象组织工具集：

• 页面导航与选择：list_pages、select_page、navigate_page 处理多标签页与跳转跟踪 (v1.0.0 起 #1853)；
• 内容采集：take_screenshot 给出图像证据 (CLI JSON 中会回写保存路径，#2070)，take_snapshot 返回可访问性 / DOM 文本；
• 输入与表单：click、fill、fill_form、press_key 覆盖基本交互；
• 网络与资源：list_network_requests、get_request_body 还原 Network 面板；
• 仿真：emulate 工具支持视口、设备、CPU、网络节流，自 v1.1.0 起加入 extraHttpHeaders 仿真 (#1176)；
• 性能与质量：trace_start / trace_stop 抓取 trace；Lighthouse 集成 (#1931) 支持 agentic browsing；
• 错误观测：通过统一 McpResponse 通道附带结构化错误日志 (v0.26.0 #2006)，并支持第三方开发者工具扩展 (v0.25.0 #1982)。

资料来源：README.md:40-140 src/McpResponse.ts:1-100 src/tools/listPages.ts:1-60

社区高频使用模式包括：多账号场景下用 list_pages 区分 (#2156)、macOS 下 bringToFront 反复抢夺焦点 (#1254)。

3. 架构骨架

flowchart LR
    A[AI 代理<br/>MCP Client] -- stdio --> B[chrome-devtools-mcp<br/>MCP Server]
    B -- 调用工具 --> T[Tool Handlers<br/>src/tools/*]
    T -- CDP ws --> C[(本地 / 远程 Chrome)]
    T --> R[McpResponse<br/>图像 / 文本 / JSON]
    R -- MCP 内容 --> A

• 入口 src/index.ts 解析 CLI 参数、构造 MCP 服务器并注册工具列表；资料来源：src/index.ts:60-160
• src/cli.ts 提供 npx chrome-devtools-mcp@latest 调用形态，控制输出格式（包括截图路径与 CLI JSON）；CLI 自 v1.1.1 起调整 pageId 为第一个位置参数 (#2142)。资料来源：src/cli.ts:1-90
• 工具模块遵循统一约定：输入 schema 由 Zod 定义，回包走 McpResponse，截图等二进制以 image 内容块呈现；资料来源：src/McpResponse.ts:30-140

4. 版本演进与生态

项目自 v0.24 起以双周节奏持续迭代，v1.0.0（2026-05-18）被视为首个稳定里程碑，公共 API 形态基本定型；当前最新为 v1.6.0（2026-07-14），引入 experimentalGcfFormat 实验旗标，将工具响应编码为 GCF 格式 (#2235)。 资料来源：package.json:1-20 GitHub Releases

社区活跃议题集中在三个方向：

• 更多调试入口：Chrome 扩展调试 (#96)、自动连接既有 Chrome (#140)、WSL 下访问宿主浏览器 (#131)；
• 多会话/多账号：单进程绑定单浏览器实例的局限 (#926)、远程调试授权持久化 (#825)、MCP 启动后切换 --browserUrl (#2154)；
• 运行时体验：list_pages 暴露页面标题 (#2156)、Cursor 插件主页字段修正 (#2172)、减少 macOS 不必要的焦点切换 (#1254)；
• 生态收录：项目已列入 CodeGuilds 等 Claude Code 生态目录 (#2177)。

资料来源：issues/96 issues/140 issues/131 issues/926 issues/825 issues/2154 issues/2156 issues/2172 issues/1254 issues/2177

总体而言，chrome-devtools-mcp 把"开发者手动 DevTools"翻译为代理可调用的语义层，常作为 Claude Code 等前端默认工具链组件出现，是 AI 代理完成网页取证、性能审查与端到端验证时的高频起点。

src/utils/ 目录是 chrome-devtools-mcp 项目中的基础设施层，集中收纳与 Chrome DevTools Protocol（CDP）交互无直接关系、但被多个上层工具复用的纯辅助逻辑。这些工具覆盖并发控制、ID 生成、键盘按键编码、本地文件处理、日志输出以及版本自检等横切关注点，让 src/tools/ 中的具体 MCP 工具实现可以专注于浏览器自动化语义本身。

模块组成与职责划分

Utils 模块按职责可划分为以下几类：

• 并发原语：Mutex.ts 提供互斥锁实现，确保对共享资源（例如浏览器会话、CDP 连接）的串行访问，避免并发 MCP 调用引发的竞态问题。
• 标识与时间戳：id.ts 提供稳定的随机标识符生成能力，常用于工具调用、页面回话追踪和事件关联。
• 输入编码：keyboard.ts 将人类可读的按键名称映射为 CDP Input.dispatchKeyEvent 所要求的 key / code / windowsVirtualKeyCode，是 press_key 等工具正确触发按键事件的前提。
• 文件与文件系统：files.ts 封装截图、下载产物等二进制或文本内容的本地持久化路径解析与写入逻辑。
• 诊断输出：logger.ts 提供统一的错误日志写入接口，配合 v0.26.0 引入的"错误日志记录方法"使用。
• 版本管理：check-for-updates.ts 在 MCP 服务器启动或运行期间检查 npm 注册表，提示用户升级到最新版本。

资料来源：src/utils/Mutex.ts:1-80；src/utils/id.ts:1-40；src/utils/keyboard.ts:1-120；src/utils/files.ts:1-60；src/utils/logger.ts:1-50；src/utils/check-for-updates.ts:1-70。

关键工作流

下面以一次完整的"工具调用"为例，展示 Utils 模块与上层工具的协作关系：

sequenceDiagram
    participant MCP as MCP 客户端
    participant Tool as src/tools/*
    participant Utils as src/utils
    participant CDP as Chrome DevTools Protocol
    MCP->>Tool: 调用工具（如 press_key）
    Tool->>Utils: id.ts 生成请求 ID
    Tool->>Utils: keyboard.ts 编码按键
    Tool->>Utils: Mutex.ts 加锁会话
    Tool->>CDP: 派发按键事件
    CDP-->>Tool: 返回结果
    Tool->>Utils: logger.ts 记录日志
    Tool->>Utils: files.ts 写产物（截图）
    Utils-->>Tool: 解锁并返回
    Tool-->>MCP: 结构化响应

并发安全由 Mutex.ts 保障，键盘语义由 keyboard.ts 翻译，二进制产物落地由 files.ts 处理，而 logger.ts 则贯穿始终。资料来源：src/utils/Mutex.ts:1-80；src/utils/keyboard.ts:1-120；src/utils/files.ts:1-60；src/utils/logger.ts:1-50。

与社区关切的关联

社区中多条热门讨论涉及 Utils 模块所支撑的能力：

• 多会话/并行浏览器支持（#926）：当前 Mutex 仅保护单一浏览器实例，社区希望扩展到多实例，这是 Mutex.ts 未来演化的潜在方向。
• macOS 焦点劫持（#1254）：连续 CDP 调用抢焦点的问题可借助 logger.ts 输出诊断信息来辅助排查。
• WSL 环境访问宿主 Chrome（#131）：跨平台路径解析在 files.ts 中以平台无关方式实现，便于在 WSL 桥接场景下复用。
• 持久化远程调试授权（#825）：重连和授权提示会在 check-for-updates.ts 的相邻路径里产生副作用日志，logger.ts 是统一的捕获点。

扩展指引

新增工具时建议遵循以下约定：

1. 优先复用：需要 ID、加锁、按键编码或文件落盘时，优先从 src/utils/ 导入，而不是在 src/tools/ 中重复实现。
2. 保持纯函数：keyboard.ts、id.ts 等模块应当保持无副作用，方便测试与跨工具复用。
3. 统一日志格式：错误与警告统一通过 logger.ts 写入，保持 MCP 客户端侧的可观察性一致。
4. 谨慎触及 Mutex：任何需要持有浏览器/CDP 会话的代码都应通过 Mutex 加锁，避免与现有 take_screenshot、list_pages 等工具产生竞态。

遵循上述约定，新工具可与现有体系平滑集成，降低维护成本。资料来源：src/utils/Mutex.ts:1-80；src/utils/id.ts:1-40；src/utils/files.ts:1-60；src/utils/logger.ts:1-50。

Watchdog 模块是 chrome-devtools-mcp 中负责进程健康监控、异常捕获与遥测上报的内部组件。它与 MCP 服务器主循环并行运行，负责在工具调用、CDP（Chrome DevTools Protocol）通信或浏览器连接出现异常时，记录结构化错误并触发上报流程，从而提高 AI 代理调试浏览器时的可观测性。资料来源：src/watchdog/Watchdog.ts:1-40

职责与边界

Watchdog 的核心职责可概括为以下三点：

• 进程存活监控：定期检查 MCP 服务器进程及派生的 Chrome 子进程是否处于健康状态，并在检测到挂起或崩溃时执行恢复动作。资料来源：src/watchdog/Watchdog.ts:42-80
• 异常聚合：捕获工具调用链路中未处理的 Promise rejection 与同步异常，将其归一化为 WatchdogEvent 结构后传递给遥测层。资料来源：src/watchdog/types.ts:10-35
• 遥测下发：通过 ErrorReporter 接口将事件批量发送到后端收集点，避免对主链路产生副作用。资料来源：src/telemetry/ErrorReporter.ts:18-60

Watchdog 不会直接干预工具的业务返回值，仅在错误日志与进程生命周期层产生影响，这与社区反馈中"macOS 上每次 CDP 命令都会窃取焦点"（#1254）等可观测性问题相关——Watchdog 的设计意图是为后续定位此类行为提供数据基础。资料来源：Issue #1254

关键数据结构

Watchdog 模块对外暴露的核心类型如下表所示：

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

WatchdogConfig 由 MCP 服务器在启动时根据 CLI 参数与默认策略组装；当 enabled 为 false 时，Watchdog 进入空操作模式，仅保留接口骨架，便于在受限环境（如 CI）下安全运行。资料来源：src/watchdog/index.ts:12-30

工作流程

下图描述了 Watchdog 在一次工具调用失败时的典型数据流：

flowchart LR
    A[MCP Tool 调用] --> B{业务逻辑}
    B -- 成功 --> C[返回结果]
    B -- 异常 --> D[Watchdog 捕获]
    D --> E[归一化为 WatchdogEvent]
    E --> F[ErrorReporter 缓冲]
    F --> G[批量上报]
    G --> H[遥测后端]

资料来源：src/watchdog/Watchdog.ts:55-95、src/telemetry/ErrorReporter.ts:30-70

与社区需求的关联

社区中高频讨论的多会话支持（#926）、WSL 环境访问（#131）以及自动连接到现有 Chrome 会话（#140）等议题，都依赖 Watchdog 提供的基础可观测性来判断连接稳定性与崩溃模式。因此，Watchdog 虽然不直接解决这些功能请求，但其数据是后续排障与功能迭代的重要依据。资料来源：Issue #926、Issue #140

配置与扩展

Watchdog 通过 WatchdogConfig 暴露有限的可调参数，避免暴露过多内部状态：

• heartbeatMs：心跳间隔，默认值为运行时根据负载自适应。
• reportBatchSize：批量上报阈值，防止突发错误导致上报风暴。
• enabled：总开关，便于在调试或测试场景下完全旁路 Watchdog。

资料来源：src/watchdog/Watchdog.ts:30-50、src/telemetry/Telemetry.ts:20-45

扩展点方面，ErrorReporter 是可替换的依赖注入接口，允许将事件转发到自定义后端（如企业内部日志平台），从而在不修改 Watchdog 主逻辑的前提下完成集成。资料来源：src/telemetry/ErrorReporter.ts:55-80

模块概述与用途

Check Latest Version.ts 是 chrome-devtools-mcp 项目中的一个独立 CLI 脚本，位于 src/bin/ 目录下 资料来源：src/bin/check-latest-version.ts:1-1。该项目通常将 src/bin/ 目录下的脚本作为命令行入口使用，由 package.json 中 bin 字段暴露给用户 资料来源：package.json:1-80。该模块的核心职责是查询 npm 注册表上发布的最新版本，并与本地 package.json 中声明的版本号进行比对。

在 chrome-devtools-mcp 项目中，版本发布节奏较为频繁（社区上下文显示近期已发布 v0.24.0 至 v1.6.0 等多个版本），因此该检查脚本在发布流程中扮演重要的守门员角色。

工作流程与核心逻辑

该脚本的执行流程大致分为三个阶段：读取本地版本、查询远程版本、输出比较结果。

flowchart TD
    A[启动 CLI] --> B[读取 package.json 当前版本]
    B --> C[请求 npm registry latest tag]
    C --> D{网络请求成功?}
    D -- 否 --> E[打印错误并退出]
    D -- 是 --> F[解析 latest 版本号]
    F --> G{本地版本 === latest?}
    G -- 是 --> H[退出码 0 - 无需更新]
    G -- 否 --> I[打印差异并按需退出非零]

脚本运行时会调用 npm 注册表的元数据接口获取当前包的最新版本标签（dist-tags.latest），并通过语义化版本比较函数判断是否落后于上游。日志输出依赖项目统一的 logger 模块 资料来源：src/utils/logger.ts:1-50。

关键依赖与集成点

check-latest-version.ts 不是 MCP 服务器运行时的组成部分，而是发布与持续集成链路的工具脚本：

• npm 注册表：通过 https://registry.npmjs.org/chrome-devtools-mcp/latest 之类的端点读取 latest tag。
• package.json：本地版本号来源，脚本通过相对路径读取当前包的版本字段 资料来源：package.json:1-80。
• 共享工具模块：与 src/main.ts 等运行时入口共享 logger 与 globalConfig 等工具 资料来源：src/globalConfig.ts:1-120.
• GitHub Actions：发布流水线中通常会调用此脚本作为前置检查，避免在没有更新的情况下触发发版流程 资料来源：.github/workflows/release.yml:1-100.

该脚本的退出码（exit code）携带了状态语义：版本一致时返回 0，存在差异时返回非零值，便于 CI 流水线据此阻断或继续发布。

社区背景与典型应用场景

社区上下文显示项目版本演进迅速（如 v0.24.0 → v0.25.0 → v0.26.0 → v1.0.0 → v1.1.0 → v1.1.1 → v1.6.0），并且涉及 multiple breaking changes 与 feature flags（如 experimentalGcfFormat）。这意味着发布前确认 latest tag 与本地代码同步，对于避免重复发版、漏发版本等问题尤为关键。

典型使用场景包括：

• 发布前自检：维护者在本地执行脚本，确认 package.json 中拟发布的版本号尚未被 npm 占用。
• CI 守门：在 release workflow 中作为 job 步骤，若 latest 与本地不同则 fail fast。
• 依赖方提示：当用户本地安装的版本落后时，可在后续工具运行中给出升级提示。

由于该脚本只承担单一职责（版本比对），其代码体量较小，但与项目整体的发布治理体系紧密耦合，是 chrome-devtools-mcp 工具链中不可或缺的一环。

Pitfall Log / 踩坑日志

项目：ChromeDevTools/chrome-devtools-mcp

摘要：发现 38 个潜在踩坑项，其中 20 个为 high/blocking；最高优先级：安装坑 - 来源证据：Memory leak in --browserUrl mode under sustained screencast + evaluate_script load: V8 heap grows to ~4GB limit, server…。

1. 安装坑 · 来源证据：Memory leak in --browserUrl mode under sustained screencast + evaluate_script load: V8 heap grows to ~4GB limit, server…

• 严重度：high
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Memory leak in --browserUrl mode under sustained screencast + evaluate_script load: V8 heap grows to ~4GB limit, server aborts (SIGABRT)
• 对用户的影响：可能阻塞安装或首次运行。
• 证据：community_evidence:github | https://github.com/ChromeDevTools/chrome-devtools-mcp/issues/2291 | 来源讨论提到 node 相关条件，需在安装/试用前复核。

2. 安装坑 · 来源证据：upload_file on a chooser-opening element crashes the tab with RESULT_CODE_KILLED_BAD_MESSAGE

• 严重度：high
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：upload_file on a chooser-opening element crashes the tab with RESULT_CODE_KILLED_BAD_MESSAGE
• 对用户的影响：可能阻塞安装或首次运行。
• 证据：community_evidence:github | https://github.com/ChromeDevTools/chrome-devtools-mcp/issues/2310 | 来源讨论提到 node 相关条件，需在安装/试用前复核。

3. 配置坑 · 来源证据：Page listing silently retargets the selection to the first page, bypassing the closed page error

• 严重度：high
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：Page listing silently retargets the selection to the first page, bypassing the closed page error
• 对用户的影响：可能增加新用户试用和生产接入成本。
• 证据：community_evidence:github | https://github.com/ChromeDevTools/chrome-devtools-mcp/issues/2304 | 来源讨论提到 node 相关条件，需在安装/试用前复核。

4. 配置坑 · 来源证据：Unified `capture_debug_bundle` Tool (HAR + Console + Performance + Screenshot)

• 严重度：high
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：Unified capture_debug_bundle Tool (HAR + Console + Performance + Screenshot)
• 对用户的影响：可能增加新用户试用和生产接入成本。
• 证据：community_evidence:github | https://github.com/ChromeDevTools/chrome-devtools-mcp/issues/632 | 来源类型 github_issue 暴露的待验证使用条件。

5. 运行坑 · 来源证据：Stop running trace when starting a new trace

• 严重度：high
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个运行相关的待验证问题：Stop running trace when starting a new trace
• 对用户的影响：可能增加新用户试用和生产接入成本。
• 证据：community_evidence:github | https://github.com/ChromeDevTools/chrome-devtools-mcp/issues/808 | 来源类型 github_issue 暴露的待验证使用条件。

6. 维护坑 · 来源证据：Input tools can leave keys and the mouse button held down; the root cause is an unguarded Keyboard.press() in Puppeteer

• 严重度：high
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个维护/版本相关的待验证问题：Input tools can leave keys and the mouse button held down; the root cause is an unguarded Keyboard.press() in Puppeteer
• 对用户的影响：可能影响升级、迁移或版本选择。
• 证据：community_evidence:github | https://github.com/ChromeDevTools/chrome-devtools-mcp/issues/2353 | 来源类型 github_issue 暴露的待验证使用条件。

7. 维护坑 · 来源证据：`list_console_messages` misses messages logged before the server attached

• 严重度：high
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个维护/版本相关的待验证问题：list_console_messages misses messages logged before the server attached
• 对用户的影响：可能增加新用户试用和生产接入成本。
• 证据：community_evidence:github | https://github.com/ChromeDevTools/chrome-devtools-mcp/issues/2382 | 来源类型 github_issue 暴露的待验证使用条件。

8. 安全/权限坑 · 失败模式：security_permissions: Cannot connect to the Chrome-devtools mcp server using the claude code

• 严重度：high
• 证据强度：source_linked
• 发现：Developers should check this security_permissions risk before relying on the project: Cannot connect to the Chrome-devtools mcp server using the claude code
• 对用户的影响：Developers may expose sensitive permissions or credentials: Cannot connect to the Chrome-devtools mcp server using the claude code
• 证据：failure_mode_cluster:github_issue | https://github.com/ChromeDevTools/chrome-devtools-mcp/issues/182 | Cannot connect to the Chrome-devtools mcp server using the claude code

9. 安全/权限坑 · 失败模式：security_permissions: Consider adding HITL approval for sensitive CDP operations

• 严重度：high
• 证据强度：source_linked
• 发现：Developers should check this security_permissions risk before relying on the project: Consider adding HITL approval for sensitive CDP operations
• 对用户的影响：Developers may expose sensitive permissions or credentials: Consider adding HITL approval for sensitive CDP operations
• 证据：failure_mode_cluster:github_issue | https://github.com/ChromeDevTools/chrome-devtools-mcp/issues/2261 | Consider adding HITL approval for sensitive CDP operations

10. 安全/权限坑 · 失败模式：security_permissions: Daemon bails with "PID directory has insecure permissions" on a 002 umask

• 严重度：high
• 证据强度：source_linked
• 发现：Developers should check this security_permissions risk before relying on the project: Daemon bails with "PID directory has insecure permissions" on a 002 umask
• 对用户的影响：Developers may expose sensitive permissions or credentials: Daemon bails with "PID directory has insecure permissions" on a 002 umask
• 证据：failure_mode_cluster:github_issue | https://github.com/ChromeDevTools/chrome-devtools-mcp/issues/2258 | Daemon bails with "PID directory has insecure permissions" on a 002 umask

11. 安全/权限坑 · 失败模式：security_permissions: Feature request: Allow persisting remote debugging permission approval

• 严重度：high
• 证据强度：source_linked
• 发现：Developers should check this security_permissions risk before relying on the project: Feature request: Allow persisting remote debugging permission approval
• 对用户的影响：Developers may expose sensitive permissions or credentials: Feature request: Allow persisting remote debugging permission approval
• 证据：failure_mode_cluster:github_issue | https://github.com/ChromeDevTools/chrome-devtools-mcp/issues/825 | Feature request: Allow persisting remote debugging permission approval

12. 安全/权限坑 · 失败模式：security_permissions: Injected input (click/fill/press_key) silently stops reaching a tab; tools still report success

• 严重度：high
• 证据强度：source_linked
• 发现：Developers should check this security_permissions risk before relying on the project: Injected input (click/fill/press_key) silently stops reaching a tab; tools still report success
• 对用户的影响：Developers may expose sensitive permissions or credentials: Injected input (click/fill/press_key) silently stops reaching a tab; tools still report success
• 证据：failure_mode_cluster:github_issue | https://github.com/ChromeDevTools/chrome-devtools-mcp/issues/2199 | Injected input (click/fill/press_key) silently stops reaching a tab; tools still report success

13. 安全/权限坑 · 失败模式：security_permissions: Security: Critical Path Traversal in evaluate_script tool (Arbitrary File Write / RCE)

• 严重度：high
• 证据强度：source_linked
• 发现：Developers should check this security_permissions risk before relying on the project: Security: Critical Path Traversal in evaluate_script tool (Arbitrary File Write / RCE)
• 对用户的影响：该失败模式可能影响开发者安装、配置、运行或升级，需要在能力资产里前置说明。
• 证据：failure_mode_cluster:unknown | security_permissions: Security: Critical Path Traversal in evaluate_script tool (Arbitrary File Write / RCE)

14. 安全/权限坑 · 失败模式：security_permissions: Visual cursor overlay for input automation on headed Chrome

• 严重度：high
• 证据强度：source_linked
• 发现：Developers should check this security_permissions risk before relying on the project: Visual cursor overlay for input automation on headed Chrome
• 对用户的影响：Developers may expose sensitive permissions or credentials: Visual cursor overlay for input automation on headed Chrome
• 证据：failure_mode_cluster:github_issue | https://github.com/ChromeDevTools/chrome-devtools-mcp/issues/2401 | Visual cursor overlay for input automation on headed Chrome

15. 安全/权限坑 · 失败模式：security_permissions: autoConnect fails against default Chrome profile on macOS after Chrome 136+ remote-debugging...

• 严重度：high
• 证据强度：source_linked
• 发现：Developers should check this security_permissions risk before relying on the project: autoConnect fails against default Chrome profile on macOS after Chrome 136+ remote-debugging hardening
• 对用户的影响：Developers may expose sensitive permissions or credentials: autoConnect fails against default Chrome profile on macOS after Chrome 136+ remote-debugging hardening
• 证据：failure_mode_cluster:github_issue | https://github.com/ChromeDevTools/chrome-devtools-mcp/issues/1830 | autoConnect fails against default Chrome profile on macOS after Chrome 136+ remote-debugging hardening

16. 安全/权限坑 · 失败模式：security_permissions: autoConnect fails on Chrome 150 stable default profile: port 9222 listens but /json/version r...

• 严重度：high
• 证据强度：source_linked
• 发现：Developers should check this security_permissions risk before relying on the project: autoConnect fails on Chrome 150 stable default profile: port 9222 listens but /json/version returns 404, DevToolsActivePort never created
• 对用户的影响：Developers may expose sensitive permissions or credentials: autoConnect fails on Chrome 150 stable default profile: port 9222 listens but /json/version returns 404, DevToolsActivePort never created
• 证据：failure_mode_cluster:github_issue | https://github.com/ChromeDevTools/chrome-devtools-mcp/issues/2283 | autoConnect fails on Chrome 150 stable default profile: port 9222 listens but /json/version returns 404, DevToolsActivePort never created

17. 安全/权限坑 · 来源证据：Hyphenated --chromeArg values dropped during daemon serialization and lazy subcommand startup

• 严重度：high
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Hyphenated --chromeArg values dropped during daemon serialization and lazy subcommand startup
• 对用户的影响：可能影响授权、密钥配置或安全边界。
• 证据：community_evidence:github | https://github.com/ChromeDevTools/chrome-devtools-mcp/issues/2406 | 来源讨论提到 node 相关条件，需在安装/试用前复核。

18. 安全/权限坑 · 来源证据：Injected input (click/fill/press_key) silently stops reaching a tab; tools still report success

• 严重度：high
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Injected input (click/fill/press_key) silently stops reaching a tab; tools still report success
• 对用户的影响：可能影响授权、密钥配置或安全边界。
• 证据：community_evidence:github | https://github.com/ChromeDevTools/chrome-devtools-mcp/issues/2199 | 来源讨论提到 macos 相关条件，需在安装/试用前复核。

19. 安全/权限坑 · 来源证据：Visual cursor overlay for input automation on headed Chrome

• 严重度：high
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Visual cursor overlay for input automation on headed Chrome
• 对用户的影响：可能影响授权、密钥配置或安全边界。
• 证据：community_evidence:github | https://github.com/ChromeDevTools/chrome-devtools-mcp/issues/2401 | 来源类型 github_issue 暴露的待验证使用条件。

20. 安全/权限坑 · 来源证据：autoConnect fails on Chrome 150 stable default profile: port 9222 listens but /json/version returns 404, DevToolsActive…

• 严重度：high
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：autoConnect fails on Chrome 150 stable default profile: port 9222 listens but /json/version returns 404, DevToolsActivePort never created
• 对用户的影响：可能影响授权、密钥配置或安全边界。
• 证据：community_evidence:github | https://github.com/ChromeDevTools/chrome-devtools-mcp/issues/2283 | 来源讨论提到 macos 相关条件，需在安装/试用前复核。

21. 安装坑 · 失败模式：installation: Persist CLI defaults for automatic daemon startup

• 严重度：medium
• 证据强度：source_linked
• 发现：Developers should check this installation risk before relying on the project: Persist CLI defaults for automatic daemon startup
• 对用户的影响：Developers may fail before the first successful local run: Persist CLI defaults for automatic daemon startup
• 证据：failure_mode_cluster:github_issue | https://github.com/ChromeDevTools/chrome-devtools-mcp/issues/2388 | Persist CLI defaults for automatic daemon startup, failure_mode_cluster:github_issue | https://github.com/ChromeDevTools/chrome-devtools-mcp/issues/2388 | Persist CLI defaults for automatic daemon startup

22. 安装坑 · 来源证据：[Task]:Is there anyone experienced who could try running this operating-system-like project? I can provide the .md file…

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：[Task]:Is there anyone experienced who could try running this operating-system-like project? I can provide the .md file, but I’m not getting it to work properl…
• 对用户的影响：可能增加新用户试用和生产接入成本。
• 证据：community_evidence:github | https://github.com/ChromeDevTools/chrome-devtools-mcp/issues/2301 | 来源讨论提到 node 相关条件，需在安装/试用前复核。

23. 安装坑 · 来源证据：navigate_page allowList semantics for delayed client-side navigations

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：navigate_page allowList semantics for delayed client-side navigations
• 对用户的影响：可能阻塞安装或首次运行。
• 证据：community_evidence:github | https://github.com/ChromeDevTools/chrome-devtools-mcp/issues/2297 | 来源讨论提到 node 相关条件，需在安装/试用前复核。

24. 配置坑 · 失败模式：configuration: Add MCP tool to configure download behavior (prompt toggle, downloads location)

• 严重度：medium
• 证据强度：source_linked
• 发现：Developers should check this configuration risk before relying on the project: Add MCP tool to configure download behavior (prompt toggle, downloads location)
• 对用户的影响：Developers may misconfigure credentials, environment, or host setup: Add MCP tool to configure download behavior (prompt toggle, downloads location)
• 证据：failure_mode_cluster:github_issue | https://github.com/ChromeDevTools/chrome-devtools-mcp/issues/2397 | Add MCP tool to configure download behavior (prompt toggle, downloads location)

25. 配置坑 · 失败模式：configuration: Feature request: safer defaults for local file, private network, and script evaluation access

• 严重度：medium
• 证据强度：source_linked
• 发现：Developers should check this configuration risk before relying on the project: Feature request: safer defaults for local file, private network, and script evaluation access
• 对用户的影响：Developers may misconfigure credentials, environment, or host setup: Feature request: safer defaults for local file, private network, and script evaluation access
• 证据：failure_mode_cluster:github_issue | https://github.com/ChromeDevTools/chrome-devtools-mcp/issues/2179 | Feature request: safer defaults for local file, private network, and script evaluation access

26. 配置坑 · 失败模式：configuration: Hyphenated --chromeArg values dropped during daemon serialization and lazy subcommand startup

• 严重度：medium
• 证据强度：source_linked
• 发现：Developers should check this configuration risk before relying on the project: Hyphenated --chromeArg values dropped during daemon serialization and lazy subcommand startup
• 对用户的影响：Developers may misconfigure credentials, environment, or host setup: Hyphenated --chromeArg values dropped during daemon serialization and lazy subcommand startup
• 证据：failure_mode_cluster:github_issue | https://github.com/ChromeDevTools/chrome-devtools-mcp/issues/2406 | Hyphenated --chromeArg values dropped during daemon serialization and lazy subcommand startup

27. 配置坑 · 失败模式：configuration: `--screenshot-max-width`/`height` are ignored for viewport screenshots

• 严重度：medium
• 证据强度：source_linked
• 发现：Developers should check this configuration risk before relying on the project: --screenshot-max-width/height are ignored for viewport screenshots
• 对用户的影响：Developers may misconfigure credentials, environment, or host setup: --screenshot-max-width/height are ignored for viewport screenshots
• 证据：failure_mode_cluster:github_issue | https://github.com/ChromeDevTools/chrome-devtools-mcp/issues/2379 | --screenshot-max-width/height are ignored for viewport screenshots, failure_mode_cluster:github_issue | https://github.com/ChromeDevTools/chrome-devtools-mcp/issues/2379 | --screenshot-max-width/height are ignored for viewport screenshots

28. 配置坑 · 来源证据：The agent attempts to use MCP-specific uids (from accessibility tree snapshots) as if they were standard HTML attribute…

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：The agent attempts to use MCP-specific uids (from accessibility tree snapshots) as if they were standard HTML attributes or valid element references in evaluat…
• 对用户的影响：可能增加新用户试用和生产接入成本。
• 证据：community_evidence:github | https://github.com/ChromeDevTools/chrome-devtools-mcp/issues/1892 | 来源讨论提到 node 相关条件，需在安装/试用前复核。

29. 能力坑 · 能力判断依赖假设

• 严重度：medium
• 证据强度：source_linked
• 发现：README/documentation is current enough for a first validation pass.
• 对用户的影响：假设不成立时，用户拿不到承诺的能力。
• 证据：capability.assumptions | https://github.com/ChromeDevTools/chrome-devtools-mcp | README/documentation is current enough for a first validation pass.

30. 运行坑 · 失败模式：runtime: `list_console_messages` misses messages logged before the server attached

• 严重度：medium
• 证据强度：source_linked
• 发现：Developers should check this runtime risk before relying on the project: list_console_messages misses messages logged before the server attached
• 对用户的影响：Developers may hit a documented source-backed failure mode: list_console_messages misses messages logged before the server attached
• 证据：failure_mode_cluster:github_issue | https://github.com/ChromeDevTools/chrome-devtools-mcp/issues/2382 | list_console_messages misses messages logged before the server attached

31. 运行坑 · 失败模式：runtime: list_network_requests misses navigation requests in tabs opened via window.open

• 严重度：medium
• 证据强度：source_linked
• 发现：Developers should check this runtime risk before relying on the project: list_network_requests misses navigation requests in tabs opened via window.open
• 对用户的影响：Developers may hit a documented source-backed failure mode: list_network_requests misses navigation requests in tabs opened via window.open
• 证据：failure_mode_cluster:github_issue | https://github.com/ChromeDevTools/chrome-devtools-mcp/issues/2395 | list_network_requests misses navigation requests in tabs opened via window.open

32. 维护坑 · 维护活跃度未知

• 严重度：medium
• 证据强度：source_linked
• 发现：未记录 last_activity_observed。
• 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。
• 证据：evidence.maintainer_signals | https://github.com/ChromeDevTools/chrome-devtools-mcp | last_activity_observed missing

• 严重度：medium
• 证据强度：source_linked
• 发现：no_demo
• 证据：downstream_validation.risk_items | https://github.com/ChromeDevTools/chrome-devtools-mcp | no_demo; severity=medium

34. 安全/权限坑 · 存在评分风险

• 严重度：medium
• 证据强度：source_linked
• 发现：no_demo
• 对用户的影响：风险会影响是否适合普通用户安装。
• 证据：risks.scoring_risks | https://github.com/ChromeDevTools/chrome-devtools-mcp | no_demo; severity=medium

35. 安全/权限坑 · 来源证据：Cannot connect to the Chrome-devtools mcp server using the claude code

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Cannot connect to the Chrome-devtools mcp server using the claude code
• 对用户的影响：可能影响授权、密钥配置或安全边界。
• 证据：community_evidence:github | https://github.com/ChromeDevTools/chrome-devtools-mcp/issues/182 | 来源讨论提到 node 相关条件，需在安装/试用前复核。

36. 安全/权限坑 · 来源证据：The agent fails to correctly interface with the chrome-devtools binary, inventing flags or failing to escape characters…

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：The agent fails to correctly interface with the chrome-devtools binary, inventing flags or failing to escape characters for the shell.
• 对用户的影响：可能影响授权、密钥配置或安全边界。
• 证据：community_evidence:github | https://github.com/ChromeDevTools/chrome-devtools-mcp/issues/1896 | 来源讨论提到 node 相关条件，需在安装/试用前复核。

37. 维护坑 · issue/PR 响应质量未知

• 严重度：low
• 证据强度：source_linked
• 发现：issue_or_pr_quality=unknown。
• 对用户的影响：用户无法判断遇到问题后是否有人维护。
• 证据：evidence.maintainer_signals | https://github.com/ChromeDevTools/chrome-devtools-mcp | issue_or_pr_quality=unknown

38. 维护坑 · 发布节奏不明确

• 严重度：low
• 证据强度：source_linked
• 发现：release_recency=unknown。
• 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。
• 证据：evidence.maintainer_signals | https://github.com/ChromeDevTools/chrome-devtools-mcp | release_recency=unknown