# Azure DevOps MCP Server

A Model Context Protocol (MCP) server that provides AI-powered tools for interacting with Azure DevOps repositories, pull requests, and work items. Built with FastMCP for seamless integration with Claude and other MCP-compatible AI assistants.

## Features

- **Project Discovery** - List all accessible Azure DevOps projects
- **Repository Management** - Resolve repository IDs, list branches
- **Pull Request Operations** - List, create, inspect, and comment on PRs
- **Work Item Management** - Create PBIs, Bugs, and custom work items
- **Diff Analysis** - Fetch complete unified diffs with original and modified content
- **Code Review** - Built-in review policy and automated review capabilities
- **PR-Work Item Linking** - Link pull requests to work items
- **Auto-Discovery** - Automatic tool and resource registration
- **Extensible Architecture** - Simple pattern for adding new functionality

## Project Structure

```
AzureDevopsMcp/
├── src/
│   ├── config.py              # Global MCP instance & configuration
│   ├── client.py              # HTTP client for Azure DevOps API
│   ├── server.py              # Server entry point
│   ├── utils/
│   │   └── helpers.py         # Helper functions (repo resolution, blob fetching)
│   ├── tools/
│   │   ├── __init__.py        # Auto-import tool modules
│   │   ├── repository.py      # Repository & project tools
│   │   ├── pull_requests.py   # Pull request tools
│   │   └── work_items.py      # Work item tools (PBI, Bug, etc.)
│   └── policies/
│       ├── __init__.py        # Auto-import policy modules
│       └── review_policy.py   # Code review policy resource
├── main.py                    # Application entry point
├── requirements.txt           # Python dependencies
├── .env                       # Environment configuration
└── README.md
```

## Setup

### 1. Clone and Install

```bash
git clone <repository-url>
cd AzureDevopsMcp
pip install -r requirements.txt
```

### 2. Configure Environment

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

```env
ADO_ORG_URL=https://dev.azure.com/YourOrganization
ADO_PROJECT=YourDefaultProject
ADO_PAT=your_personal_access_token_here
```

**Getting a Personal Access Token (PAT):**
1. Go to Azure DevOps → User Settings → Personal Access Tokens
2. Create new token with permissions:
   - `Code (Read & Write)` - for repository and PR operations
   - `Pull Request Threads (Read & Write)` - for PR comments
   - `Work Items (Read & Write)` - for creating/updating work items
3. Copy the token to your `.env` file

### 3. Run the Server

```bash
python main.py
```

The server will run in stdio mode, ready to accept MCP protocol requests.

## Available Tools

### Project & Repository Tools

#### `list_projects() -> List[Dict]`
Lists all Azure DevOps projects you have access to.

**Returns:** List of projects with name, id, description, and state.

**Usage:** Call this before creating work items to discover available projects.

---

#### `resolve_repo_id(repo_key: str, project: str = None) -> str`
Converts a repository name to its GUID identifier.

**Parameters:**
- `repo_key` - Repository name (e.g., "my-api") or GUID

**Returns:** Repository GUID

---

#### `list_branches(repo_id: str, filter_name: str = None, top: int = 100) -> List[Dict]`
Lists branches in a repository.

**Parameters:**
- `repo_id` - Repository GUID from `resolve_repo_id`
- `filter_name` - Optional filter by name prefix (e.g., "feature/")
- `top` - Maximum number of branches to return

**Returns:** List of branches with name, fullName, isDefault, creator, objectId

---

### Pull Request Tools

#### `list_pull_requests(repo_id: str, status: str = "active", top: int = 10) -> List[Dict]`
Lists pull requests for a repository.

**Parameters:**
- `repo_id` - Repository GUID
- `status` - Filter: `"active"`, `"completed"`, `"abandoned"`
- `top` - Maximum number of PRs

---

#### `get_pull_request(repo_id: str, pr_id: int) -> str`
Retrieves detailed information about a specific pull request.

---

#### `create_pull_request(repo_id: str, source_branch: str, target_branch: str, title: str, description: str = None, work_item_ids: List[int] = None) -> Dict`
Creates a new pull request.

**Parameters:**
- `repo_id` - Repository GUID
- `source_branch` - Full ref name (e.g., "refs/heads/feature/my-feature")
- `target_branch` - Full ref name (e.g., "refs/heads/main")
- `title` - PR title
- `description` - Optional PR description
- `work_item_ids` - Optional list of work item IDs to link

**Returns:** Created PR details including id, url, title, status

---

#### `set_pr_description(repo_id: str, pr_id: int, description: str) -> Dict`
Updates the description of an existing pull request.

**LLM Instructions:** The description should include a structured format with:
- Summary section with bullet points
- Test plan section with checkboxes
- Auto-detected checkboxes for tests and documentation based on diff analysis

---

#### `get_pull_request_full_diff(repo_id: str, pr_id: int) -> Dict`
Fetches complete diff and all review comments for a PR.

---

#### `add_pull_request_comment(repo_id: str, pr_id: int, comment: str, file_path: str = None, line: int = None) -> str`
Adds a comment to a pull request (top-level or inline).

---

#### `link_pr_to_work_item(repo_id: str, pr_id: int, work_item_id: int, project: str) -> Dict`
Links a pull request to a work item.

---

### Work Item Tools

#### `list_work_item_types(project: str) -> List[Dict]`
Lists all available work item types in a project.

**Usage:** Call this to discover what work item types are available (Bug, PBI, Task, etc.).

---

#### `list_area_paths(project: str, depth: int = 3) -> List[Dict]`
Lists all area paths in a project for organizing work items.

---

#### `list_iteration_paths(project: str, depth: int = 3) -> List[Dict]`
Lists all iteration paths (sprints) in a project.

---

#### `create_product_backlog_item(project: str, title: str, assigned_to: str, ...) -> Dict`
Creates a new Product Backlog Item (PBI).

**Required Parameters:**
- `project` - Project name (use `list_projects()` first)
- `title` - PBI title
- `assigned_to` - Email or display name of assignee

**Optional Parameters:**
- `description` - HTML description
- `acceptance_criteria` - HTML acceptance criteria
- `area_path` - Area path for organization
- `iteration_path` - Sprint assignment
- `priority` - Priority (1-4)
- `tags` - Semicolon-separated tags

---

#### `create_bug(project: str, title: str, assigned_to: str, description: str, steps_to_reproduce: str, expected_behavior: str, ...) -> Dict`
Creates a new Bug work item (using custom "Bugs" type with required fields).

**Required Parameters:**
- `project` - Project name
- `title` - Bug title
- `assigned_to` - Assignee
- `description` - Bug description
- `steps_to_reproduce` - Steps to reproduce the bug
- `expected_behavior` - Expected app behavior

**Optional Parameters:**
- `environment` - Environment (default: "Dev")
- `area_path`, `iteration_path`, `priority`, `tags`

---

#### `create_work_item(project: str, work_item_type: str, title: str, assigned_to: str, ...) -> Dict`
Creates a work item of ANY type. Most flexible tool for custom work item types.

**Parameters:**
- `work_item_type` - Exact type name from `list_work_item_types()`
- `custom_fields` - Dict of custom field reference names to values

**Example with custom fields:**
```python
create_work_item(
    project="MyProject",
    work_item_type="Bugs",
    title="Fix login error",
    assigned_to="john@company.com",
    custom_fields={
        "Custom.Environment": "Dev",
        "Custom.Stepstoreproduce": "1. Go to login\n2. Click submit",
        "Custom.Expectedappbehavior": "User should be logged in"
    }
)
```

---

## Resources

### `policy://review` - Code Review Policy
Official code review standards and expectations for PR reviews.

**Usage:** LLMs should load this resource before performing automated code reviews.

## Extending the Server

### Adding a New Tool

**Step 1:** Create your tool module in `src/tools/`

```python
# src/tools/my_tools.py
from ..config import mcp, ADO_ORG_URL
from ..client import client

@mcp.tool()
def my_new_tool(param: str) -> dict:
    """Tool description for LLM."""
    # Implementation
    pass
```

**Step 2:** Register in `src/tools/__init__.py`

```python
from . import my_tools  # noqa: F401
```

### Adding a New Resource

**Step 1:** Create resource module in `src/policies/`

```python
# src/policies/my_policy.py
from ..config import mcp

@mcp.resource(uri="policy://my-policy", name="My Policy", description="...")
def get_my_policy() -> str:
    return "Policy content..."
```

**Step 2:** Register in `src/policies/__init__.py`

## Architecture

- **Global MCP Instance** (`src/config.py`) - Single FastMCP instance shared across all modules
- **Auto-Discovery** - Modules self-register by importing in `__init__.py`
- **Separation of Concerns** - Tools, resources, utilities, and configuration cleanly separated
- **Type Safety** - Full type hints for better IDE support and error checking

## Contributing

Contributions welcome! Please follow the existing code structure and patterns when adding new functionality.