MCP Gh Code Review

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 -访问存储库文件和结构

*个人访问令牌（经典）：*

• repo scope-完全访问存储库

可选：

• 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 --stdio

2.Webhook服务器

接收和处理GitHub webhook事件。

地方发展：

uvicorn mcp_server.webhooks:app --reload

生产：

uvicorn mcp_server.webhooks:app --host 0.0.0.0 --port 8000 --workers 4

GitHub 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

可用工具

拉取请求工具

问题工具

系统工具

示例提示

对于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-256 HMAC验证
• 令牌安全 -从未记录，使用环境变量或秘密管理器
• 非根容器 -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 expired

403禁止：

• 检查存储库访问权限
• 验证令牌范围包括 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许可证-请参阅 许可证 了解详情。