MCP GitHub审核服务器
一个以生产为中心的模型上下文协议（MCP）服务器，用于自动化GitHub拉取请求审查、内联评论线程和智能响应。
特性
- 8个JSON-RPC工具 -5个公关工具+3个问题工具+健康检查
- Webhook集成 -带有GitHub签名验证的FastAPI端点
- 自动化测试套件 -跨工具、错误处理和webhook流的Pytest覆盖率
- 结构化日志记录 -带有速率限制跟踪和错误上下文的JSON日志
- 机器人检测 -自动识别机器人帐户并提供回复指导
快速开始
安装
使用uvx（推荐-无需安装）：
uvx --from git+https://github.com/KenkoGeek/mcp-gh-code-review mcp-gh-review或者在本地安装（Python 3.11+）：
git clone https://github.com/KenkoGeek/mcp-gh-code-review.git
cd mcp-gh-code-review
python -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"配置
cp .env.example .env
# Edit .env with your credentials
# GITHUB_TOKEN=ghp_your_token_here
# GITHUB_REPOSITORY=owner/repo必修的：
GITHUB_TOKEN-具有最低权限的GitHub个人访问令牌（见下文）GITHUB_REPOSITORY-存储库格式owner/repo（在具有GitHub远程的git存储库中运行时可选；服务器读取.git/config自动。如果两者都存在，则优先进行git检测）
GitHub令牌权限：
*细粒度个人访问令牌（推荐）：*
- 存储库权限：
- pull_requests: write -创建/更新公关评论和评论 - issues: write -在公关讨论中添加评论 - metadata: read -读取基本存储库信息 - contents: read -访问存储库文件和结构
*个人访问令牌（经典）：*
reposcope-完全访问存储库
可选：
WEBHOOK_SECRET-webhook签名验证的秘密LOG_LEVEL-日志记录级别（调试、信息、警告、错误）
用法
1.MCP客户端集成
从Claude Desktop、IDE或任何兼容MCP的客户端连接。
克劳德桌面版 (~/Library/Application Support/Claude/claude_desktop_config.json):
选项A：使用uvx（推荐）：
{
"mcpServers": {
"github-review": {
"command": "uvx",
"args": [
"--from",
"git+https://github.com/KenkoGeek/mcp-gh-code-review",
"mcp-gh-review"
],
"env": {
"GITHUB_TOKEN": "ghp_your_token_here",
"GITHUB_REPOSITORY": "owner/repo"
}
}
}
}选项B：使用本地安装：
{
"mcpServers": {
"github-review": {
"command": "/path/to/.venv/bin/python",
"args": ["-m", "mcp_server.cli", "--stdio"],
"env": {
"GITHUB_TOKEN": "ghp_your_token_here",
"GITHUB_REPOSITORY": "owner/repo"
}
}
}
}独立运行：
export GITHUB_TOKEN=ghp_your_token_here
export GITHUB_REPOSITORY=owner/repo
python -m mcp_server.cli --stdio2.Webhook服务器
接收和处理GitHub webhook事件。
地方发展：
uvicorn mcp_server.webhooks:app --reload生产：
uvicorn mcp_server.webhooks:app --host 0.0.0.0 --port 8000 --workers 4GitHub Webhook配置：
- 有效载荷URL：
https://your-domain.com/webhook - 内容类型：
application/json - 秘密：设置
WEBHOOK_SECRET在.env - 事件：拉取请求、拉取请求评论、问题评论
3.Docker部署
使用GitHub容器注册表中的预构建映像：
# MCP server
docker run -i \
-e GITHUB_TOKEN=ghp_xxx \
-e GITHUB_REPOSITORY=owner/repo \
ghcr.io/kenkogeek/mcp-gh-code-review:latest
# Webhook server
docker run -p 8000:8000 \
-e GITHUB_TOKEN=ghp_xxx \
-e GITHUB_REPOSITORY=owner/repo \
-e WEBHOOK_SECRET=your_secret \
ghcr.io/kenkogeek/mcp-gh-code-review:latest \
uvicorn mcp_server.webhooks:app --host 0.0.0.0本地构建：
docker build -t mcp-gh-review .
# Run MCP server
docker run -i \
-e GITHUB_TOKEN=ghp_xxx \
-e GITHUB_REPOSITORY=owner/repo \
mcp-gh-review
# Run webhook server
docker run -p 8000:8000 \
-e GITHUB_TOKEN=ghp_xxx \
-e GITHUB_REPOSITORY=owner/repo \
-e WEBHOOK_SECRET=your_secret \
mcp-gh-review \
uvicorn mcp_server.webhooks:app --host 0.0.0.0发展
# Python 3.11+ virtualenv recommended
python -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"
# Lint and test
ruff check src tests
pytest --cov=mcp_server --cov-report=term --cov-report=xml可用工具
拉取请求工具
| 工具 | 说明 |
|---|---|
review_pr | 全面的公关分析，包括评论、评论和帖子 |
reply_to_comment | 使用数据库ID回复内联PR评论 |
get_review_threads | 通过GraphQL获取状态为isResolved的评论线程 |
submit_pending_review | 提交具有指定事件类型的待审核评论 |
问题工具
| 工具 | 说明 |
|---|---|
list_issues | 列出所有存储库问题（自动过滤PR） |
review_issue | 通过评论和机器人/用户注释获取问题详细信息 |
reply_to_issue_comment | 对问题意见的回复 |
系统工具
| 工具 | 说明 |
|---|---|
health | 检查服务器状态和GitHub API速率限制 |
示例提示
对于pull请求审核：
- “审查PR#15并提出改进建议”
- “分析PR#23中的更改并检查安全问题”
- “PR#8中未解决的评论是什么？”
- “回复PR#12中所有未解决的意见”
- “将我的待审核提交为批准”
对于问题管理：
- “列出存储库中所有未解决的问题”
- “审查问题#10并提供反馈”
- “用状态更新回复问题#5”
- “显示所有已关闭的问题”
MCP服务器自动：
- 检测机器人评论（不会回复依赖者）
- 标识自己的评论（不会回复自己）
- 为响应提供上下文感知指导
发展
测试
pip install -e .[dev]
pytest
pytest --cov=mcp_server # With coverage代码检查
ruff check src/
mypy src/建筑
看 docs/architecture.md 查看详细的组件图和数据流。
GitHub Webhooks → FastAPI → MCP Server → GitHub REST/GraphQL APIs监控
Webhook运行状况终结点：
curl http://localhost:8000/health答复：
{
"status": "ok"
}MCP健康工具(health):
- 返回连接令牌的GitHub REST和GraphQL速率限制遥测
- 缓存的曲面计数来自
GitHubClient和GitHubGraphQLClient - 有助于决定何时限制自动化
结构化日志：
- 所有操作均已记录
structlog - JSON格式，便于解析
- 包括上下文：事件ID、参与者、动作
安全
- Webhook验证 -
X-Hub-Signature-256HMAC验证 - 令牌安全 -从未记录，使用环境变量或秘密管理器
- 非根容器 -Docker以无特权模式运行
app用户 - 输入验证 -Pydantic模型验证所有输入
- 速率限制跟踪 -监控GitHub API限制
故障排除
利率限制问题
检查电流限制：
curl http://localhost:8000/health | jq .rate_limit解决：
- 使用GitHub应用程序获得更高的限制（5000/小时vs 60/小时）
- 使用ETags启用条件请求
- 实现请求缓存
身份验证错误
401未经授权：
# Verify token has required permissions
gh auth status
# Regenerate token if expired403禁止：
- 检查存储库访问权限
- 验证令牌范围包括
repo或细粒度权限 - 确保不达到次要速率限制
Webhook问题
签名验证失败：
# Verify WEBHOOK_SECRET matches GitHub configuration
echo $WEBHOOK_SECRET
# Check webhook delivery logs in GitHub settings有效载荷验证错误：
- 确保webhook发送
application/json内容类型 - 验证有效载荷是否包括所需
action领域 - 查看GitHub webhook交付响应以了解详细信息
连接错误
网络超时：
# Test GitHub API connectivity
curl -H "Authorization: token $GITHUB_TOKEN" https://api.github.com/user解决：
- 检查防火墙/代理设置
- 验证api.github.com的DNS解析
- 启用重试逻辑（已针对网络错误实现）
日志记录和调试
启用调试日志记录：
export LOG_LEVEL=DEBUG
python -m mcp_server.cli --stdio查看结构化日志：
# Logs output to stderr in JSON format
python -m mcp_server.cli --stdio 2> debug.log
jq . debug.log # Pretty print JSON logs常见日志事件：
github_api_request-带有方法、路径和状态的API调用review_pr_start/review_pr_complete-工具调用error-上下文和GitHub错误消息失败
贡献
许可证
MIT许可证-请参阅 许可证 了解详情。