agile-analytics-mcp

Agile Analytics ローカル AI コネクター

Model Context Protocol （MCP）に対応する Claude などのアシスタントに、チームの Agile Analytics の数値について質問できます。スプリントの概要、サイクルタイム、フロー効率、仕掛かり作業、滞留期間、予測などに対応します。このコネクターはお使いのコンピューター上で動作し、お客様自身のアクセス権を使って Azure DevOps を読み取ります。また、Agile Analytics 拡張機能独自のメトリックコードを実行するため、拡張機能に表示される数値と同じ数値で回答します。

このコネクターは Agile Analytics サブスクリプションの一部です。組織に拡張機能がインストールされ、対象プロジェクトのワークフローマッピングが保存されている場合にのみ回答します。Baytek にデータが送信されることはありません。

完全なガイド：https://ado-analytics.baytekdev.com/docs/local-ai-connector/

はじめる前に

• お使いのコンピューターに Node.js 22 以降が必要です（node --version）。このコネクターは、Node.js に付属する npx で動作します。
• Azure DevOps 組織に Agile Analytics がインストールされている必要があります。また、質問するプロジェクトのワークフローマッピングが保存済みである必要があります（拡張機能の Configuration → Workflow Mapping）。
• 管理者スイッチがオンになっている必要があります（管理者がオフにしていない限りオンです。下記の「組織で無効にする」を参照してください）。

1. 個人用アクセストークンを作成する

Azure DevOps で、ユーザー設定 → 個人用アクセストークン → 新しいトークンを開きます。組織、有効期限を選択し、次の 3 つのスコープだけを指定してください。

• 作業項目：読み取り
• プロジェクトとチーム：読み取り
• 拡張機能データ：読み取り

ほかに必要な権限はありません。このトークンでコネクターができるのは読み取りのみで、何かを変更することはできません。

トークンの設定場所

• **Windows：**ユーザー環境変数として、名前を AZURE_DEVOPS_PAT に設定します（スタート →「アカウントの環境変数を編集」→ 新規）。アシスタントの設定ファイルには保存しないでください。新しい変数を認識させるため、設定後にアシスタントを再起動してください。
• **macOS と Linux：**デスクトップアシスタントはシェルのプロファイルを読み込まないため、サーバーエントリーの "env" ブロックに AZURE_DEVOPS_PAT として追加します（下記の例を参照）。また、設定ファイルを自分のユーザーアカウントだけが読み取れるようにしてください（chmod 600 <file>）。

トークンはコネクターのメモリ内に保持されます。表示、ログへの記録、書き込みが行われることはありません。

2. アシスタントにコネクターを追加する

コネクターは次のコマンドで起動します。

npx -y @baytekdev/agile-analytics-mcp

Claude Desktop（設定 → 開発者 → 設定を編集。claude_desktop_config.json が開きます）：

{
  "mcpServers": {
    "agile-analytics": {
      "command": "npx",
      "args": ["-y", "@baytekdev/agile-analytics-mcp"]
    }
  }
}

macOS と Linux では、同じエントリーにトークンを追加してください。

{
  "mcpServers": {
    "agile-analytics": {
      "command": "npx",
      "args": ["-y", "@baytekdev/agile-analytics-mcp"],
      "env": { "AZURE_DEVOPS_PAT": "<your token>" }
    }
  }
}

Claude Code（1 つのコマンドで設定。ユーザーアカウントにのみ保存されます）：

claude mcp add --scope user agile-analytics -- npx -y @baytekdev/agile-analytics-mcp

macOS と Linux では、-e を使ってエントリーにトークンを渡します。

claude mcp add --scope user agile-analytics -e AZURE_DEVOPS_PAT=<your token> -- npx -y @baytekdev/agile-analytics-mcp

Windows では、Claude Code は cmd /c を介して npx を起動します。

claude mcp add --scope user agile-analytics -- cmd /c npx -y @baytekdev/agile-analytics-mcp

VS Code（コマンドパレット →「MCP：ユーザー設定を開く」。ユーザー設定の mcp.json が開きます）：

{
  "servers": {
    "agile-analytics": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@baytekdev/agile-analytics-mcp"]
    }
  }
}

macOS と Linux では、そのエントリーに "env": { "AZURE_DEVOPS_PAT": "<your token>" } を追加してください。トークンをワークスペースの .vscode/mcp.json やプロジェクトの .mcp.json に保存しないでください。これらのファイルは共有されたり、コミットされたりすることがよくあります。

3. 質問する

組織（dev.azure.com/<org> の部分）、プロジェクト、チームを指定します。例：「組織 contoso、プロジェクト Contoso Web のチーム Platform のスプリント概要」。各回答はツールが返す数値で、アシスタントがそれを文章にまとめます。

Azure CLI を使ってサインインする

トークンを作成したくない場合は、Azure CLI を使えます。az login を一度実行し、AZURE_DEVOPS_PAT を未設定のままにしてください。この方法は Microsoft Entra に接続された組織で利用できます。Microsoft アカウントのみの組織では利用できません。Entra テナントを指定するには、args に "--tenant", "<tenant-guid>" を追加します（GUID 以外の値は拒否されます）。

コネクターは次の順序で認証情報を探します。まず AZURE_DEVOPS_PAT、次に旧形式の AZURE_DEVOPS_MCP_TEST_PAT（引き続き有効ですが、後日削除されます）、最後に Azure CLI です。

ツール

• sprint_summary（sprintId、デフォルトは直近の完了済みスプリント）：完了したアイテムとポイント、サイクルタイム、持ち越し、コミットメント（1 日目の終わりにコミットした内容、コミットした内容のうち完了した割合、信頼性、追加および削除されたスコープ）。1 日目が終わるまでは、コミットメントは null です。
• cycle_time と flow_efficiency（sprints は 3、6、または 12、デフォルトは 6）：直近 N 件の完了済みスプリント。進行中のスプリントは含まれません。
• wip：進行中のスプリントで、現在作業中のアイテム。
• aging：現在のスプリントで未完了の作業（前のスプリントからの持ち越しアイテムを含む）。各アイテムのステージ、そのステージに滞在している日数、フロー中の日数が含まれます。weekendBasis（business-days または calendar-days）は、経過日数に使う日数の基準を指定します。拡張機能に保存された Aging の設定を使用し、保存されていない場合は Aging ビューと同じデフォルト値を使用します。
• forecast（mode が howMany の場合は windowDays、デフォルトは 30、または backlog を指定した when）：Monte Carlo ビューのデフォルトの予測。

すべての回答には scope も含まれます。includesSubTeams（拡張機能の「サブチームの作業を含める」がこのチームに適用され、有効になっているか）と excludedTeamCount（この回答から除外される他のチームのアイテム数）が含まれるため、拡張機能と同じアイテムが集計されます。

読み取る情報と、決して読み取らない情報

• **Azure DevOps へのリクエスト：**固定された読み取りリクエストのリスト（ID のみを選択する作業項目クエリを 1 件含む）。それ以外のリクエストは送信前に拒否されます。
• **作業項目のフィールド：**状態、種類、日付、スプリントとエリアパス、見積もり、ボード列、ブロック済みフラグ。タイトル、担当者、タグ、説明、コメントは決して読み取りません。
• **チーム設定：**チームのスプリントと稼働日、およびこのチームに属するチーム。
• **Agile Analytics の設定：**保存済みのワークフローマッピング、「Exclude from metrics」リスト、Item Types マッピング、管理者スイッチ、自分の WIP 上限と週末の設定、組織とプロジェクトの週末のデフォルト設定、サブチームの選択。名前が指定された設定のみです。設定の一覧は取得しないため、ライセンスやその他の値は確認できません。
• ワークフローマッピングを推測することは決してありません。保存済みのマッピングがない場合、回答は workflow-not-mapped になります。

回答に含まれるのは数値、日付、固定の語句、ID、作業項目 ID のみです。タイトル、名前、コメントは含まれません。

コンピューターの外部に送信される情報

ユーザー自身のアクセス権を使って、dev.azure.com および extmgmt.dev.azure.com にリクエストを送信します。Baytek には何も送信されません。ライセンスの確認、テレメトリ、利用回数の計測は行われません。回答はアシスタントに渡されます。その回答をアシスタントがどう扱うかは、ユーザーとアシスタントのプロバイダーとの間で決まります。

組織で無効にする

組織の管理者は、拡張機能でコネクターを全ユーザーに対して無効にできます：Configuration → General、「Allow the local AI connector」。無効にしない限り有効です。コネクターは回答のたびにこの設定を読み取ります。無効の場合、すべてのツールの回答は disabled-by-admin になり、設定を読み取れない場合は on ではなく settings-unreadable になります。このスイッチは各ユーザーのコンピューター上でコネクターに適用されます。Azure DevOps の権限は変更されません。

エラー

エラーは {"error":"workflow-not-mapped"} のようなコードのみです。

• azure-cli-sign-in-required：トークンが見つからず、Azure CLI にサインインしていません。AZURE_DEVOPS_PAT を設定するか（ステップ 1 を参照）、az login を実行してください。
• workflow-not-mapped：まず、拡張機能でこのプロジェクトのワークフローマッピングを保存してください。
• disabled-by-admin：管理者がコネクターを無効にしました。
• settings-unreadable：拡張機能の設定を読み取れませんでした（拡張機能がインストールされているか、またトークンに Extension Data: Read の権限があるか確認してください）。
• ado-request-failed：Azure DevOps がリクエストを拒否したか、リクエストが失敗しました（トークンのスコープと有効期限を確認してください）。
• team-not-found、sprint-not-found、no-finished-sprints、invalid-input、request-not-allowed、internal-error。

呼び出し間で保持される内容

プロジェクトのチーム一覧、各チームの担当領域、各チームの稼働日は10分間メモリ上に保持されます。ディスクには何も書き込まれず、アシスタントを終了すると消去されます。管理者スイッチやワークフローのマッピングなど、それ以外のすべての情報は呼び出しのたびに最新の状態が読み込まれます。Azure DevOps でチームや担当領域を変更した場合、反映まで最大10分かかることがあります。すぐに反映するには、アシスタントを再起動してください。

このバージョンに含まれない機能

• 滞留期間ゾーンと傾向（p50／p85の範囲とスプリントごとの傾向）。

このリポジトリについて

このリポジトリには、コネクターのドキュメントが含まれています。パッケージは npm で @baytekdev/agile-analytics-mcp として公開されており、 Visual Studio Marketplace で提供されている Agile Analytics for Azure DevOps の一部です。 ソースコードはここでは公開されていません。

ご質問や問題がある場合は、このリポジトリでイシューを作成するか、 [email protected] までご連絡ください。