内容
# MCP 代码审查代理
本项目是一个面向后端的 AI 代码审查工作流，构建使用：
- 一个 **MCP 服务器**（模型上下文协议），提供仓库工具
- 一个 **MCP 客户端代理**，连接到该服务器
- **Claude API**，用于推理和审查生成
- 可选的 **GitHub 集成**，直接在拉取请求上发布评论
它的设计目的是展示如何为 LLM 提供受控、可审计的仓库操作访问权限（读取文件、差异代码、运行测试），而不是将整个仓库上下文转储到单个提示中。
## 60 秒演示
```bash
git clone https://github.com/PavanKumarc8/mcp-code-review-agent.git
cd mcp-code-review-agent
npm install
npm run build
export ANTHROPIC_API_KEY="your_anthropic_key"
export GITHUB_TOKEN="your_github_token"
npm run agent -- --diff "diff --git a/src/example.ts b/src/example.ts\n@@ -1 +1 @@\n-const timeout = 1000;\n+const timeout = 10;"
```
## 本项目的作用
- 在 Node.js + TypeScript 中启动本地 MCP 服务器。
- 暴露 3 种工具：
- `read_file`（安全，仓库根目录约束的文件读取）
- `get_diff`（针对 `main` 的 git 差异）
- `run_tests`（执行 `npm test`，返回输出 + 退出代码）
- 运行一个客户端代理：
- 向 Claude 发送 PR 差异
- 允许 Claude 根据需要调用 MCP 工具
- 收集工具结果并返回结构化的最终审查
- 可选地，从 GitHub 获取 PR 差异并将审查作为 PR 评论发布。
## MCP 架构（无需 MCP 背景知识）
将 MCP 视为模型运行时和后端工具之间的类型化 RPC 层。
1. **MCP 服务器 (`src/index.ts`)**
- 拥有实际功能（文件系统/git/测试执行）。
- 使用清晰的输入模式（Zod）注册工具。
- 强制执行安全约束（例如，路径限制到仓库根目录）。
2. **MCP 客户端 + Claude (`src/agent.ts`)**
- 通过 stdio 连接到 MCP 服务器。
- 列出可用工具并将它们作为函数/工具定义暴露给 Claude。
- 运行工具循环：
- Claude 请求工具调用
- 代理通过 MCP 执行
- 代理将工具结果返回给 Claude
- 打印最终的代码审查。
3. **GitHub 集成 (`src/github-review.ts`)**
- 通过 Octokit 获取开放的 PR 差异。
- 调用相同的审查代理流程。
- 将生成的审查作为 PR 评论发布回。
这种模式很重要的原因：
- 保持工具访问明确且可测试
- 将模型推理与基础设施访问分离
- 支持比无约束的仅提示流程更安全的生产化
## 项目结构
- `src/index.ts` - MCP 服务器入口点和工具注册
- `src/tool-handlers.ts` - 可测试的工具处理逻辑
- `src/agent.ts` - MCP 客户端 + Claude 审查循环
- `src/github-review.ts` - GitHub 获取 + 评论发布
- `tests/tool-handlers.test.ts` - Vitest 工具处理单元测试
## 安装
### 1) 安装依赖项
```bash
npm install
```
### 2) 构建
```bash
npm run build
```
### 3) 运行测试（可选但推荐）
```bash
npm run test
```
## 环境变量
- `ANTHROPIC_API_KEY`（**必填**）
`@anthropic-ai/sdk` 使用的 API 密钥。
- `GITHUB_TOKEN`（**GitHub PR 评论流程必填**）
`@octokit/rest` 用于读取 PR 差异和发布评论的令牌。
- `MCP_REPO_ROOT`（**可选**）
服务器安全检查为 `read_file` 强制执行的仓库根目录，并用作 git/test 命令的工作目录。
如果省略，则默认为当前工作目录。
## 用法
### A) 从提供的差异字符串进行本地审查
```bash
npm run agent -- --diff "diff --git a/src/example.ts b/src/example.ts
@@ -1,3 +1,3 @@
-const timeout = 1000;
+const timeout = 10;"
```
可选标志：
- `--model <claude-model>`
- `--maxToolRounds <n>`
- `--repoRoot <path>`
- `--server <path-to-server-entry>`
### B) 直接在 GitHub PR 上审查和评论
```bash
npm run github-review -- --owner your-org --repo your-repo --pr 123
```
可选标志：
- `--model <claude-model>`
- `--maxToolRounds <n>`
- `--repoRoot <local-path-to-repo>`
- `--server <path-to-server-entry>`
## 示例审查输出
```text
错误
- `src/retry.ts`：重试循环现在使用 10ms 超时而不是 1000ms，在失败时可能导致请求风暴。
- `src/cache.ts`：在冷缓存路径上，可能在取消引用 `entry.value` 之前缺少空检查。
样式问题
- `src/controller/user.ts`：混合错误响应形状（`{error}` vs `{message}`）降低了 API 一致性。
- `src/service/auth.ts`：函数 `validate` 超过 100 行并组合解析 + 策略检查。
建议
- 添加一个集成测试，模拟重复的上游故障并验证重试回退行为。
- 考虑在中间件中集中错误序列化，以保持处理程序专注于业务逻辑。
```
## 招聘人员友好摘要
本项目演示了与生产相关的后端工程模式：
- 类型化的协议驱动的工具接口
- 文件系统/进程访问的安全执行边界
- 具有显式控制流的 LLM 工具编排
- 用于开发人员工作流的 GitHub 自动化集成
- 带有依赖项模拟的单元测试工具处理程序（Vitest）
简而言之：这是一个 AI 辅助的代码审查管道，构建得像后端系统一样，而不仅仅是一个提示脚本。
