review-gate

Extensible Model Context Protocol (MCP) server for automated pre-PR code review and branch synchronization verification.

Features

• Strict Rebase Sync Verification: Automatically verifies if the feature branch is rebased on top of the base branch (main/master or remote origin). Rejects stale reviews if the base branch has moved ahead.
• Deep Git Context: Unified diff with --unified=10 lines of context and a high-level file change summary (git diff --stat).
• Uncommitted Modifications Handling: Seamlessly inspects committed branch changes as well as uncommitted (staged and unstaged) modifications, flagging dirty states with warnings.
• Extensible Review Harnesses: Decoupled architecture supporting multiple execution backends, starting with OpenCode using the deepseek/deepseek-flash model.
• Structured Findings: Generates both machine-readable determinations (APPROVED, CHANGES_REQUESTED, COMMENT) and human-readable Markdown reports.
• Continuous Integration: Includes Forgejo Actions CI workflow running on Incus KVM runners.

Installation & Development

This project is managed with uv:

# Set up virtual environment and install dependencies
uv venv
uv pip install -e ".[test]"

# Run test suite
uv run pytest -v

MCP Configuration

Add review-gate to your MCP configuration (e.g. ~/.gemini/config/mcp_config.json):

{
  "mcpServers": {
    "review-gate": {
      "command": "uv",
      "args": [
        "--directory",
        "/absolute/path/to/mcp-review-gate",
        "run",
        "review-gate"
      ]
    }
  }
}

Available Tools

review_pr_changes

Reviews code changes before submitting a pull request.

Parameters:

• repo_path (str, default: "."): Path to the target git repository.
• base_branch (str, optional): Target base branch (auto-detects main, master, or origin/HEAD).
• task_description (str, optional): Summary of what this feature / PR accomplishes.
• review_focus (str, optional): Lenses such as "security", "performance", "edge cases".
• harness (str, default: "opencode"): Execution harness name.
• model (str, default: "deepseek/deepseek-flash"): Model identifier.
• extra_instructions (str, optional): Additional custom instructions.
• include_uncommitted (bool, default: true): Include working tree modifications.
• strict_fetch (bool, default: false): Reject review if remote fetch fails against an existing remote.
• exclude_patterns (list of str, optional): Glob patterns of paths to exclude from diff transmission.
• session_id (str, optional): Existing OpenCode session ID to continue multi-round review.
• iteration (int, default: 1): Current review loop iteration.
• max_iterations (int, default: 2): Maximum review loop iterations before concluding.

Environment Variables

• OPENCODE_TIMEOUT (default: 600): Total maximum runtime in seconds for the opencode subprocess execution.
• REVIEW_GATE_WAIT_TIMEOUT (default: 150): Per-call soft wait window in seconds before returning ## [REVIEW IN PROGRESS: RETRY TO COLLECT], preventing MCP client transport timeouts (such as Antigravity's 3-minute hard limit) while review execution continues in the background. Values are clamped to a maximum of 170s to guarantee staying beneath the client's hard transport deadline; non-numeric, zero, negative or NaN values fall back to the default.

Background Execution & Caching

Reviews run as background tasks owned by an in-process coordinator (coordinator.py), so a review survives the MCP call that started it being timed out or cancelled.

• Review key: repository, base commit, HEAD, diff hash, a digest of task_description/review_focus/extra_instructions, harness, model, session and round. Identical calls join the same running task; any difference starts a new review.
• Completed results are cached for 30 minutes (at most 256 entries). The latest round result of a session is also kept with the session (2 hours), so retries can still collect it. Fail-closed guardrails (truncated diff, sensitive files, strict fetch, branch sync) always run before a cached result is returned.
• Failures are never cached. Whether a result is a completed review is decided only by the harness-set execution_status field, never by model-authored text. A failure that finishes while no caller is waiting is reported once (kept for 2 minutes) to the next identical call; the call after that re-runs the review.
• Limits: at most 2 reviews execute concurrently; at most 4 may be in flight (running or queued) globally and 2 per repository, otherwise ## [REVIEW QUEUE FULL: RETRY LATER] is returned. Only one round per session may run at a time (## [REVIEW BUSY: SESSION ROUND RUNNING]).
• Superseding: a new request for the same repository and session (or the same repository with no session) cancels older requests in that lane that are still queued (not yet executing); their waiting callers receive ## [REVIEW SUPERSEDED: RETRY]. Note that two agents running round-1 reviews against the same repository with different parameters share a lane and may supersede each other's queued reviews.
• State is in memory only and is lost when the server restarts.

Security & Advisory Threat Model

Note

review-gate is designed as an advisory pre-PR coding assistant that executes within the developer's or agent's local environment. It is not a deterministic, cryptographically signed pre-merge security boundary against malicious or compromised local actors.

Threat Model & Boundaries

• Advisory Pre-PR Assistance: review-gate provides automated feedback to assist engineers and autonomous agents before opening pull requests. An APPROVED verdict indicates that the advisory model found no blocking issues; it does not replace mandatory continuous integration, branch protection, or human review.
• Self-Attestation Context: In local MCP execution, the calling agent provides invocation arguments (repo_path, task_description, etc.). True cryptographic gating, audit logs, and mandatory check policies must reside in server-side repository settings (e.g., Forgejo branch protection, Incus CI workflows) rather than the local environment.
• Server-Side Validation: Caller-supplied parameters (task_description, review_focus, extra_instructions) are treated strictly as advisory context. They cannot override or relax server-side safety checks, prompt injection boundaries, or blocking-issue verdict overrides.
• Fail-Closed Determinations: If critical or major defects or vulnerabilities are detected, or if review output cannot be authenticated, the final verdict fails closed to CHANGES_REQUESTED.
• Sensitive File Guardrails: Exclusions matching secret patterns (.env*, *credential*, *private*key*, *token*) prevent automatic approval if sensitive files are touched in the branch.
• Execution Isolation & Read-Only Scoping: OpenCode executes within the target repository with a scoped permission profile allowing read-only repository inspection (read, read_file, glob, grep, file_search, list_dir) to verify context, caller sites, and type definitions. Write actions and command executions (bash, edit, write, patch) are denied by default. Untrusted diffs are enclosed within random cryptographic nonces to mitigate prompt injection.

Rules & Agent Guidance

See RULES.md and AGENTS_TEMPLATE.md for workflow guidelines and commit conventions when addressing review feedback.