Azure Assistant MCP

🚀 Azure-Assistant-MCP

Azure-Assistant-MCPは、Azure Resource Graph (ARG) を使用してAzureを探索するための最小限で高速なMCPサーバーです。Azure環境に関する質問に答えるためのKQLを生成し、明確なスコープ指定とオプションの管理グループのカバレッジを持って実行します。

🚀 クイックスタート

このプロジェクトは、独自の責任で使用してください。「現状のまま」提供され、いかなる保証も伴いません。このプロジェクトの使用方法、設定、アクセス制御、および組織のポリシーへの準拠については、ユーザー自身が完全に責任を負います。作者および貢献者は、このソフトウェアの使用に起因する損害、データ損失、セキュリティインシデント、費用、またはポリシー違反について一切の責任を負いません。また、いかなる雇用主または組織がこのプロジェクトを承認またはサポートしていることを意味するものではありません。

✨ 主な機能

• 一般的なタスクについて自然言語をKQLに変換し、常にクエリを表示します。
• ページング上限 (top) を持ってARGに対して直接KQLを実行します。
• レスポンスに明確なスコープ（テナント + サブスクリプションまたは管理グループ）を表示します。
• サブスクリプションを自動検出するか、管理グループスコープでクエリを実行します。
• オプションの診断モードで、迅速なスコープデバッグを行います。

📦 インストール

• リポジトリのルートディレクトリから以下のコマンドを実行します。
  • pip install -e .
  • またはラッパースクリプトを使用します: ./azure-assistant-mcp.sh (.venv が存在する場合はこれを優先します)
• クライアントでラッパーコマンドを使用して、MCP stdioサーバーとして追加します。
  • ラッパースクリプトが実行可能であることを確認します: chmod +x ./azure-assistant-mcp.sh
  • 例 (Claude Desktop CLI):

    claude mcp add azure-assistant-mcp \
      /your/path/Azure-Assistant-MCP/azure-assistant-mcp.sh \
      --env AZURE_ASSISTANT_CONFIG=/your/path/Azure-Assistant-MCP/azure-config.json \
      --scope user \
      --transport stdio
    

💻 使用例

基本的な使用法

• テナント内の管理グループでサブスクリプションを一覧表示する:
  • ツール: list-subscriptions
  • 入力: { "tenant_name": "Contoso" }
• テナント内のすべてのサブスクリプションにおけるVMの数をカウントする:
  • ツール: ask-azure
  • 入力: { "tenant_name": "Contoso", "question": "How many virtual machines exist?" }
• 管理グループスコープですべてのサブスクリプションに対して直接KQLを実行する:
  • ツール: run-arg-kql
  • 入力: { "tenant_name": "Contoso", "kql_query": "resourcecontainers | where type =~ 'microsoft.resources/subscriptions' | project name, subscriptionId | order by name asc" }

📚 ドキュメント

構成

• シークレット情報を azure-config.json (gitによって無視されます) に配置します。構造については azure-config-example.json を参照してください。
• 起動スクリプトは AZURE_ASSISTANT_CONFIG をリポジトリの azure-config.json にエクスポートし、誤ったクロスリポジトリ構成を避けます。
• AZURE_ASSISTANT_CONFIG を使用して、カスタムの場所を指定することもできます。

スキーマ

• トップレベル
  • debug (オプション): 診断ツールを有効にします。
  • tenants: 構成されたテナントのリスト
• テナントごと
  • id: テナントのGUID
  • name: フレンドリーな名前
  • service_principal.client_id / service_principal.client_secret
  • default_subscription_id (オプションのフォールバック)
  • management_group_id (オプション; contoso-root のような短い名前または完全なリソースID)。サーバーは短い名前に正規化します。

スコープルール

• subscription_ids が指定された場合: それらのサブスクリプションを使用します。
• それ以外で use_all_subscriptions が true で、management_group_id が構成されている場合: ARGで管理グループスコープで実行します。
• それ以外の場合: ARMを介してサブスクリプションを列挙し、そのリストを使用します。
• それでもない場合: default_subscription_id にフォールバックします。
• レスポンスには常に Tenant と、Scope: managementGroup=... または Subscriptions used: N が表示されます。

ツール

• ask-azure:
  • 入力: { "question": string, "tenant_name?": string, "subscription_ids?": string[], "use_all_subscriptions?": boolean, "auto_execute?": boolean }
  • 質問に対するKQLを生成します。auto_execute が true (デフォルト) の場合、スコープルールを使用して実行します。tenant_name が省略された場合、サーバーはテキストからヒューリスティックに推測します（名前と頭字語をマッチングします）。
• list-tenants:
  • 入力: {}
  • azure-config.json から構成されたテナントを、それらのID、オプションの management_group_id、および default_subscription_id とともに一覧表示し、スコープとSPNの選択を支援します。
• run-arg-kql:
  • 入力: { "kql_query": string, "tenant_name?": string, "subscription_ids?": string[], "use_all_subscriptions?": boolean, "top?": integer }
  • スコープルールを使用して提供されたKQLを実行します。ヘッダーに Rows、Tenant、およびスコープ行を追加します。
• run-kql-template:
  • 入力: { "template_name": string, "params?": object, "tenant_name?": string, "subscription_ids?": string[], "use_all_subscriptions?": boolean, "top?": integer }
  • src/azure_assistant_mcp/kql/<template_name>.md (fenced kql) または .kql を読み込み、params から単純な {{key}} 置換を適用し、スコープルールで実行します。
• list-subscriptions:
  • 入力: { "tenant_name?": string }
  • サブスクリプションを一覧表示します。可能な場合はARM列挙を使用し、ARGで補完します。構成されている場合は管理グループスコープを優先し、完全なリストを返します。
• vm-count-by-tenant:
  • 入力: { "tenant_names?": string[], "use_all_subscriptions?": boolean }
  • スコープルールを使用して、テナントごとに簡単なVMカウントを実行します。
• diagnostics (debug が true の場合のみ表示):
  • 入力: { "tenant_name?": string }
  • 構成パス、解決されたテナント、正規化されたMG ID、ARM列挙サンプルとカウント、ARG MGカバレッジサンプルとカウント、およびデフォルトのスコープ決定を表示します。
• arg-tables:
  • 入力: {}
  • 一般的なAzure Resource Graphテーブル (resourcecontainers、resources、resourcechanges、advisorresources、healthresources、policyresources) の概要を、目的と典型的なユースケースとともに表示します。
• arg-examples:
  • 入力: { "topic?": string } ここで topic は subscriptions、resourcegroups、changes、containerchanges、advisor、health、または policy です。
  • ARGテーブル全体の一般的なシナリオに対するサンプルKQLスニペットを返します。

KQLテンプレート (クエリのカスタマイズ)

• Pythonコードに触れることなく、組み込みツールとサンプルで使用されるKQLを編集することができます。
• テンプレートは src/azure_assistant_mcp/kql/ に .md ファイルとして、fenced ```kql ブロック (または単純な .kql ファイル) で保存されます。
• 実行時に、サーバーはこれらのテンプレートを読み込みます。フォールバックはありません: 必要なテンプレートが欠落している場合、サーバーはエラーを発生させ、修正できるようにします。
• AZURE_ASSISTANT_KQL_PATH を別のフォルダに設定することで、テンプレートディレクトリをオーバーライドできます。
• 例:
  • list_subscriptions.md
  • list_resource_groups.md
  • untagged_resource_groups.md
  • manual_changes.md
  • resource_changes_recent.md
  • stopped_vms.md
  • generic_list_resources.md
  • 独自のテンプレートを作成し、例えば kubernetes_inventory.md を作成したら、run-kql-template { "template_name": "kubernetes_inventory", "params": { ... } } で実行できます。

🔧 技術詳細

• コードは src/azure_assistant_mcp/ にあります。エントリポイントは azure_assistant_mcp:main です。
• ラッパースクリプト: azure-assistant-mcp.sh (PYTHONPATH を設定し、AZURE_ASSISTANT_CONFIG を固定します)
• 下位互換性のためのエイリアス: azure-assistant.sh (非推奨)
• 依存関係: mcp、python-dotenv、azure-identity、azure-mgmt-resourcegraph、azure-mgmt-subscription

📄 ライセンス

• このプロジェクトはApache-2.0ライセンスの下でライセンスされています。詳細な条件については LICENSE を参照してください。
• 帰属: このプロジェクトには NOTICE ファイルが含まれています。Apache-2.0 §4(d) に従い、再配布者はいかなるソース配布物、および通常そのような通知が表示されるドキュメントまたはアバウトダイアログにおいて、NOTICE 内の帰属通知を保持しなければなりません。

商用利用とスポンサー

• エンタープライズユーザーは、ドキュメントまたはアバウトページでこのプロジェクトを帰属させることをお勧めします。
• 組織がこのプロジェクトから利益を得ている場合、スポンサーシップまたは商用サポート契約を検討してください。
• オプション:
  • 商用サポート/ライセンスの問い合わせ: イシューを作成するか、メンテナーに連絡してください。
  • 

トラブルシューティング

• サブスクリプションが1つしか表示されない場合:
  • すべてのターゲットサブスクリプションを含む management_group_id を追加するか、subscription_ids を明示的に渡してください。
• ARGから BadRequest が返される場合:
  • KQL構文と選択されたスコープを確認してください。小さなクエリと top を使用して run-arg-kql から始めてください。
• スコープをすばやく検証する場合:
  • debug: true を有効にし、テナントに対して diagnostics ツールを実行してください。

開発

• コードは src/azure_assistant_mcp/ にあります。エントリポイントは azure_assistant_mcp:main です。
• ラッパースクリプト: azure-assistant-mcp.sh (PYTHONPATH を設定し、AZURE_ASSISTANT_CONFIG を固定します)
• 下位互換性のためのエイリアス: azure-assistant.sh (非推奨)
• 依存関係: mcp、python-dotenv、azure-identity、azure-mgmt-resourcegraph、azure-mgmt-subscription

貢献

• イシューとプルリクエストは大歓迎です。例やログから実際のテナントID、シークレット、または組織名を省略してください。

セキュリティ

⚠️ 重要提示

実際の資格情報をコミットしないでください。azure-config.json はgitによって無視されます。サンプルファイルをテンプレートとして使用してください。 シークレット情報を安全なストアに保存し、構成をテンプレート化することを検討してください。 サービスプリンシパルがクエリするスコープに対して最小限の権限を持っていることを確認してください。

💡 使用建议

本プロジェクトを使用する際には、自身の責任で適切な設定と管理を行ってください。また、セキュリティに関する事項には十分な注意を払い、組織のポリシーに準拠するようにしてください。