Devops Enhanced MCP

🚀 DevOps Enhanced MCP

このアプリケーションは、現在の作業ディレクトリに基づいて認証コンテキストを自動的に切り替える、動的なAzure DevOps MCP（Model Context Protocol）サーバーです。これにより、単一の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 local configuration (contains PAT tokens)
.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. フォールバック構成：一致が見つからない場合にはデフォルトの構成を使用します。

認証

サーバーは、Azure DevOpsの認証にPersonal Access Tokens（PAT）を使用しています。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-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サーバーが適切に構成されていることを確認します。
• 接続テスト：リトライロジックを持つサーバーの接続を検証します。
• 準備状態チェック：サーバーが基本コマンドに応答することを確認します。
• ウォームアップ期間：サーバーの初期化のための設定可能な遅延（デフォルト: 10s）。

🔍 包括的なテストカバレッジ

• ✅ 前提条件：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サーバーは、Azure DevOpsの操作にClaude Codeとシームレスに連携するように設計されています。

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ファイルを参照してください。