JinDaGe - blacksmith-mcp MCP Details

article

README

🚀 Blacksmith MCP

Blacksmith MCP 是一个 MCP 服务器，它能将 Claude 与你的 Blacksmith CI 数据相连接。通过自然对话，你可以查询工作流运行情况、分析测试失败原因、检测不稳定测试以及监控使用情况。

🚀 快速开始

如果你已在 Chrome 中登录 Blacksmith，则无需进行配置：

# 添加到 Claude Code
claude mcp add blacksmith -- npx blacksmith-mcp

# 设置你的组织（仅需运行一次）
export BLACKSMITH_ORG="your-org-name"

MCP 会自动从 Chrome cookies 中提取你的会话信息，无需手动复制令牌。

✨ 主要特性

借助自然对话，可轻松查询工作流运行、分析测试失败、检测不稳定测试以及监控使用情况。
能自动从 Chrome cookies 中提取会话信息，避免手动复制令牌。

📦 安装指南

选项 1：Claude Code CLI

claude mcp add blacksmith -- npx blacksmith-mcp

选项 2：项目配置

在 .mcp.json 中添加以下内容：

{
  "mcpServers": {
    "blacksmith": {
      "type": "stdio",
      "command": "npx",
      "args": ["blacksmith-mcp"],
      "env": {
        "BLACKSMITH_ORG": "your-org-name"
      }
    }
  }
}

选项 3：全局安装

npm install -g blacksmith-mcp

💻 使用示例

基础用法

以下是一些与 Claude 进行对话以获取信息的示例：

调试失败的运行

> **你:** 为什么上次 CI 运行失败了？
>
> **Claude:** *使用 `list_runs(status="failure", limit=1)` 然后使用 `get_failed_tests`*
>
> 上次运行失败，有 34 个测试失败。主要问题如下：
> - **连接超时**（12 个测试） - `api/` 中的测试在连接测试数据库时超时
> - **未定义属性**（8 个测试） - 在新的暗模式代码中，`user.settings.theme` 未定义
> - **断言失败**（14 个测试） - UI 组件中的快照不匹配

查找不稳定测试

> **你:** 哪些测试不稳定？
>
> **Claude:** *使用 `get_flaky_tests(days=7, min_runs=5)`*
>
> 找到 3 个不稳定测试：
> | 测试 | 不稳定率 | 模式 |
> |------|------------|---------|
> | `should handle concurrent requests` | 40%（4/10 次运行） | 在 CI 上失败，在本地通过 |
> | `renders loading state` | 20%（2/10 次运行） | 与 setTimeout 存在竞态条件 |
> | `validates auth token` | 30%（3/10 次运行） | 间歇性网络超时 |

比较分支

> **你:** 我的 PR 是否引入了新的测试失败？
>
> **Claude:** *使用 `compare_test_runs` 比较 PR 运行与基础分支*
>
> 你的 PR 引入了 2 个新的失败：
> - `UserProfile.test.tsx`："Cannot read property 'avatar' of undefined"
> - `api/users.test.ts`：预期状态码 200，实际得到 404
>
> 5 个之前失败的测试现在通过了（不错！）。

📚 详细文档

配置

身份验证

自动（推荐）：在 Chrome 中登录 app.blacksmith.sh。MCP 会自动提取你的会话 cookie。

手动：设置 BLACKSMITH_SESSION_COOKIE 环境变量，并将其值设置为你的会话 cookie。

环境变量

| 变量 | 是否必需 | 描述 | |------|----------|-------------| | BLACKSMITH_ORG | 是 | 你的 Blacksmith 组织名称 | | BLACKSMITH_SESSION_COOKIE | 否 | 会话 cookie（如果未设置，将自动从 Chrome 中提取） |

可用工具

工作流运行

| 工具 | 描述 | |------|-------------| | list_runs | 列出带有过滤器（状态、分支、工作流、执行者、PR）的工作流运行 | | get_run | 获取运行详情，包括所有作业 | | list_jobs | 列出工作流运行的作业 | | get_job | 获取作业详情（步骤、时间、运行器信息） | | get_job_logs | 获取作业的原始日志输出 |

测试分析

| 工具 | 描述 | |------|-------------| | get_job_tests | 获取作业的所有测试结果 | | get_failed_tests | 获取带有完整错误消息的失败测试 | | get_failures_by_pattern | 按错误模式对失败进行分组（例如，"Cannot read properties"） | | compare_test_runs | 比较两次运行之间的失败情况（查找回归问题） | | get_flaky_tests | 检测间歇性失败的测试 | | get_slow_tests | 查找超过持续时间阈值的测试 | | get_test_history | 跟踪特定测试的通过/失败历史 | | get_trends | 分析趋势：持续时间、失败率、测试数量 |

使用情况与计费

| 工具 | 描述 | |------|-------------| | get_current_usage | 当前核心使用情况（活动与最大） | | get_invoice_amount | 当前计费周期的金额 | | get_usage_summary | 计费分钟数与免费额度 | | get_cache_stats | 缓存大小、按存储库的条目 | | get_cache_entries | 存储库的详细缓存条目 |

组织

| 工具 | 描述 | |------|-------------| | list_orgs | 列出可访问的组织 | | get_org_status | 组织状态（个人、已加入、区域） | | search_logs | 在所有作业中搜索日志 |

🔧 技术细节

此 MCP 使用 Blacksmith 的内部 Web API，该 API 未公开文档。该 API 是从 Blacksmith 网页应用逆向工程而来，可能会在未通知的情况下发生更改。

📄 许可证

本项目采用 MIT 许可证。

贡献

欢迎贡献代码！请先打开一个 issue 讨论提议的更改。

故障排除

会话过期

如果你看到 SESSION_EXPIRED，说明你的 Blacksmith 会话已过期。只需在 Chrome 中重新登录 app.blacksmith.sh 并重试。

Cookie 提取失败

自动提取 cookie 需要满足以下条件：

安装了 Chrome 的 macOS 系统
已在 Chrome 中登录 Blacksmith
Chrome 未使用锁定的配置文件运行

如果提取失败，请手动设置 BLACKSMITH_SESSION_COOKIE。

未设置组织

运行 list_orgs 查看可用组织，然后将 BLACKSMITH_ORG 设置为你的组织名称。

blacksmith-mcp