ReviewGuard

ReviewGuard MCP

MCP 服务（review-guard-mcp）可让 AI Agent 在安全边界内处理 GitHub PR 审查。该服务持有启用了写入权限的 GitHub 令牌，仅公开审查操作，因此 Agent 无法看到令牌。允许执行哪些操作由服务启动时固定，而非由 Agent 决定。

原因

创建审查评论需要启用了写入权限的 GitHub 令牌，但直接将令牌交给 Agent 可能导致意外操作或提示词注入操作：提交批准、请求更改、关闭他人的审查讨论，或操作无关的代码仓库。该服务作为中间层，将令牌的权限缩减为你选择启用的审查功能。

模式

该服务支持两种使用模式：

待处理模式（默认）

Agent 读取 PR 讨论上下文并创建待处理（草稿）审查。在人工打开 PR、检查草稿评论并亲自提交审查之前，它写入的任何内容都不会对其他人可见。提交操作在结构上不可达：submit 工具根本不会注册，底层客户端也会拒绝所有提交操作。

当 Agent 协助人工审查者时，适合使用此模式。例如，在 IDE 设置（Claude Code、Codex、Theia）中，Agent 起草行内评论，而人工仍是正式审查者。

提交模式（选择启用，--allow-submit）

使用 --allow-submit 启动后，服务还会注册 submit 工具，以便 Agent 自行发布审查。安全措施仍然有效：

• 允许的审查操作仅限于你列出的范围（例如，只允许评论，不允许批准）。
• 每次提交的审查都以固定的、由服务配置的免责声明开头，Agent 无法更改或删除。
• 可选地，--allow-resolve 允许 Agent 解决自己的审查讨论（绝不会解决他人的讨论）；--repo/--pr 则将服务限定到单个拉取请求。

此模式适用于无人值守的自主审查机器人，例如监视器：它会审查所有请求机器人账户进行审查的 PR，并发布真实的审查（仅评论）。

安装

需要 Node.js >= 22。

全局安装（使 review-guard-mcp 可通过 PATH 使用）：

npm install -g @eclipsesource/review-guard-mcp

或指定固定版本：

npm install -g @eclipsesource/review-guard-mcp@<version>

该服务也已列入 MCP Registry， 名称为 com.eclipsesource/review-guard，因此浏览注册表的客户端可以找到 并从中安装。该条目仅包含元数据，没有可连接的托管实例： 它描述的是上述 npm 包，客户端会在默认的待处理模式下在本地安装并运行该包。

从源代码安装

需要 npm >= 12 以及该版本支持的 Node 版本（参见 CONTRIBUTING.md）：

git clone https://github.com/eclipsesource/review-guard.git
cd review-guard
npm ci
npm run build
npm link          # creates a global symlink to the binary

工具

工具	可用性	描述
get_pr_review_context	始终可用	获取 PR 作者／消息、已提交的评审摘要、含已解决状态的行内评审讨论串、回应和永久链接，以及 PR 的一般评论
list_pending_review	始终可用	列出已认证用户待处理的草稿评审，包括所有当前待处理的评审评论及其永久链接
add_review_comments	始终可用	向已认证用户待处理的评审添加一条或多条评论；如有需要，会创建待处理的评审
modify_review_comment	始终可用	更新或删除已认证用户待处理的评审中的一条评论
delete_pending_review	始终可用	删除已认证用户待处理的评审及其所有评论
submit	--allow-submit	将待处理的评审作为正式评审提交。action 仅限允许的选项，且评审摘要始终以固定的、由服务端配置的免责声明开头
resolve_review_thread	--allow-resolve	解决已认证用户自己的某个评审讨论串（例如，最新一次推送已修复的先前问题）。拒绝处理由其他人发起的讨论串

提交模式标志

默认情况下，服务无法提交评审。若要允许提交，请使用 --allow-submit 启动服务，并列出 approve、comment、reject 中的一个或多个选项：

review-guard-mcp --port 4000 \
  --allow-submit approve,comment \
  --submit-body "This is an autonomous, AI-based review and may contain mistakes."

• --allow-submit <csv> 启用 submit 工具，并将其 action 枚举限制为这些值。approve 对应 APPROVE，comment 对应 COMMENT，reject 对应 REQUEST_CHANGES。无效的操作会中止启动。
• --submit-body <text> 设置每次提交时附带的固定评审摘要前缀。Agent 无法更改或删除该前缀，只能在其下方追加自己的摘要。如果设置了 --allow-submit，但未提供此选项，则会使用内置的默认免责声明。其措辞会根据允许的操作进行调整（当不允许 approve 时，会说明该评审并非批准，而不是对批准进行限定）。此选项要求设置 --allow-submit，且内容不能为空。
• --allow-resolve 注册 resolve_review_thread 工具。客户端只会解决首条评论由已认证用户撰写的讨论串，因此，机器人可以在重新评审时整理自己已修复的问题，但绝不会关闭其他评审者的讨论。

如果未设置 --allow-submit，则不会注册 submit 工具，且 submitReview 客户端方法会拒绝所有操作，因此无法通过结构实现提交。

限定到单个 PR（可选启用）

使用 --repo <owner/name> --pr <number> 启动服务，将其固定到一个拉取请求：

review-guard-mcp --port 4000 --repo eclipsesource/some-repo --pr 123

限定后，所有工具都会移除其 owner/repo/pull_number 参数，并且只对该 PR 执行操作。resolve_review_thread 还会检查线程是否属于该 PR。客户端（github.ts）会独立于工具架构执行此限制，因此调用方无法访问令牌本来可以写入的其他 PR 或仓库。只要服务用于审查已知 PR 的自动化审查（通常还会配合提交模式），就应启用此功能，以免受到提示词注入的 Agent 在无关 PR 上发表评论或解决线程。必须同时提供这两个标志。省略它们时，服务不受限制（由调用方在每次调用时提供 PR）。

MCP 客户端配置

Stdio 模式（推荐用于 IDE）

服务以由 IDE 管理的子进程运行。无需配置端口。

对于使用通用 JSON 配置格式的 MCP 客户端（Claude Code、VS Code、Theia）：

{
  "mcpServers": {
    "review-guard": {
      "command": "npx",
      "args": ["-y", "@eclipsesource/review-guard-mcp", "--stdio"]
    }
  }
}

对于 Codex，将服务添加到 ~/.codex/config.toml 或可信的项目本地 .codex/config.toml：

[mcp_servers.review-guard]
command = "npx"
args = ["-y", "@eclipsesource/review-guard-mcp", "--stdio"]

也可以固定到特定版本：

{
  "mcpServers": {
    "review-guard": {
      "command": "npx",
      "args": ["-y", "@eclipsesource/review-guard-mcp@<version>", "--stdio"]
    }
  }
}

远程 HTTP 模式

服务独立运行，并公开一个 Streamable HTTP 端点。

启动服务：

review-guard-mcp --port 4000                     # bind to 127.0.0.1 (localhost only)
review-guard-mcp --port 4000 --host 172.17.0.1   # bind to a specific address instead

然后，将 MCP 客户端指向打印出的 URL（例如 http://127.0.0.1:4000/mcp）。每个 POST 都是独立的无状态请求。

Codex HTTP 配置使用相同的 TOML 格式：

[mcp_servers.review-guard]
url = "http://127.0.0.1:4000/mcp"

--host 标志

默认情况下，HTTP 服务绑定到 127.0.0.1，因此容器和其他计算机无法访问它。传入 --host <address>，改为绑定到一个特定地址。由于该端点未经身份验证，启动时会拒绝未指定地址（0.0.0.0、::）。

主要使用场景是在容器内运行的审查 Agent（例如沙盒化的 Agent 运行时）需要访问主机上的 MCP 服务。在 Linux 上，绑定到容器网络的网关 IP，例如 Docker 默认桥接网络的网关（通常为 172.17.0.1）：

review-guard-mcp --port 4000 \
  --host "$(docker network inspect bridge --format '{{(index .IPAM.Config 0).Gateway}}')"

主机防火墙也必须允许来自容器子网的 MCP 端口流量，例如使用 ufw：

sudo ufw allow from 172.17.0.0/16 to any port 4000 proto tcp

在容器内，可以将客户端指向任何可访问主机的本地名称：网关 IP 本身、host.docker.internal（Docker）、host.containers.internal（Podman），或运行时映射到主机的 localhost/127.0.0.1 别名。使用非环回的 --host 时，服务会接受这些名称对应的 Host 标头，同时仍拒绝未知主机，因此 DNS 重绑定防护仍然有效。

身份验证

如果已安装并完成身份验证的 GitHub CLI（gh auth login），则无需配置令牌。服务会通过 gh auth token 自动获取令牌。

如果无法使用 gh，请通过 MCP 配置显式提供令牌：

{
  "mcpServers": {
    "review-guard": {
      "command": "npx",
      "args": ["-y", "@eclipsesource/review-guard-mcp", "--stdio"],
      "env": { "GITHUB_TOKEN": "ghp_..." }
    }
  }
}

完整的解析顺序如下：

1. GITHUB_TOKEN 环境变量
2. GH_TOKEN 环境变量
3. gh auth token，从 GitHub CLI 读取令牌

建议使用限定到待审查仓库的细粒度个人访问令牌。

安全注意事项

• Agent 永远不会看到令牌。 服务会持有令牌，并且只会公开启动时配置的工具集。
• HTTP 模式默认绑定到 127.0.0.1，并根据绑定地址验证 Host 标头（防止 DNS 重绑定），因此恶意网站无法通过受害者的浏览器访问服务。
• /mcp 端点本身不需要身份验证。 任何能够访问该端口的人都可以使用已配置的功能。请将其限制在 localhost 上；如果使用非环回地址的 --host，则通过防火墙将端口限制到预期的子网，因为否则该网络上的每台机器或容器都可以访问它。启动时会拒绝未指定的绑定地址（0.0.0.0、::）。
• 优先使用范围精细的令牌，仅授予审核中的仓库权限；自动化设置还应添加 --repo/--pr 范围限制。

请按照 SECURITY.md 中的说明，私下报告漏洞。

安全不变量

src/github.ts 模块是唯一与 GitHub 通信的文件。默认情况下，它无法提交审核。除待审核写入外的所有功能都在构造时受到门控。它强制执行以下规则：

1. 注释/线程变更中不得包含 event 字段。 草稿注释始终会将审核保持为 PENDING，因为会完全省略 event。
2. 提交审核需主动启用并受门控。 只有在 submitReview 中才会调用 submitPullRequestReview mutation；该函数会拒绝任何不在构造时传入的 allowSubmit 集合中的操作。未使用 --allow-submit 构建的客户端（默认情况）永远无法提交审核。始终不支持 DISMISS。
3. 提交审核正文固定。 提交的审核始终以服务配置的 --submit-body 开头。调用方只能在其后追加内容，不能替换或删除该正文。
4. 线程解决功能需主动启用，且仅限本人发起的线程。 只有设置了 --allow-resolve 才会运行 resolveReviewThread，并且会拒绝处理非当前已认证用户发起的线程。
5. 绝不会调用 REST 提交/撤销端点。
6. 仅允许写入本人审核。 写入工具只会影响已认证用户自己的审核。
7. PR 范围限制。 使用 --repo/--pr 启动时，客户端内部会拒绝所有针对其他 PR 或仓库的操作，不受工具架构影响。
8. 可审计。 在 src/github.ts 中搜索 submitPullRequestReview、dismiss、APPROVE、REQUEST_CHANGES。mutation 和事件仅出现在 submitReview 中。相关门控由 test/github.test.ts 中的单元测试覆盖。
9. 变更后断路检查（深度防御）。 创建审核后，会验证响应状态是否为 PENDING。与上述门控不同，此检查用于检测而非阻止违规：一旦发现违规，工具调用就会失败并返回 MCP 错误，告知 Agent 停止操作并提醒人工审核者，因为许多 MCP 客户端不会主动向用户显示工具错误。

开发

开发需要 npm >= 12，以及受其支持的 Node 版本。完整指南请参阅 CONTRIBUTING.md。

npm ci                           # install dependencies
npm run build                    # compile TypeScript to dist/
npm run dev                      # tsx watch mode
npm run typecheck                # type-check sources, tests, and configs
npm run lint                     # ESLint
npm run format:check             # Prettier
npm test                         # vitest suite
npm run test:integration         # manual suite against a real repo (see CONTRIBUTING.md)

架构

src/
├── index.ts     # Entry point: token resolution, mode dispatch (--stdio / HTTP)
├── args.ts      # CLI parsing: every flag in one place, unknown flags abort startup
├── server.ts    # MCP server factory with tool schemas (shared by both transports)
├── stdio.ts     # Stdio transport (for IDE-managed lifetime)
├── http.ts      # HTTP transport (node:http, Streamable HTTP)
└── github.ts    # Safety boundary: GraphQL mutations + REST reads
test/            # vitest suite: CLI parsing, safety gates, tool registration

• GraphQL 用于获取已解析的审核线程上下文及执行变更（addPullRequestReview、addPullRequestReviewThread、updatePullRequestReviewComment、deletePullRequestReviewComment、deletePullRequestReview，以及仅在通过主动启用的门控后可用的 submitPullRequestReview 和 resolveReviewThread）。
• REST 用于获取分页完善的 PR 审核摘要和常规 PR 对话注释。
• HTTP 模式仅绑定到 127.0.0.1（或通过 --host 指定的特定地址）。

贡献

欢迎贡献，请参阅 CONTRIBUTING.md。贡献者 必须签署 CLA，系统会在拉取请求中自动检查。

许可证

MIT