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