内容
# github-ops-mcp
一个提供基于 GitHub API 的运维工具的 MCP 服务器 — 问题分类、PR 审查监控、仓库健康审计和团队访问审查。专为与 [Claude Code](https://docs.anthropic.com/en/docs/claude-code) 或 Claude Desktop 配合使用而设计，它为运维团队提供了一个对话式界面，以自动化管理基于 GitHub 的工作流的繁琐任务。
## 快速开始
```bash
git clone https://github.com/avg-ape/github-ops-mcp.git
cd github-ops-mcp
python3 -m venv .venv
source .venv/bin/activate
pip install -e .
```
可选：设置 GitHub token 以提高速率限制和写入操作：
```bash
cp .env.example .env
# 编辑 .env 并添加您的 token
```
### 与 Claude Code 配合使用
将以下内容添加到您的 Claude Code MCP 配置（`~/.claude/settings.json`）：
```json
{
"mcpServers": {
"github-ops": {
"command": "/path/to/github-ops-mcp/.venv/bin/python",
"args": ["-m", "github_ops_mcp.server"]
}
}
}
```
然后询问 Claude：
- "对 pallets/flask 中的问题进行分类"
- "为 my-org/my-repo 显示 PR 审查仪表盘"
- "对 fastapi/fastapi 运行健康审计"
- "查找 my-org/backend 中 14 天未被触及的过时 PR"
## 工具
| 工具 | 描述 |
|------|-------------|
| `triage_issues` | 查找缺少标签、指派者或里程碑的问题 |
| `bulk_label_issues` | 对匹配文本筛选的问题应用标签（默认为 dry-run） |
| `stale_issue_report` | 查找 N 天内无活动的問題，按标签/指派者分组 |
| `close_resolved_issues` | 批量关闭超过 N 天的已标记问题（默认为 dry-run） |
| `pr_review_dashboard` | 按审查状态分组的开放 PR，附带等待时间 |
| `stale_pr_report` | N 天内无活动的 PR |
| `pr_check_status` | 跨所有开放 PR 的 CI/check 状态聚合 |
| `repo_health_audit` | 评分卡：分支保护、CODEOWNERS、CI、许可证、安全策略 |
| `repo_compare` | 比较多个仓库的健康审计 |
| `team_access_review` | 列出仓库或组织的用戶和权限级别 |
| `permission_audit` | 查找绕过团队的外部协作者和直接访问 |
## 架构
**GitHub 客户端（`github_client.py`）：** 基于 `httpx` 的异步 HTTP 客户端 — 而不是像 PyGitHub 这样的包装库。支持 REST 和 GraphQL 端点、通过 `Link` 头的自动分页、速率限制跟踪和结构化错误处理。
**为什么选择 httpx 而不是 PyGitHub：** 展示了对 HTTP 基础知识、异步模式和 API 设计的理解。客户端大约 120 行，恰好满足需求 — 没有框架开销。
**REST 与 GraphQL：** REST 用于写入和简单读取。GraphQL 用于复杂的查询，这些查询需要多个 REST 调用（例如，在单个请求中具有检查状态的 PR 审查）。
**Pydantic 模型（`models.py`）：** 所有工具输出都是类型化的 Pydantic 模型，具有人类可读的 `__str__` 方法。Claude 获取结构化的数据来进行推理，而不是原始的 JSON 转储。
**速率限制：** 客户端读取 `X-RateLimit-Remaining` 头，并在达到限制时显示清晰的错误消息。适用于公共仓库（60 请求/小时）或通过个人访问令牌进行身份验证（5,000 请求/小时）。
## 开发
```bash
# 安装开发依赖
pip install -e ".[dev]"
# 运行单元测试
pytest tests/ -v
# 运行集成测试（调用真实的 GitHub API）
pytest tests/ -v --integration
```
## 许可证
MIT
