# pr-guard-mcp

`pr-guard-mcp` 是一个面向 Pull Request 的安全审计 MCP Server。

它可以让 Codex、Claude Code、Cursor 等支持 MCP 的 AI Agent 对 `git diff` 或 PR diff 做安全检查，帮助你在代码合并前发现明显风险。

## 功能

- 检测新增代码中的密钥泄露，例如 AWS key、GitHub token、数据库连接串、私钥片段
- 识别高风险代码模式，例如 `eval`、命令执行、SQL 字符串拼接
- 识别依赖文件里的新增依赖，例如 `package.json`、`requirements.txt`、`pyproject.toml`、`pom.xml`
- 输出结构化 JSON，方便 AI Agent 生成 PR review 评论

## 安装

```bash
npm install
npm run build
```

## 本地运行

```bash
npm run dev
```

## Demo

```bash
npm run demo
```

示例会分析 `examples/insecure.diff`，输出类似下面的安全摘要：

```json
{
  "summary": {
    "totalFindings": 3,
    "critical": 1,
    "high": 1,
    "medium": 1
  },
  "findings": [
    {
      "category": "dangerous-pattern",
      "severity": "critical",
      "title": "Potential command execution added"
    }
  ]
}
```

## MCP 工具

### `analyze_pr_diff`

分析一段 unified diff 文本，并返回安全风险列表。

输入：

```json
{
  "diff": "这里放 git diff 或 PR diff 文本"
}
```

输出字段：

- `summary`：按严重程度统计的风险数量
- `findings`：具体风险列表，包括类型、严重程度、文件、行号、证据和修复建议

### `analyze_github_pr`

输入 GitHub PR URL，自动拉取 PR diff 并进行安全分析。

输入：

```json
{
  "prUrl": "https://github.com/owner/repo/pull/123",
  "token": "可选，私有仓库或高频请求时使用"
}
```

说明：

- 公共仓库可以不传 `token`
- 私有仓库需要传 GitHub token
- token 只用于请求 GitHub API，不会出现在分析结果里

### `generate_review_comment`

输入 diff 文本，生成可以直接粘贴到 PR 里的 Markdown 安全审计评论。

输入：

```json
{
  "diff": "这里放 git diff 或 PR diff 文本"
}
```

输出示例：

```markdown
## PR 安全审计结果

发现 1 个风险：critical 1，high 0，medium 0，low 0。

| 严重程度 | 类型 | 位置 | 问题 | 建议 |
|---|---|---|---|---|
| critical | dangerous-pattern | src/app.js:3 | Potential command execution added | Avoid shell execution with user-controlled input... |
```

## MCP 客户端配置示例

构建完成后，可以把它配置到支持 MCP 的客户端中：

```json
{
  "mcpServers": {
    "pr-guard": {
      "command": "node",
      "args": ["D:/github-xiang-mu/pr-guard-mcp/dist/server.js"]
    }
  }
}
```

## 适合场景

- 合并 PR 前做轻量安全检查
- 让 AI Agent 生成安全 review 评论
- 快速检查新增代码里是否出现明显密钥和危险 API
- 作为后续 GitHub PR 自动审计工具的基础版本

## 当前限制

- 当前版本支持 GitHub PR URL，但还不会自动把评论写回 PR
- 检测规则以启发式正则为主，不能替代完整 SAST
- 依赖风险目前只识别新增依赖，还没有接入 npm、PyPI、Maven 漏洞库

## 后续计划

- 接入 GitHub Advisory、npm audit、PyPI advisory 和 OSV
- 支持自动向 PR 提交 review comment
- 增加更多语言的危险 API 规则