# MCP Code Review Server

一个基于 MCP (Model Context Protocol) 的代码审查工具，帮助前端开发者在迭代结束后自动生成详细的代码 Review 文档（HTML 格式），方便在小组内分享和讲解代码改动。

## 功能特性

- 🔍 **分支对比**: 对比开发分支与目标分支（如 main/master/develop）的代码差异
- 🔗 **Commit Hash 模式**: 支持指定起始 commit hash，无需目标分支即可获取变更
- 👤 **作者筛选**: 根据 Git 提交作者筛选出你自己的改动（多人协作场景下非常有用）
- 📊 **智能分析**: 自动分析代码变更类型、复杂度、关键改动点
- 📋 **文件功能描述**: 通过 LLM 根据文件路径批量生成文件功能描述（50字以内），展示在报告中
- 📄 **HTML 报告**: 生成美观的 HTML 格式 Review 文档，包含代码差异高亮
- 📋 **提交时间线**: 展示完整的提交记录
- 🚫 **智能过滤**: 自动排除图片、字体等二进制资源文件，以及无实际代码差异的文件

## 安装

```bash
# 克隆或进入项目目录
cd mcp-xl-code-review

# 安装依赖
npm install

# 构建项目
npm run build
```

## 配置 MCP Server

### 在 Claude Desktop 中配置

编辑 Claude Desktop 配置文件：

**macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
**Windows**: `%APPDATA%\Claude\claude_desktop_config.json`

添加以下配置：

```json
{
  "mcpServers": {
    "code-review": {
      "command": "node",
      "args": ["/path/to/mcp-xl-code-review/build/index.js"]
    }
  }
}
```

### 在 Cursor 中配置

在 Cursor 的 MCP 设置中添加：

```json
{
  "mcpServers": {
    "code-review": {
      "command": "node",
      "args": ["/path/to/mcp-xl-code-review/build/index.js"]
    }
  }
}
```

### 使用 npx 运行（无需全局安装）

```json
{
  "mcpServers": {
    "code-review": {
      "command": "npx",
      "args": ["-y", "mcp-xl-code-review"]
    }
  }
}
```

## 工具说明

本 MCP Server 提供 3 个工具和 3 个提示词模板：

所有工具均支持两种使用模式：

- **分支对比模式**: 提供 `target_branch`，对比开发分支与目标分支的差异
- **Commit Hash 模式**: 提供 `from_commit`，获取该 commit 之后到开发分支的所有变更，无需指定目标分支

## 提示词模板（Prompts）

在 MCP 面板中可以直接看到以下提示词模板，点击即可快速使用：

| 模板名称 | 说明 |
|---------|------|
| `generate-review` | 生成代码Review报告（分支对比模式） |
| `generate-review-from-commit` | 生成代码Review报告（Commit Hash模式） |
| `list-authors` | 查看提交作者列表 |

使用方式：在 MCP 面板的 Prompts 区域选择对应模板，填入参数即可自动生成提示词并执行。

### 1. `list_branch_authors`

列出变更范围内所有提交的作者信息，帮助用户确认自己的 Git 用户名。

### 2. `get_changed_files`

获取变更文件的路径列表。用于：
- 了解本次迭代涉及哪些文件
- 根据文件路径让 LLM 批量生成文件功能描述

### 3. `generate_code_review`

生成代码 Review 报告（HTML 格式）。支持接收文件功能描述参数，在报告中展示。

## 使用方式

配置完成后，在 AI 助手中使用以下指令：

### 一句话生成 Review 报告（推荐）

直接告诉 AI 你要生成代码 Review 报告，AI 会自动完成以下流程：

**分支对比模式：**
> "帮我生成代码 Review 报告，仓库路径是 /path/to/my-project，开发分支是 feature/my-branch，目标分支是 main，作者是 Zhang San"

**Commit Hash 模式：**
> "帮我生成代码 Review 报告，仓库路径是 /path/to/my-project，开发分支是 feature/my-branch，从 commit abc1234 开始，作者是 Zhang San"

AI 会自动：
1. 调用 `generate_code_review` 获取变更文件列表
2. 根据每个文件的完整路径理解其功能，生成简短的中文功能描述（50字以内）
3. 再次调用 `generate_code_review` 传入文件描述，生成完整的 HTML 报告

整个过程在一轮对话中自动完成，无需手动干预。

### 文件功能描述示例

AI 会根据文件路径智能生成功能描述，例如：
- `src/api/settlement.ts` → "结算管理API接口"
- `src/views/Settlement/Corporate.vue` → "结算列表页面"
- `src/utils/date.ts` → "日期格式化工具函数"
- `src/store/user.ts` → "用户状态管理"
- `src/components/UploadFile.vue` → "文件上传组件"

### 查看提交作者列表

当你不确定自己的 Git 用户名时：

> "帮我查看 /path/to/my-project 仓库中 feature/my-branch 分支相对于 main 分支的所有提交作者"

### `generate_code_review` 参数说明

| 参数 | 必填 | 说明 |
|------|------|------|
| `repo_path` | ✅ | Git 仓库的本地绝对路径 |
| `dev_branch` | ✅ | 开发分支名称（你的工作分支） |
| `target_branch` | ⚠️ | 目标对比分支（如 main、master、develop），与 `from_commit` 二选一 |
| `from_commit` | ⚠️ | 起始 commit hash，与 `target_branch` 二选一 |
| `author` | ❌ | Git 提交作者名称或邮箱，用于筛选特定作者的提交 |
| `output_path` | ❌ | HTML 报告输出路径，默认生成在仓库根目录 |
| `file_descriptions` | ❌ | 文件功能描述列表，每个元素包含 `path`（文件路径）和 `description`（功能描述，50字以内） |

### `get_changed_files` 参数说明

| 参数 | 必填 | 说明 |
|------|------|------|
| `repo_path` | ✅ | Git 仓库的本地绝对路径 |
| `dev_branch` | ✅ | 开发分支名称 |
| `target_branch` | ⚠️ | 目标对比分支（如 main、master、develop），与 `from_commit` 二选一 |
| `from_commit` | ⚠️ | 起始 commit hash，与 `target_branch` 二选一 |
| `author` | ❌ | Git 提交作者名称或邮箱，用于筛选特定作者的提交 |

### `list_branch_authors` 参数说明

| 参数 | 必填 | 说明 |
|------|------|------|
| `repo_path` | ✅ | Git 仓库的本地绝对路径 |
| `dev_branch` | ✅ | 开发分支名称 |
| `target_branch` | ⚠️ | 目标对比分支，与 `from_commit` 二选一 |
| `from_commit` | ⚠️ | 起始 commit hash，与 `target_branch` 二选一 |

## 报告内容

生成的 HTML 报告包含以下内容：

1. **变更概览**: 统计信息（文件数、提交数、新增/删除行数）、参与开发者列表
2. **文件功能描述**: 每个文件的功能描述（由 LLM 根据文件路径生成，50字以内）
3. **文件变更详情**: 每个文件的关键改动点、代码差异
4. **代码差异高亮**: 带语法高亮的 diff 视图，支持 Vue SFC 多段语言高亮
5. **文件目录导航**: 左侧固定目录栏，展示文件名和功能描述，支持快速跳转

## 项目结构

```
mcp-xl-code-review/
├── src/
│   ├── index.ts            # MCP Server 入口
│   ├── git-utils.ts        # Git 操作工具类
│   ├── analyzer.ts         # 代码分析器
│   └── report-generator.ts # HTML 报告生成器
├── build/                  # 编译输出目录
├── package.json
├── tsconfig.json
└── README.md
```

## 技术栈

- **TypeScript**: 主要开发语言
- **MCP SDK**: Model Context Protocol 服务端 SDK
- **Git**: 通过 child_process 调用 Git 命令
- **Node.js**: 运行环境

## 开发

```bash
# 开发模式（监听文件变化）
npm run dev

# 构建
npm run build

# 清理构建产物
npm run clean
```

## 注意事项

1. 确保本地已安装 Git 并且可以在命令行中使用
2. 仓库路径必须是本地已克隆的 Git 仓库
3. 分支名称需要是本地已存在的分支（如果远程分支未拉取，请先 `git fetch`）
4. 作者名称匹配使用 Git 的 `--author` 参数，支持部分匹配
5. 图片、字体、压缩包等二进制资源文件会被自动过滤，不会出现在报告中
6. 无实际代码差异的文件（如仅格式变更）也会被自动排除

## License

MIT