STARWARCLOUD STARWAR.AI
返回市场
活性目录MCP

活性目录MCP

作者：aaronsb17 星标更新：2025-03-24
安装使用来源：spider==github.com

项目介绍

Azure DevOps MCP 服务器

<p align="center"> <img src="docs/ado-mcp-400x400.png" alt="ADO MCP Logo" width="400" height="400"> </p>

此MCP（模型上下文协议）服务器提供了通过AI助手与Azure DevOps服务交互的工具。

架构

该服务器遵循基于实体的架构，按资源类型对操作进行分组，而不是暴露许多原子工具。这种方法提供了几个优点：

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

架构图

flowchart TB
    客户端[AI 助手] -->|MCP 请求| 服务器[MCP 服务器]
    服务器 -->|MCP 响应| 客户端
    
    subgraph "Azure DevOps MCP 服务器"
        服务器 --> 请求处理器[请求处理器]
        请求处理器 --> 工具注册表[工具注册表]
        工具注册表 --> 实体工具[实体工具]
        实体工具 --> API客户端[API 客户端]
        API客户端 --> 错误工具[错误工具]
        API客户端 --> 分页工具[分页工具]
        API客户端 -->|HTTP 请求| AzureDevOps[Azure DevOps API]
        AzureDevOps -->|HTTP 响应| API客户端
        配置管理器[配置管理器] --> API客户端
    end
    
    classDef 主要 fill:#4285F4,stroke:#0D47A1,color:white
    classDef 次要 fill:#34A853,stroke:#0D652D,color:white
    classDef 辅助 fill:#FBBC05,stroke:#866A00,color:white
    classDef 外部 fill:#EA4335,stroke:#980905,color:white
    
    class 服务器,请求处理器 主要
    class 工具注册表,实体工具,API客户端 次要
    class 错误工具,分页工具,配置管理器 辅助
    class 客户端,AzureDevOps 外部

组件结构

classDiagram
    class 实体工具 {
        +名称: 字符串
        +描述: 字符串
        +操作: 记录~字符串, 函数~
        +模式: 记录~字符串, Zod模式~
        +获取定义(): 工具定义
        +执行(参数: 未知): 承诺~任何~
        #注册操作(操作, 处理程序, 模式, 描述)
    }
    
    class ADOAPI客户端 {
        +配置: ADOAPI配置
        +连接: WebAPI
        +获取核心API()
        +获取工作项跟踪API()
        +获取GitAPI()
        +获取管道API()
        +处理错误(错误, 上下文)
    }
    
    class 工具注册表 {
        +注册工具(工具: 工具)
        +获取工具(名称: 字符串): 工具
        +获取工具定义(): 工具定义[]
    }
    
    class 错误工具 {
        +创建错误(代码, 消息, 上下文)
        +处理API错误(错误, 来源, 操作)
    }
    
    class 分页工具 {
        +规范化分页参数(参数)
        +创建分页结果(项目, 总数, 继续令牌)
        +编码继续令牌(数据)
        +解码继续令牌(令牌)
    }
    
    实体工具 --> ADOAPI客户端 : 使用
    实体工具 --> 错误工具 : 使用
    实体工具 --> 分页工具 : 使用
    工具注册表 --> 实体工具 : 注册

关键组件

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

最近改进

1. 增强的错误处理

服务器现在包括一个全面的错误处理系统，提供：

  • 分类错误：错误按类型分类（身份验证、授权、验证等）。
  • 上下文信息：错误包含来源、操作和其他相关上下文。
  • 用户友好的消息：错误消息设计为有用且可操作。
  • 故障排除提示：在适用的情况下，错误包含解决问题的建议。
flowchart LR
    错误[API 错误] --> 处理器[错误处理器]
    处理器 --> 分类{分类}
    分类 -->|身份验证| 身份验证错误[身份验证错误]
    分类 -->|授权| 授权错误[授权错误]
    分类 -->|未找到| 未找到错误[未找到错误]
    分类 -->|验证| 验证错误[验证错误]
    分类 -->|速率限制| 速率限制错误[速率限制错误]
    分类 -->|服务| 服务错误[服务错误]
    分类 -->|未知| 未知错误[未知错误]
    
    身份验证错误 & 授权错误 & 未找到错误 & 验证错误 & 速率限制错误 & 服务错误 & 未知错误 --> 格式化[格式化用户消息]
    格式化 --> MCP错误[MCP 错误响应]
    
    classDef 错误 fill:#EA4335,stroke:#980905,color:white
    classDef 过程 fill:#4285F4,stroke:#0D47A1,color:white
    classDef 结果 fill:#34A853,stroke:#0D652D,color:white
    
    class 错误,身份验证错误,授权错误,未找到错误,验证错误,速率限制错误,服务错误,未知错误 错误
    class 处理器,分类,格式化 过程
    class MCP错误 结果

2. 基于游标的分页

所有列表操作现在支持基于游标的分页，具有：

  • 继续令牌：用于恢复分页的编码令牌。
  • 可定制的页面大小：控制每页的结果数量。
  • 一致的接口：所有列表操作中的同一分页参数。
  • 高效的资源使用：仅获取所需的数据。
sequenceDiagram
    参与者 客户端 as AI 助手
    参与者 服务器 as MCP 服务器
    参与者 API as Azure DevOps API
    
    客户端->>服务器: 列表请求 (最大结果=10)
    服务器->>API: API 请求 (顶部=10, 跳过=0)
    API->>服务器: 包含项目的响应
    
    注释 over 服务器: 创建继续令牌
    
    服务器->>客户端: 包含项目和令牌的响应
    
    客户端->>服务器: 带令牌的列表请求
    
    注释 over 服务器: 解码令牌以获取位置
    
    服务器->>API: API 请求 (顶部=10, 跳过=10)
    API->>服务器: 包含更多项目的响应
    服务器->>客户端: 包含项目和新令牌的响应

3. 改进的文档

每个工具和操作现在包括：

  • 详细的描述：清楚地解释每个工具和操作的作用。
  • 参数文档：所有参数的全面文档。
  • 使用示例：如何使用每个操作的真实世界示例。
  • 类型信息：所有输入和输出的清晰类型定义。

可用的实体工具

项目工具

管理Azure DevOps项目。

操作：

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

存储库工具

管理Git存储库。

操作：

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

工作项工具

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

操作：

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

拉取请求工具

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

操作：

  • 列表：列出存储库中的拉取请求，支持过滤和分页。
  • 获取：获取特定拉取请求的详细信息。

管道工具

管理CI/CD管道。

操作：

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

使用示例

列出项目并支持分页

{
  "操作": "列表",
  "列表参数": {
    "最大结果": 10,
    "继续令牌": "来自上一次请求的可选令牌"
  }
}

获取项目详细信息

{
  "操作": "获取",
  "获取参数": {
    "项目ID": "my-project",
    "包含功能": true
  }
}

列出项目中的存储库

{
  "操作": "列表",
  "列表参数": {
    "项目ID": "my-project",
    "最大结果": 20
  }
}

列出存储库中的分支

{
  "操作": "列表分支",
  "列表分支参数": {
    "项目ID": "my-project",
    "存储库ID": "my-repo",
    "最大结果": 15
  }
}

获取工作项详细信息

{
  "操作": "获取",
  "获取参数": {
    "ID": 123,
    "扩展": "关系"
  }
}

创建工作项

{
  "操作": "创建",
  "创建参数": {
    "项目ID": "my-project",
    "类型": "任务",
    "标题": "实现新功能",
    "描述": "此任务涉及实现新功能XYZ",
    "分配给": "user@example.com"
  }
}

列出存储库中的拉取请求并支持过滤

{
  "操作": "列表",
  "列表参数": {
    "项目ID": "my-project",
    "存储库ID": "my-repo",
    "状态": "活动",
    "最大结果": 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 文件，具有以下结构：

{
  "组织": "your-organization",
  "项目": "your-project",
  "凭证": {
    "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

## 许可证

MIT 许可证 © 2025 Aaron Bockelie <aaronsb@gmail.com>