# devops-wrangler

An MCP (Model Context Protocol) server for Azure DevOps work item management. Enables AI assistants like Claude to create, query, update, and manage work items, sprints, and more.

## Installation

### Using npx (recommended)

```bash
npx devops-wrangler
```

### Global installation

```bash
npm install -g devops-wrangler
```

## Configuration

### Claude Code

The easiest way to add the server:

```bash
claude mcp add --transport stdio devops-wrangler -- npx devops-wrangler
```

Or manually add to your MCP settings (`~/.claude/mcp_servers.json`):

```json
{
  "mcpServers": {
    "devops-wrangler": {
      "command": "npx",
      "args": ["devops-wrangler"]
    }
  }
}
```

### Claude Desktop

Add to your Claude Desktop config:

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

```json
{
  "mcpServers": {
    "devops-wrangler": {
      "command": "npx",
      "args": ["devops-wrangler"]
    }
  }
}
```

## Setup

Once configured, use the `ado_configure` tool to connect to your Azure DevOps organization:

```
Configure Azure DevOps with:
- PAT: your-personal-access-token
- Organization: https://dev.azure.com/your-org
```

### Creating a Personal Access Token (PAT)

1. Go to Azure DevOps → User Settings → Personal Access Tokens
2. Create a new token with the following scopes:
   - **Work Items**: Read & Write
   - **Project and Team**: Read
   - **Graph**: Read (for user lookups)

## Available Tools

### Configuration

| Tool | Description |
|------|-------------|
| `ado_configure` | Configure Azure DevOps connection with PAT and organization URL |
| `ado_status` | Check current configuration status |

### Projects

| Tool | Description |
|------|-------------|
| `ado_projects` | List projects, set active project, or list area paths |

### Work Items

| Tool | Description |
|------|-------------|
| `ado_create_items` | Create work items with optional hierarchy (Epic > Feature > User Story > Task) |
| `ado_query_items` | Query existing work items with filters |
| `ado_update_item` | Update work item fields (title, state, assignee, description, etc.) |
| `ado_delete_item` | Delete a work item (soft delete to recycle bin or permanent) |
| `ado_link_item` | Link work items to each other, PRs, commits, or branches |

### Comments & Tags

| Tool | Description |
|------|-------------|
| `ado_comments` | Add or list comments on work items (supports markdown) |
| `ado_tags` | List, add, remove, or query tags |

### Sprints & Plans

| Tool | Description |
|------|-------------|
| `ado_sprints` | List sprints, assign items to sprints, create/delete sprints |
| `ado_plans` | View delivery plans and roadmaps |

## Usage Examples

### Create a feature with user stories

```
Create a Feature called "User Authentication" with these User Stories:
- Implement login page
- Add password reset flow
- Create session management
```

### Query active bugs

```
Show me all active bugs in the project
```

### Add to current sprint

```
Create a Task called "Fix API timeout" and add it to the current sprint
```

### Update work item

```
Update work item #12345 - set state to "Active" and assign to john@example.com
```

## Features

- **Hierarchical work item creation**: Create Epics with Features, User Stories, and Tasks in a single operation
- **Sprint management**: List sprints, create new sprints, assign work items to current sprint
- **Markdown support**: Comments and descriptions support full markdown formatting
- **Tag management**: Add, remove, and query work items by tags
- **Linking**: Connect work items to each other, pull requests, commits, or branches

## License

ISC