AzPolicyMCP

AzPolicyMCP

あらゆるリソースの種類に対応する Azure ポリシーの作成を支援する、シンプルな MCP サーバーです。

概要

このドキュメントでは、Azure Policy Model Context Protocol（MCP）サーバーの要件について説明します。このサーバーの主な目的は、LLM がユーザーによる Azure カスタムポリシーの効果的な生成、検証、デプロイを支援できるようにすることです。関連する組み込みポリシーを例として取得するツール、生成されたポリシーの構造を公式スキーマに照らして検証するツール、Azure REST API を介してポリシー割り当てを管理するツールを提供することで、LLM が誤った、または準拠していない可能性のある Azure ポリシー JSON を生成する問題を解決します。また、ユーザーの意図（監査／拒否と修復）に基づいて、適切なポリシー効果を選択できるよう LLM を支援することも目的としています。対象ユーザーは、Azure Policy の定義や割り当てと連携する必要がある LLM アプリケーション（チャットボットやコードアシスタントなど）です。ユーザーのリクエストに基づいて、正確で準拠した Azure ポリシーを作成、検証、デプロイするための、標準化された信頼性の高いインターフェースを LLM に提供できる点が、このサーバーの価値です。

主な機能

1. get_builtin_policies ツール（実装済み）：

   • 機能： Azure/azure-policy GitHub リポジトリから Azure 組み込みポリシーの最上位カテゴリを取得します。カテゴリ名による絞り込みも任意で指定できます。
   • 重要な理由： LLM が利用可能なポリシーカテゴリ（例：「Storage」「Compute」「Network」）を見つけられるようにします。
   • 仕組み： GitHub API を使用して、built-in-policies/policyDefinitions パス内のディレクトリを一覧表示します。カテゴリ名とそれぞれに対応するパスの一覧を返します。

2. get_policies_in_category ツール（実装済み）：

   • 機能： get_builtin_policies から取得した指定カテゴリのパス内にある個々のポリシー定義ファイル（名前、パス、ダウンロード URL）を取得します。ファイル名によるポリシーの絞り込みも任意で指定できます。
   • 重要な理由： LLM が特定の分野を詳しく調べ、関連するポリシーの例を見つけられるようにします。
   • 仕組み： GitHub API を使用して、指定されたカテゴリのパス内にあるファイルを一覧表示します。JSON ファイル名、パス、直接ダウンロードできる URL の一覧を返します。

3. get_policy_content ツール（実装済み）：

   • 機能： get_policies_in_category から取得した直接ダウンロード URL を使用して、特定のポリシー定義の JSON コンテンツを取得します。
   • 重要な理由： 実際のポリシー JSON を提供します。LLM はこれを具体例またはテンプレートとして使用できます。
   • 仕組み： 指定された GitHub の raw コンテンツ URL に HTTP GET リクエストを送信します。ポリシー JSON を文字列として返します。

4. verify_policy_structure ツール（一時的に無効）：

   • 機能： 指定された JSON 文字列を、公式の Azure Policy 定義スキーマに照らして検証します。
   • 重要な理由： LLM が生成したカスタムポリシーが、エンドユーザーに提示される前に Azure で必要とされる正しい構文と構造に準拠していることを確認し、デプロイエラーを防ぎます。
   • 仕組み（予定）： ポリシー定義（JSON 文字列）を入力として受け取ります。JSON を解析し、jsonschema ライブラリを使用して、ローカルに保存された公式の Azure Policy JSON スキーマ（schemas/policyDefinition.json）に照らして検証します。成功メッセージまたは検証エラーを返します。(現在、問題があるため server.py でコメントアウトされています。)

5. deploy_policy_assignment ツール（実装済み）：

   • 機能： 指定されたポリシー定義（JSON または ID）と割り当てパラメーター（スコープ、名前など）を使用して、Azure Policy Assignment を作成または更新します。
   • 重要な理由： 生成して検証したポリシーをターゲットの Azure 環境にデプロイし、LLM がワークフローを完了できるようにします。
   • 仕組み： 環境変数（TENANT_ID、CLIENT_ID、CLIENT_SECRET）で設定された Azure 認証資格情報を使用し、MSAL でアクセストークンを取得します。適切な Azure REST API 呼び出し（PUT）を構成して、providers/Microsoft.Authorization/policyAssignments エンドポイントに実行します。

6. query_policy_compliance ツール（実装済み）：

   • 機能： 指定されたスコープ内のリソースのコンプライアンス状態を照会します。必要に応じて、ポリシー割り当て名またはコンプライアンス状態でフィルタリングできます。
   • 重要な理由： LLM がポリシーのコンプライアンス状態を報告できるようにし、デプロイされたポリシーの有効性についてユーザーに貴重なフィードバックを提供します。
   • 仕組み： Azure Policy Insights REST API を使用して、指定されたスコープにあるリソースのコンプライアンスデータを取得します。

7. delete_policy_assignment ツール（実装済み）：

   • 機能： 指定されたスコープから既存の Azure Policy Assignment を削除します。
   • 重要な理由： クリーンアップや削除を含め、LLM がポリシー割り当てのライフサイクルを管理できるようにします。
   • 仕組み： ポリシー割り当て用の Azure REST API エンドポイントに HTTP DELETE リクエストを実行します。

8. create_policy_definition ツール（実装済み）：

   • 機能： 指定された詳細情報（名前、表示名、説明、モード、パラメーター、ポリシールールなど）を使用して、Azure Policy Definition を作成または更新します。
   • 重要な理由： LLM が Azure 内でカスタム Azure ポリシーを直接定義できるようにし、ポリシー管理のエンドツーエンドのワークフローを実現します。
   • 仕組み： 環境変数（TENANT_ID、CLIENT_ID、CLIENT_SECRET）で設定された Azure 認証資格情報を使用し、MSAL でアクセストークンを取得します。適切な Azure REST API 呼び出し（PUT）を構成して、providers/Microsoft.Authorization/policyDefinitions エンドポイントに実行します。

9. インテント識別のサポート（新しい要件）：

   • 内容： ユーザーの目標が、非準拠リソースを監査または防止すること（Audit、Deny などの効果を使用）なのか、既存のリソースを修復すること（DeployIfNotExists、Modify などの効果を使用）なのかを LLM が判断するための機能またはガイダンスです。
   • 重要な理由： 適切なポリシー効果を選択することは、ユーザーが望む結果を実現し、policyRule を正しく構成するうえで重要です。
   • 仕組み： 次のような方法が考えられます。
     • create_policy_prompt（機能 9）を拡張し、LLM がユーザーに意図を明確にするよう明示的に尋ねる。
     • 下書きのポリシー定義を分析し、キーワードや構造に基づいて適切な効果を提案するツールを追加する。
     • 各効果の一般的なユースケースに関するガイダンス（ルールまたはリソース内など）を提供する。

10. （任意の拡張）azure_policy_schema リソース： * 機能： MCP リソース URI（例：schema://azurepolicy）を介して、公式の Azure Policy JSON スキーマを公開します。 * 重要な理由： LLM クライアントがスキーマ定義を直接取得できるようにし、生成を試みる前に対象の構造をより深く理解できるようにします。 * 仕組み： これは現行バージョンですでに実装されています。

11. （任意の拡張）azure_resource_types リソース： * 機能： MCP リソース URI（例：types://azure/resources）を介して、一般的な Azure リソースプロバイダーの名前空間と種類の一覧を提供します。 * 重要な理由： ポリシールール内でリソースの種類を示す正しい識別子を LLM が使用できるようにします。

12. （任意の拡張機能）create_policy_prompt プロンプト： * 機能： ポリシー作成プロセスをガイドする、再利用可能な MCP プロンプトテンプレートを定義します。これには、意図の明確化も含まれます。 * 重要な理由： LLM のワークフローを標準化し、利用可能なツールやリソースを効果的に使えるよう促します（例：「{resource_type} に対して {requirement} を適用するポリシーを生成してください。これが新しいリソースを監査／ブロックするものか、既存のリソースを修復するものかを明確にしてください。例を参照するにはポリシー取得ツールを使用し、確定する前に verify_policy_structure を使用してください。デプロイには deploy_policy_assignment を使用してください。」）。

13. （新規）azure_resource_graph_query ツール（計画中）： * 機能： LLM が Azure REST API を使用して任意の Azure Resource Graph クエリを実行できるようにし、リソース、サブスクリプション ID、リソースグループなどを検出できるようにします。 * 重要な理由： LLM が Azure 環境の構造と内容を動的に検出できるようにします。これには、サブスクリプション ID、リソースの種類、リソース間の関係の取得が含まれ、適切なポリシーのデプロイと割り当てに不可欠です。 * 仕組み： Azure 認証（MSAL）を使用してトークンを取得し、ユーザー指定のクエリを指定して Resource Graph REST API エンドポイント（POST https://management.azure.com/providers/Microsoft.ResourceGraph/resources?api-version=2022-10-01）を呼び出します。結果は JSON として返されます。クエリの例としては、すべてのサブスクリプションの一覧表示、すべての VM の検索、種類や場所ごとのリソースの集計などがあります。

ユーザーエクスペリエンス

この MCP サーバーの主な「ユーザー」は、LLM クライアントアプリケーションです。操作の流れは次のとおりです。

1. エンドユーザーが LLM アプリケーションにカスタム Azure ポリシーをリクエストします（例：「App Services で HTTPS を適用するポリシーを作成してください」）。
2. LLM アプリケーションが Azure Policy MCP Server とやり取りします。
3. LLM が get_builtin_policies を（任意でクエリを指定して）呼び出し、関連するポリシーカテゴリを検索します。
4. LLM が選択したカテゴリパスに対して get_policies_in_category を（任意でクエリを指定して）呼び出し、関連するポリシーファイルを検索します。
5. LLM が 1 つ以上のポリシーのダウンロード URL を使用して get_policy_content を呼び出し、例を取得します。
6. LLM は（実装されている場合）、必要な構造を理解するために schema://azurepolicy に対して read_resource を呼び出すことがあります。
7. LLM はユーザーとやり取りし（create_policy_prompt によってガイドされる場合があります）、意図（監査／ブロックか修復か）を明確にし、適切なポリシー効果を判断します。
8. LLM はユーザーのリクエスト、明確化した意図、取得した例やスキーマに基づいてカスタムポリシー JSON を生成します。
9. LLM は、生成した JSON を指定して verify_policy_structure を呼び出す必要があります（有効化された場合）。
10. 有効な場合、LLM はデプロイのスコープとパラメーターをユーザーに確認します。
11. LLM は検証済みのポリシー定義と割り当ての詳細を指定して deploy_policy_assignment を呼び出します。
12. LLM は必要に応じて query_policy_compliance を使用してコンプライアンス状況を照会します。
13. LLM は必要に応じて delete_policy_assignment を使用してポリシー割り当てを削除します。
14. LLM はデプロイ結果（成功または詳細を含む失敗）をエンドユーザーに提示します。
15. 検証（ステップ 9）またはデプロイ（ステップ 11）が失敗した場合、LLM はエラーフィードバックを使用してポリシー／パラメーターを修正し、再検証／デプロイを再試行します。

Azure 認証の設定（実装済み）

MCP サーバーには、msal ライブラリを使用した Azure 認証が含まれるようになりました。認証のため、次の環境変数が設定されていることを確認してください。

• TENANT_ID：Azure Active Directory のテナント ID。
• CLIENT_ID：Azure AD アプリケーションのクライアント ID。
• CLIENT_SECRET：Azure AD アプリケーションのクライアントシークレット。

これらの認証情報は、deploy_policy_assignment、query_policy_compliance、delete_policy_assignment、create_policy_definition ツールを正しく動作させるために必要です。

技術アーキテクチャ

• コアフレームワーク： FastMCP を使用する Python mcp-sdk。
• サーバーコンポーネント：
  • server.py：FastMCP のメインアプリケーション定義。ツール（get_builtin_policies、get_policies_in_category、get_policy_content、deploy_policy_assignment、query_policy_compliance、delete_policy_assignment、create_policy_definition）を登録します。検証用のスキーマを読み込みます。
  • schemas/policyDefinition.json：公式の Azure Policy JSON スキーマファイルのローカル保存コピー（無効化されている verify_policy_structure で使用）。
  • （新規） 資格情報用の環境変数を使用した、msal ライブラリによる Azure 認証の設定。
• データモデル：
  • MCP ツールの入出力（server.py の関数シグネチャと型ヒントで定義）。
  • Azure Policy の JSON 構造（dict/string として処理）。
  • Azure Policy Schema の JSON 構造（server.py で jsonschema により読み込み）。
• API とインテグレーション：
  • FastMCP が公開する MCP プロトコルインターフェース。
  • requests による GitHub API（ポリシー取得ツールで使用）。
  • （新規） httpx による Azure REST API（deploy_policy_assignment、query_policy_compliance、delete_policy_assignment、create_policy_definition で使用）。
• 主なライブラリ： mcp[cli]、requests、jsonschema、（新規） msal、httpx。
• インフラストラクチャ： Python 3.x 環境。Azure 資格情報の安全な設定が必要です（例：環境変数、Azure でホストする場合のマネージド ID）。

開発ロードマップ

• フェーズ 1：MVP（コア機能）

  • 基本的な FastMCP サーバープロジェクト構成をセットアップします（server.py）。
  • 公式の Azure Policy JSON スキーマを取得し、schemas/ に保存します。
  • jsonschema と保存済みスキーマを使用して、verify_policy_structure ツールを実装し、修正します。（現在、作業が保留・無効化されています）
  • GitHub API（requests）を使用して、get_builtin_policies、get_policies_in_category、get_policy_content を実装します。
  • すべてのツールの基本的なユニットテスト。
  • セットアップと使用方法を説明する基本的な README.md。
  • LLM がリソースをクエリし、サブスクリプション ID を取得し、環境の詳細を確認できるように、Azure Resource Graph API ツール（azure_resource_graph_query）を実装します。
  • Resource Graph ツールの使用方法を文書化し、クエリ例を提示します。
  • ポリシーのデプロイツールでサブスクリプション ID が指定されていない場合に、提案または自動取得するロジックを追加します。

• フェーズ 2：機能強化と信頼性

  • azure_policy_schema MCP リソースを実装します。
  • azure_resource_types MCP リソースを実装します（このリストの作成が必要です）。
  • 意図の明確化に関するガイダンスを含めて、create_policy_prompt MCP プロンプトを実装します。
  • スキーマファイルを確認・更新する仕組みを実装します。
  • ツールのエラー処理とログ記録を改善します（タイムアウトは追加済みで、さらなる改善も可能です）。
  • テストカバレッジを拡大します。
  • Resource Graph ツールの結果をポリシーのデプロイワークフローに統合します（例：スコープの自動提案、リソースの存在確認）。

• フェーズ 3：デプロイと高度な機能（新規）

  • 堅牢な Azure 認証の仕組みを実装します（例：サービスプリンシパルまたはマネージド ID を使用する azure-identity）。
  • さまざまなスコープとパラメーターに対応する deploy_policy_assignment ツールを実装します。
  • 単純なプロンプトでは不十分な場合に、意図の識別（監査／拒否と修復）をサポートするロジックまたはツールを追加します。
  • マネージド ID が必要なポリシー（deployIfNotExists／Modify）の割り当てをサポートします。
  • デプロイのインテグレーションテスト（慎重なセットアップが必要）を含め、テストカバレッジをさらに拡大します。
  • Resource Graph ツールを拡張し、高度なクエリ、結合、集計をサポートして、環境に関するより詳細な情報を提供します。

論理的な依存関係の流れ

1. mcp-sdk を使用して基本的な Python プロジェクトを構築します。
2. Azure Policy JSON スキーマ（schemas/policyDefinition.json）を取得して統合します。
3. GitHub API のデータアクセスツール（get_builtin_policies、get_policies_in_category、get_policy_content）を実装します。
4. verify_policy_structure を実装して修正します（スキーマに依存）。(ブロック中)
5. オプションのリソースを実装します。
6. オプションのプロンプトを実装します（意図の明確化を含む）。
7. Azure 認証を実装します。
8. deploy_policy_assignment を実装します（検証と認証に依存）。
9. 信頼性向上機能を実装します（スキーマの更新）。

当初は、GitHub API を介したポリシーの取得を機能させることに重点を置いていました。次の重点は、検証の問題を解決し、その後デプロイ機能を実装することです。

現在の状況と次のステップ

• 状況： MCP サーバーは稼働中です。ポリシーカテゴリの検出（get_builtin_policies）、カテゴリ内のポリシー一覧表示（get_policies_in_category）、ポリシーコンテンツの取得（get_policy_content）、ポリシー割り当てのデプロイ（deploy_policy_assignment）、コンプライアンスの照会（query_policy_compliance）、ポリシー割り当ての削除（delete_policy_assignment）、ポリシー定義の作成（create_policy_definition）を行うツールが実装済みで、機能しています。基本的なエラー処理とタイムアウトが含まれています。verify_policy_structure ツールは実装済みですが、実行時エラーや検証ロジックの問題により、現在コメントアウトされています。スキーマファイル（schemas/policyDefinition.json）は存在します。
• 次のアクションプラン：
  1. verify_policy_structure のデバッグと修正： server.py 内のツールのコメントアウトを解除し、jsonschema の検証エラーを調査します。schemas/policyDefinition.json ファイルに対して、ポリシー JSON が正しく検証されることを確認します。
  2. Azure Resource Graph API ツールの実装： 任意の Resource Graph クエリを実行するツールを追加し、LLM がサブスクリプション ID やリソースの詳細を動的に取得できるようにします。ドキュメントにクエリ例を記載します。
  3. 基本的な README の追加： 環境の設定方法、サーバーの実行方法、利用可能なツールの使い方を説明する README.md を作成します。
  4. ユニットテスト： 現在機能しているポリシー取得ツールから、ユニットテストの追加を開始します。

リスクと軽減策

• リスク： verify_policy_structure ツールの修正が難しい、またはスキーマの大幅な調整が必要になる可能性があります。
  • 軽減策： jsonschema のドキュメントと具体的な検証エラーを詳しく確認します。ダウンロードしたスキーマを Azure のドキュメントにある例と比較します。必要に応じて、まずはより簡単な検証方法を検討します。
• （新規）リスク： Azure 認証を安全かつ確実に扱うことが複雑です。
  • 軽減策： azure-identity などの標準ライブラリを使用します。認証情報管理のベストプラクティス（環境変数、Key Vault、Managed Identity）に従います。セットアップ要件を明確に記載します。
• （新規）リスク： Azure Policy Assignments REST API には固有の仕様があります（スコープ、パラメーター、修復のための ID 管理など）。
  • 軽減策： まずは、より簡単な割り当てシナリオ（例：リソースグループスコープでの Audit ポリシー）から開始します。パラメーターやさまざまなスコープへの対応を段階的に追加します。Azure REST API のドキュメントを十分に参照します。API レスポンスに対する包括的なエラー処理を実装します。
• （新規）リスク： LLM が、ポリシーの効果（監査／拒否と修復）に関するユーザーの意図を誤って解釈する可能性があります。
  • 軽減策： 明確なプロンプト（create_policy_prompt）を設計します。例を提示します。やり取りを記録し、LLM によくある誤りを特定します。プロンプトだけでは不十分な場合は、明示的なチェックや専用の分析ツールの追加を検討します。
• （新規）リスク： 誤ったポリシーや割り当てをデプロイすると、Azure 環境に悪影響を及ぼす可能性があります。
  • 軽減策： verify_policy_structure の手順が重要であることを強調します。deploy_policy_assignment 内に必須パラメーターのチェックを実装します。デプロイ前にユーザーの確認を促します。本番以外の環境でテストするよう勧めます。
• リスク： GitHub API のレート制限や停止により、ポリシー取得ツールに影響が及ぶ可能性があります。
  • 軽減策： 現在の実装では認証なしのリクエストを使用しています（レート制限がより厳しくなる可能性があります）。この制限を記載します。後から、認証済みリクエスト（より高い上限）用に GitHub トークンのオプションサポートを追加することを検討します。一時的なエラーが頻発するようになった場合は、適切な再試行ロジックを実装します。必要に応じて、結果を短時間キャッシュします。
• リスク： ローカルに保存されたスキーマ（schemas/policyDefinition.json）を最新の状態に保つには、手間がかかります。
  • 軽減策： 定期的な確認／手動更新の手順をバックログ（フェーズ 2）に追加します。現在のスキーマの出典と日付を記載します。

付録

• Azure Policy のドキュメント
• Azure Policy の GitHub リポジトリ
• （新規） Azure Policy Assignments REST API
• Azure Resource Graph REST API
• Azure Resource Graph Query Language
• Azure Resource Graph クエリの例
• MCP Python SDK のドキュメント（ユーザー提供の README.md を参照）
• JSON Schema の仕様
• Requests ライブラリ
• jsonschema ライブラリ
• （新規） azure-identity ライブラリ
• （新規） Azure Policy Definitions REST API
• （新規） MSAL Python のドキュメント
• （新規） httpx ライブラリ