Code Review MCP — Cursor-first PR reviewer

End-to-end MCP that reviews GitHub PRs using your local toolchain and Cursor’s AI. It fetches PR diffs, loads project docs, runs static/security/tests, posts inline comments (when allowed), and generates a Markdown report.

Requirements

• Node.js 18+
• Cursor
• GitHub Personal Access Token (repo permissions) — loaded via .env.mcp
• Optional tools (auto-detected; skipped if missing):
  • ESLint, Prettier, TypeScript (tsc) from project devDependencies
  • Semgrep CLI (pipx install semgrep or brew install semgrep)
  • Playwright (npm i -D @playwright/test and npx playwright install)

Installation

• Clone this repo (or copy tools/mcp-code-review.mjs and .mcp/code-review/ into your project repo)
• Install Node deps in the repo: npm ci (or npm i)
• Ensure .cursor/mcp.json points to the absolute path of tools/mcp-code-review.mjs

Example .cursor/mcp.json:

{
  "mcpServers": {
    "code-review": {
      "command": "node",
      "args": ["/absolute/path/to/tools/mcp-code-review.mjs"]
    }
  }
}

Environment (auth)

• The MCP loads only .env.mcp (repo root) by default, or --env-file=/path/to/env
• Required:
  • GITHUB_TOKEN=... (must have access to the target repo; SSO-authorized if org enforces it)
• Optional:
  • JIRA_BASE_URL, JIRA_EMAIL, JIRA_API_KEY
  • FIGMA_TOKEN
  • SEMGREP_RULES_DIR=.mcp/code-review/semgrep-rules

Project files the MCP auto-detects

• Repo docs (AI context):
  • codebase_structure.md and watchouts.md at repo root
  • All .md under .mcp/code-review/ (e.g., your-rules.md)
• Lint/format/types:
  • ESLint/Prettier run from local node_modules/.bin using your project configs
  • TypeScript runs if tsconfig.json exists
• Security:
  • Semgrep rules from .mcp/code-review/semgrep-rules/ if present, otherwise p/ci
• Tests:
  • Playwright runs if playwright.config.ts/js exists at repo root

Usage

In Cursor chat inside the target repo:

• @code-review 123 (auto-detect repo from git origin)
• @code-review owner/repo#123
• @code-review https://github.com/owner/repo/pull/123
• @code-review latest

Flags:

• --env-file=/abs/path/to/.env.mcp (override default)
• --dry-run (skip posting/comments, still generate report)
• --commit-report (commit report to PR branch when permitted)
• --auto-fix or --auto-fix=force (apply ESLint/Prettier fixes, commit & push)
• --skip-static --skip-security --skip-tests --skip-figma
• --semgrep-rules-dir=/path/to/rules (override rules)
• --max-diff-chars=20000 --max-file-hunks=10 --verbose

Outputs:

• Logs: mcp-logs/ (per-run files)
• Artifacts: mcp-artifacts/<owner>-<repo>-PR<#>-<ts>/
• Report: mcp-reports/code-review-<owner>-<repo>-PR<#>-<ts>.md

Notes:

• If the authenticated user is the PR author, GitHub may reject review posting; the MCP will skip comments but still write the report (see Pipeline Status in the report).
• Older logs/reports (>1 day) are pruned, and only the latest report for a PR is kept.

Sub-tools (advanced)

You can call focused tools directly:

• @github.resolve_pr { prId: "owner/repo#123" }
• @github.fetch_files { owner: "owner", repo: "repo", pull_number: 123 }
• @jira.fetch { prMeta: { title: "...", body: "...", branch: "..." } }
• @analysis.run_static { files: ["src/..."], runTsc: true }
• @security.run_semgrep {}
• @tests.run_playwright {}
• @report.generate {...}
• @cleanup.prune { owner:"owner", repo:"repo", pull_number:123 }

CI recommendations

Run the same tools in CI for consistent enforcement:

• ESLint: npx eslint . --max-warnings=0
• Prettier: npx prettier --check .
• Semgrep: pipx install semgrep && semgrep --config .mcp/code-review/semgrep-rules --error -- .
• Playwright: npx playwright install --with-deps && npx playwright test --reporter=line

Troubleshooting

• Bad credentials: ensure .env.mcp is present and logs show Auth loaded from .env.mcp:.... Verify PAT: curl -H "Authorization: Bearer $GITHUB_TOKEN" https://api.github.com/user → must be 200.
• Jira skipped: ensure Jira key in PR branch/title/body, and JIRA_* are set.
• Semgrep skipped: install CLI or set rules dir.
• Playwright skipped: add playwright.config.* and install browsers.

For platform-specific setup (macOS/Windows), see docs/Platform-Setup.md.