mcpField
T
troubleshooting

troubleshooting

github.com/gsmlg-dev开发037 次安装3 周前更新
代码仓库

关于 troubleshooting

troubleshooting 是用于排查 Chrome DevTools MCP 服务配置与连接问题的诊断技能，面向遇到工具缺失、服务启动或浏览器连接故障的用户。它按配置检查、错误分类、文档查询和诊断命令逐步处理。

主要功能

  1. 01查找并解读 MCP 配置文件
  2. 02按常见错误模式分流排查
  3. 03核对已知问题与环境要求
  4. 04生成适用的配置片段
  5. 05运行诊断命令并查找相关议题

适用场景

  1. 01排查 DevToolsActivePort 错误
  2. 02诊断服务连接到空白 Chrome 配置
  3. 03处理工具数量受限或扩展工具缺失
  4. 04收集日志并搜索未解决问题

MCP 相关

该技能帮助用户配置和排查 Chrome DevTools MCP 服务，并检查 MCP 客户端的只读模式及服务器参数。

安装

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

$npx skills add https://github.com/gsmlg-dev/code-agent --skill troubleshooting

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

详细介绍

故障排查向导

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

步骤 1：查找并读取配置

首先应查找并读取 MCP 配置文件。在用户的工作区中搜索以下文件：.mcp.json、gemini-extension.json、.claude/settings.json、.vscode/launch.json 或 .gemini/settings.json。

如果找到配置文件，请读取并分析，以找出潜在问题，例如：

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

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

步骤 2：排查常见连接错误

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

错误：Could not find DevToolsActivePort

此错误与 --autoConnect 功能密切相关。它表示 MCP 服务找不到由正在运行且可调试的 Chrome 实例创建的文件。这不是一般性的连接失败。

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

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

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

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

如果服务成功启动，但只能使用数量有限的一部分工具（例如 list_pages、get_console_message、lighthouse_audit、take_heapsnapshot），这很可能是因为 MCP 客户端启用了只读模式。

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

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

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

  1. 检查是否包含 --categoryExtensions 标志：确保在 MCP 服务配置中传入此标志，以启用扩展类别工具。
  2. 确保 MCP 服务配置为启动 Chrome，而非连接到某个实例：Chrome 149 之前的版本在连接到现有实例（--auto-connect、--browserUrl）时无法加载扩展。
其他常见错误

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

  • Target closed
  • "Tool not found"（检查是否使用了 --slim，它只会启用导航和截图工具）。
  • 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 环境。
  • 如果需要更多信息，运行 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