# pr-genie-mcp

An AI-powered [MCP server](https://modelcontextprotocol.io) that converts Azure DevOps work items into complete pull requests. Point it at a work item, and it handles the rest -- branch creation, code changes, build validation, PR submission, and work item updates.

Works with **any MCP client**: Claude Code, GitHub Copilot, Cursor, Windsurf, and more.

## Quick start

### 1. Install

```bash
npm install -g pr-genie-mcp
```

Or run directly with npx (no install needed):

```bash
npx pr-genie-mcp
```

### 2. Set environment variables

Create a `.env` file in your project root, or export these variables:

```bash
# Azure DevOps organization URL (both formats supported)
ADO_ORG_URL=https://dev.azure.com/your-org
# ADO_ORG_URL=https://your-org.visualstudio.com

# Default project name
ADO_PROJECT=YourProject

# Personal Access Token (scopes: Work Items R/W, Code R/W, Pull Requests R/W)
ADO_PAT=your-pat-here
```

### 3. Connect to your MCP client

See [MCP client configuration](#mcp-client-configuration) below.

---

## MCP client configuration

### Claude Code

Add to your project's `.mcp.json`:

```json
{
  "mcpServers": {
    "pr-genie": {
      "command": "npx",
      "args": ["-y", "pr-genie-mcp"],
      "env": {
        "ADO_ORG_URL": "https://dev.azure.com/your-org",
        "ADO_PROJECT": "YourProject",
        "ADO_PAT": "your-pat-here"
      }
    }
  }
}
```

### GitHub Copilot (VS Code)

Add to `.vscode/mcp.json` in your workspace:

```json
{
  "servers": {
    "pr-genie": {
      "command": "npx",
      "args": ["-y", "pr-genie-mcp"],
      "env": {
        "ADO_ORG_URL": "https://dev.azure.com/your-org",
        "ADO_PROJECT": "YourProject",
        "ADO_PAT": "your-pat-here"
      }
    }
  }
}
```

### Cursor

Add to your Cursor MCP settings (Settings > MCP Servers > Add):

```json
{
  "mcpServers": {
    "pr-genie": {
      "command": "npx",
      "args": ["-y", "pr-genie-mcp"],
      "env": {
        "ADO_ORG_URL": "https://dev.azure.com/your-org",
        "ADO_PROJECT": "YourProject",
        "ADO_PAT": "your-pat-here"
      }
    }
  }
}
```

### Windsurf

Add to `~/.codeium/windsurf/mcp_config.json`:

```json
{
  "mcpServers": {
    "pr-genie": {
      "command": "npx",
      "args": ["-y", "pr-genie-mcp"],
      "env": {
        "ADO_ORG_URL": "https://dev.azure.com/your-org",
        "ADO_PROJECT": "YourProject",
        "ADO_PAT": "your-pat-here"
      }
    }
  }
}
```

> **Tip**: Instead of putting secrets in config files, set `ADO_PAT` as a system environment variable and omit it from the `env` block.

---

## Repository-level configuration (optional)

Create a `.pr-genierc.json` in your target repository root to customize build, test, and lint commands:

```json
{
  "build": "dotnet build MyApp.sln",
  "test": "dotnet test Tests/Tests.csproj --no-build",
  "lint": "dotnet format --verify-no-changes",
  "testTimeout": 120000,

  "branch": {
    "base": "develop/v4",
    "naming": "users/{user}/wi{id}-{slug}"
  },

  "pr": {
    "draft": true,
    "targetBranch": "develop/v4",
    "mergeStrategy": "squash"
  },

  "safety": {
    "sensitivePatterns": [".env*", "*.key", "*.pem"],
    "maxFilesChanged": 20,
    "maxLinesChanged": 500
  }
}
```

If no `.pr-genierc.json` is found, pr-genie auto-detects your project type (Node.js, .NET, Python, Go, Java, Rust) and uses sensible defaults.

---

## Available tools

### Discovery

| Tool | Description |
|------|-------------|
| `fetch_work_item` | Fetch complete work item with fields, relations, comments, and images |
| `fetch_work_item_attachments` | Download all attachments (images as visual content, text as text) |

### Repository setup

| Tool | Description |
|------|-------------|
| `clone_repo` | Clone an ADO Git repository with PAT auth |
| `create_feature_branch` | Create a feature branch from the default branch |
| `push_branch` | Push current branch to remote |

### Code intelligence

| Tool | Description |
|------|-------------|
| `detect_project_type` | Identify language, framework, build system, test runner, linter |
| `search_code` | Full-text git grep search with context lines |
| `get_coding_standards` | Read .editorconfig, linter configs, CONTRIBUTING.md, CODEOWNERS |

### Build and validation

| Tool | Description |
|------|-------------|
| `run_build` | Execute build command (from config or auto-detect) |
| `run_tests` | Run test suite with configurable targeting |
| `run_linter` | Run linter with optional auto-fix |
| `validate_no_secrets` | Scan staged changes for hardcoded secrets |

### Pull request lifecycle

| Tool | Description |
|------|-------------|
| `create_pull_request` | Create a PR in Azure DevOps |
| `link_pr_to_work_item` | Create bidirectional PR/work item link |
| `get_pr_details` | Fetch PR metadata, reviewer votes, threads, build status |
| `reply_to_pr_comment` | Post reply to a PR comment thread |
| `update_pr_thread_status` | Mark thread as fixed, resolved, won't fix, etc. |

### Work item management

| Tool | Description |
|------|-------------|
| `add_work_item_comment` | Post comment to work item discussion |
| `update_work_item_state` | Change work item state, assignee, or tags |
| `ping` | Health check -- verifies the server is running |

### Browser tools (optional)

Requires `playwright` to be installed separately.

| Tool | Description |
|------|-------------|
| `browser_launch` | Launch browser and navigate to URL |
| `browser_click` | Click elements by selector |
| `browser_type` | Type into input fields |
| `browser_close` | Close browser session |

```bash
# Install playwright for browser tools
npm install playwright
npx playwright install chromium
```

---

## Guided prompts

pr-genie includes three guided workflows that orchestrate multiple tools:

| Prompt | Description |
|--------|-------------|
| `generate-pr` | End-to-end: work item -> clone -> branch -> implement -> validate -> PR |
| `resolve-pr-comments` | Address reviewer feedback: analyze threads -> fix code -> reply -> push |
| `repro-bug` | Visual bug reproduction with browser screenshots |

---

## How it works

1. **You** point your AI assistant at a work item: "Implement work item #12345"
2. **pr-genie** fetches the work item, clones the repo, creates a branch
3. **Your AI** reads the code, understands the codebase, implements changes
4. **pr-genie** runs builds, tests, linters, scans for secrets
5. **pr-genie** creates the PR, links it to the work item, updates the state

The AI stays in the loop at every step. You review and approve before anything ships.

---

## Prerequisites

- **Node.js** 20 or later
- **Git** installed and in PATH
- **Azure DevOps PAT** with Work Items, Code, and Pull Requests read/write scopes

---

## Development

```bash
git clone https://github.com/AirWalk-Digital/Camp-AIR.git
cd Camp-AIR/pr-genie
npm install
npm run build
npm start
```

Watch mode for development:

```bash
npm run dev
```

---

## License

MIT