Chrome DevTools MCP 的…

在 Chrome DevTools MCP 服务器启动失败、连接失败或页面工具报错时，用于定位配置、参数、环境和已知问题并给出修复方案。

适用场景

解决思路

1. 首先在工作区定位并读取 MCP 配置文件：搜索 `.mcp.json`、`gemini-extension.json`、`.claude/settings.json`、`.vscode/launch.json` 或 `.gemini/settings.json`。
2. 如果找到配置文件，读取并解释它，以识别潜在问题，例如：参数或标志错误、缺失环境变量、在不兼容环境中使用 `--autoConnect`。
3. 如果找不到这些文件，才要求用户提供其配置文件内容。
4. 在阅读文档或建议配置更改前，先检查错误消息是否匹配常见连接错误模式。
5. 如果错误是 `Could not find DevToolsActivePort`：它是 `--autoConnect` 特有的错误，表示 MCP server 找不到由运行中可调试 Chrome 实例创建的文件，不是通用连接失败；不要立即建议切换到 `--browserUrl`。
6. 针对 `Could not find DevToolsActivePort`，先让用户确认正确 Chrome 版本（例如错误提到 Chrome Canary）正在运行。
7. 如果用户确认 Chrome 正在运行，指示用户启用远程调试：打开新标签页，导航到 `chrome://inspect/#remote-debugging`，并确保勾选 “Enable remote debugging”。
8. 用户确认以上两步后，下一步只调用 `list_pages` 工具，用最简单安全的方式验证连接是否成功；不要重试原来的复杂命令。
9. 如果 `list_pages` 成功，问题解决；如果仍以相同错误失败，再进入高级步骤，例如建议 `--browserUrl` 或检查沙箱问题。
10. 如果 server 启动成功但 `list_pages` 返回空列表或创建新 profile，而不是连接现有 Chrome：检查参数拼写。
11. 检查 flag 拼写，例如 `--autoBronnect` 而不是 `--autoConnect`。
12. 验证配置，确保参数完全匹配预期标志。
13. 如果 server 启动成功但只有有限工具子集（例如 `list_pages`、`get_console_message`、`lighthouse_audit`、`take_heapsnapshot`）：这可能是 MCP 客户端强制只读模式。
14. 说明 `chrome-devtools-mcp` 中所有工具都标注为 `readOnlyHint: true`（安全、非修改工具）或 `readOnlyHint: false`（会修改浏览器状态的工具，如 `emulate`、`click`、`navigate_page`）。
15. 要访问完整工具集，用户必须在 MCP 客户端禁用只读模式（例如退出 Gemini CLI 中的 “Plan Mode” 或调整客户端的工具安全设置）。
16. 如果扩展相关工具（如 `install_extension`）不可用，或加载的扩展不工作：检查 `--categoryExtensions` 标志，确保在 MCP server 配置中传入它以启用扩展类别工具。
17. 确保 MCP server 配置为启动 Chrome，而不是连接已有实例：Chrome 149 之前无法在连接已有实例（`--auto-connect`、`--browserUrl`）时加载扩展。
18. 从失败的工具调用或 MCP 初始化日志中识别其他常见错误：`Target closed`。
19. 识别 “Tool not found”（检查是否使用 `--slim`，它只启用导航和截图工具）。
20. 识别缺失 `pageId`：页面作用域工具需要 `pageId` 参数；调用 `list_pages` 查找活动页面 ID。
21. 识别 `ProtocolError: Network.enable timed out` 或 `The socket connection was closed unexpectedly`。
22. 识别 `Error [ERR_MODULE_NOT_FOUND]: Cannot find module`。
23. 识别任何沙箱或主机验证错误。
24. 读取 `https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/docs/troubleshooting.md`，将错误映射到已知问题。
25. 阅读已知问题时特别注意：沙箱限制（macOS Seatbelt、Linux 容器）、WSL 要求、`--autoConnect` 握手、超时和要求（需要运行 Chrome 144+）。
26. 基于确切错误和用户环境（OS、MCP 客户端）制定正确的 MCP 配置片段。
27. 检查是否需要传 `--browser-url=http://127.0.0.1:9222` 而不是 `--autoConnect`（例如在 Claude Desktop 等沙箱环境中）。
28. 检查是否需要让用户在 Chrome 中启用远程调试（`chrome://inspect/#remote-debugging`）并接受连接提示；如果使用 `--autoConnect`，要求用户验证它已启用。
29. 检查是否需要添加 `--logFile <absolute_path_to_log_file>` 以捕获调试日志用于分析。
30. 检查是否需要在 Windows 上使用 Codex 时增加 `startup_timeout_ms`（例如 20000）。
31. 如果不确定用户配置，要求用户提供当前 MCP server JSON 配置。
32. 如果问题仍不清楚，运行诊断命令直接测试 server：运行 `npx chrome-devtools-mcp@latest --help` 验证安装和 Node.js 环境。
33. 如果需要更多信息，运行 `DEBUG=* npx chrome-devtools-mcp@latest --logFile=/tmp/cdm-test.log` 捕获详细日志，并分析输出中的错误。
34. 如果 troubleshooting 文档未覆盖特定错误，检查环境中是否有 `gh`（GitHub CLI）工具。
35. 如果有 `gh`，搜索 GitHub 仓库中类似 issue：`gh issue list --repo ChromeDevTools/chrome-devtools-mcp --search "<error snippet>" --state all`。
36. 或者建议用户查看 `https://github.com/ChromeDevTools/chrome-devtools-mcp/issues` 和 `https://github.com/ChromeDevTools/chrome-devtools-mcp/discussions` 寻求帮助。

适用边界 · 注意事项

• 问题与 Chrome DevTools MCP 无关，或不是 `list_pages`、`new_page`、`navigate_page` 失败、server 初始化失败等场景时，不要使用此流程。
• 当前环境没有 Chrome DevTools MCP、Chrome、Node/npx，或无法访问 MCP 配置/日志时，此流程无法完整执行。
• 用户无法配合确认 Chrome 运行状态、启用远程调试、提供配置或运行诊断命令时，应先解决这些前提。