Devops MCP

🚀 Azure DevOps MCP

現在の作業ディレクトリに基づいて認証コンテキストを自動的に切り替える、動的なAzure DevOps MCP（Model Context Protocol）サーバーです。これにより、単一のMCPサーバーから複数のAzure DevOps組織とプロジェクトとのシームレスな統合が可能になります。

🚀 クイックスタート

Azure DevOps MCPは、現在の作業ディレクトリに基づいて認証コンテキストを自動的に切り替えることができる動的なサーバーです。これにより、単一のMCPサーバーから複数のAzure DevOps組織とプロジェクトとのシームレスな統合が可能になります。

✨ 主な機能

• ローカル構成ファイル：各リポジトリには .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 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

認証

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

1. 自動コンテキスト切り替え：RiverSyncまたはMulaプロジェクトディレクトリで作業するとき
2. 透過的な認証：手動での構成は必要ありません
3. 豊富なツールセット：包括的なAzure DevOps機能
4. エラー回復：認証とネットワークの問題をグレースフルに処理

セキュリティに関する考慮事項

• PATトークンは構成ファイルに保存されます（適切なファイルパーミッションを確保してください）
• すべてのAzure DevOps API通信にはHTTPSが使用されます
• 認証はすべてのリクエストごとに適切なトークンエンコーディングで処理されます
• トークンのキャッシュや構成ファイル以外の永続化は行われません

トラブルシューティング

一般的な問題

1. インストールコマンドの問題（Issue #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

🔧 技術詳細

ディレクトリ検出ロジック

サーバーは、以下のようなインテリジェントなディレクトリ検出を使用します。

1. 完全一致：構成されたディレクトリパスの直接一致
2. ネストされたディレクトリのサポート：親プロジェクトディレクトリを検出
3. 最長一致の優先順位：最も具体的なディレクトリ一致が優先されます
4. 親ディレクトリの検索：ディレクトリツリーを上に検索して一致を探します
5. フォールバック構成：一致が見つからない場合はデフォルトの構成を使用します

コアコンポーネント

• AzureDevOpsMCPProxy：MCPプロトコルを処理するメインサーバークラス
• DirectoryDetector：スマートなディレクトリ検出と構成マッピング
• ToolHandlers：Azure DevOps APIの統合とツールの実装
• ConfigLoader：構成ファイルの読み込みと検証

リクエストフロー

1. ツール呼び出しを受信：MCPクライアントがツール呼び出しリクエストを送信
2. コンテキスト検出：ディレクトリ検出器が現在のプロジェクトコンテキストを識別
3. 構成切り替え：サーバーが適切なAzure DevOps構成に切り替える
4. APIリクエスト：ツールハンドラーがAzure DevOpsに認証済みのAPIリクエストを送信
5. レスポンス処理：レスポンスがフォーマットされ、MCPクライアントに返される

📄 ライセンス

MITライセンス - 詳細については LICENSE ファイルを参照してください。