# 🔍 MCP-CodeReviewer

> **基于 MCP 协议的三层漏斗式 AI 代码审查引擎**
> 通过确定性静态分析与动态模型路由，在保证审查深度的同时降低 70%+ 的 LLM Token 消耗。

[![Python 3.11+](https://img.shields.io/badge/Python-3.10+-blue.svg)](https://python.org)
[![MCP Protocol](https://img.shields.io/badge/MCP-Protocol-green.svg)](https://modelcontextprotocol.io)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)

---

## 🏗️ 架构

```
PR 触发 → GitHub Actions
  → git diff (宿主机) → Docker 容器
    → ci_runner.py
      → 白名单代码提取 + 正则函数提取
      → RAG 规范检索 (独立降级)
      → 影响面雷达 ripgrep (独立降级)
      → Phase3 Prompt 拼装
      → LLM 审查 (deepseek-v4-flash)
      → 三级防御 L1/L2/L3 → GitHub 行级评论 (含 Suggestion)
      → ReviewMetrics 落盘 → upload-artifact
```

## 🚀 快速开始

### 1. 安装

```bash
git clone <repo-url>
cd mcp-code-reviewer
pip install -r requirements.txt
```

### 2. Mock 模式（无需 API Key）

```bash
python orchestrator.py --mock
```

### 3. 真实审查

```bash
export DEEPSEEK_API_KEY=***
python orchestrator.py
```

### 4. 接入 GitHub PR

```bash
# 复制 workflow 到目标仓库
cp .github/workflows/ai-review.yml <target-repo>/.github/workflows/

# 配置 Secrets: DEEPSEEK_API_KEY
# 配置 Actions 权限: Read and write
# 创建 PR，自动触发审查
```

详见 [DEPLOYMENT_GUIDE.md](DEPLOYMENT_GUIDE.md)

## 📁 项目结构

```
├── mcp_server.py          # MCP Server (3 Tools)
├── orchestrator.py        # MCP Client + Prompt 工程
├── ci_runner.py           # CI/CD 桥梁 + 三级防御
├── rag_engine.py          # 轻量 RAG (SQLite)
├── impact_analyzer.py     # 影响面雷达 (ripgrep)
├── metrics.py             # ReviewMetrics 黑匣子
├── Dockerfile             # 生产级镜像
├── scripts/
│   └── aggregate_metrics.py  # Metrics 聚合分析
└── test_cases/            # 测试用例
```

## 🛡️ 三级防御

| 级别 | 方法 | 防护目标 |
|------|------|----------|
| L1 | unidiff 行号映射 O(1) 精确匹配 | 防 LLM 幻觉原代码 |
| L2 | 物理字符串切片提取缩进 | 防正则跨行漏洞 |
| L3 | AST 宽容预检 + 补 pass | 防破坏性提交 |

校验失败不丢弃 issue → 降级为纯文本警告评论。

## 🧪 测试

```bash
python test_static_analysis.py     # 15 用例 ✅
python test_complexity_router.py   # 9 用例 ✅
python eval_quality.py             # LLM 质量评估 (30 bugs)
```

## 📊 可观测性

每次审查自动生成 `review_metrics.json`，包含 30+ 指标：

- 管线各阶段耗时 (RAG/雷达/LLM)
- 三级防御 L1/L2/L3 通过/失败计数
- Suggestion 成功率
- RAG 降级率

```bash
# 本地聚合分析
python scripts/aggregate_metrics.py ./downloaded_metrics/
```

## 🔧 技术栈

| 组件 | 技术 |
|------|------|
| MCP Server | Python + mcp SDK + FastAPI |
| 静态分析 | ast.NodeVisitor |
| Diff 解析 | unidiff |
| 影响面分析 | ripgrep |
| RAG | SQLite + numpy |
| LLM Gateway | litellm |
| 容器化 | Docker (python:3.11-slim) |
| CI/CD | GitHub Actions |

## 📝 技术债

见 [TECH_DEBT.md](TECH_DEBT.md)

## License

MIT