# Azure DevOps PR Reviewer MCP Server

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

A Model Context Protocol (MCP) server for automated code reviews on Azure DevOps Pull Requests. This server enables AI assistants like Claude and Kiro to review PRs, validate requirements, post inline comments, and manage the review workflow automatically.

## Features

- **Get PR Information**: Fetch complete PR details including changed files with full content
- **Validate PRs**: Run comprehensive validation checks (status, reviewers, checklist, work items)
  - Smart reviewer validation: Only checks required reviewers, skips optional reviewers
- **Post Findings**: Create inline comments on specific lines in PR files
  - Enhanced diff analysis with multiple fallback strategies for accurate line mapping
- **Set Review Votes**: Approve, reject, or request changes on PRs
- **List PRs**: Browse open pull requests in repositories

### Recent Improvements

**v1.0.1 (Latest)**
- **Enhanced Diff Computation**: Added intelligent fallback mechanism that computes changed lines from file contents when Azure DevOps API doesn't provide change blocks. This ensures reliable line number mapping for inline comments even in edge cases.
- **Accurate Line Targeting**: Inline comments now only target lines that were actually changed in the PR, preventing comments on unchanged code.
- **Correct Author Attribution**: Comments now correctly @mention the specific file change author rather than defaulting to the PR author for all comments.
- **Smarter Reviewer Validation**: The validation now focuses only on required reviewers and properly skips optional reviewers, providing more accurate PR approval status.

## Installation

### Prerequisites

- Python 3.10 or higher
- Azure DevOps Personal Access Token (PAT) with Code (Read & Write) permissions
- Git installed on your system

### Setup

1. Clone this repository:
```bash
git clone https://github.com/MalinduDilshan/azdo-code-review-mcp.git
cd azdo-code-review-mcp
```

2. Install dependencies:
```bash
pip install -r requirements.txt
```

3. Create a `.env` file in the project root:
```bash
# Azure DevOps Configuration
AZURE_DEVOPS_ORG=your-organization
AZURE_DEVOPS_PROJECT=your-project
AZURE_DEVOPS_PAT=your-personal-access-token
AZURE_DEVOPS_URL=https://dev.azure.com
AZURE_DEVOPS_USER_DISPLAY_NAME=Your Name
AZURE_DEVOPS_USER_EMAIL=your.email@example.com

# Optional: Skip specific reviewer groups
SKIP_REVIEWER_GROUPS=Group1,Group2

# Optional: Skip validations and jump directly to code review
SKIP_VALIDATIONS=false
```

## Usage

### With Kiro AI Assistant

Add to your `.kiro/settings/mcp.json`:

```json
{
  "mcpServers": {
    "azure-devops-reviewer": {
      "command": "python",
      "args": ["-m", "mcp.server"],
      "cwd": "/path/to/azdo-code-review-mcp",
      "env": {
        "AZURE_DEVOPS_ORG": "your-org",
        "AZURE_DEVOPS_PROJECT": "your-project",
        "AZURE_DEVOPS_PAT": "your-pat"
      }
    }
  }
}
```

### With Claude Desktop

Add to your Claude Desktop configuration:

**MacOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
**Windows**: `%APPDATA%\Claude\claude_desktop_config.json`

```json
{
  "mcpServers": {
    "azure-devops-reviewer": {
      "command": "python",
      "args": ["-m", "src.mcp.server"],
      "cwd": "/path/to/azdo-code-review-mcp",
      "env": {
        "AZURE_DEVOPS_ORG": "your-org",
        "AZURE_DEVOPS_PROJECT": "your-project",
        "AZURE_DEVOPS_PAT": "your-pat"
      }
    }
  }
}
```

### Standalone Usage

```python
from src.azure_devops import AzureDevOpsConnector

# Initialize connector
connector = AzureDevOpsConnector(
    organization="my-org",
    project="my-project",
    pat="my-personal-access-token"
)

# Get PR information
pr_info = connector.get_pr_info(pr_number=123, repo_name="my-repo")

# Post a comment
connector.post_inline_comment(
    pr_number=123,
    repo_name="my-repo",
    file_path="/src/main.py",
    line_number=42,
    comment_text="Consider adding error handling here"
)

# Set review vote
connector.set_pr_review_vote(
    pr_number=123,
    repo_name="my-repo",
    vote=10  # 10 = Approved, -5 = Waiting for Author
)
```

## Available Tools

### get_pr
Fetch PR information and all changed files with content in one call.

**Parameters:**
- `pr_url` (optional): Full Azure DevOps PR URL
- `organization`, `project`, `repository`, `pr_number` (alternative to pr_url)

### validate_pr
Run comprehensive PR validation checks including status, reviewers, checklist items, and linked work items.

**Note**: Reviewer validation intelligently focuses on required reviewers only, skipping optional reviewers for more accurate approval status.

**Parameters:**
- Same as `get_pr`

### post_findings
Post code review findings as inline comments on specific lines.

**Key Features:**
- Enhanced with robust diff computation using multiple fallback strategies
- Automatically filters findings to only comment on lines that were actually changed in the PR
- Maps finding lines to nearest changed lines when exact match isn't in the diff (within 5-line distance)
- Correctly attributes comments to the file change author (not just PR author)
- Ensures accurate line number mapping even when Azure DevOps API change blocks are unavailable

**Parameters:**
- PR identification (same as `get_pr`)
- `findings`: Array of objects with:
  - `file_path`: Path to file in PR
  - `line_number`: Line number for comment
  - `comment`: Review comment text
  - `severity`: (optional) "error", "warning", or "info"

### set_vote
Set your review vote on the PR.

**Parameters:**
- PR identification (same as `get_pr`)
- `vote`: -10 (Rejected), -5 (Waiting for Author), 0 (No Vote), 5 (Approved with Suggestions), 10 (Approved)

### list_prs
List open pull requests in a repository.

**Parameters:**
- `organization`, `project`, `repository`

## Configuration Options

| Environment Variable | Required | Default | Description |
|---------------------|----------|---------|-------------|
| `AZURE_DEVOPS_ORG` | Yes | - | Your Azure DevOps organization name |
| `AZURE_DEVOPS_PROJECT` | Yes | - | Default project name |
| `AZURE_DEVOPS_PAT` | Yes | - | Personal Access Token with Code (Read & Write) permissions |
| `AZURE_DEVOPS_URL` | No | `https://dev.azure.com` | Base URL for Azure DevOps |
| `AZURE_DEVOPS_USER_DISPLAY_NAME` | No | - | Display name for review comments |
| `AZURE_DEVOPS_USER_EMAIL` | No | - | Email for review comments |
| `SKIP_REVIEWER_GROUPS` | No | - | Comma-separated list of reviewer groups to skip |
| `SKIP_VALIDATIONS` | No | `false` | Skip validation checks and go directly to review |

## Creating an Azure DevOps PAT

1. Go to your Azure DevOps organization
2. Click on User Settings (top right) → Personal Access Tokens
3. Click "New Token"
4. Set a name and expiration
5. Under "Scopes", select:
   - **Code**: Read & Write
   - **Work Items**: Read (if using work item validation)
6. Click "Create" and copy the token immediately

## Project Structure

```
azdo-code-review-mcp/
├── src/
│   ├── azure_devops/      # Core Azure DevOps integration
│   │   ├── base.py        # Base connector with auth
│   │   ├── connector.py   # Main connector class
│   │   ├── models.py      # Data models
│   │   ├── pr_info.py     # PR information retrieval
│   │   ├── pr_diff.py     # Diff analysis
│   │   ├── pr_comments.py # Comment posting
│   │   └── pr_review.py   # Review and voting
│   ├── mcp/               # MCP server implementation
│   │   ├── server.py      # Main MCP server
│   │   ├── schemas.py     # Tool schemas
│   │   └── tools/         # Tool handlers
│   │       ├── get_pr.py
│   │       ├── validate_pr.py
│   │       ├── post_findings.py
│   │       ├── set_vote.py
│   │       └── list_prs.py
│   └── config.py          # Configuration management
├── tests/
│   └── test_server.py     # Component tests
├── .github/               # GitHub Actions and templates
├── .env.example           # Example environment file
├── requirements.txt       # Python dependencies
└── README.md             # This file
```

## Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

1. Fork the repository
2. Create your feature branch (`git checkout -b feature/AmazingFeature`)
3. Commit your changes (`git commit -m 'Add some AmazingFeature'`)
4. Push to the branch (`git push origin feature/AmazingFeature`)
5. Open a Pull Request

## License

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

## Troubleshooting

### Common Issues

**"Authentication failed"**
- Verify your PAT is correct and hasn't expired
- Ensure the PAT has Code (Read & Write) permissions
- Check that the organization and project names are correct

**"Line number out of range"**
- The server validates line numbers against the actual diff using multiple fallback strategies
- Changed lines are now computed from file contents when API change blocks are unavailable
- Comments are automatically filtered to only target lines that were actually changed in the PR
- If a finding line is not in the diff, the server will attempt to map it to the nearest changed line within a 5-line distance
- Ensure you're commenting on lines that were actually changed in the PR

**"Cannot find PR"**
- Verify the PR number, repository name, and project are correct
- Check that the PR exists and is accessible with your PAT

## Support

For issues, questions, or contributions, please use the [GitHub Issues](https://github.com/MalinduDilshan/azdo-code-review-mcp/issues) page.

## Acknowledgments

Built with the [Model Context Protocol](https://modelcontextprotocol.io/) by Anthropic.