Azure DevOps MCP Server

Azure DevOps MCP サーバー

この MCP（Model Context Protocol）サーバーは、AI アシスタントから Azure DevOps サービスを操作するためのツールを提供します。

アーキテクチャ

このサーバーは、個別の操作を多数公開するのではなく、リソースの種類ごとに操作をグループ化するエンティティベースのアーキテクチャを採用しています。この方法には、次のような利点があります。

1. 直感的な構成：ツールは、操作対象のエンティティ（プロジェクト、リポジトリ、作業項目など）ごとに整理されています
2. ツール数の削減：個別のツールを何十個も用意する代わりに、複数の操作を備えた少数のエンティティツールを用意しています
3. 一貫したインターフェイス：すべてのエンティティツールで、操作とパラメーターに同じパターンを採用しています
4. 優れたエラー処理：各エンティティツールで、その領域に固有のエラーを処理できます
5. 見つけやすさの向上：ユーザーは各エンティティで利用できる操作を簡単に見つけられます

アーキテクチャ図

flowchart TB
    Client[AI Assistant] -->|MCP Request| Server[MCP Server]
    Server -->|MCP Response| Client
    
    subgraph "Azure DevOps MCP Server"
        Server --> RequestHandler[Request Handler]
        RequestHandler --> ToolRegistry[Tool Registry]
        ToolRegistry --> EntityTools[Entity Tools]
        EntityTools --> ApiClient[API Client]
        ApiClient --> ErrorUtils[Error Utilities]
        ApiClient --> PaginationUtils[Pagination Utilities]
        ApiClient -->|HTTP Request| AzureDevOps[Azure DevOps API]
        AzureDevOps -->|HTTP Response| ApiClient
        ConfigManager[Configuration Manager] --> ApiClient
    end
    
    classDef primary fill:#4285F4,stroke:#0D47A1,color:white
    classDef secondary fill:#34A853,stroke:#0D652D,color:white
    classDef utility fill:#FBBC05,stroke:#866A00,color:white
    classDef external fill:#EA4335,stroke:#980905,color:white
    
    class Server,RequestHandler primary
    class ToolRegistry,EntityTools,ApiClient secondary
    class ErrorUtils,PaginationUtils,ConfigManager utility
    class Client,AzureDevOps external

コンポーネント構成

classDiagram
    class EntityTool {
        +name: string
        +description: string
        +operations: Record~string, Function~
        +schemas: Record~string, ZodSchema~
        +getDefinition(): ToolDefinition
        +execute(args: unknown): Promise~any~
        #registerOperation(operation, handler, schema, description)
    }
    
    class ADOApiClient {
        +config: ADOApiConfig
        +connection: WebApi
        +getCoreApi()
        +getWorkItemTrackingApi()
        +getGitApi()
        +getPipelineApi()
        +handleError(error, context)
    }
    
    class ToolRegistry {
        +registerTool(tool: Tool)
        +getTool(name: string): Tool
        +getToolDefinitions(): ToolDefinition[]
    }
    
    class ErrorUtils {
        +createError(code, message, context)
        +handleApiError(error, source, operation)
    }
    
    class PaginationUtils {
        +normalizePaginationParams(params)
        +createPaginationResult(items, totalCount, continuationToken)
        +encodeContinuationToken(data)
        +decodeContinuationToken(token)
    }
    
    EntityTool --> ADOApiClient : uses
    EntityTool --> ErrorUtils : uses
    EntityTool --> PaginationUtils : uses
    ToolRegistry --> EntityTool : registers

主要コンポーネント

• エンティティツール：各ツールは Azure DevOps の主要なエンティティ（プロジェクト、リポジトリ、作業項目など）を表し、複数の操作（一覧表示、取得、作成など）を提供します
• ツールレジストリ：エンティティツールの登録と実行を管理します
• API クライアント：Azure DevOps REST API との通信を処理します
• エラーユーティリティ：詳細なコンテキストとユーザーにわかりやすいメッセージを含む、標準化されたエラー処理を提供します
• ページネーションユーティリティ：一覧表示操作向けに、カーソルベースのページネーションを実装します
• 構成マネージャー：環境変数または構成ファイルから構成を読み込み、検証します

最近の改善

1. エラー処理の強化

このサーバーには、次の機能を備えた包括的なエラー処理システムが追加されました。

• エラーの分類：エラーを種類（認証、認可、検証など）ごとに分類します
• コンテキスト情報：エラーに、発生元、操作、その他の関連コンテキストを含めます
• ユーザーにわかりやすいメッセージ：役立ち、問題解決につながるエラーメッセージを提供します
• トラブルシューティングのヒント：該当する場合、エラーに問題の解決方法を提案します

flowchart LR
    Error[API Error] --> Handler[Error Handler]
    Handler --> Category{Categorize}
    Category -->|Authentication| AuthError[Authentication Error]
    Category -->|Authorization| AuthzError[Authorization Error]
    Category -->|Not Found| NotFoundError[Not Found Error]
    Category -->|Validation| ValidationError[Validation Error]
    Category -->|Rate Limit| RateLimitError[Rate Limit Error]
    Category -->|Service| ServiceError[Service Error]
    Category -->|Unknown| UnknownError[Unknown Error]
    
    AuthError & AuthzError & NotFoundError & ValidationError & RateLimitError & ServiceError & UnknownError --> Format[Format User Message]
    Format --> McpError[MCP Error Response]
    
    classDef error fill:#EA4335,stroke:#980905,color:white
    classDef process fill:#4285F4,stroke:#0D47A1,color:white
    classDef result fill:#34A853,stroke:#0D652D,color:white
    
    class Error,AuthError,AuthzError,NotFoundError,ValidationError,RateLimitError,ServiceError,UnknownError error
    class Handler,Category,Format process
    class McpError result

2. カーソルベースのページネーション

すべての一覧表示操作で、次の機能を備えたカーソルベースのページネーションが利用できるようになりました。

• 継続トークン：ページネーションを再開するためのエンコード済みトークン
• ページサイズのカスタマイズ：1 ページあたりの結果数を指定できます
• 一貫したインターフェイス：すべての一覧表示操作で同じページネーションパラメーターを使用します
• 効率的なリソース利用：必要なデータだけを取得します

sequenceDiagram
    participant Client as AI Assistant
    participant Server as MCP Server
    participant API as Azure DevOps API
    
    Client->>Server: List request (maxResults=10)
    Server->>API: API request (top=10, skip=0)
    API->>Server: Response with items
    
    Note over Server: Create continuation token
    
    Server->>Client: Response with items and token
    
    Client->>Server: List request with token
    
    Note over Server: Decode token to get position
    
    Server->>API: API request (top=10, skip=10)
    API->>Server: Response with more items
    Server->>Client: Response with items and new token

3. ドキュメントの改善

各ツールと操作に、次の内容が追加されました。

• 詳細な説明：各ツールと操作の機能を明確に説明します
• パラメーターのドキュメント：すべてのパラメーターを詳しく説明します
• 使用例：各操作の実際の使用例を示します
• 型情報：すべての入力と出力について、型を明確に定義します

利用可能なエンティティツール

Projects ツール

Azure DevOps プロジェクトを管理します。

操作：

• list：ページネーションに対応し、組織内のすべてのプロジェクトを一覧表示します
• get：特定のプロジェクトの詳細情報を取得します

Repositories ツール

Git リポジトリを管理します。

操作：

• list：ページネーションに対応し、プロジェクト内のすべての Git リポジトリを一覧表示します
• get：特定の Git リポジトリの詳細情報を取得します
• listBranches：ページネーションに対応し、Git リポジトリ内のすべてのブランチを一覧表示します

Work Items ツール

作業項目（バグ、タスク、ユーザーストーリーなど）を管理します。

操作：

• get：特定の作業項目の詳細情報を取得します
• create：プロジェクトに新しい作業項目を作成します

Pull Requests ツール

リポジトリ内のプルリクエストを管理します。

操作：

• list：フィルタリングとページネーションに対応し、リポジトリ内のプルリクエストを一覧表示します
• get：特定のプルリクエストの詳細情報を取得します

パイプラインツール

CI/CD パイプラインを管理します。

操作：

• list：ページネーションに対応し、プロジェクト内のすべてのパイプラインを一覧表示します
• get：特定のパイプラインの詳細情報を取得します

使用例

ページネーションを使ってプロジェクトを一覧表示する

{
  "operation": "list",
  "listParams": {
    "maxResults": 10,
    "continuationToken": "optional-token-from-previous-request"
  }
}

プロジェクトの詳細を取得する

{
  "operation": "get",
  "getParams": {
    "projectId": "my-project",
    "includeCapabilities": true
  }
}

プロジェクト内のリポジトリを一覧表示する

{
  "operation": "list",
  "listParams": {
    "projectId": "my-project",
    "maxResults": 20
  }
}

リポジトリ内のブランチを一覧表示する

{
  "operation": "listBranches",
  "listBranchesParams": {
    "projectId": "my-project",
    "repositoryId": "my-repo",
    "maxResults": 15
  }
}

###作業項目の詳細を取得する

{
  "operation": "get",
  "getParams": {
    "id": 123,
    "expand": "Relations"
  }
}

作業項目を作成する

{
  "operation": "create",
  "createParams": {
    "projectId": "my-project",
    "type": "Task",
    "title": "Implement new feature",
    "description": "This task involves implementing the new feature XYZ",
    "assignedTo": "[email protected]"
  }
}

フィルタリングしてプルリクエストを一覧表示する

{
  "operation": "list",
  "listParams": {
    "projectId": "my-project",
    "repositoryId": "my-repo",
    "status": "Active",
    "maxResults": 10
  }
}

構成

環境変数または構成ファイルを使用してサーバーを構成できます。

環境変数

• ADO_ORGANIZATION：Azure DevOps の組織名（必須）
• ADO_PROJECT：デフォルトのプロジェクト名（任意）
• ADO_PAT：認証用の個人用アクセストークン（必須）
• ADO_API_URL：API のベース URL（任意。デフォルトは https://dev.azure.com）
• ADO_API_VERSION：API バージョン（任意。デフォルトは 7.0）
• ADO_API_MAX_RETRIES：API 呼び出しの最大再試行回数（任意。デフォルトは 3）
• ADO_API_DELAY_MS：再試行間の遅延時間（ミリ秒、任意。デフォルトは 1000）
• ADO_API_BACKOFF_FACTOR：再試行時のバックオフ係数（任意。デフォルトは 2）

構成ファイル

または、次の構成で config/azuredevops.json ファイルを作成できます。

{
  "organization": "your-organization",
  "project": "your-project",
  "credentials": {
    "pat": "your-personal-access-token"
  },
  "api": {
    "baseUrl": "https://dev.azure.com",
    "version": "7.0",
    "retry": {
      "maxRetries": 3,
      "delayMs": 1000,
      "backoffFactor": 2
    }
  }
}

開発

サーバーをビルドする

npm run build

サーバーを実行する

node build/index.js

Docker

docker build -t azure-devops-mcp:local .
docker run -i --rm -e ADO_ORGANIZATION=your-org -e ADO_PAT=your-pat azure-devops-mcp:local

## License

MIT License © 2025 Aaron Bockelie <[email protected]>