Ado MCP

Azure DevOps MCP服务器

此MCP（模型上下文协议）服务器提供了通过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：获取特定拉取请求的详细信息

管道工具

管理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": "user@example.com"
  }
}

列出带筛选的拉取请求

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