Devops Enhanced MCP

🚀 DevOps增强型MCP

这是一个动态的Azure DevOps MCP（模型上下文协议）服务器，它能够根据当前工作目录自动切换认证上下文。借助这个服务器，用户可以通过单个MCP服务器与多个Azure DevOps组织和项目实现无缝集成。

✨ 主要特性

• 本地配置文件：每个仓库都包含 .azure-devops.json 配置文件。
• 动态环境切换：根据目录位置自动检测项目上下文。
• 多项目支持：支持无限数量的项目，并为每个项目提供独立的认证。
• 全面的Azure DevOps集成：涵盖工作项、仓库、构建等功能。
• 零配置切换：通过本地配置文件，可在项目之间实现无缝切换。
• 安全的令牌存储：每个仓库将PAT令牌本地存储（不纳入git管理）。
• 错误处理与回退机制：具备强大的错误处理能力，在出现问题时可优雅地回退到环境变量。

📦 安装指南

# 安装依赖
npm install

# 构建项目
npm run build

# 启动服务器
npm start

💻 使用示例

基础用法

获取当前上下文

{
  "name": "get-current-context",
  "arguments": {
    "directory": "/Users/wangkanai/Sources/riversync"
  }
}

查询工作项

{
  "name": "get-work-items",
  "arguments": {
    "wiql": "SELECT [System.Id], [System.Title] FROM WorkItems WHERE [System.State] = 'Active'"
  }
}

创建工作项

{
  "name": "create-work-item",
  "arguments": {
    "type": "Task",
    "title": "Implement new feature",
    "description": "Add authentication system",
    "assignedTo": "user@example.com"
  }
}

获取仓库列表

{
  "name": "get-repositories",
  "arguments": {
    "includeLinks": true
  }
}

📚 详细文档

本地配置

每个仓库都应包含一个 .azure-devops.json 配置文件：

配置文件结构

{
  "organizationUrl": "https://dev.azure.com/your-org",
  "project": "YourProject",
  "pat": "your-pat-token-here",
  "description": "Azure DevOps configuration for this repository",
  "settings": {
    "timeout": 30000,
    "retries": 3,
    "apiVersion": "7.1"
  },
  "tools": {
    "workItems": true,
    "repositories": true,
    "builds": true,
    "pullRequests": true,
    "pipelines": true
  },
  "meta": {
    "configVersion": "1.0",
    "lastUpdated": "2025-07-21",
    "createdBy": "devops-enhanced-mcp"
  }
}

安全配置

重要提示：请将 .azure-devops.json 添加到你的 .gitignore 文件中：

# Azure DevOps MCP本地配置（包含PAT令牌）
.azure-devops.json

示例项目

• RiverSync项目
  • 目录：/Users/wangkanai/Sources/riversync
  • 配置：包含RiverSync组织设置的 .azure-devops.json 文件。
• Mula项目
  • 目录：/Users/wangkanai/Sources/mula
  • 配置：包含Mula组织设置的 .azure-devops.json 文件。

可用工具

工作项

• get-work-items：使用WIQL查询或特定ID检索工作项。
• create-work-item：创建新的工作项，可指定标题、描述、分配对象和标签。

仓库

• get-repositories：列出当前项目上下文中的所有仓库。

构建

• get-builds：获取构建定义和最近的构建历史记录。

上下文管理

• get-current-context：根据目录获取当前的Azure DevOps上下文。

目录检测逻辑

服务器采用智能目录检测机制：

1. 精确匹配：直接匹配配置的目录路径。
2. 嵌套目录支持：可检测父项目目录。
3. 最长匹配优先：最具体的目录匹配优先。
4. 父目录搜索：在目录树中向上搜索匹配项。
5. 回退配置：在未找到匹配项时使用默认配置。

认证

服务器使用个人访问令牌（PAT）进行Azure DevOps认证。PAT令牌在每个仓库的本地 .azure-devops.json 配置文件中按项目进行配置。

PAT令牌要求

PAT令牌应具备以下权限范围：

• 工作项：读写权限。
• 代码：只读权限。
• 构建：只读权限。
• 项目和团队：只读权限。

错误处理

服务器具备全面的错误处理功能：

• 配置错误：在配置缺失时进行优雅回退。
• 认证错误：认证失败时提供清晰的错误消息。
• API错误：针对Azure DevOps API问题提供详细的错误报告。
• 网络错误：具备重试逻辑和超时处理。

测试与验证

增强验证系统（推荐）

增强验证系统包括MCP服务器启动、连接验证和就绪检查：

• MCP服务器预热

# 准备MCP服务器进行验证
./warmup-mcp.sh

# 使用自定义配置文件
./warmup-mcp.sh custom-config.json

• 增强综合验证

# 进行包含MCP服务器初始化的全面验证
./validate-enhanced.sh

# 跳过交互式Claude测试（更快）
./validate-enhanced.sh --skip-interactive

# 为慢速系统进行扩展预热
./validate-enhanced.sh --warmup 20

# 仅测试特定仓库
./validate-enhanced.sh --repos "RiverSync,Mula"

# 使用自定义配置文件
./validate-enhanced.sh --config custom-config.json

# 显示所有选项
./validate-enhanced.sh --help

• 手动测试

# 手动构建并测试服务器
npm run build
node test-server.js

配置文件

通用验证系统使用 validation-config.json：

{
  "proxyPath": "/Users/wangkanai/Sources/devops-enhanced-mcp",
  "repositories": [
    {
      "name": "RiverSync",
      "path": "/Users/wangkanai/Sources/riversync",
      "expectedOrganization": "riversync",
      "organizationUrl": "https://dev.azure.com/riversync",
      "project": "RiverSync",
      "enabled": true
    }
  ],
  "testSettings": {
    "timeoutSeconds": 30,
    "skipInteractive": false,
    "mcpServerName": "devops-enhanced-mcp",
    "configFileName": ".azure-devops.json"
  },
  "expectedTools": ["workItems", "repositories", "builds", "pullRequests", "pipelines"]
}

增强验证功能

增强验证系统包括：

• 🚀 MCP服务器管理
  • 启动验证：确保MCP服务器配置正确。
  • 连接测试：验证服务器连接性，具备重试逻辑。
  • 就绪检查：确认服务器响应基本命令。
  • 预热期：可配置服务器初始化延迟（默认：10秒）。
• 🔍 全面测试覆盖
  • ✅ 先决条件：PowerShell、Claude Code、目录结构、代理构建。
  • ✅ MCP初始化：服务器启动、连接性和就绪验证。
  • ✅ 本地配置：验证 .azure-devops.json 文件是否包含预期值。
  • ✅ 服务器配置：在不使用环境变量的情况下验证本地范围。
  • ✅ Claude集成：执行MCP命令并检测上下文。
  • ✅ 动态切换：在多个仓库之间进行环境切换。
  • ✅ 错误处理：全面检测和报告错误，具备重试逻辑。

预期结果

• 全面验证结果：
  • 通过率：成功实施时应大于90%。
  • 两个仓库中的所有MCP命令均正常运行。
  • 可根据目录位置自动切换上下文。

旧版环境配置（已弃用）

服务器以前支持使用全局 config/environments.json 文件进行环境映射。为了提高安全性和项目隔离性，此方法已弃用，建议使用本地 .azure-devops.json 配置文件。

如果需要从旧的基于环境的配置进行迁移，请将设置转换为每个仓库中的本地配置文件。

架构

核心组件

• AzureDevOpsMCPProxy：处理MCP协议的主服务器类。
• DirectoryDetector：智能目录检测和配置映射。
• ToolHandlers：Azure DevOps API集成和工具实现。
• ConfigLoader：配置文件加载和验证。

请求流程

1. 工具调用接收：MCP客户端发送工具调用请求。
2. 上下文检测：目录检测器识别当前项目上下文。
3. 配置切换：服务器切换到适当的Azure DevOps配置。
4. API请求：工具处理程序向Azure DevOps发送经过认证的API请求。
5. 响应处理：对响应进行格式化并返回给MCP客户端。

与Claude Code集成

此MCP服务器旨在与Claude Code无缝协作，用于Azure DevOps操作：

1. 自动上下文切换：在RiverSync或Mula项目目录中工作时自动切换。
2. 透明认证：无需手动配置。
3. 丰富的工具集：提供全面的Azure DevOps功能。
4. 错误恢复：优雅处理认证和网络问题。

安全考虑

• PAT令牌存储在配置文件中（请确保设置正确的文件权限）。
• 所有Azure DevOps API通信均使用HTTPS。
• 每个请求都使用正确的令牌编码进行认证。
• 除配置文件外，不进行令牌缓存或持久化存储。

故障排除

常见问题

1. 未找到配置文件：确保 .azure-devops.json 文件存在于项目目录中。
2. 认证错误：验证PAT令牌的权限和有效期。
3. 目录检测问题：检查项目中是否存在有效的 .azure-devops.json 文件。
4. API错误：验证本地配置中的Azure DevOps组织和项目名称。

调试模式

通过设置环境变量来启用调试日志：

export DEBUG=devops-enhanced-mcp
npm start

📄 许可证

本项目采用MIT许可证，详情请参阅 LICENSE 文件。