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

npm install

Build

npm run build

Running as MCP Server

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

# 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:

{
  "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:

# 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:

{
  "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:

- 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

{
  "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:

- 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