# ADO MCP Server — Azure DevOps × Claude Code Bridge

Connects **Azure DevOps work items** to **Claude Code** via the MCP protocol.  
Type `work on task #123` in Claude Code → it fetches the full ticket → writes code → opens a PR.

---

## Project Structure

```
ado-mcp-server/
├── src/
│   ├── index.js              # MCP server entry point (4 tools exposed)
│   ├── ado-client.js         # Azure DevOps HTTP client (PAT auth)
│   └── tools/
│       ├── get-ticket.js     # ado_get_work_item
│       ├── list-tickets.js   # ado_list_work_items
│       └── update-ticket.js  # ado_update_work_item_state + ado_add_comment
├── CLAUDE.md                 # ← Copy this to your GitHub repo root!
├── .env                      # Your secrets (never commit this)
├── .env.example              # Template
└── package.json
```

---

## Setup (One-Time)

### 1. Configure your credentials

```bash
# .env
ADO_ORG=your-actual-org-name          # found in: https://dev.azure.com/{ORG}
ADO_PROJECT=your-actual-project-name
ADO_PAT=xxxxxxxxxxxxxxxxxxxxxxxxxxxx   # from ADO → User Settings → PATs
```

**Create a PAT in Azure DevOps:**
1. Go to `https://dev.azure.com/{your-org}`
2. Click your avatar → **Personal Access Tokens**
3. **New Token** → Name it `claude-mcp`
4. Scopes: `Work Items → Read & Write`
5. Copy the token into `.env`

### 2. Install dependencies

```bash
cd E:\MCP\ado-mcp-server
npm install
```

### 3. Register with Claude Code CLI

```bash
claude mcp add ado-server node E:\MCP\ado-mcp-server\src\index.js
```

**Or manually** add to `%APPDATA%\Claude\claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "ado-server": {
      "command": "node",
      "args": ["E:\\MCP\\ado-mcp-server\\src\\index.js"]
    }
  }
}
```

### 4. Install GitHub CLI (for PR creation)

```bash
winget install GitHub.cli
gh auth login
```

### 5. Copy CLAUDE.md to your GitHub repo root

```bash
copy E:\MCP\ado-mcp-server\CLAUDE.md C:\path\to\your-github-repo\CLAUDE.md
```

---

## Daily Usage

```bash
# Open Claude Code in your repo
cd C:\path\to\your-github-repo
claude
```

Then just type any of these:

```
> work on task #123
> implement PBI 456
> what's in the current sprint?
> show me unassigned bugs
> list tasks assigned to me
```

Claude will automatically:
1. Fetch the full ticket from Azure DevOps
2. Mark it as "In Progress"
3. Create a feature branch
4. Write the code following the acceptance criteria
5. Commit and push
6. Create a PR on GitHub
7. Post the PR link as a comment on the ADO ticket

---

## Available MCP Tools

| Tool | Description | Example Prompt |
|------|-------------|----------------|
| `ado_get_work_item` | Full ticket details | "work on task #123" |
| `ado_list_work_items` | List/filter tickets | "show sprint backlog" |
| `ado_update_work_item_state` | Change ticket state | auto-called when starting/completing |
| `ado_add_comment` | Add comment to ticket | auto-called after PR creation |

---

## Troubleshooting

**"Missing required environment variables"**  
→ Make sure `.env` exists and has all 3 values: `ADO_ORG`, `ADO_PROJECT`, `ADO_PAT`

**"401 Unauthorized"**  
→ Your PAT may be expired or missing `Work Items (Read & Write)` scope. Regenerate it.

**"Tool not found in Claude Code"**  
→ Run `claude mcp list` to verify the server is registered. Re-run the `claude mcp add` command.

**PR creation fails**  
→ Run `gh auth status` — make sure GitHub CLI is authenticated.