devicecloud

devicecloud-mcp

无需打开仪表板，即可诊断失败的 DeviceCloud 运行，让 Agent 帮你修复问题。

当 DeviceCloud 运行在 CI 中失败时，失败原因、失败截图和日志都藏在 Web 仪表板里。这个服务会将所有信息直接拉取到你的编辑器中，让 AI 助手（Claude Code、Cursor、Claude Desktop 等）读取证据、找到根本原因，并修复工作流或应用代码。提交后，CI 会重新运行，而仪表板仍然不用打开。

DeviceCloud 是一个用于在真实设备上运行 Maestro 工作流的平台。CI 会触发运行；这个服务则用于调试失败的运行。

它可以让助手：

• 一次调用即可诊断运行：提供失败的工作流、失败原因、失败截图路径，以及可供后续处理的通过／失败／不稳定摘要
• 评估套件健康状况：在指定时间范围内，将每个工作流分类为健康、不稳定、故障或回归，让你知道应该优先修复什么
• 列出最近的上传记录，并按名称（提交消息 + 短 SHA）或日期筛选
• 查看任意上传中每个工作流的状态和 failReason
• 获取 JUnit XML 报告
• 下载并自动解压 HTML 报告（并突出显示失败截图）
• 将原始构建产物（日志、截图、视频）下载为 zip 文件
• 通过每个工作流的通过率分析，识别不稳定与确实故障的工作流
• 深入查看特定工作流文件的运行历史

该服务以只读方式访问 DeviceCloud REST API：不依赖 dcd CLI，Agent 执行的任何操作都不会触发计费运行。触发和重新运行测试由 CI 负责；取消运行则需在仪表板中操作。

安装

需要 Node.js 22+——使用 node --version 检查。无需单独安装；该服务通过 npx 按需运行。

将以下内容添加到 MCP 客户端配置中：

{
  "mcpServers": {
    "devicecloud": {
      "command": "npx",
      "args": ["-y", "devicecloud-mcp"],
      "env": {
        "DEVICE_CLOUD_API_KEY": "<your-key>"
      }
    }
  }
}

前往 console.devicecloud.dev/settings 获取 API 密钥。

Claude Code：使用一条命令添加

无需编辑 JSON——一步即可注册服务：

claude mcp add devicecloud --env DEVICE_CLOUD_API_KEY=<your-key> -- npx -y devicecloud-mcp

添加 -s user，即可在每个项目中使用，而不仅限于当前项目。

配置助手

上方的配置块适用于所有客户端；只有文件位置不同。

Claude Code（项目级，.mcp.json）

将以下内容添加到你希望提供这些工具的任意项目根目录中的 .mcp.json 文件：

{
  "mcpServers": {
    "devicecloud": {
      "command": "npx",
      "args": ["-y", "devicecloud-mcp"],
      "env": {
        "DEVICE_CLOUD_API_KEY": "${DEVICE_CLOUD_API_KEY}"
      }
    }
  }
}

然后从你的 shell 配置文件中导出密钥，这样 Claude Code 的子进程就能继承它：

# ~/.zshrc or ~/.bashrc
export DEVICE_CLOUD_API_KEY="<your-key>"

只在交互式 shell 中设置还不够；Claude Code 会在自己的环境中启动 MCP，因此变量必须设置在配置文件中。

Claude Code（用户级，~/.claude.json）

如果你希望所有项目都能使用，而非仅限单个项目，请在 ~/.claude.json 的 mcpServers 下添加相同的 devicecloud 配置块。

Claude Desktop

编辑 ~/Library/Application Support/Claude/claude_desktop_config.json（macOS）或 %APPDATA%\Claude\claude_desktop_config.json（Windows）。保存后重启 Claude Desktop；服务连接后，聊天输入框中会出现工具图标。

Cursor

添加到 ~/.cursor/mcp.json（全局）或项目根目录下的 .cursor/mcp.json（项目级）。

Windsurf

编辑 ~/.codeium/windsurf/mcp_config.json。

其他兼容 MCP 的客户端

任何支持 stdio MCP 服务的客户端都使用相同的 { command, args, env } 格式。请查阅客户端文档，了解配置文件的位置。

注意： OpenAI 产品（ChatGPT、Codex、Assistants API）使用自己的工具协议，不支持 MCP 服务。

验证

重启助手后：

List recent DeviceCloud uploads, limit 3.

你应该会看到包含 uploads 数组的 JSON 格式响应。如果看到的是 DEVICE_CLOUD_API_KEY env var is required，说明变量没有传递到启动的进程中；请确认已从 shell 配置文件中导出该变量（而不只是设置在当前 shell 中）。

可用工具

工具	用途
diagnose_run	从这里开始。 一次调用即可对某次运行进行分诊（uploadId 或 name）：按流程合并重试结果，并返回失败流程及其失败原因、耗时和自动下载的失败截图路径，同时提供通过／失败／不稳定汇总和建议的后续步骤。设置 includeReport: false 可跳过截图下载；outputDir 用于设置报告解压位置（默认为 /tmp）。
suite_health	在回溯时间窗口内将每个流程分类为健康、不稳定、故障或回归，并按问题严重程度从高到低排序，方便你在深入排查前判断是否值得修复失败。回归（之前通过、近期开始失败）会排在最前面。筛选条件与 list_flow_analytics 相同（platform、appId、days、startDate、endDate、tags）。
list_uploads	列出近期上传记录。可按 name（* 通配符）、from、to、limit、offset 筛选。
get_upload_status	整体状态 + 每项测试的状态、耗时、failReason。提供 uploadId 或 name。
get_results	某次上传的流程结果行：id、test_file_name、status、fail_reason、duration_seconds、retry_of。可选的客户端 status 筛选器。
get_junit_report	获取某次上传的原始 JUnit XML。
get_html_report	下载并自动解压 HTML 报告。返回解压目录和文件清单，并突出显示 failureScreenshots[]（这是最有助于调试的材料）。
download_artifacts	原始材料（日志、截图、视频）的 ZIP 文件。results: "FAILED"（默认）或 "ALL"。默认保存到 /tmp；不会自动解压。
list_flow_analytics	在回溯时间窗口内（默认 14 天）按流程统计通过率、运行次数和平均耗时。可用于区分不稳定流程和确实故障的流程。
get_flow_runs	查看某个流程文件的单次运行历史（必须提供 fileName）。返回状态、耗时、failReason 以及每次运行所属的 uploadId。可在使用 list_flow_analytics 后深入检查特定流程。

上传命名约定

上传通常以触发它们的提交或构建命名。常见约定是包含短 SHA：

fix(login): handle expired session (a1b2c3d4)

使用 name = "*a1b2c3d4*" 筛选，即可查找特定提交的所有上传记录。通配符是 *，不是 %。

上传记录存在与否

通过 CLI、CI 步骤、GitHub Action 或直接调用 API 触发运行时，DeviceCloud 会创建上传记录。某个提交是否有上传记录，完全取决于你的 CI 设置。如果 list_uploads 没有返回你预期的 SHA 对应记录，可能是该提交没有触发运行。

故障排除

• DEVICE_CLOUD_API_KEY env var is required：衍生 MCP 无法读取该变量。请在 ~/.zshrc / ~/.bashrc 中导出该变量，然后重启助手。
• unzip failed（来自 get_html_report）：缺少 unzip 二进制文件或该文件崩溃。使用 brew install unzip 安装（macOS 自带；Linux 通常也自带）。
• HTTP 401 / 403：API 密钥错误或已撤销。请前往 console.devicecloud.dev/settings 重新生成。
• 你的 SHA 对应的 list_uploads 结果为空：该提交可能没有触发运行。请参阅上文“上传记录存在与否”。