# codereview-mcp

[![CI](https://github.com/lukaisluka/codereview-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/lukaisluka/codereview-mcp/actions/workflows/ci.yml)
[![Python 3.11+](https://img.shields.io/badge/python-3.11%2B-blue)](https://www.python.org/)
[![License: MIT](https://img.shields.io/badge/license-MIT-green)](LICENSE)

A **stateless MCP server** that reviews, rates, and improves pull requests on demand —
from any MCP client (Claude Code, Cursor, OMP, ...). Built on **Streamable HTTP** and
deployable as a single container behind Nginx.

**[简体中文文档](README.zh-CN.md)**

## Why

Most AI code-review bots hook into webhooks and CI pipelines. codereview-mcp flips the
model: the review happens **inside your AI client's conversation** — you paste an MR/PR
link, ask for a review, and get a structured report you can discuss, refine, and post
back. The server holds no sessions and stores nothing, so it scales horizontally and
leaves no trace.

## Features

- **One URL in, one report out** — the platform (GitLab / GitHub / GHE) is auto-detected
  from the URL shape; no per-repo setup.
- **Structured review** — the LLM returns strict JSON (file / line / severity / suggestion);
  the Markdown report, risk rating, and Critical/High/Medium/Low statistics are rendered
  by code, never by the model.
- **Huge-MR protection** — generated files (lockfiles, minified bundles, protobuf code)
  are filtered first; oversized diffs are split into chunks, reviewed concurrently
  (map-reduce), and merged. Everything filtered/truncated/dropped is stated honestly in
  the report's coverage notes.
- **Real-time progress** — MCP progress notifications stream every stage
  (fetch → filter → LLM → merge).
- **Any OpenAI-compatible LLM** — DeepSeek, Claude gateways, private vLLM / Ollama.
- **Defense-in-depth auth** — static bearer token at the Nginx gateway plus an optional
  independent server-side token check.
- **Stateless Streamable HTTP** — no sticky sessions; safe behind any load balancer.

## Tools

| Tool | What it does |
| --- | --- |
| `run_pr_review` | Full defect-oriented review → Markdown report (summary, risk rating, findings sorted by severity, coverage notes). Optional `post=true` writes the report back as a PR/MR comment. |
| `generate_code_improvements` | Non-defect improvement suggestions (refactoring, performance, testability, readability, security hardening) → Markdown report. |
| `post_review_comment` | Post any Markdown back to the PR/MR as a comment; returns the comment URL. |

## Quick start (local)

```bash
git clone https://github.com/lukaisluka/codereview-mcp.git
cd codereview-mcp
uv sync

cp .env.example .env
# edit .env: GitLab/GitHub token, LLM endpoint + key

uv run codereview-mcp   # serves http://0.0.0.0:8000/mcp
```

## Docker deployment (recommended)

```bash
cp .env.example .env          # fill in real values, incl. NGINX_AUTH_TOKEN
docker compose up -d --build  # nginx gateway on http://<host>:8080
```

The compose stack runs the service (memory-capped at 500 MB) behind an Nginx gateway
that enforces the static bearer token and proxies SSE without buffering. Layered
timeouts: Nginx 300 s → LLM 240 s → Git API 30 s, so the gateway is always the last to
give up.

Point your MCP client at `http://<host>:8080/mcp` with header
`Authorization: Bearer <NGINX_AUTH_TOKEN>` — see [examples/mcp-clients.md](examples/mcp-clients.md)
for Claude Code / Cursor / generic JSON snippets and [examples/python_client.py](examples/python_client.py)
for a programmatic client with progress callbacks.

## Configuration

All settings come from environment variables (or `.env`). Key ones:

| Variable | Default | Description |
| --- | --- | --- |
| `GIT_PROVIDER` | `gitlab` | Startup hint; actual routing follows the `pr_url` shape. |
| `GITLAB_URL` / `GITLAB_PERSONAL_ACCESS_TOKEN` | — | GitLab root URL + token (API scope). |
| `GITHUB_URL` / `GITHUB_TOKEN` | `github.com` / — | GitHub or GHE; token optional for public repos, required for writes/GHE. |
| `MODEL_NAME` | `openai/deepseek-chat` | Model name; a litellm-style `provider/` prefix is stripped automatically. |
| `OPENAI_API_BASE` / `OPENAI_API_KEY` | — | Any OpenAI-compatible endpoint. Key may be empty for intranet hosts (vLLM/Ollama). |
| `LLM_TIMEOUT_S` | `240` | Per-call LLM timeout (keep ≥ 180 and below the gateway's 300 s). |
| `MAX_DIFF_SIZE_KB` / `CHUNK_SIZE_KB` / `MAX_LLM_CHUNKS` | `100` / `24` / `10` | Huge-MR protection thresholds. |
| `MCP_HOST` / `MCP_PORT` / `MCP_ENDPOINT` | `0.0.0.0` / `8000` | `/mcp` bind address and endpoint path. |
| `MCP_AUTH_TOKEN` | empty | Optional server-side bearer check (defense in depth; `/health` is exempt). |
| `NGINX_AUTH_TOKEN` | — | Static bearer token enforced by the Nginx gateway (compose deployment). |
| `REVIEW_LANGUAGE` | `中文` | Language for report prose (summary / descriptions). |
| `LLM_CONCURRENCY` | `4` | Parallel chunk reviews in map-reduce mode. |

Full list with comments: [.env.example](.env.example)

## Development

```bash
uv sync                # install with dev group
uv run pytest          # 90+ tests, fully mocked boundaries
uv run ruff check .    # lint
uv run ruff format .   # format
```

Project layout:

```
src/codereview_mcp/
├── config.py          # env-driven settings (pydantic-settings)
├── server.py          # FastMCP tools, bearer middleware, /health, entrypoint
├── git/               # URL parser, GitLab/GitHub clients, provider factory
└── review/            # diff protection, prompts, LLM client, JSON parsing,
                       # models, markdown rendering, orchestration service
```

## License

[MIT](LICENSE)