https://github.com/aaronsb/ado-mcp

Azure DevOps MCP Server
https://github.com/aaronsb/ado-mcp
Last synced: 3 days ago
JSON representation
Azure DevOps MCP Server
Host: GitHub
URL: https://github.com/aaronsb/ado-mcp
Owner: aaronsb
License: mit
Created: 2025-03-11T23:25:22.000Z (about 2 months ago)
Default Branch: main
Last Pushed: 2025-03-24T12:08:40.000Z (about 2 months ago)
Last Synced: 2025-03-24T13:24:40.302Z (about 2 months ago)
Language: TypeScript
Size: 959 KB
Stars: 3
Watchers: 2
Forks: 1
Open Issues: 0
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project

awesome-devops-mcp-servers - aaronsb/ado-mcp - Azure DevOps MCP Server for integrating AI assistants with Azure DevOps services. (Cloud Infrastructure / ☁️ Cloud Providers)
awesome-devops-mcp-servers - aaronsb/ado-mcp - Azure DevOps MCP Server for integrating AI assistants with Azure DevOps services. (Cloud Infrastructure / ☁️ Cloud Providers)
README

        # 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

```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

```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

```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

```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

```json

{

  "operation": "list",

  "listParams": {

    "maxResults": 10,

    "continuationToken": "optional-token-from-previous-request"

  }

}

```

### Get Project Details

```json

{

  "operation": "get",

  "getParams": {

    "projectId": "my-project",

    "includeCapabilities": true

  }

}

```

### List Repositories in a Project

```json

{

  "operation": "list",

  "listParams": {

    "projectId": "my-project",

    "maxResults": 20

  }

}

```

### List Branches in a Repository

```json

{

  "operation": "listBranches",

  "listBranchesParams": {

    "projectId": "my-project",

    "repositoryId": "my-repo",

    "maxResults": 15

  }

}

```

### Get Work Item Details

```json

{

  "operation": "get",

  "getParams": {

    "id": 123,

    "expand": "Relations"

  }

}

```

### Create a Work Item

```json

{

  "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

```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:

```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

```bash

npm run build

```

### Running the Server

```bash

node build/index.js

```

### Docker

```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
ecosyste.ms

Data

Tools

Indexes

Applications

Experiments

Awesome

https://github.com/aaronsb/ado-mcp

Awesome Lists containing this project

README
