内容
# PR Review MCP Server with Multi-LLM Support & Interactive Webhook Integration
一个全面的模型上下文协议（Model Context Protocol，MCP）服务器，提供使用多个LLM（大语言模型）提供者（OpenAI、Claude、Gemini、Groq、Perplexity）进行自动化拉取请求（PR）审查，支持与GitHub和Bitbucket的集成，具有**实时Webhook处理**和**交互式AI助手命令**的功能。
## 特性
- 🤖 **多LLM支持**：OpenAI、Claude、Gemini、Groq、Perplexity
- 🔧 **多平台**：支持GitHub和Bitbucket集成
- 🖥️ **Web UI**：用户友好的PR审查界面
- 📡 **MCP服务器**：与VS Code、Cursor和其他MCP客户端兼容
- 🔍 **审查类型**：全面审查、安全审查、性能审查、风格审查
- ⚡ **实时**：即时PR分析和反馈
- 🔔 **Webhook集成**：在创建/更新时自动进行PR审查
- 💬 **交互式命令**：AI助手在PR评论中响应`/assistant`命令
- 📝 **逐提交分析**：对每个提交进行审查并提供行内评论
- 🛡️ **安全分析**：专门的安全漏洞扫描
## 先决条件
- Python 3.8+
- Git
- 您所选择的LLM提供者的API密钥
- GitHub个人访问令牌（具有`repo`和`pull_requests`权限）
- （可选）Bitbucket应用密码
- Webhook端点的公共URL（使用ngrok、cloudflared或类似工具进行本地开发）
## 快速开始
### 1. 克隆和设置
```bash
git clone <repository-url>
cd mcp-pr-review
python -m venv venv
source venv/bin/activate # 在Windows上：venv\Scripts\activate
pip install -r requirements.txt
```
### 2. 环境配置
复制示例环境文件并进行配置：
```bash
cp .env.example .env
```
使用您的API密钥编辑`.env`文件：
```env
# GitHub配置
GITHUB_TOKEN=your_github_token_here
# Bitbucket配置（可选）
BITBUCKET_USERNAME=your_bitbucket_username
BITBUCKET_APP_PASSWORD=your_bitbucket_app_password
# LLM提供者API密钥（至少添加一个）
OPENAI_API_KEY=your_openai_key_here
ANTHROPIC_API_KEY=your_claude_key_here
GOOGLE_API_KEY=your_gemini_key_here
GROQ_API_KEY=your_groq_key_here
PERPLEXITY_API_KEY=your_perplexity_key_here
# 默认LLM提供者
DEFAULT_LLM_PROVIDER=openai
```
### 3. 运行服务
**选项A：完整系统（MCP + Web UI + Webhooks）**
```bash
python scripts/run_server.py
```
**选项B：单独服务**
```bash
# 仅MCP服务器
python src/mcp_server.py
# 仅Web UI
python ui/app.py
# 仅Webhook服务器
python bitbucket_webhook_server.py # 端口8050
python github_webhook_server.py # 端口8051
```
这将启动：
- ✅ MCP服务器（标准输入输出模式）
- ✅ Web UI在 http://localhost:8080
- ✅ Bitbucket Webhook在 http://localhost:8050/bitbucket-webhook
- ✅ GitHub Webhook在 http://localhost:8051/github-webhook
### 4. Webhook设置
#### 本地开发
```bash
# 使用cloudflared公开暴露webhooks
cloudflared tunnel --url http://localhost:8050 # 对于Bitbucket
cloudflared tunnel --url http://localhost:8051 # 对于GitHub
```
#### Bitbucket Webhook配置
1. 转到您的Bitbucket仓库 → 设置 → Webhooks
2. 添加Webhook，URL为：`https://your-domain.com/bitbucket-webhook`
3. 选择以下事件：
- `pullrequest:created`
- `pullrequest:updated`
- `pullrequest:comment_created`
- `pullrequest:comment_updated`
#### GitHub Webhook配置
1. 转到您的GitHub仓库 → 设置 → Webhooks
2. 添加Webhook，URL为：`https://your-domain.com/github-webhook`
3. 选择以下事件：
- `pull_request`（打开、同步、重新打开）
- `issue_comment`（创建、编辑）
## 使用
### 1. 自动Webhook审查
一旦配置了webhooks，系统会自动：
- **审查新创建的PR**
- **重新审查更新了新提交的PR**
- **逐个分析每个提交**并提供行内评论
- **发布一般和行内反馈**
### 2. 交互式AI助手命令
在PR评论中使用以下命令与AI助手互动：
#### 基本命令
```
/assistant
```
触发对整个PR的全面重新审查
#### 获取建议
```
/assistant suggestion
/assistant suggestion for error handling
/assistant suggestion optimize performance
```
#### 解释更改
```
/assistant explain
/assistant explain the database changes
/assistant explain why this approach was chosen
```
#### 安全分析
```
/assistant security
```
#### 可用响应类型
- **🤖 全面PR审查**：带有行内评论的完整重新分析
- **💡 代码建议**：针对性的改进建议
- **📖 更改解释**：对更改的详细解释
- **🔒 安全分析**：安全漏洞评估
### 3. Web UI
1. 打开 http://localhost:8080
2. 选择仓库提供者（GitHub/Bitbucket）
3. 选择LLM提供者
4. 输入仓库详细信息：
- **所有者**：`microsoft`（对于microsoft/vscode）
- **仓库**：`vscode`
- **PR编号**：`123`
5. 点击“审查拉取请求”
### 4. MCP集成（VS Code/Cursor）
将其添加到您的MCP配置中：
**VS Code** (`.vscode/settings.json`):
```json
{
"mcpServers": {
"pr-review-server": {
"command": "python",
"args": ["src/mcp_server.py"],
"cwd": "/path/to/mcp-pr-review",
"env": {
"GITHUB_TOKEN": "your_github_token",
"OPENAI_API_KEY": "your_openai_key"
}
}
}
}
```
**Cursor** (`mcp.json`):
```json
{
"mcpServers": {
"pr-review-server": {
"command": "python",
"args": ["src/mcp_server.py"],
"cwd": "/path/to/mcp-pr-review",
"env": {
"GITHUB_TOKEN": "your_github_token",
"OPENAI_API_KEY": "your_openai_key"
}
}
}
}
```
## 项目结构
```
mcp-pr-review/
├── README.md
├── requirements.txt
├── .env.example
├── bitbucket_webhook_server.py # Bitbucket webhook监听器
├── github_webhook_server.py # GitHub webhook监听器
├── config/
│ ├── settings.py
│ └── llm_providers.json
├── src/
│ ├── mcp_server.py # 主MCP服务器
│ ├── models/
│ │ ├── pr_data.py # PR数据模型
│ │ └── review_result.py # 审查结果模型
│ ├── providers/ # LLM提供者实现
│ │ ├── base_provider.py
│ │ ├── openai_provider.py
│ │ ├── claude_provider.py
│ │ └── ...
│ ├── services/ # 核心服务
│ │ ├── llm_service.py
│ │ ├── github_service.py
│ │ ├── bitbucket_service.py
│ │ ├── base_repo_service.py
│ │ ├── repo_service_factory.py
│ │ └── config_service.py
│ └── utils/
│ └── logger.py
├── ui/
│ ├── app.py # FastAPI web界面
│ ├── templates/
│ └── static/
└── scripts/
└── run_server.py # 服务器启动器
```
## 审查类型与特性
### 自动审查特性
- **逐提交分析**：每个提交单独审查
- **行内评论**：对代码行的具体建议
- **一般评论**：整体PR评估
- **多文件支持**：跨所有更改文件进行审查
### 审查类型
- **全面**：涵盖所有方面的完整代码审查
- **安全**：关注漏洞和安全最佳实践
- **性能**：分析性能影响和优化
- **风格**：代码风格、一致性和最佳实践
### 交互式特性
- **命令识别**：在评论中响应`/assistant`命令
- **上下文感知**：理解特定请求（例如，“解释数据库更改”）
- **线程回复**：回复以评论回复的形式出现
- **多平台**：在GitHub和Bitbucket上均可使用
## API端点
### Webhook端点
- `POST /bitbucket-webhook` - 处理Bitbucket PR和评论事件
- `POST /github-webhook` - 处理GitHub PR和评论事件
### Web UI端点
- `GET /` - 主要审查界面
- `POST /api/review` - 手动PR审查API
- `GET /api/providers` - 列出可用的LLM提供者
- `GET /debug/providers` - 调试提供者信息
## 获取API密钥
### GitHub令牌
1. 转到GitHub → 设置 → 开发者设置 → 个人访问令牌
2. 生成新令牌（经典）
3. 选择权限：`repo`（完全仓库访问）、`pull_requests`
4. 将令牌复制到您的`.env`文件中
### LLM提供者密钥
- **OpenAI**：https://platform.openai.com/api-keys
- **Anthropic（Claude）**：https://console.anthropic.com/
- **Google（Gemini）**：https://ai.google.dev/
- **Groq**：https://console.groq.com/keys
- **Perplexity**：https://www.perplexity.ai/settings/api
### Bitbucket应用密码（可选）
1. Bitbucket → 个人设置 → 应用密码
2. 创建应用密码，权限为：仓库（读取）、拉取请求（读/写）
3. 使用您的Bitbucket用户名（而不是电子邮件）+ 应用密码
## 故障排除
### 常见问题
1. **“没有名为'config'的模块”错误**：
```bash
# 确保您在项目根目录
cd mcp-pr-review
python scripts/run_server.py
```
2. **Webhook未接收事件**：
- 验证Webhook URL是否可公开访问
- 检查仓库设置中的Webhook事件配置
- 查看Webhook服务器日志以获取错误信息
3. **助手命令无法工作**：
- 确保在Webhook配置中启用了评论事件
- 验证评论以`/assistant`开头
- 检查身份验证凭据
4. **GitHub 401 未授权**：
- 验证您的GitHub令牌是否具有`repo`和`pull_requests`权限
- 检查令牌是否已过期
5. **Bitbucket 401 未授权**：
- 使用Bitbucket用户名（而不是电子邮件）
- 使用应用密码（而不是登录密码）
- 确保应用密码具有仓库和PR权限
### 调试命令
```bash
# 测试导入
python -c "from src.services.llm_service import LLMService; print('✓ 导入正常')"
# 检查提供者
curl http://localhost:8080/api/providers
# 调试端点
curl http://localhost:8080/debug/providers
# 测试Webhook端点
curl -X POST http://localhost:8050/bitbucket-webhook -H "Content-Type: application/json" -d '{}'
curl -X POST http://localhost:8051/github-webhook -H "Content-Type: application/json" -d '{}'
```
### 所需权限
#### GitHub令牌权限
- `repo` - 完全仓库访问
- `pull_requests` - PR读/写访问
#### Bitbucket应用密码权限
- 仓库：读取
- 拉取请求：读取、写入
## 开发
### 添加新的LLM提供者
1. 在`src/providers/`中创建提供者类
2. 实现`BaseProvider`接口
3. 添加到`LLMService._initialize_providers()`
4. 更新配置文件
### 添加新的助手命令
1. 更新`parse_assistant_command()`函数
2. 添加新的命令处理函数
3. 更新帮助文本和文档
### 扩展Webhook功能
- 在Webhook处理程序中添加新的事件类型
- 扩展仓库服务类以支持额外的API端点
- 添加新的审查类型或分析方法
## 示例工作流
### 工作流1：自动审查
1. 开发者创建/更新PR
2. Webhook触发自动审查
3. 系统发布一般评论和行内建议
4. 开发者即时收到反馈
### 工作流2：交互式助手
1. 开发者评论：`/assistant suggestion for error handling`
2. 助手分析PR，重点关注错误处理
3. 助手回复具体建议
4. 开发者可以提出后续问题
### 工作流3：安全审查
1. 开发者评论：`/assistant security`
2. 助手进行安全重点分析
3. 助手报告潜在漏洞
4. 开发者解决安全问题
## 贡献
1. Fork该仓库
2. 创建功能分支
3. 进行更改
4. 如果适用，添加测试
5. 使用ngrok/cloudflared测试Webhook功能
6. 提交拉取请求
## 许可证
MIT许可证 - 详见LICENSE文件
## 支持
- **问题**：在GitHub上创建一个问题
- **讨论**：使用GitHub讨论进行提问
- **文档**：查看`docs/`文件夹以获取详细指南
- **Webhook测试**：使用ngrok或cloudflared进行本地Webhook测试
**注意**：该项目需要至少一个LLM提供者API密钥才能正常运行。对于Webhook功能，您还需要可公开访问的URL。建议首先使用OpenAI以获得最可靠的体验，然后根据需要添加其他提供者和Webhook集成。
Sources
[1] base_repo_service.py https://ppl-ai-file-upload.s3.amazonaws.com/web/direct-files/attachments/81348741/9928a771-5197-4379-a7c3-155d3c647bcb/base_repo_service.py
[2] bitbucket_service.py https://ppl-ai-file-upload.s3.amazonaws.com/web/direct-files/attachments/81348741/1e7d4876-9ef7-43cd-9d99-82c91cd08fc5/bitbucket_service.py
[3] bitbucket_webhook_server.py https://ppl-ai-file-upload.s3.amazonaws.com/web/direct-files/attachments/81348741/5137e542-49d9-4e21-90db-0b5dc396c475/bitbucket_webhook_server.py
MCP 市场
