Code Review Analyst MCP Server

Gemini-powered MCP server for pull request analysis with structured outputs for findings, release risk, and focused patch suggestions.

Overview

This server runs over stdio transport and exposes three review-focused tools: review_diff, risk_score, and suggest_patch. It also publishes an internal://instructions resource and a get-help prompt for in-client guidance.

Key Features

• Structured review analysis with strict JSON output envelopes (ok, result, error).
• Three complementary workflows: full review, release risk scoring, and targeted patch generation.
• Runtime diff-size budget guard (MAX_DIFF_CHARS, default 120000).
• Optional task execution support (execution.taskSupport: "optional") with in-memory task store.
• Progress notifications when clients provide _meta.progressToken.
• Shared Gemini adapter with timeout, retries, safety thresholds, and structured observability logs to stderr.
• Docker image available via GitHub Container Registry.

Requirements

• Node.js >=24
• One API key: GEMINI_API_KEY or GOOGLE_API_KEY
• MCP client that supports stdio servers and tool calls

Quick Start

Standard config for most MCP clients:

{
  "mcpServers": {
    "code-review-analyst": {
      "command": "npx",
      "args": ["-y", "@j0hanz/code-review-analyst-mcp@latest"],
      "env": {
        "GEMINI_API_KEY": "YOUR_API_KEY"
      }
    }
  }
}

[!TIP] For local development, build and run directly via node dist/index.js after npm run build.

Client Configuration

{
  "servers": {
    "code-review-analyst": {
      "command": "npx",
      "args": ["-y", "@j0hanz/code-review-analyst-mcp@latest"],
      "env": {
        "GEMINI_API_KEY": "YOUR_API_KEY"
      }
    }
  }
}

code --add-mcp '{"name":"code-review-analyst","command":"npx","args":["-y","@j0hanz/code-review-analyst-mcp@latest"]}'

{
  "mcpServers": {
    "code-review-analyst": {
      "command": "npx",
      "args": ["-y", "@j0hanz/code-review-analyst-mcp@latest"],
      "env": {
        "GEMINI_API_KEY": "YOUR_API_KEY"
      }
    }
  }
}

{
  "mcpServers": {
    "code-review-analyst": {
      "command": "npx",
      "args": ["-y", "@j0hanz/code-review-analyst-mcp@latest"],
      "env": {
        "GEMINI_API_KEY": "YOUR_API_KEY"
      }
    }
  }
}

claude mcp add code-review-analyst -- npx -y @j0hanz/code-review-analyst-mcp@latest

{
  "mcpServers": {
    "code-review-analyst": {
      "command": "npx",
      "args": ["-y", "@j0hanz/code-review-analyst-mcp@latest"],
      "env": {
        "GEMINI_API_KEY": "YOUR_API_KEY"
      }
    }
  }
}

amp mcp add code-review-analyst -- npx -y @j0hanz/code-review-analyst-mcp@latest

{
  "mcpServers": {
    "code-review-analyst": {
      "command": "npx",
      "args": ["-y", "@j0hanz/code-review-analyst-mcp@latest"],
      "env": {
        "GEMINI_API_KEY": "YOUR_API_KEY"
      }
    }
  }
}

{
  "context_servers": {
    "code-review-analyst": {
      "command": "npx",
      "args": ["-y", "@j0hanz/code-review-analyst-mcp@latest"]
    }
  }
}

{
  "mcpServers": {
    "code-review-analyst": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e",
        "GEMINI_API_KEY",
        "ghcr.io/j0hanz/code-review-analyst-mcp:latest"
      ]
    }
  }
}

MCP Surface

Tools

review_diff

Analyze a unified diff and return structured findings, overall merge risk, and test recommendations.

Returns (inside result):

• summary, overallRisk (low|medium|high), findings[], testsNeeded[]

Example:

{
  "ok": true,
  "result": {
    "summary": "One high-risk auth-path change without null guards.",
    "overallRisk": "high",
    "findings": [
      {
        "severity": "high",
        "file": "src/auth.ts",
        "line": 42,
        "title": "Missing null check",
        "explanation": "Null response can throw and break login.",
        "recommendation": "Guard for null before property access."
      }
    ],
    "testsNeeded": ["Add auth null-path regression test"]
  }
}

risk_score

Score deployment risk for a diff and explain the score drivers.

Returns (inside result):

• score (0..100), bucket (low|medium|high|critical), rationale[]

suggest_patch

Generate a focused unified-diff patch for one selected finding.

Returns (inside result):

• summary, patch (unified diff text), validationChecklist[]

Resources

Prompts

Tasks & Progress

• Server declares capabilities.tasks with tool-call task support.
• Each tool is registered with execution.taskSupport: "optional".
• Progress updates are emitted via notifications/progress when _meta.progressToken is provided.
• Task storage uses in-memory task store (InMemoryTaskStore).

Configuration

Runtime Mode

CLI Arguments

The server binary accepts optional command-line flags:

Example:

npx @j0hanz/code-review-analyst-mcp@latest --model gemini-2.5-pro --max-diff-chars 200000

Environment Variables

Security

• Stdio transport avoids HTTP exposure in the current runtime path.
• Runtime logs and warnings are written to stderr; no non-protocol output is written to stdout.
• Input and output contracts use strict Zod schemas (z.strictObject) with explicit bounds.
• Oversized diffs are rejected early with E_INPUT_TOO_LARGE.
• Tool metadata marks calls as readOnlyHint: true and openWorldHint: true (external model call, no local state mutation).

Development

Install and run locally:

npm install
npm run build
npm start

Useful scripts:

[!TIP] Set TASK_TIMEOUT_MS (env var) to enforce a timeout on build/test script tasks in scripts/tasks.mjs.

Debugging with MCP Inspector:

npx @modelcontextprotocol/inspector node dist/index.js

Docker

Build and run locally with Docker:

docker build -t code-review-analyst-mcp .
docker run -i --rm -e GEMINI_API_KEY code-review-analyst-mcp

Or use Docker Compose:

docker compose up --build

Build & Release

Releases are managed via the Release GitHub Actions workflow (manual dispatch):

1. Version bump — increments package.json and server.json, commits and tags.
2. npm publish — publishes @j0hanz/code-review-analyst-mcp with OIDC provenance.
3. MCP Registry — publishes io.github.j0hanz/code-review-analyst to the MCP Registry.
4. Docker image — builds and pushes multi-arch (linux/amd64, linux/arm64) to ghcr.io/j0hanz/code-review-analyst-mcp.

Troubleshooting

• E_INPUT_TOO_LARGE: Split diff into smaller chunks or increase MAX_DIFF_CHARS.
• E_REVIEW_DIFF / E_RISK_SCORE / E_SUGGEST_PATCH: Verify API key env vars and retry with narrower input.
• Gemini request timed out after ...ms.: Reduce diff/prompt size or increase timeout in caller.
• Gemini returned an empty response body.: Retry and check upstream model health.
• Malformed model JSON response: Retry with same schema and inspect stderr logs.
• Inspector not connecting: Ensure the server is built (npm run build) before running the inspector.
• Claude Desktop logs: Check ~/Library/Logs/Claude/mcp*.log (macOS) for server communication issues.

Contributing & License

• Contributions are welcome. Please open an issue or pull request on GitHub.
• License: MIT (see package.json).