Content
# MCP-Based Code Review Agent
This project is a backend-oriented AI code review workflow built with:
- an **MCP server** (Model Context Protocol) that exposes repository tools
- an **MCP client agent** that connects to that server
- the **Claude API** for reasoning and review generation
- optional **GitHub integration** to post reviews directly on pull requests
It is designed to show how to give an LLM controlled, auditable access to repo operations (read files, diff code, run tests) instead of dumping full repository context into a single prompt.
## Demo in 60 Seconds
```bash
git clone https://github.com/PavanKumarc8/mcp-code-review-agent.git
cd mcp-code-review-agent
npm install
npm run build
export ANTHROPIC_API_KEY="your_anthropic_key"
export GITHUB_TOKEN="your_github_token"
npm run agent -- --diff "diff --git a/src/example.ts b/src/example.ts\n@@ -1 +1 @@\n-const timeout = 1000;\n+const timeout = 10;"
```
## What This Project Does
- Starts a local MCP server in Node.js + TypeScript.
- Exposes 3 tools:
- `read_file` (safe, repo-root constrained file reads)
- `get_diff` (git diff for a ref against `main`)
- `run_tests` (executes `npm test`, returns output + exit code)
- Runs a client agent that:
- sends a PR diff to Claude
- allows Claude to call the MCP tools as needed
- collects tool results and returns a structured final review
- Optionally fetches a PR diff from GitHub and posts the review as a PR comment.
## MCP Architecture (No MCP Background Required)
Think of MCP as a typed RPC layer between the model runtime and your backend tools.
1. **MCP Server (`src/index.ts`)**
- Owns the real capabilities (filesystem/git/test execution).
- Registers tools with clear input schemas (Zod).
- Enforces safety constraints (for example, path restriction to repo root).
2. **MCP Client + Claude (`src/agent.ts`)**
- Connects to the MCP server over stdio.
- Lists available tools and exposes them to Claude as function/tool definitions.
- Runs a tool loop:
- Claude requests tool calls
- agent executes via MCP
- agent returns tool results back to Claude
- Prints the final code review.
3. **GitHub Integration (`src/github-review.ts`)**
- Fetches an open PR diff via Octokit.
- Calls the same review agent flow.
- Posts the generated review back as a PR comment.
Why this pattern matters:
- keeps tool access explicit and testable
- separates model reasoning from infrastructure access
- supports safer productionization than unconstrained prompt-only flows
## Project Structure
- `src/index.ts` - MCP server entry point and tool registration
- `src/tool-handlers.ts` - testable tool handler logic
- `src/agent.ts` - MCP client + Claude review loop
- `src/github-review.ts` - GitHub fetch + comment posting
- `tests/tool-handlers.test.ts` - Vitest unit tests for tool handlers
## Setup
### 1) Install dependencies
```bash
npm install
```
### 2) Build
```bash
npm run build
```
### 3) Run tests (optional but recommended)
```bash
npm run test
```
## Environment Variables
- `ANTHROPIC_API_KEY` (**required**)
API key used by `@anthropic-ai/sdk`.
- `GITHUB_TOKEN` (**required for GitHub PR commenting flow**)
Token used by `@octokit/rest` to read PR diff and post comments.
- `MCP_REPO_ROOT` (**optional**)
Repo root enforced by server safety checks for `read_file`, and used as working directory for git/test commands.
If omitted, defaults to current working directory.
## Usage
### A) Local review from a provided diff string
```bash
npm run agent -- --diff "diff --git a/src/example.ts b/src/example.ts
@@ -1,3 +1,3 @@
-const timeout = 1000;
+const timeout = 10;"
```
Optional flags:
- `--model <claude-model>`
- `--maxToolRounds <n>`
- `--repoRoot <path>`
- `--server <path-to-server-entry>`
### B) Review and comment directly on a GitHub PR
```bash
npm run github-review -- --owner your-org --repo your-repo --pr 123
```
Optional flags:
- `--model <claude-model>`
- `--maxToolRounds <n>`
- `--repoRoot <local-path-to-repo>`
- `--server <path-to-server-entry>`
## Example Review Output
```text
Bugs
- `src/retry.ts`: Retry loop now uses 10ms timeout instead of 1000ms, which can cause request storms under failure.
- `src/cache.ts`: Missing null check before dereferencing `entry.value` may throw on cold cache paths.
Style Issues
- `src/controller/user.ts`: Mixed error response shapes (`{error}` vs `{message}`) reduce API consistency.
- `src/service/auth.ts`: Function `validate` exceeds 100 lines and combines parsing + policy checks.
Suggestions
- Add an integration test that simulates repeated upstream failures and verifies retry backoff behavior.
- Consider centralizing error serialization in middleware to keep handlers focused on business logic.
```
## Recruiter-Friendly Summary
This project demonstrates production-relevant backend engineering patterns:
- typed protocol-driven tool interfaces
- safe execution boundaries around filesystem/process access
- LLM tool orchestration with explicit control flow
- GitHub automation integration for developer workflow
- unit-tested tool handlers with dependency mocking (Vitest)
In short: it is an AI-assisted code review pipeline built like a backend system, not just a prompt script.
