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 文件。