Azure DevOps MCP Server

ADO MCP Logo

This MCP (Model Context Protocol) server provides tools for interacting with Azure DevOps services through AI assistants.

Architecture

The server follows an entity-based architecture that groups operations by resource type rather than exposing many atomic tools. This approach provides several benefits:

Intuitive organization: Tools are organized by the entities they operate on (projects, repositories, work items, etc.)
Reduced tool count: Instead of dozens of individual tools, we have a handful of entity tools with multiple operations
Consistent interface: All entity tools follow the same pattern for operations and parameters
Better error handling: Each entity tool can handle errors specific to its domain
Easier discovery: Users can easily discover available operations for each entity

Architecture Diagram

hljs language-mermaid

flowchart TB
    Client[AI Assistant] -->|MCP Request| Server[MCP Server]
    Server -->|MCP Response| Client
    
    subgraph "Azure DevOps MCP Server"
        Server --> RequestHandler[Request Handler]
        RequestHandler --> ToolRegistry[Tool Registry]
        ToolRegistry --> EntityTools[Entity Tools]
        EntityTools --> ApiClient[API Client]
        ApiClient --> ErrorUtils[Error Utilities]
        ApiClient --> PaginationUtils[Pagination Utilities]
        ApiClient -->|HTTP Request| AzureDevOps[Azure DevOps API]
        AzureDevOps -->|HTTP Response| ApiClient
        ConfigManager[Configuration Manager] --> ApiClient
    end
    
    classDef primary fill:#4285F4,stroke:#0D47A1,color:white
    classDef secondary fill:#34A853,stroke:#0D652D,color:white
    classDef utility fill:#FBBC05,stroke:#866A00,color:white
    classDef external fill:#EA4335,stroke:#980905,color:white
    
    class Server,RequestHandler primary
    class ToolRegistry,EntityTools,ApiClient secondary
    class ErrorUtils,PaginationUtils,ConfigManager utility
    class Client,AzureDevOps external

Component Structure

hljs language-mermaid

classDiagram
    class EntityTool {
        +name: string
        +description: string
        +operations: Record~string, Function~
        +schemas: Record~string, ZodSchema~
        +getDefinition(): ToolDefinition
        +execute(args: unknown): Promise~any~
        #registerOperation(operation, handler, schema, description)
    }
    
    class ADOApiClient {
        +config: ADOApiConfig
        +connection: WebApi
        +getCoreApi()
        +getWorkItemTrackingApi()
        +getGitApi()
        +getPipelineApi()
        +handleError(error, context)
    }
    
    class ToolRegistry {
        +registerTool(tool: Tool)
        +getTool(name: string): Tool
        +getToolDefinitions(): ToolDefinition[]
    }
    
    class ErrorUtils {
        +createError(code, message, context)
        +handleApiError(error, source, operation)
    }
    
    class PaginationUtils {
        +normalizePaginationParams(params)
        +createPaginationResult(items, totalCount, continuationToken)
        +encodeContinuationToken(data)
        +decodeContinuationToken(token)
    }
    
    EntityTool --> ADOApiClient : uses
    EntityTool --> ErrorUtils : uses
    EntityTool --> PaginationUtils : uses
    ToolRegistry --> EntityTool : registers

Key Components

Entity Tools: Each tool represents a major Azure DevOps entity (projects, repositories, work items, etc.) and provides multiple operations (list, get, create, etc.)
Tool Registry: Manages the registration and execution of entity tools
API Client: Handles communication with the Azure DevOps REST API
Error Utilities: Provides standardized error handling with detailed context and user-friendly messages
Pagination Utilities: Implements cursor-based pagination for list operations
Configuration Manager: Loads and validates configuration from environment variables or config file

Recent Improvements

1. Enhanced Error Handling

The server now includes a comprehensive error handling system that provides:

Categorized errors: Errors are categorized by type (authentication, authorization, validation, etc.)
Contextual information: Errors include the source, operation, and other relevant context
User-friendly messages: Error messages are designed to be helpful and actionable
Troubleshooting tips: Where applicable, errors include suggestions for resolving the issue

hljs language-mermaid

flowchart LR
    Error[API Error] --> Handler[Error Handler]
    Handler --> Category{Categorize}
    Category -->|Authentication| AuthError[Authentication Error]
    Category -->|Authorization| AuthzError[Authorization Error]
    Category -->|Not Found| NotFoundError[Not Found Error]
    Category -->|Validation| ValidationError[Validation Error]
    Category -->|Rate Limit| RateLimitError[Rate Limit Error]
    Category -->|Service| ServiceError[Service Error]
    Category -->|Unknown| UnknownError[Unknown Error]
    
    AuthError & AuthzError & NotFoundError & ValidationError & RateLimitError & ServiceError & UnknownError --> Format[Format User Message]
    Format --> McpError[MCP Error Response]
    
    classDef error fill:#EA4335,stroke:#980905,color:white
    classDef process fill:#4285F4,stroke:#0D47A1,color:white
    classDef result fill:#34A853,stroke:#0D652D,color:white
    
    class Error,AuthError,AuthzError,NotFoundError,ValidationError,RateLimitError,ServiceError,UnknownError error
    class Handler,Category,Format process
    class McpError result

2. Cursor-based Pagination

All list operations now support cursor-based pagination with:

Continuation tokens: Encoded tokens for resuming pagination
Customizable page size: Control the number of results per page
Consistent interface: Same pagination parameters across all list operations
Efficient resource usage: Only fetch the data you need

hljs language-mermaid

sequenceDiagram
    participant Client as AI Assistant
    participant Server as MCP Server
    participant API as Azure DevOps API
    
    Client->>Server: List request (maxResults=10)
    Server->>API: API request (top=10, skip=0)
    API->>Server: Response with items
    
    Note over Server: Create continuation token
    
    Server->>Client: Response with items and token
    
    Client->>Server: List request with token
    
    Note over Server: Decode token to get position
    
    Server->>API: API request (top=10, skip=10)
    API->>Server: Response with more items
    Server->>Client: Response with items and new token

3. Improved Documentation

Each tool and operation now includes:

Detailed descriptions: Clear explanations of what each tool and operation does
Parameter documentation: Comprehensive documentation for all parameters
Usage examples: Real-world examples of how to use each operation
Type information: Clear type definitions for all inputs and outputs

Available Entity Tools

Projects Tool

Manages Azure DevOps projects.

Operations:

list: List all projects in the organization with pagination support
get: Get detailed information about a specific project

Repositories Tool

Manages Git repositories.

Operations:

list: List all Git repositories in a project with pagination support
get: Get detailed information about a specific Git repository
listBranches: List all branches in a Git repository with pagination support

Work Items Tool

Manages work items (bugs, tasks, user stories, etc.).

Operations:

get: Get detailed information about a specific work item
create: Create a new work item in a project

Pull Requests Tool

Manages pull requests in repositories.

Operations:

list: List pull requests in a repository with filtering and pagination support
get: Get detailed information about a specific pull request

Pipelines Tool

Manages CI/CD pipelines.

Operations:

list: List all pipelines in a project with pagination support
get: Get detailed information about a specific pipeline

Usage Examples

List Projects with Pagination

hljs language-json

{
  "operation": "list",
  "listParams": {
    "maxResults": 10,
    "continuationToken": "optional-token-from-previous-request"
  }
}

Get Project Details

hljs language-json

{
  "operation": "get",
  "getParams": {
    "projectId": "my-project",
    "includeCapabilities": true
  }
}

List Repositories in a Project

hljs language-json

{
  "operation": "list",
  "listParams": {
    "projectId": "my-project",
    "maxResults": 20
  }
}

List Branches in a Repository

hljs language-json

{
  "operation": "listBranches",
  "listBranchesParams": {
    "projectId": "my-project",
    "repositoryId": "my-repo",
    "maxResults": 15
  }
}

Get Work Item Details

hljs language-json

{
  "operation": "get",
  "getParams": {
    "id": 123,
    "expand": "Relations"
  }
}

Create a Work Item

hljs language-json

{
  "operation": "create",
  "createParams": {
    "projectId": "my-project",
    "type": "Task",
    "title": "Implement new feature",
    "description": "This task involves implementing the new feature XYZ",
    "assignedTo": "user@example.com"
  }
}

List Pull Requests with Filtering

hljs language-json

{
  "operation": "list",
  "listParams": {
    "projectId": "my-project",
    "repositoryId": "my-repo",
    "status": "Active",
    "maxResults": 10
  }
}

Configuration

The server can be configured using environment variables or a configuration file.

Environment Variables

ADO_ORGANIZATION: Azure DevOps organization name (required)
ADO_PROJECT: Default project name (optional)
ADO_PAT: Personal Access Token for authentication (required)
ADO_API_URL: Base URL for the API (optional, defaults to https://dev.azure.com)
ADO_API_VERSION: API version (optional, defaults to 7.0)
ADO_API_MAX_RETRIES: Maximum number of retries for API calls (optional, defaults to 3)
ADO_API_DELAY_MS: Delay between retries in milliseconds (optional, defaults to 1000)
ADO_API_BACKOFF_FACTOR: Backoff factor for retries (optional, defaults to 2)

Configuration File

Alternatively, you can create a config/azuredevops.json file with the following structure:

hljs language-json

{
  "organization": "your-organization",
  "project": "your-project",
  "credentials": {
    "pat": "your-personal-access-token"
  },
  "api": {
    "baseUrl": "https://dev.azure.com",
    "version": "7.0",
    "retry": {
      "maxRetries": 3,
      "delayMs": 1000,
      "backoffFactor": 2
    }
  }
}

Development

Building the Server

hljs language-bash

npm run build

Running the Server

hljs language-bash

node build/index.js

Docker

hljs language-bash

docker build -t azure-devops-mcp:local .
docker run -i --rm -e ADO_ORGANIZATION=your-org -e ADO_PAT=your-pat azure-devops-mcp:local

## License

MIT License © 2025 Aaron Bockelie <aaronsb@gmail.com>

ado-mcp

Azure DevOps MCP Server

Architecture

Architecture Diagram

Component Structure

Key Components

Recent Improvements

1. Enhanced Error Handling

2. Cursor-based Pagination

3. Improved Documentation

Available Entity Tools

Projects Tool

Repositories Tool

Work Items Tool

Pull Requests Tool

Pipelines Tool

Usage Examples

List Projects with Pagination

Get Project Details

List Repositories in a Project

List Branches in a Repository

Get Work Item Details

Create a Work Item

List Pull Requests with Filtering

Configuration

Environment Variables

Configuration File

Development

Building the Server

Running the Server

Docker

Similar Packages

Repository

Original Author

Publisher