mcpField
T
troubleshooting

troubleshooting

github.com/chromedevtools开发54.4k3.3k 次安装今天更新
代码仓库

关于 troubleshooting

用于排查 Chrome DevTools MCP 服务配置与连接问题的技能，涵盖配置检查、常见错误分析、诊断命令及相关 GitHub 问题查询。

主要功能

  1. 01检查 MCP 配置文件
  2. 02分析常见连接错误
  3. 03查阅已知故障说明
  4. 04提出配置建议
  5. 05运行诊断命令
  6. 06搜索相关 GitHub 问题

适用场景

  1. 01解决 Chrome 连接失败
  2. 02排查工具缺失或受限
  3. 03调查服务启动错误

MCP 相关

该技能帮助诊断和配置 Chrome DevTools MCP 服务，包括连接设置和可用工具。

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/chromedevtools/chrome-devtools-mcp --skill troubleshooting

安装后在 Claude Code 中输入/troubleshooting确认已加载。

详细介绍

故障排除向导

你将充当故障排除向导，帮助用户配置和修复其 Chrome DevTools MCP 服务设置。当触发此技能时（例如，list_pages、new_page 或 navigate_page 执行失败，或服务无法启动），请按照以下逐步诊断流程操作：

步骤 1：查找并读取配置

首先应定位并读取 MCP 配置文件。在用户的工作区中搜索以下文件：.mcp.json、.vscode/mcp.json、gemini-extension.json 或 .gemini/settings.json（如果可访问，也包括 ~/.claude.json 等用户级文件）。

如果找到配置文件，请读取并解读，查找以下潜在问题：

  • 参数或标志不正确。
  • 缺少环境变量。
  • 在不兼容的环境中使用 --autoConnect。

只有在找不到上述任何文件时，才应请用户提供其配置文件内容。

步骤 2：判断常见连接错误

在阅读文档或建议修改配置之前，请检查错误消息是否符合以下常见模式。

错误：Could not find DevToolsActivePort

此错误与 --autoConnect 功能高度相关。这意味着 MCP 服务无法找到由正在运行且可调试的 Chrome 实例创建的文件。这不是一般性的连接失败。

首要目标是引导用户确保 Chrome 正在运行且配置正确。不要立即建议改用 --browserUrl。请严格按照以下顺序操作：

  1. 请用户确认当前正在运行正确的 Chrome 版本（例如，如果错误消息中提到 "Chrome Canary"，就确认是否正在运行该版本）。
  2. **如果用户确认 Chrome 正在运行，请指导其启用远程调试。**请明确说明网址和操作：“请在 Chrome 中打开新标签页，前往 chrome://inspect/#remote-debugging，并确认已勾选 ‘Enable remote debugging’ 复选框。”
  3. **用户确认已完成以上两步后，你接下来唯一应执行的操作是调用 list_pages 工具。**这是验证连接是否成功的最简单、最安全的方法。暂时不要重试原先更复杂的命令。
  4. **如果 list_pages 执行成功，问题即已解决。**如果仍然因相同错误而失败，则可以继续采取更高级的步骤，例如建议使用 --browserUrl 或检查沙箱问题。
症状：服务启动，但创建了新的空配置文件

如果服务成功启动，但 list_pages 返回空列表，或创建了新的配置文件而不是连接到现有的 Chrome 实例，请检查参数中是否有拼写错误。

  • **检查标志拼写错误：**例如，误写为 --autoBronnect，而不是 --autoConnect。
  • **核对配置：**确保参数与预期标志完全一致。
症状：工具缺失／仅有少量工具可用

如果服务成功启动，但只有有限的一组工具可用（例如 list_pages、list_console_messages、get_console_message、list_network_requests），很可能是 MCP 客户端启用了只读模式。

chrome-devtools-mcp 中的所有工具都标注了 readOnlyHint: true（适用于安全且不会修改状态的工具）或 readOnlyHint: false（适用于会修改浏览器状态的工具，例如 emulate、click、navigate_page）。若要使用完整的工具集，用户必须在其 MCP 客户端中关闭只读模式（例如，在 Gemini CLI 中退出“Plan Mode”，或调整客户端的工具安全设置）。

症状：扩展工具缺失或扩展无法加载

如果扩展相关工具（例如 install_extension）不可用，或加载的扩展无法正常工作：

  1. 检查是否包含 --categoryExtensions 标志：确保在 MCP 服务配置中传入此标志，以启用扩展类别工具。
其他常见错误

从工具调用失败或 MCP 初始化日志中识别其他错误消息：

  • Target closed
  • “Tool not found”（检查是否使用了 --slim，它仅启用导航、脚本执行和截图工具）。
  • 缺少 pageId：页面范围的工具需要 pageId 参数。调用 list_pages 查找活动页面 ID。
  • ProtocolError: Network.enable timed out 或 The socket connection was closed unexpectedly
  • Error [ERR_MODULE_NOT_FOUND]: Cannot find module
  • 任何沙盒或主机验证错误。
步骤 3：阅读已知问题

阅读 https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/docs/troubleshooting.md 的内容，将错误对应到已知问题。特别留意：

  • 沙盒限制（macOS Seatbelt、Linux 容器）。
  • WSL 要求。
  • --autoConnect 握手、超时和要求（需要正在运行的 Chrome 144+）。
步骤 4：制定配置

根据具体错误和用户的环境（操作系统、MCP 客户端），制定正确的 MCP 配置片段。检查用户是否需要：

  • 使用 --browser-url=http://127.0.0.1:9222 而不是 --autoConnect（例如，在 Claude Desktop 这类沙盒环境中）。
  • 在 Chrome 中启用远程调试（chrome://inspect/#remote-debugging）并接受连接提示。如果使用 --autoConnect，请让用户确认已启用此功能。
  • 添加 --logFile <absolute_path_to_log_file> 以收集调试日志供分析。
  • 如果在 Windows 上使用 Codex，增大 startup_timeout_ms（例如，设为 20000）。

如果不确定用户的配置，请让用户提供当前的 MCP 服务 JSON 配置。

步骤 5：运行诊断命令

如果问题仍不明确，请运行诊断命令直接测试服务：

  • 运行 npx chrome-devtools-mcp@latest --help，以验证安装和 Node.js 环境。
  • 如果需要更多信息，运行 NODE_DEBUG=* npx chrome-devtools-mcp@latest --logFile=/tmp/cdm-test.log 以收集详细日志。分析输出中的错误。
步骤 6：在 GitHub 上查找现有问题

如果 https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/docs/troubleshooting.md 未涵盖具体错误，请检查环境中是否有 gh（GitHub CLI）工具。如果有，请在 GitHub 仓库中搜索类似问题： gh issue list --repo ChromeDevTools/chrome-devtools-mcp --search "<error snippet>" --state all

或者，你可以建议用户前往 https://github.com/ChromeDevTools/chrome-devtools-mcp/issues 和 https://github.com/ChromeDevTools/chrome-devtools-mcp/discussions 寻求帮助。

评论

支持 Markdown