Devops MCP

🚀 Azure DevOps MCP

Azure DevOps MCP（Model Context Protocol）是一个动态服务器，它能根据当前工作目录自动切换认证上下文。这使得单个 MCP 服务器可以与多个 Azure DevOps 组织和项目实现无缝集成。

🚀 快速开始

本项目是一个动态的 Azure DevOps MCP 服务器，可依据当前工作目录自动切换认证上下文，让单个 MCP 服务器能与多个 Azure DevOps 组织和项目实现无缝集成。你可以按照以下步骤进行安装和使用：

1. 按照“📦 安装指南”中的步骤安装本项目。
2. 参考“📚 详细文档”中的内容进行本地配置。
3. 查看“💻 使用示例”了解如何使用本项目提供的工具。

✨ 主要特性

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

📦 安装指南

Claude Code 安装（推荐）

# 安装并添加到 Claude Code MCP
claude mcp add devops-mcp -- -y @wangkanai/devops-mcp

⚠️ 重要提示

-y 标志会自动接受包安装提示，确保 MCP 服务器的非交互式执行顺利进行。

Claude Desktop 安装

对于 Claude Desktop 用户，将以下配置添加到你的 MCP 设置中：

{
  "mcpServers": {
    "devops-mcp": {
      "command": "npx",
      "args": ["-y", "@wangkanai/devops-mcp"]
    }
  }
}

Claude Desktop MCP 设置位置：

• macOS：~/Library/Application Support/Claude/claude_desktop_config.json
• Windows：%APPDATA%\Claude\claude_desktop_config.json

其他安装方法

全局安装

# 全局安装
npm install -g @wangkanai/devops-mcp

# 添加到 Claude Code MCP
claude mcp add devops-mcp -- devops-mcp

开发安装

# 克隆仓库
git clone https://github.com/wangkanai/devops-mcp.git
cd devops-mcp

# 安装依赖
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-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 文件。

可用工具

📋 如需包含详细示例的完整命令文档，请参阅 MCP-COMMANDS.md

工作项

• get-work-items：使用 WIQL 查询或特定 ID 检索工作项，并可选择字段。
• create-work-item：创建新的工作项，支持完整的层次结构（Epic → Feature → User Story → Task）。
• update-work-item：更新现有工作项，包括状态、分配、父关系和迭代路径。
• add-work-item-comment：为现有工作项添加注释，以跟踪进度。

仓库与拉取请求

• get-repositories：列出当前项目上下文中的所有仓库。
• get-pull-requests：获取拉取请求，并可进行过滤（状态、创建者、仓库）。

构建与管道

• get-builds：获取构建定义和最近的构建历史，并可进行过滤。
• trigger-pipeline：使用参数和分支选择触发构建管道。
• get-pipeline-status：获取详细的构建状态和时间线信息。

上下文管理

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

🎯 关键特性

• ✅ 层次化工作项：支持完整的 Epic → Feature → User Story → Task 层次结构。
• ✅ 父关系：在创建工作项时可建立父子关系。
• ✅ WIQL 查询：支持强大的工作项查询语言，用于复杂搜索。
• ✅ 冲刺管理：支持迭代路径分配和管理。
• ✅ 管道集成：可触发构建并监控部署状态。
• ✅ 多项目支持：可在 Azure DevOps 组织之间无缝切换。

目录检测逻辑

服务器使用智能目录检测：

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

认证

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

PAT 令牌要求

PAT 令牌应具有以下范围：

• 工作项：读取和写入。
• 代码：读取。
• 构建：读取。
• 项目和团队：读取。

错误处理

服务器包含全面的错误处理机制：

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

测试与验证

增强验证系统（推荐）

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

1. MCP 服务器预热

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

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

2. 增强的全面验证

# 进行包含 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

3. 手动测试

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

配置文件

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

{
  "proxyPath": "/Users/wangkanai/Sources/devops-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-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. 安装命令问题（问题 #14 解决方案）

问题：不正确的安装命令导致服务器无法启动。 根本原因：文档过时，显示了错误的命令语法。 解决方案：使用正确的安装命令：

# ✅ 正确（推荐）
claude mcp add devops-mcp -- -y @wangkanai/devops-mcp

# ❌ 错误（将失败）

其他可用命令：

# 全局安装方法
npm install -g @wangkanai/devops-mcp
claude mcp add devops-mcp -- devops-mcp

2. 配置问题

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

3. 安装验证

使用以下命令测试你的安装：

# 测试服务器启动（直接构建并运行）
npm run build && node dist/index.js

# 验证 MCP 集成
mcp__devops-mcp__get-current-context

# 测试工作项创建
mcp__devops-mcp__create-work-item --type "Task" --title "Test Item"

调试模式

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

export DEBUG=devops-mcp
npm start

NPM 包技术细节

• 包名称：@wangkanai/devops-mcp
• 二进制名称：devops-mcp（由 NPM 自动生成）
• 最新版本：使用 npm view @wangkanai/devops-mcp version 进行检查。
• 安装验证：使用 npm list -g @wangkanai/devops-mcp 进行验证。

📄 许可证

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