# mcp-review-pr

An MCP (Model Context Protocol) server for **multi-language PR review** with deterministic analysis. It provides AI-powered code review tools that automatically detect languages, apply relevant review guidelines, and run quality checks on your pull requests.

## ✨ Features

- **Skill-Based Architecture** — Modular review skills that auto-activate based on file types, path patterns, and content detection
- **Deterministic Quality Checks** — Run linters and tests as part of the review pipeline, not just AI suggestions
- **Impact Analysis** — Classify changes by architectural layer (UI, domain, infra, shared) and detect breaking changes
- **Smart Diff Chunking** — Automatically splits large PRs into prioritized chunks for incremental review
- **Result Caching** — Cache diff results and guidelines keyed by commit SHA for fast re-runs
- **Custom Rules** — Layer project-specific rules on top of skill-provided guidelines via a simple `rules.md` file
- **Configurable** — Tune behavior with `.mcp.config.json` (ignored files, risk thresholds, max diff size, etc.)

## 📦 Built-in Skills

| Skill | Priority | Activates On | Linter |
|---|---|---|---|
| **Security** | 15 | `.ts`, `.js`, `.tsx`, `.jsx`, `.mjs` + `api/`, `auth/`, `middleware/` paths | — |
| **React** | 10 | `.tsx`, `.jsx` + React imports + `components/`, `pages/`, `app/` paths | ESLint |
| **TypeScript** | 8 | `.ts`, `.mts`, `.cts` | ESLint |
| **Clean Architecture** | 7 | `.ts`, `.js`, `.tsx`, `.jsx` + `domain/`, `usecases/`, `services/`, `repositories/`, etc. | — |
| **JavaScript** | 5 | `.js`, `.mjs`, `.cjs` | ESLint |

Skills are activated automatically when PR diffs match their criteria. Multiple skills can be active simultaneously — their guidelines and rules are merged by priority.

## 🛠 MCP Tools

The server exposes the following tools via the MCP protocol:

| Tool | Description |
|---|---|
| `get_pr_diff` | Get structured file diffs with additions, deletions, and change types |
| `analyze_impact` | Classify changes by layer, detect breaking changes, assign risk level |
| `list_skills` | List all available skills and which ones are active for the current PR |
| `get_skill_guidelines` | Get merged review guidelines from all active skills + custom rules |
| `load_rules` | Load all applicable rules (skill rules + custom repo rules) |
| `run_quality_checks` | Run skill linters and test suites, returns lint issues and test results |
| `generate_review` | Full structured PR review combining all tools into a comprehensive `ReviewOutput` |

## 🚀 Getting Started

### Prerequisites

- Node.js ≥ 18
- npm

### Installation

```bash
npm install
```

### Build

```bash
npm run build
```

### Running as MCP Server

Start the server over stdio transport (for integration with MCP-compatible clients):

```bash
# Using the compiled output
npm start

# Or during development
npm run dev
```

Then configure your MCP client to connect via stdio. For example, in your MCP client config:

```json
{
  "mcpServers": {
    "review-pr": {
      "command": "node",
      "args": ["/path/to/mcp-review-pr/dist/server.js"]
    }
  }
}
```

### Running as CLI

The CLI provides standalone usage without an MCP client:

```bash
# Review the current repository
npx mcp-review

# Compare against a specific branch
npx mcp-review --base develop

# List available skills and which are active
npx mcp-review --mode skills

# Show active guidelines for your PR
npx mcp-review --mode guidelines

# Analyze impact only
npx mcp-review --mode impact

# Output as markdown instead of JSON
npx mcp-review --format markdown

# Use custom skills directory
npx mcp-review --skills-dir ./my-skills
```

#### CLI Options

| Option | Alias | Description | Default |
|---|---|---|---|
| `--repo <path>` | `-r` | Repository path | Current directory |
| `--base <branch>` | `-b` | Base branch to diff against | `main` |
| `--skills-dir <path>` | `-s` | Custom skills directory | Built-in skills |
| `--format <type>` | `-f` | Output format: `json` or `markdown` | `json` |
| `--mode <mode>` | `-m` | Mode: `review`, `skills`, `guidelines`, `impact`, `server` | `review` |
| `--help` | `-h` | Show help | — |

## ⚙️ Configuration

Create a `.mcp.config.json` in your repository root to customize behavior:

```json
{
  "productionBranches": ["main", "production"],
  "maxDiffLines": 5000,
  "failOnRiskLevel": "high",
  "ignoreFiles": ["package-lock.json", "yarn.lock", "pnpm-lock.yaml"],
  "enableCaching": true
}
```

| Option | Type | Default | Description |
|---|---|---|---|
| `productionBranches` | `string[]` | `["main", "production"]` | Branches considered production |
| `maxDiffLines` | `number` | `5000` | Max diff lines per review chunk |
| `failOnRiskLevel` | `string` | `"high"` | Risk level threshold to flag |
| `ignoreFiles` | `string[]` | Lock files | Files to exclude from review |
| `enableCaching` | `boolean` | `true` | Enable diff/guideline caching |

### Custom Rules

Add a `rules.md` file to your repository root with project-specific review rules:

```markdown
- All API endpoints must validate input with Zod schemas
- Database queries must use parameterized statements
- Components must have display names for debugging
```

These rules are merged with skill-provided rules during review.

## 🧩 Creating Custom Skills

Skills are directories containing three files. Place them in the `skills/` directory (or a custom directory via `--skills-dir`):

```
skills/
└── my-skill/
    ├── skill.json      # Manifest (required)
    ├── guideline.md    # Review guidelines
    └── rules.md        # Checklist rules
```

### `skill.json` — Manifest

```json
{
  "name": "my-skill",
  "description": "Description of what this skill reviews",
  "version": "1.0.0",
  "filePatterns": ["**/*.py"],
  "activateOn": {
    "extensions": [".py"],
    "fileContains": ["import django"],
    "pathPatterns": ["views/", "models/"]
  },
  "priority": 8,
  "linter": {
    "command": "npx",
    "args": ["pylint", "--output-format", "json"],
    "fileExtensions": [".py"]
  }
}
```

| Field | Required | Description |
|---|---|---|
| `name` | ✅ | Unique skill identifier |
| `description` | — | Human-readable description |
| `version` | — | Semantic version |
| `filePatterns` | — | Glob patterns for relevant files |
| `activateOn` | ✅ | Activation criteria (see below) |
| `priority` | — | Higher = evaluated first (default: 0) |
| `linter` | — | Optional linter configuration |

**Activation criteria** (any match triggers activation):

- `extensions` — File extensions in the diff (e.g., `[".ts", ".tsx"]`)
- `fileContains` — Strings found in diff content (e.g., `["from 'react'"]`)
- `pathPatterns` — Path substrings in changed files (e.g., `["components/"]`)

### `guideline.md` — Review Guidelines

Free-form markdown that provides context and best practices for the reviewer. This is included in the review context when the skill is active.

### `rules.md` — Review Rules

A markdown list of specific, checkable rules:

```markdown
- Use strict type annotations, avoid `any`
- Prefer `const` over `let` where possible
- All exported functions must have JSDoc comments
```

## 🏗 Architecture

```
src/
├── server.ts         # MCP server — registers all tools
├── cli.ts            # CLI entry point with argument parsing
├── config.ts         # .mcp.config.json loader
├── types.ts          # Shared TypeScript types
├── cache.ts          # Diff and guideline caching (SHA-keyed)
├── chunker.ts        # Smart diff chunking with priority ordering
├── retry.ts          # Exponential backoff utility
├── skills/
│   ├── index.ts      # Public API re-exports
│   ├── types.ts      # Skill manifest & runtime types
│   ├── loader.ts     # Skill discovery, activation, guideline/rule loading
│   └── runner.ts     # Skill linter execution
└── tools/
    ├── diff.ts       # Git diff extraction via simple-git
    ├── impact.ts     # Change impact & risk analysis
    ├── quality.ts    # Lint + test orchestration
    ├── review.ts     # Structured review generation
    └── rules.ts      # Custom rules.md loader
```

## 📜 Scripts

| Script | Description |
|---|---|
| `npm run build` | Compile TypeScript to `dist/` |
| `npm run dev` | Run in development mode (via `tsx`) |
| `npm start` | Start the compiled MCP server |
| `npm test` | Run tests (Vitest) |
| `npm run test:watch` | Run tests in watch mode |
| `npm run typecheck` | Type-check without emitting |
| `npm run lint` | Lint source files with ESLint |

## 📄 License

MIT