What is Ado Mcp

ado-mcp is an Azure DevOps MCP Server that provides tools for interacting with Azure DevOps services through AI assistants. It utilizes an entity-based architecture to streamline operations related to various Azure DevOps resources.

Use cases

ado-mcp can be used in scenarios such as automating project management tasks, integrating Azure DevOps with AI-driven applications, managing repositories and work items, and providing user-friendly interfaces for developers to interact with Azure DevOps services.

How to use

To use ado-mcp, users can send MCP requests through an AI assistant, which communicates with the MCP Server. The server processes these requests and returns responses based on the operations defined for each entity tool.

Key features

Key features of ado-mcp include intuitive organization of tools by entity type, reduced tool count with multiple operations per tool, a consistent interface across all tools, enhanced error handling with categorized errors, and support for cursor-based pagination.

Where to use

undefined

Azure DevOps MCP Server

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:

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

Architecture Diagram

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

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

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

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

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

Get Project Details

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

List Repositories in a Project

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

List Branches in a Repository

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

Get Work Item Details

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

Create a Work Item

{
  "operation": "create",
  "createParams": {
    "projectId": "my-project",
    "type": "Task",
    "title": "Implement new feature",
    "description": "This task involves implementing the new feature XYZ",
    "assignedTo": "[email protected]"
  }
}

List Pull Requests with Filtering

{
  "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:

{
  "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

npm run build

Running the Server

node build/index.js

Docker

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 <[email protected]>