# Azure DevOps MCP Server

MCP (Model Context Protocol) server for Azure DevOps Work Item Tracking integration. Enables AI assistants like Claude to search, create, update, and manage work items in Azure DevOps.

## Features

- **Search Work Items**: Query using WIQL (Work Item Query Language)
- **Get Work Item**: Retrieve detailed work item information by ID
- **Create Work Item**: Create Bugs, Tasks, User Stories, Features, etc.
- **Update Work Item**: Modify fields, change state, update assignments
- **Add Comments**: Add discussion comments to work items

## Installation

```bash
npm install @bugzy-ai/azure-devops-mcp-server
```

Or run directly with npx:

```bash
npx @bugzy-ai/azure-devops-mcp-server
```

## Configuration

### Environment Variables

| Variable | Required | Description |
|----------|----------|-------------|
| `AZURE_DEVOPS_ORG_URL` | Yes | Organization URL (e.g., `https://dev.azure.com/myorg`) |
| `AZURE_DEVOPS_PAT` | Yes | Personal Access Token |
| `AZURE_DEVOPS_MCP_DEBUG` | No | Enable debug logging to `.azure-devops-mcp/mcp.log` |

> **Note:** Project name is specified per-request, not via environment variable. The AI agent discovers the project from context (e.g., `.bugzy/runtime/project-context.md`) or uses `azuredevops_list_projects` to find available projects.

### Creating a Personal Access Token (PAT)

1. Go to Azure DevOps → User Settings → Personal Access Tokens
2. Click "New Token"
3. Set the required scopes:
   - `vso.work` - Read work items
   - `vso.work_write` - Create and update work items
4. Copy the token and set it as `AZURE_DEVOPS_PAT`

### MCP Configuration

Add to your MCP configuration file (e.g., `claude_desktop_config.json`):

```json
{
  "mcpServers": {
    "azure-devops": {
      "command": "npx",
      "args": ["@bugzy-ai/azure-devops-mcp-server"],
      "env": {
        "AZURE_DEVOPS_ORG_URL": "https://dev.azure.com/your-org",
        "AZURE_DEVOPS_PAT": "your-pat-token"
      }
    }
  }
}
```

## Tools

### azuredevops_list_projects

List all projects in the Azure DevOps organization. Use this to discover available projects.

```typescript
{
  top?: number,   // Max projects to return (default: 100, max: 100)
  skip?: number   // Number to skip for pagination (default: 0)
}
```

### azuredevops_search_work_items

Search for work items using WIQL queries.

```typescript
{
  project: string,     // Azure DevOps project name (required)
  wiql: string,        // WIQL query
  maxResults?: number  // Max results (default: 50, max: 200)
}
```

**Example WIQL queries:**

```sql
-- Find open bugs
SELECT [System.Id], [System.Title], [System.State]
FROM WorkItems
WHERE [System.WorkItemType] = 'Bug'
  AND [System.State] <> 'Closed'
ORDER BY [System.CreatedDate] DESC

-- Find work items assigned to me
SELECT [System.Id], [System.Title]
FROM WorkItems
WHERE [System.AssignedTo] = @Me
  AND [System.State] = 'Active'

-- Find recent items in a specific area
SELECT [System.Id], [System.Title], [System.WorkItemType]
FROM WorkItems
WHERE [System.AreaPath] UNDER 'Project\Team'
  AND [System.CreatedDate] >= @Today - 7
```

### azuredevops_get_work_item

Get detailed information about a work item.

```typescript
{
  project: string,      // Azure DevOps project name (required)
  id: number,           // Work item ID
  fields?: string[],    // Specific fields to retrieve
  expand?: "None" | "Relations" | "Fields" | "Links" | "All"
}
```

### azuredevops_create_work_item

Create a new work item.

```typescript
{
  project: string,       // Azure DevOps project name (required)
  type: string,          // "Bug", "Task", "User Story", etc.
  title: string,         // Work item title
  description?: string,  // Description (HTML supported)
  areaPath?: string,     // Area path
  iterationPath?: string,// Iteration/sprint path
  assignedTo?: string,   // User email or display name
  priority?: number,     // 1-4 (1=Critical, 4=Low)
  severity?: string,     // For bugs: "1 - Critical", "2 - High", etc.
  tags?: string,         // Semicolon-separated tags
  parentId?: number      // Parent work item ID
}
```

### azuredevops_update_work_item

Update an existing work item using JSON Patch operations.

```typescript
{
  project: string,  // Azure DevOps project name (required)
  id: number,
  operations: Array<{
    op: "add" | "remove" | "replace",
    path: string,   // e.g., "/fields/System.State"
    value?: any
  }>
}
```

**Example - Change state to Active:**

```json
{
  "id": 123,
  "operations": [
    { "op": "replace", "path": "/fields/System.State", "value": "Active" }
  ]
}
```

### azuredevops_add_comment

Add a comment to a work item.

```typescript
{
  project: string,  // Azure DevOps project name (required)
  id: number,       // Work item ID
  text: string      // Comment text (HTML supported)
}
```

## Development

```bash
# Install dependencies
npm install

# Build
npm run build

# Run with MCP Inspector (for testing)
npm run dev

# Watch mode
npm run build:watch
```

## Debugging

Enable debug logging by setting `AZURE_DEVOPS_MCP_DEBUG=true`. Logs are written to `.azure-devops-mcp/mcp.log`.

## License

MIT