# Azure DevOps MCP Server

MCP (Model Context Protocol) server for managing Azure DevOps Work Items including Epics, Features, User Stories, Tasks, Bugs, and more.

## Features

- **Read Work Items**: Get individual work items or list by type with filters
- **Create Work Items**: Create Epics, Features, User Stories, Tasks, Bugs, etc.
- **Update Work Items**: Modify any field including state, assignment, description
- **Delete Work Items**: Move to recycle bin or permanently delete
- **Query Work Items**: Execute custom WIQL queries
- **Link Work Items**: Create parent-child and other relationships
- **Get Metadata**: List work item types, iterations, and area paths

## Prerequisites

- Node.js 18 or higher
- Azure DevOps account with a Personal Access Token (PAT)
- PAT needs `Work Items (Read & Write)` scope

## Installation

```bash
npm install
npm run build
```

## Configuration

Set the following environment variables:

```bash
export AZURE_DEVOPS_ORG="your-organization"
export AZURE_DEVOPS_PROJECT="your-project"
export AZURE_DEVOPS_PAT="your-personal-access-token"
```

### Creating a PAT

1. Go to Azure DevOps > User Settings > Personal Access Tokens
2. Create new token with these scopes:
   - Work Items: Read & Write
3. Copy the token (you won't see it again!)

## Usage with Claude Desktop

Add to your Claude Desktop configuration (`claude_desktop_config.json`):

```json
{
  "mcpServers": {
    "azure-devops": {
      "command": "node",
      "args": ["path/to/azure-devops-mcp/dist/index.js"],
      "env": {
        "AZURE_DEVOPS_ORG": "your-organization",
        "AZURE_DEVOPS_PROJECT": "your-project",
        "AZURE_DEVOPS_PAT": "your-pat"
      }
    }
  }
}
```

## Available Tools

### get_work_item
Get a single work item by ID.

```json
{
  "id": 123,
  "expand": "Relations"
}
```

### list_work_items
List work items by type with optional filters.

```json
{
  "type": "User Story",
  "state": "Active",
  "assignedTo": "user@example.com",
  "top": 10
}
```

### create_work_item
Create a new work item.

```json
{
  "type": "Task",
  "title": "Implement login feature",
  "description": "<p>Details here</p>",
  "assignedTo": "developer@example.com",
  "priority": 2,
  "parentId": 100
}
```

### update_work_item
Update an existing work item.

```json
{
  "id": 123,
  "state": "Resolved",
  "comment": "Fixed the issue"
}
```

### delete_work_item
Delete a work item.

```json
{
  "id": 123,
  "permanent": false
}
```

### query_work_items
Execute a WIQL query.

```json
{
  "query": "SELECT [System.Id] FROM WorkItems WHERE [System.State] = 'Active' AND [System.AssignedTo] = @Me"
}
```

### get_child_work_items
Get all children of a work item.

```json
{
  "parentId": 100
}
```

### link_work_items
Link two work items.

```json
{
  "sourceId": 100,
  "targetId": 101,
  "linkType": "System.LinkTypes.Hierarchy-Forward",
  "comment": "Added as child"
}
```

### get_work_item_types
List available work item types.

### get_iterations
List project iterations/sprints.

### get_area_paths
List project area paths.

## Common Link Types

- `System.LinkTypes.Hierarchy-Forward` - Parent to Child
- `System.LinkTypes.Hierarchy-Reverse` - Child to Parent
- `System.LinkTypes.Related` - Related work items
- `System.LinkTypes.Dependency-Forward` - Successor
- `System.LinkTypes.Dependency-Reverse` - Predecessor

## Common Work Item Fields

- `System.Title` - Title
- `System.Description` - Description (HTML)
- `System.State` - State (New, Active, Resolved, Closed)
- `System.AssignedTo` - Assigned user
- `System.AreaPath` - Area path
- `System.IterationPath` - Iteration/Sprint
- `System.Tags` - Tags (semicolon separated)
- `Microsoft.VSTS.Common.Priority` - Priority (1-4)
- `Microsoft.VSTS.Scheduling.StoryPoints` - Story points
- `Microsoft.VSTS.Scheduling.OriginalEstimate` - Original estimate
- `Microsoft.VSTS.Scheduling.RemainingWork` - Remaining work
- `Microsoft.VSTS.Common.AcceptanceCriteria` - Acceptance criteria

## License

MIT