# az-devops-cli-mcp

Azure DevOps MCP tools for **Claude Code** and **Codex CLI** — boards, work items, repos, and PRs.

[![PyPI version](https://img.shields.io/pypi/v/az-devops-cli-mcp)](https://pypi.org/project/az-devops-cli-mcp/)
[![CI](https://github.com/PraiseSinkamba/az-devops-cli-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/PraiseSinkamba/az-devops-cli-mcp/actions)
[![Python 3.10+](https://img.shields.io/pypi/pyversions/az-devops-cli-mcp)](https://pypi.org/project/az-devops-cli-mcp/)

---

## Install & Register

```bash
# 1. Install
pip install az-devops-cli-mcp

# 2. Login (once per machine)
az login
az devops configure --defaults organization=https://dev.azure.com/YOUR_ORG

# 3. Register with Claude Code
claude mcp add az-devops-cli-mcp -- python -m az_devops_cli_mcp.server

# 4. Register with Codex CLI
codex mcp add az-devops-cli-mcp -- python -m az_devops_cli_mcp.server
```

Restart Claude Code or Codex CLI. All 13 tools are ready.

---

## How It Works

The server runs as a **stdio process** — spawned on demand by the client, no ports or background services needed.

```
Claude Code / Codex CLI
        |  spawns on demand
        v
python -m az_devops_cli_mcp.server   (stdin/stdout)
        |
        v
      az CLI  (your az login session)
```

---

## Available Tools (13 total)

### Work Items
| Tool | What it does |
|---|---|
| `create_work_item` | Create Task, Bug, User Story, Epic |
| `get_work_item` | Get item by ID |
| `update_work_item` | Update state, assignment, title |
| `set_iteration` | Assign to sprint (required for Sprint board) |
| `query_work_items` | WIQL query for bulk lookups |
| `link_work_items` | Link items (Child, Parent, Related) |
| `get_work_item_relations` | Verify hierarchy after linking |
| `add_comment` | Add discussion comment / agent log |

### Repos / PRs
| Tool | What it does |
|---|---|
| `list_prs` | List PRs by status |
| `get_pr` | Get PR details |
| `create_pr` | Open a new PR |
| `link_pr_to_work_item` | Trace PR to work item |
| `list_branches` | List repo branches |

---

## AG2 Usage (optional)

```python
from autogen import ConversableAgent
from az_devops_cli_mcp import ALL_TOOLS, WORK_ITEM_TOOLS, REPO_TOOLS

agent = ConversableAgent(
    name="devops_agent",
    tools=ALL_TOOLS,
    system_message="You manage Azure DevOps for LytStore..."
)
```

---

## Configuration

| Method | How |
|---|---|
| `az devops configure` | Preferred — org set globally for your machine |
| `AZURE_DEVOPS_ORG` env var | Per-session override |
| `.env` file | `AZURE_DEVOPS_ORG=https://dev.azure.com/YOUR_ORG` |

---

## Safety

Destructive commands (`delete`, `remove`, `destroy`) are blocked at the core layer.
The agent returns an error and requires explicit user confirmation.

---

## Manual MCP Config (fallback)

If `claude mcp add` / `codex mcp add` aren't available, add this to your config file manually.

**Claude Code** — `~/.claude/claude_desktop_config.json`:
```json
{
  "mcpServers": {
    "az-devops-cli-mcp": {
      "type": "stdio",
      "command": "python",
      "args": ["-m", "az_devops_cli_mcp.server"]
    }
  }
}
```

**Codex CLI** — `~/.codex/config.json`: same block.

---

## Contributing

```bash
git clone https://github.com/PraiseSinkamba/az-devops-cli-mcp
cd az-devops-cli-mcp
pip install -e ".[dev]"
pytest tests/
```