内容
# CI 调查员 MCP
用于调查 GitHub Actions CI 失败的已发布 MCP 服务器。
该软件包提供了以下工具：
- 列出最近失败的工作流运行
- 从日志中总结失败的运行
- 将失败的运行与之前的成功运行进行比较
- 检测分支上的不稳定作业
- 解释可能的根本原因类别
- 建议补救和验证步骤
- 报告故障趋势和 CI 健康状况
- 确定可能的回归提交/PR
- 为通知生成故障摘要
## 可用工具
### 1) 获取失败的运行
列出仓库的最近失败的工作流运行。
输入：
- `owner`（字符串，必填）：仓库所有者或组织
- `repo`（字符串，必填）：仓库名称
- `limit`（数字，选填，默认值：10，最小值：1，最大值：100）
返回：
- 带有 id、工作流名称、分支、简短提交、URL 和时间戳的失败运行数组
### 2) 总结失败
获取并总结失败的运行。
输入：
- `owner`（字符串，必填）
- `repo`（字符串，必填）
- `run_id`（数字，必填）：失败的工作流运行 ID
返回：
- 运行 ID
- 失败的作业名称
- 失败的步骤名称
- 日志摘录文本
注意：
- 尝试运行日志下载
- 备用失败作业日志
- 当日志不可用时，备用检查运行注释
### 3) 与上一次成功比较
将失败的运行与同一分支上的上一次成功运行进行比较。
输入：
- `owner`（字符串，必填）
- `repo`（字符串，必填）
- `run_id`（数字，必填）：失败的工作流运行 ID
返回：
- 失败的运行快照
- 上一次成功的运行快照（或 `null`）
- 差异字段：
- `commit_changed`
- `author_changed`
- `event_changed`
- `commits_between`（GitHub 比较 URL 或备用文本）
### 4) 检测不稳定的测试
通过分析分支上的最近完成的运行来检测不稳定的作业。
输入：
- `owner`（字符串，必填）
- `repo`（字符串，必填）
- `branch`（字符串，必填）
- `limit`（数字，选填，默认值：30，最小值：1，最大值：100）
返回：
- 仓库和分支元数据
- 分析的运行数量
- 不稳定的作业，带有通过/失败计数和不稳定性得分
### 5) 解释失败的根本原因
根据日志和备用数据对可能的失败原因进行分类。
输入：
- `owner`（字符串，必填）
- `repo`（字符串，必填）
- `run_id`（数字，必填）
返回：
- 原因类别（`test_regression`、`infra_network`、`dependency`、`timeout`、`lint_or_type`、`auth_permissions`、`unknown`）
- 置信度和支持证据行
- 失败的作业和失败的步骤
### 6) 建议修复失败
为失败的运行建议实际的补救和验证步骤。
输入：
- `owner`（字符串，必填）
- `repo`（字符串，必填）
- `run_id`（数字，必填）
返回：
- 分类类别
- 有针对性的建议
- 验证检查清单
### 7) 列出失败趋势
总结可配置时间窗口内的重复失败作业。
输入：
- `owner`（字符串，必填）
- `repo`（字符串，必填）
- `days`（数字，选填，默认值：14）
- `branch`（字符串，选填）
- `limit`（数字，选填，默认值：100）
返回：
- 选定窗口内的故障总数
- 顶级故障作业，带有出现次数和首次/最后一次看到的时间戳
### 8) 查找回归 PR 或提交
为失败的运行查找可能的回归提交和链接的 PR。
输入：
- `owner`（字符串，必填）
- `repo`（字符串，必填）
- `run_id`（数字，必填）
返回：
- 可疑提交 SHA
- 从上一次成功到失败提交的比较 URL
- 可疑 PR 元数据（如果可用）
### 9) CI 健康评分
使用通过/失败和不稳定作业信号计算分支的 CI 健康评分。
输入：
- `owner`（字符串，必填）
- `repo`（字符串，必填）
- `branch`（字符串，必填）
- `days`（数字，选填，默认值：14）
- `limit`（数字，选填，默认值：100）
返回：
- 通过/失败率
- 不稳定作业计数
- 总体健康评分（0-100）
### 10) 故障通知摘要
为警报/分类工作流生成最近故障的去重摘要。
输入：
- `owner`（字符串，必填）
- `repo`（字符串，必填）
- `interval_hours`（数字，选填，默认值：24）
- `branch`（字符串，选填）
- `limit`（数字，选填，默认值：20）
返回：
- 分组故障签名
- 出现次数
- 最新运行引用和紧凑示例摘要
## 要求
- Node.js 20+
- 环境中的 GitHub token
推荐的 token 权限：
- `actions:read`
- `checks:read`
- `contents:read`
## 使用 MCP 客户端
单独运行服务器比将其连接到 MCP 客户端更有用。
在客户端配置文件中设置 `GITHUB_TOKEN`：
```json
{
"servers": {
"ci-investigator": {
"command": "npx",
"args": ["-y", "ci-investigator-mcp"],
"env": {
"GITHUB_TOKEN": "ghp_your_token"
}
}
}
}
```
在 Windows 上，用 `cmd /c` 包装 `npx`：
```json
{
"servers": {
"ci-investigator": {
"command": "cmd",
"args": ["/c", "npx", "-y", "ci-investigator-mcp"],
"env": {
"GITHUB_TOKEN": "ghp_your_token"
}
}
}
}
```
## 故障排除
- `401` 或 `403` 错误：验证 `GITHUB_TOKEN` 和权限。
- 空或部分日志：某些工作流/日志工件可能不可用；服务器使用备用策略。
- 未找到运行：确认 `run_id`、`owner` 和 `repo` 正确。
### IDE 找不到 `node` 或 `npx`
一些 IDE（VS Code，Cursor）启动时路径有限，无法找到通过 nvm 或类似版本管理器安装的 Node.js。
运行以下命令找到完整路径：
```bash
which node && which npx
```
然后在 MCP 配置中使用完整路径：
```json
{
"servers": {
"ci-investigator": {
"command": "/Users/your-user/.nvm/versions/node/v22.14.0/bin/npx",
"args": ["-y", "ci-investigator-mcp"],
"env": {
"GITHUB_TOKEN": "your_token",
"PATH": "/Users/your-user/.nvm/versions/node/v22.14.0/bin:/usr/local/bin:/usr/bin:/bin"
}
}
}
}
```
### 许可证
ISC
