Azure DevOps MCP Server

Azure DevOps MCP 服务

此 MCP（Model Context Protocol）服务提供了一组工具，供 AI 助手与 Azure DevOps 服务交互。

架构

该服务采用基于实体的架构，按资源类型对操作进行分组，而不是公开大量原子工具。这种方式有以下优点：

1. 组织直观：工具按其操作的实体（项目、存储库、工作项等）进行组织
2. 工具数量更少：我们使用少量实体工具，每个工具支持多种操作，而不是数十个单独的工具
3. 接口一致：所有实体工具的操作和参数都遵循相同模式
4. 错误处理更完善：每个实体工具都能处理其领域内的特定错误
5. 更易发现：用户可以轻松发现每个实体可用的操作

架构图

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

组件结构

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

关键组件

• 实体工具：每个工具代表一个主要的 Azure DevOps 实体（项目、存储库、工作项等），并提供多种操作（列出、获取、创建等）
• 工具注册表：管理实体工具的注册和执行
• API 客户端：处理与 Azure DevOps REST API 的通信
• 错误处理工具：提供标准化的错误处理，包含详细上下文和易于理解的消息
• 分页工具：为列表操作实现基于游标的分页
• 配置管理器：从环境变量或配置文件加载并验证配置

近期改进

1. 增强的错误处理

该服务现包含一套全面的错误处理系统，可提供：

• 错误分类：按类型对错误进行分类（身份验证、授权、验证等）
• 上下文信息：错误包含来源、操作及其他相关上下文
• 易于理解的消息：错误消息旨在提供帮助并便于采取后续措施
• 故障排除提示：适用时，错误会附带解决问题的建议

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. 基于游标的分页

所有列表操作现均支持基于游标的分页，具有以下特性：

• 延续令牌：经过编码的令牌，用于恢复分页
• 可自定义的页面大小：控制每页的结果数量
• 一致的接口：所有列表操作都使用相同的分页参数
• 高效利用资源：只获取所需数据

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. 改进的文档

现在，每个工具和操作都包含：

• 详细说明：清晰解释每个工具和操作的功能
• 参数文档：为所有参数提供全面的文档
• 用法示例：展示如何使用每项操作的真实示例
• 类型信息：清晰定义所有输入和输出的类型

可用的实体工具

项目工具

管理 Azure DevOps 项目。

操作：

• list：列出组织中的所有项目，并支持分页
• get：获取特定项目的详细信息

存储库工具

管理 Git 存储库。

操作：

• list：列出项目中的所有 Git 存储库，并支持分页
• get：获取特定 Git 存储库的详细信息
• listBranches：列出 Git 存储库中的所有分支，并支持分页

工作项工具

管理工作项（Bug、任务、用户故事等）。

操作：

• get：获取特定工作项的详细信息
• create：在项目中创建新的工作项

拉取请求工具

管理存储库中的拉取请求。

操作：

• list：列出存储库中的拉取请求，并支持筛选和分页
• get：获取特定拉取请求的详细信息

Pipelines 工具

管理 CI/CD 管道。

操作：

• list：列出项目中的所有管道，支持分页
• get：获取特定管道的详细信息

使用示例

分页列出项目

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

获取项目详情

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

列出项目中的存储库

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

列出存储库中的分支

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

获取工作项详情

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

创建工作项

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

筛选并列出拉取请求

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

配置

可以使用环境变量或配置文件配置服务。

环境变量

• ADO_ORGANIZATION：Azure DevOps 组织名称（必填）
• ADO_PROJECT：默认项目名称（可选）
• ADO_PAT：用于身份验证的个人访问令牌（必填）
• ADO_API_URL：API 的基础 URL（可选，默认为 https://dev.azure.com）
• ADO_API_VERSION：API 版本（可选，默认为 7.0）
• ADO_API_MAX_RETRIES：API 调用的最大重试次数（可选，默认为 3）
• ADO_API_DELAY_MS：重试间隔（毫秒）（可选，默认为 1000）
• ADO_API_BACKOFF_FACTOR：重试退避系数（可选，默认为 2）

配置文件

或者，你可以创建 config/azuredevops.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
    }
  }
}

开发

构建服务

npm run build

运行服务

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