# MCP GitHub Code Reviewer

An MCP (Model Context Protocol) server that gives Claude the ability to fetch Pull Request diffs from GitHub and post inline code review comments directly on the PR — either as a pending draft for you to approve, or published immediately.

## How it works

```text
You (Claude Code) ──► MCP Server (src/index.ts) ──► GitHub API
                           │
                     Two tools + two prompts exposed:
                     • get_pull_request_diff
                     • post_pr_review_comment
                     • review_pr (prompt — guided)
                     • review_pr_auto (prompt — autonomous)
```

When running as an MCP server, Claude can call these tools in response to natural language prompts. You describe which PR to review, and Claude fetches the diff, analyzes the code, and posts structured inline comments.

You can also use the built-in `review_pr` prompt to give Claude step-by-step instructions automatically — no need to describe the process manually each time.

## Prompts available

There are two prompts, each with a different review style:

### `review_pr` — guided review

Instructs Claude to follow a fixed step-by-step process: fetch the diff, analyze it across specific categories, and post inline comments.

| Parameter     | Type   | Required | Description                     |
| ------------- | ------ | -------- | ------------------------------- |
| `owner`       | string | yes      | GitHub username or organization |
| `repo`        | string | yes      | Repository name                 |
| `pull_number` | number | yes      | PR number                       |
| `status`      | string | no       | `PENDING` (default) or `PUBLIC` |

The prompt instructs Claude to focus on:
- Bugs and logic errors
- Security vulnerabilities
- Performance issues
- Code style and readability
- Missing error handling

### `review_pr_auto` — autonomous review

Just fetches the diff and lets the LLM review freely using its own judgment — no rigid checklist.

| Parameter     | Type   | Required | Description                     |
| ------------- | ------ | -------- | ------------------------------- |
| `owner`       | string | yes      | GitHub username or organization |
| `repo`        | string | yes      | Repository name                 |
| `pull_number` | number | yes      | PR number                       |
| `status`      | string | no       | `PENDING` (default) or `PUBLIC` |

## Tools available

### `get_pull_request_diff`

Fetches the raw diff of a Pull Request from GitHub.

| Parameter     | Type   | Description                     |
| ------------- | ------ | ------------------------------- |
| `owner`       | string | GitHub username or organization |
| `repo`        | string | Repository name                 |
| `pull_number` | number | PR number                       |

### `post_pr_review_comment`

Posts an inline review comment on a specific line of a changed file.

| Parameter     | Type   | Description                                                                      |
| ------------- | ------ | -------------------------------------------------------------------------------- |
| `owner`       | string | GitHub username or organization                                                  |
| `repo`        | string | Repository name                                                                  |
| `pull_number` | number | PR number                                                                        |
| `path`        | string | File path (e.g. `src/app.js`)                                                    |
| `line`        | number | Line number where the comment will appear                                        |
| `body`        | string | Comment text in Markdown                                                         |
| `status`      | string | `PENDING` saves as a draft (you publish on GitHub); `PUBLIC` submits immediately |

## Prerequisites

- Node.js 18+
- A GitHub Personal Access Token with `repo` scope
- Claude Code (to use as an MCP server)

## Installation

```bash
npm install
```

## Configuration

Create a `.env` file in the project root:

```env
GITHUB_TOKEN=ghp_YourGitHubTokenHere
```

## Running as an MCP server (Claude Code)

Add this server to your Claude Code MCP configuration (`~/.claude/claude_desktop_config.json` or via `claude mcp add`):

```json
{
  "mcpServers": {
    "github-code-reviewer": {
      "command": "npx",
      "args": ["tsx", "/path/to/mcp-github-reviewer/src/index.ts"],
      "env": {
        "GITHUB_TOKEN": "ghp_YourGitHubTokenHere"
      }
    }
  }
}
```

Or start the server manually:

```bash
npx -y @modelcontextprotocol/inspector@latest --mode cli npx tsx src/index.ts
```

## Example usage

---

**Guided review (step-by-step):**

```
Use the prompt review_pr with owner="seu-usuario", repo="seu-repo", pull_number=42
```

---

**Autonomous review (LLM decides):**

```
Use the prompt review_pr_auto with owner="seu-usuario", repo="seu-repo", pull_number=42
```

---

**Publish comments immediately:**

```
Use the prompt review_pr with owner="seu-usuario", repo="seu-repo", pull_number=42, status="PUBLIC"
```

---

**Manual prompt (without using any built-in prompt):**

> Review the PR 360 in seu-usuario/seu-repositorio and use post_pr_review_comment with status: "PENDING" so I can double-check everything on GitHub before publishing.

---

## Project structure

```text
mcp-github-reviewer/
├── src/
│   └── index.ts      # MCP server — exposes tools to Claude
├── package.json
├── tsconfig.json
└── .env              # GITHUB_TOKEN goes here
```

## Dependencies

| Package                     | Role                                          |
| --------------------------- | --------------------------------------------- |
| `@modelcontextprotocol/sdk` | MCP server framework                          |
| `@octokit/rest`             | GitHub API client                             |
| `dotenv`                    | Loads `.env` variables                        |
| `tsx`                       | Runs TypeScript directly without a build step |