Code Review MCP

AI-powered code review using Zhipu GLM. The server gathers git diffs and optional source context, then asks the model for a focused review.

Installation

Install dependencies:

git clone https://github.com/Enferlain/review-mcp.git
cd review-mcp
cp .env.example .env
# Optional: edit .env and add your API key
uv sync

Then add it to your MCP client.

For local development, use uv run from your clone:

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

For day-to-day use from Git, uvx avoids hardcoding a local install path:

{
  "mcpServers": {
    "review-mcp": {
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/Enferlain/review-mcp",
        "review-mcp"
      ]
    }
  }
}

The MCP caller should pass the repository being reviewed as working_directory on each review_with_context call. If your MCP client cannot pass a per-call workspace, you can still start the server with a fixed fallback:

"args": [
  "--from",
  "git+https://github.com/Enferlain/review-mcp",
  "review-mcp",
  "--workspace-dir",
  "/absolute/path/to/the-repo-you-want-reviewed"
]

Configuration

Environment variables (in .env):

• AI_API_KEY (required): Your API key
• ZHIPU_API_KEY (optional): Backward-compatible fallback key name
• GLM_API_KEY (optional): Alternate fallback key name
• ZHIPU_BASE_URL (optional): Override API endpoint
• AI_MODEL / ZHIPU_MODEL (optional): Override the review model (default: glm-5.3-flash); can also be set per call via the model parameter — use the list_models tool to see what the endpoint offers
• AI_REASONING_EFFORT / ZHIPU_REASONING_EFFORT (optional): Reasoning effort (default: max), sent for GLM models with reasoning controls (the glm-4.5+ family); also settable per call via the reasoning_effort parameter, where none disables thinking. Note: these request parameters are now sent for the whole glm-4.5+ family, not just glm-5.2.
• AI_API_TIMEOUT_SECONDS (optional): Timeout for each model API request (default: 900)
• MAX_REVIEW_CONTEXT_CHARS (optional): Explicit character-based safety ceiling for the accumulated request. Unset by default; character counts are not used as a proxy for model tokens. The completion API's usage.prompt_tokens is the authoritative context measurement, and the provider enforces its own model window.
• MAX_REVIEW_TOOL_RESULT_CHARS (optional): Per-tool result ceiling before truncation (default: 20000)
• MAX_REVIEW_MODEL_CALLS (optional): Review-turn budget (default: 64; invalid values or values below 2 fall back to 64), including one reserved tool-free final synthesis call. Transient failures can cause up to three HTTP attempts per turn. This bounds long tool loops independently of the selected model's context window. Provider context-limit errors still end the review with a failure; this budget does not estimate tokens.
• REVIEW_TOOL_TIMEOUT_SECONDS (optional): End the MCP tool call before the host-level timeout (default: 1800)
• REVIEW_MCP_INCLUDE_TRACE (optional): Append diagnostic trace details to returned and saved reviews (true/false, default: false).

Usage

The MCP exposes 2 tools: review_with_context and list_models

review_with_context

Parameters:

• diff_target: 'staged' (default), 'unstaged', or a git ref like 'HEAD~1'
• context_files: Additional files or OpenSpec change folders to include as context
• focus_files: Specific files to focus the review on
• task_description: Description of what you're trying to accomplish
• working_directory: Git repository root to review (required unless the server was started with --workspace-dir)
• include_trace: Append a diagnostic trace to the returned and saved review when true (optional; defaults to REVIEW_MCP_INCLUDE_TRACE, then false). An explicit false disables tracing even when the environment enables it.
• model: Model id for this review, e.g. glm-5.3 (optional; defaults to AI_MODEL/ZHIPU_MODEL, then glm-5.3-flash)
• reasoning_effort: none, minimal, low, medium, high, xhigh, or max (optional; defaults to AI_REASONING_EFFORT/ZHIPU_REASONING_EFFORT, then max; only sent for reasoning-capable GLM models, none disables thinking; invalid values return an error listing the options)

Progress pairs ongoing and finished work: Reading … / Read …, Searching … / Searched …, and Inspecting … / Inspected …. Searches include their result counts. Each review turn reports the messages sent, then the provider-reported input and output token counts when available. These are per-turn counts; the input includes conversation history. Retries, shortened results, and finalization are also reported.

One review is a tool-use conversation. The model requests repository tools; this server executes them and sends their results back so the model can decide what to inspect next or produce its findings. Each exchange is a review turn, not a separate review. A single completion request cannot execute local repository tools by itself. Progress reports observable actions, not the model's private reasoning.

When called, it automatically:

1. Reads any files listed in context_files
2. Expands explicitly provided OpenSpec change folders into their context files
3. Resolves render_diffs() and file:/// links inside those context files
4. Includes an initial scoped diff when focus_files or context-file render_diffs() links identify files
5. Lets GLM inspect a bounded repository tree, search with ripgrep, and read targeted line ranges
6. Lets GLM request repository-wide staged and unstaged diffs even when focus_files is active
7. Deduplicates repeated requests/results, records provider-reported token usage, and enforces the optional character safety ceiling plus per-tool result limits
8. Returns the final review

OpenSpec change folders are included only when the MCP caller passes the folder path in context_files, for example:

{
  "context_files": [
    "/home/imi/Projects/sd-scripts/openspec/changes/resource-intelligence-system"
  ]
}

CLI and MCP responses contain the review followed by Review artifacts: <directory>. Diagnostic traces are appended to the review only when enabled with include_trace=true, --trace, or REVIEW_MCP_INCLUDE_TRACE=true. Tracing is off by default. The saved review.md includes the trace when enabled; no separate trace file is created.

Trace output is meant for debugging review behavior and can be disabled again once the setup is behaving as expected.

list_models

Lists the model ids currently available from the configured provider, queried live from the endpoint's models listing (using the configured API key and ZHIPU_BASE_URL) rather than a hardcoded snapshot. Returns one model id per line with the configured default model marked, e.g.:

glm-4.5
glm-4.6
glm-5.2
glm-5.3  <- current default

If the configured default model is not offered by the endpoint, a trailing Configured default: <model> (not offered by this endpoint) line notes it instead. The listing uses a short request timeout (15s) and returns an Error: ... message when no API key is configured or the provider cannot be reached.

CLI mode (streaming progress)

Some MCP clients (Codex CLI at the time of writing) neither request MCP progress notifications nor render them, so a long review_with_context call shows no sign of life until it finishes. The same review can instead run as a subprocess whose output streams live over the host's exec channel:

uvx --from git+https://github.com/Enferlain/review-mcp.git@main review-mcp run <workspace> \
  [--diff-target staged] [--context PATH ...] [--focus PATH ...] [--task TEXT] \
  [--model ID] [--reasoning-effort max] [--trace] [--timeout 1800] \
  [--heartbeat 120] [--progress plain|ndjson|none]

• The review text is printed to stdout (the invoking agent captures it as command output); exit code 0 on success, 1 on a failed/timed-out review, 130 on Ctrl-C.
• Progress goes to stderr as concise [ 12.3s] action lines by default. --progress ndjson emits JSON records for automation (schema_version, type = status | heartbeat | result, ts, elapsed, message; result records add ok and chars). Consumers should ignore unknown keys and types. Heartbeats default to 120 seconds of silence; --heartbeat 0 disables them. --progress none silences stderr.

chars counts the saved review text, excluding the artifacts path footer and the newline added when printing it.

• review-mcp models prints the same live model listing as the list_models tool.

Every review started through the CLI or MCP tool automatically keeps a private review-mcp-run-* directory in the system temporary directory. Its path is reported in startup progress (or supplied as artifacts_dir and result_file in CLI NDJSON records). The directory contains:

• review.md: the completed review or error response, atomically saved before

stdout is written, so losing the terminal connection cannot lose a saved result. The artifacts path footer is added to the returned response, not to this file.

• progress.ndjson: progress records written as they happen, even when terminal

progress is disabled with --progress none.

• status.json: request options, process ID, outcome, and whether a result exists.

Files are retained after exit, Ctrl-C, or timeout. A hard kill can leave the last status as running or a partial last progress record; an unfinished review has no final result or resume support. If an MCP request is canceled while its worker continues, a result that finishes later is still saved. Temporary files may be removed by the OS. With CLI --progress none, no path is printed; locate runs under the system temporary directory by their review-mcp-run-* prefix and request metadata.

Review and provider diagnostics use the selected progress format too. --progress none suppresses them, including on interruption. Timeout values must be finite and positive; heartbeat values must be finite and nonnegative (0 disables heartbeats).

Example progress (one review, with repository tools between analysis turns):

[    0.0s] Preparing review of HEAD^.
[    0.1s] Review turn 1: sending 2 messages to glm-5.3 (effort: max).
[    4.0s] Review turn 1: received response; 1,234 input tokens, 120 output tokens.
[    4.0s] Reading server.py, lines 120–180
[    4.1s] Read server.py, lines 120–180
[    4.1s] Searching review_mcp for 'run_agentic_review'
[    4.2s] Searched review_mcp for 'run_agentic_review': 3 matching line(s).
[    4.3s] Review turn 2: sending 5 messages to glm-5.3.
[   11.0s] review finished

Running the bare review-mcp command with no arguments still starts the MCP server, so existing host registrations are unaffected.

Codex / VS Code Notes

This server now starts cleanly under MCP hosts because it avoids doing heavy work at import time. A few setup notes still matter:

1. Prefer passing working_directory per tool call so one MCP config can review any repo.
2. If your MCP client cannot inject the current repo automatically, set --workspace-dir in the config as a fixed fallback.
3. Prefer setting AI_API_KEY (or the GLM_API_KEY alias) as a system/user environment variable instead of storing it in MCP config.
4. The tool-level working_directory argument still overrides the configured workspace when your agent provides it.

Example Windows fallback path:

"args": [
  "--directory",
  "D:/Projects/review-mcp",
  "run",
  "review-mcp",
  "--workspace-dir",
  "D:/Projects/myrepo"
]

Example prompt to your AI assistant:

"Review my staged changes"

Security Note

Model-requested tree, search, and file-read tools are confined to the selected repository root, including protection against .. and symlink escapes. Explicit caller-provided context_files may still reference readable files outside the repository, so use those deliberately in sensitive environments.