Blacksmith

Blacksmith MCP

一个将 Claude 连接到你的 Blacksmith CI 数据的 MCP 服务。查询工作流运行记录、分析测试失败、检测不稳定测试并监控用量——全部通过自然对话完成。

为什么选择它？

调试 CI 失败通常需要在多个页面间点击仪表板、复制运行 ID 并拼凑信息。有了这个 MCP，你只需提问：

• “上一次 CI 运行为什么失败了？”
• “本周哪些测试不稳定？”
• “比较 main 和我的 PR 之间的测试失败情况。”
• “什么占用了最多的缓存空间？”

Claude 会处理 API 调用，并为你提供可执行的见解。

快速开始

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

# Add to Claude Code
claude mcp add blacksmith -- npx blacksmith-mcp

# Set your org (run once)
export BLACKSMITH_ORG="your-org-name"

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

安装

选项 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

配置

身份验证

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

手动： 将会话 Cookie 值设置为 BLACKSMITH_SESSION_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	搜索所有作业中的日志

对话示例

调试失败的运行

你： 上一次 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%（10 次运行中 4 次）	在 CI 中失败，在本地通过
renders loading state	20%（10 次运行中 2 次）	与 setTimeout 有竞争条件
validates auth token	30%（10 次运行中 3 次）	间歇性网络超时

比较分支

你： 我的 PR 是否引入了新的测试失败？

Claude： 使用 compare_test_runs 比较 PR 运行结果与基础分支

你的 PR 引入了 2 个新失败：

• UserProfile.test.tsx：“Cannot read property 'avatar' of undefined”
• api/users.test.ts：预期为 200，实际为 404

之前失败的 5 个测试现在通过了（不错！）。

开发

# Install dependencies
pnpm install

# Build
pnpm build

# Development mode (watch)
pnpm dev

# Test with MCP Inspector
npx @modelcontextprotocol/inspector node dist/index.js

故障排除

会话已过期

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

Cookie 提取失败

自动提取 Cookie 需要：

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

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

未设置组织

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

API 说明

此 MCP 使用 Blacksmith 的内部 Web API，该 API 未公开文档。该 API 是通过逆向分析 Blacksmith Web 应用获得的，可能会在不另行通知的情况下发生变化。

许可证

MIT

参与贡献

欢迎贡献！请先提交 issue，讨论拟议的更改。