mcp-agent-review

# mcp-agent-review An MCP (Model Context Protocol) server that provides **agentic code review** powered by OpenAI-compatible models. Designed for use with [Claude Code](https://docs.anthropic.com/en/docs/claude-code). ## Features - **Deep analysis** — focuses on logic errors, architecture issues, doc-code consistency, and security risks (not style/lint) - **Agentic review** — the model can read files, grep code, check git blame, explore project structure, and search git history to verify findings - **False-positive suppression** — mandatory tool verification, confidence rating, and self-critique phase - **Intent-aware review** — pass `task_description` to catch mismatches between intent and implementation - **Directed focus** — pass `review_focus` to get deeper analysis on a specific dimension (security, performance, concurrency, etc.) - **Any OpenAI-compatible API** — works with GitHub Models (free), OpenAI, Azure OpenAI, or any compatible provider - **Zero config for git repos** — auto-detects diffs, reads CLAUDE.md for project context - **Sensitive file protection** — blocks access to `.env`, `*.pem`, `*.key`, credentials, and other sensitive files ## Installation ```bash # From PyPI pip install mcp-agent-review # From source git clone https://github.com/lzx1413/mcp-agent-review cd mcp_agent_review pip install . ``` ## Claude Code Integration Add to your Claude Code settings (`~/.claude.json` or `.claude/settings.json`): ### GitHub Models (free) ```json { "mcpServers": { "code-review": { "command": "mcp-agent-review", "env": { "GITHUB_TOKEN": "your-github-token" } } } } ``` ### OpenAI (or other providers) ```json { "mcpServers": { "code-review": { "command": "mcp-agent-review", "env": { "OPENAI_API_KEY": "your-api-key", "OPENAI_BASE_URL": "https://api.openai.com/v1", "REVIEW_MODEL": "gpt-4o" } } } } ``` ## Environment Variables | Variable | Required | Default | Description | |----------|----------|---------|-------------| | `GITHUB_TOKEN` | Yes* | — | GitHub personal access token (free via GitHub Models) | | `OPENAI_API_KEY` | Yes* | — | API key for OpenAI or compatible provider (takes priority over `GITHUB_TOKEN`) | | `OPENAI_BASE_URL` | No | `https://models.github.ai/inference` | Base URL for the API | | `REVIEW_MODEL` | No | `gpt-4o` | Model to use for review | | `MAX_TOOL_ROUNDS` | No | `8` | Max agentic tool-use rounds | | `MAX_FILE_LINES` | No | `1000` | Max lines to read per file | *One of `GITHUB_TOKEN` or `OPENAI_API_KEY` is required. ## Tool Parameters | Parameter | Required | Description | |-----------|----------|-------------| | `diff` | No | Custom diff string. If omitted, auto-reads from `git diff` | | `base` | No | Base branch/commit for PR review (e.g. `main`) | | `task_description` | No | What the changes are intended to accomplish (e.g. `fix race condition in pool`). Enables intent-vs-implementation mismatch detection | | `review_focus` | No | Specific dimension to prioritize (e.g. `security`, `performance`, `concurrency safety`). Deeper analysis on this area | ## Usage Once configured in Claude Code, the `review_code` tool is available: - **Auto-detect changes**: just call `review_code` with no arguments — it reads `git diff` - **PR review**: pass `base='main'` to review all changes since diverging from main - **Custom diff**: pass a diff string directly via the `diff` parameter - **Intent-aware review**: pass `task_description` to describe what the changes are for — helps catch gaps between intent and implementation - **Directed focus**: pass `review_focus` (e.g. `'security'`, `'performance'`) to get deeper analysis on a specific dimension ### Example prompts in Claude Code ``` Review my current changes ``` ``` Review the changes on this branch against main ``` ``` Review my changes, the task is to fix the race condition in the connection pool, focus on concurrency safety ``` ## How It Works 1. **Context collection** — reads CLAUDE.md, git log, commit messages, and full source of changed files 2. **Agentic review** — sends context + diff to the model, which can use tools (read_file, grep_code, git_blame, list_files, search_git_history, find_test_files) to investigate 3. **Self-critique** — a second pass filters out low-confidence or speculative findings 4. **Structured output** — returns findings with confidence level, category, file location, and explanation ## License MIT