# PR Reviews MCP Server

An MCP (Model Context Protocol) server that lets Cursor check GitHub and Codeberg PRs for change requests, reviews, and conversations.

## Features

- **`check_pr_reviews`**: Get complete review feedback, change requests, code comments, and conversations for a PR
- **`get_pr_status`**: Quick summary of PR review status (approvals, change requests, comment counts)
- **`view_diff`**: Render PR or commit diffs in a beautiful GitHub-style HTML viewer and open in browser
- **`view_local_diff`**: View local git changes (uncommitted, staged, or vs remote) in browser

## Setup

### 1. Install Dependencies

```bash
pip install -e .
```

Or with uv (faster):

```bash
uv pip install -e .
```

### 2. Create Access Tokens

**For GitHub:**
1. Go to https://github.com/settings/tokens
2. Click "Generate new token (classic)"
3. Give it a name like "PR Reviews MCP"
4. Select scopes:
   - `repo` (for private repositories)
   - Or just `public_repo` (for public repositories only)
5. Generate and copy the token

**For Codeberg (optional):**
1. Go to https://codeberg.org/user/settings/applications
2. Click "Generate New Token"
3. Give it a name like "PR Reviews MCP"
4. Select scopes:
   - `read:repository` (minimum)
   - Or `write:repository` (if you plan to add write features later)
5. Generate and copy the token

### 3. Configure Environment

```bash
cp .env.example .env
# Edit .env and add your tokens (at least one is required)
```

You need at least one token configured (GitHub or Codeberg) depending on which platforms you want to use.

### 4. Add to Cursor

Add this to your Cursor MCP settings (`~/.cursor/mcp.json` or workspace settings):

```json
{
  "mcpServers": {
    "pr-reviews": {
      "command": "python",
      "args": ["-m", "pr_reviews_mcp.server"],
      "env": {
        "GITHUB_TOKEN": "your_github_token_here",
        "CODEBERG_TOKEN": "your_codeberg_token_here"
      }
    }
  }
}
```

Or if using uv:

```json
{
  "mcpServers": {
    "pr-reviews": {
      "command": "uvx",
      "args": ["--from", "/Users/ryanli/Documents/GitHub/issues-mcp", "pr-reviews-mcp"],
      "env": {
        "GITHUB_TOKEN": "your_github_token_here",
        "CODEBERG_TOKEN": "your_codeberg_token_here"
      }
    }
  }
}
```

## Usage in Cursor

Once configured, you can ask Cursor things like:

- "Check the PR at https://github.com/owner/repo/pull/123 for change requests"
- "What's the review status of https://codeberg.org/owner/repo/pulls/456?"
- "Show me all conversations on this PR"
- "Show me the diff for https://github.com/owner/repo/pull/123"
- "View the changes in https://codeberg.org/owner/repo/commit/abc123"
- "Show me my uncommitted changes"
- "View my staged changes"
- "Compare my branch to origin/main"

The MCP server will fetch:
- ✅ All reviews (approved, changes requested, comments)
- 💬 Code-level review comments
- 📝 General PR conversation comments
- ⚠️ Change requests with reviewer feedback
- 🎨 Beautiful diff viewer with GitHub-style UI

**See [EXAMPLES.md](EXAMPLES.md) for more detailed usage examples and sample outputs.**

## Tools

### check_pr_reviews

Get complete PR review information including all change requests and conversations.

**Input:**
- `pr_url`: Full PR URL (e.g., `https://github.com/owner/repo/pull/123` or `https://codeberg.org/owner/repo/pulls/123`)

**Returns:**
- Change requests with reviewer feedback
- All reviews with states (approved/changes requested/commented)
- Code review comments with file paths and line numbers
- General PR conversation comments

### get_pr_status

Quick summary of PR review status.

**Input:**
- `pr_url`: Full PR URL (GitHub or Codeberg)

**Returns:**
- Number of approvals
- Number of change requests
- Comment counts
- List of reviewers requesting changes

### view_diff

Render PR or commit diff in a beautiful GitHub-style HTML viewer.

**Input:**
- `url`: PR URL or commit URL (e.g., `https://github.com/owner/repo/pull/123` or `https://github.com/owner/repo/commit/abc123`)

**Returns:**
- Opens HTML diff viewer in your browser
- GitHub-style syntax highlighting
- Shows all file changes with additions/deletions
- Dark theme matching GitHub's design

### view_local_diff

View local git changes in browser with GitHub-style formatting.

**Input:**
- `repo_path`: Path to git repository (any directory inside works)
- `diff_type`: (optional) Type of diff:
  - `"uncommitted"` - Working directory changes (default)
  - `"staged"` - Staged changes ready to commit
  - `"branch"` - Compare current branch to remote
- `branch`: (optional) Remote branch to compare against (e.g., `"origin/main"`)

**Returns:**
- Opens HTML diff viewer showing local changes
- Same GitHub-style UI as remote diffs
- No network request needed
- Perfect for reviewing before committing

## Development

Run directly for testing:

```bash
python -m pr_reviews_mcp.server
```

The server communicates via stdio using the MCP protocol.

Run the test script to verify platform detection:

```bash
pip install -e .
python3 test_platforms.py
```

## Platform Support

### GitHub
- Full support for all PR reviews, comments, and conversations
- Uses PyGithub library for robust API access
- Requires `GITHUB_TOKEN` environment variable

### Codeberg
- Full support via Gitea API (Codeberg runs on Gitea)
- Direct REST API calls using httpx
- Requires `CODEBERG_TOKEN` environment variable
- Review state names slightly differ (`REQUEST_CHANGES` vs `CHANGES_REQUESTED`)

Both platforms provide the same features:
- ✅ Review approvals
- ❌ Change requests
- 💬 Code-level review comments with file paths
- 📝 General PR discussion threads