# critique-mcp

[![CI](https://github.com/Nimra3261/critique-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/Nimra3261/critique-mcp/actions/workflows/ci.yml)

An MCP server that gives an agent the tools to actually review a pull
request — not just summarize the diff, but pull it apart, lint the changed
code, flag when tests weren't updated, and post a real review back to
GitHub.

Python · [Model Context Protocol](https://modelcontextprotocol.io) · GitHub REST API

---

## Tools

| Tool | What it does |
|---|---|
| `list_changed_files` | Files changed in a PR, with diff stats and patch text |
| `check_test_coverage` | Flags PRs that change source files without touching any test file |
| `run_linter` | Runs `ruff` against every changed Python file at the PR's head commit |
| `post_review` | Submits a real review (comment / approve / request changes) on the PR |

Each tool is a thin, independently testable function — `run_linter` doesn't
know how `check_test_coverage` works, and neither talks to GitHub except
through `GitHubClient`. The agent decides how to combine them; this server
just gives it hands.

`check_test_coverage` is a PR-level heuristic, not per-file coverage
instrumentation: it flags "source files changed, zero test files touched
anywhere in this PR," the same coarse signal tools like Danger.js use. A PR
that changes five source files and touches one unrelated test won't be
flagged — a precise version would need real coverage data, not filenames.

## Why this exists

I've found and fixed exactly the kind of bug these tools catch, by hand, in
other people's PRs — a vacuous-pass test assertion in
[chroma-core/chroma](https://github.com/chroma-core/chroma/pull/7508), a
validator that only checked one element of a list in
[weaviate-python-client](https://github.com/weaviate/weaviate-python-client/pull/2108),
a float-precision bug in
[qdrant-client](https://github.com/qdrant/qdrant-client/pull/1310). This
turns that review process into tools an agent can call directly, instead of
a human doing the same checks by hand every time.

## Setup

Requires Python 3.11+, [ruff](https://docs.astral.sh/ruff/) on PATH, and a
[GitHub personal access token](https://github.com/settings/tokens) with
`repo` scope (read-only is enough unless you want `post_review` to work).

```bash
cp .env.example .env      # then add your token to .env
python -m venv .venv && source .venv/bin/activate   # Windows: .venv\Scripts\activate
pip install -r requirements.txt
```

## Usage

Add it to Claude Desktop / Claude Code's MCP config:

```json
{
  "mcpServers": {
    "critique": {
      "command": "python",
      "args": ["-m", "critique_mcp.server"],
      "env": { "GITHUB_TOKEN": "ghp_..." }
    }
  }
}
```

Then ask the agent to use it: "Use critique to review PR #42 on owner/repo —
check for lint issues and missing tests, then post a summary review."

## Tests

```bash
pytest
```

Every GitHub API call is mocked in tests — nothing here makes a live network
call unless you run the server itself.