AzPolicyMCP

AzPolicyMCP

用于帮助为任何资源类型创建 Azure Policy 的简单 MCP 服务。

概述

本文档概述了 Azure Policy 模型上下文协议（MCP）服务的需求。该服务的主要目标是帮助大模型有效地生成、验证并部署 Azure 自定义策略。它通过提供工具来获取相关内置策略作为示例、根据官方架构验证生成的策略结构，并通过 Azure REST API 管理策略分配，从而解决大模型生成可能不正确或不合规的 Azure 策略 JSON 的问题。它还旨在帮助大模型根据用户意图（审核/拒绝或修正）选择适当的策略效果。目标用户是需要与 Azure Policy 定义和分配交互的大模型应用（例如聊天机器人或代码助手）。其价值在于为大模型提供标准化、可靠的接口，以便根据用户请求创建、验证和部署准确且合规的 Azure 策略。

核心功能

1. get_builtin_policies 工具（已实现）：

   • 功能： 从 Azure/azure-policy GitHub 仓库获取 Azure 内置策略的顶级类别。可按名称筛选类别。
   • 重要性： 让大模型能够发现可用的策略类别（例如，“Storage”“Compute”“Network”）。
   • 工作原理： 使用 GitHub API 列出 built-in-policies/policyDefinitions 路径下的目录。返回类别名称及其对应路径的列表。

2. get_policies_in_category 工具（已实现）：

   • 功能： 获取从 get_builtin_policies 获得的指定类别路径中的单个策略定义文件（名称、路径、下载 URL）。可按文件名筛选策略。
   • 重要性： 让大模型能够深入特定领域并查找相关策略示例。
   • 工作原理： 使用 GitHub API 列出所提供类别路径中的文件。返回 JSON 文件名、路径和直接下载 URL 的列表。

3. get_policy_content 工具（已实现）：

   • 功能： 使用从 get_policies_in_category 获取的直接下载 URL，获取特定策略定义的原始 JSON 内容。
   • 重要性： 提供实际的策略 JSON，大模型可将其用作具体示例或模板。
   • 工作原理： 向所提供的 GitHub 原始内容 URL 发出 HTTP GET 请求。以字符串形式返回策略 JSON。

4. verify_policy_structure 工具（暂时禁用）：

   • 功能： 根据官方 Azure Policy 定义架构验证给定的 JSON 字符串。
   • 重要性： 确保大模型生成的任何自定义策略在呈现给最终用户之前，都符合 Azure 要求的正确语法和结构，避免部署错误。
   • 工作原理（预期）： 将策略定义（以 JSON 字符串形式）作为输入。使用 jsonschema 库解析 JSON，并根据本地存储的官方 Azure Policy JSON 架构副本（schemas/policyDefinition.json）进行验证。返回成功消息或验证错误。（目前由于存在问题，已在 server.py 中注释掉。）

5. deploy_policy_assignment 工具（已实现）：

   • 功能： 使用提供的策略定义（JSON 或 ID）和分配参数（范围、名称等），创建或更新 Azure Policy Assignment。
   • 重要性： 使大模型能够完成工作流，将生成并验证后的策略部署到目标 Azure 环境中。
   • 工作方式： 使用通过环境变量（TENANT_ID、CLIENT_ID、CLIENT_SECRET）配置的 Azure 身份验证凭据，通过 MSAL 获取访问令牌。构造并执行对 providers/Microsoft.Authorization/policyAssignments 终结点的相应 Azure REST API 调用（PUT）。

6. query_policy_compliance 工具（已实现）：

   • 功能： 查询指定范围内资源的合规状态，可按策略分配名称或合规状态筛选。
   • 重要性： 允许大模型报告策略合规状态，为用户提供有关已部署策略效果的有价值反馈。
   • 工作方式： 使用 Azure Policy Insights REST API 检索指定范围内资源的合规数据。

7. delete_policy_assignment 工具（已实现）：

   • 功能： 从指定范围删除现有的 Azure Policy Assignment。
   • 重要性： 使大模型能够管理策略分配的生命周期，包括清理和移除。
   • 工作方式： 向用于策略分配的 Azure REST API 终结点发送 HTTP DELETE 请求。

8. create_policy_definition 工具（已实现）：

   • 功能： 使用提供的详细信息（名称、显示名称、说明、模式、参数、策略规则等）创建或更新 Azure Policy Definition。
   • 重要性： 允许大模型直接在 Azure 中定义自定义 Azure 策略，从而实现完整的端到端策略管理工作流。
   • 工作方式： 使用通过环境变量（TENANT_ID、CLIENT_ID、CLIENT_SECRET）配置的 Azure 身份验证凭据，通过 MSAL 获取访问令牌。构造并执行对 providers/Microsoft.Authorization/policyDefinitions 终结点的相应 Azure REST API 调用（PUT）。

9. 意图识别支持（新需求）：

   • 内容： 提供功能或指导，帮助大模型判断用户的目标是审计／阻止不合规资源（使用 Audit、Deny 等效果），还是修复现有资源（使用 DeployIfNotExists、Modify 等效果）。
   • 重要性： 选择正确的策略效果对于实现用户期望的结果和正确构建 policyRule 至关重要。
   • 工作方式： 可能包括：
     • 增强 create_policy_prompt（功能 9），明确要求大模型向用户澄清意图。
     • 可能添加一个工具，用于分析策略定义草稿，并根据关键词或结构建议合适的效果。
     • 提供指导（例如，在规则／资源中），说明不同效果的常见用例。

10. （可选增强）azure_policy_schema 资源： * 功能： 通过 MCP 资源 URI（例如 schema://azurepolicy）公开官方 Azure Policy JSON 架构。 * 重要性： 允许大模型客户端直接获取架构定义，使其在尝试生成内容之前更好地理解目标结构。 * 工作方式： 当前版本已实现此功能。

11. （可选增强）azure_resource_types 资源： * 功能： 通过 MCP 资源 URI（例如 types://azure/resources）提供常见 Azure 资源提供程序命名空间和类型的列表。 * 重要性： 帮助大模型在策略规则中使用正确的资源类型标识符。

12. （可选增强）create_policy_prompt 提示词： * 功能： 定义一个可复用的 MCP 提示词模板，引导大模型创建策略，包括澄清意图。 * 重要性： 标准化大模型的工作流，引导其有效使用可用的工具和资源（例如：“为 {resource_type} 生成一项策略，以强制执行 {requirement}。请确认此策略是用于审计／阻止新资源，还是用于修正现有资源。 使用策略获取工具查找示例，并在定稿前调用 verify_policy_structure。调用 deploy_policy_assignment 进行部署。”）。

13. （新增）azure_resource_graph_query 工具（计划中）： * 功能： 允许大模型使用 Azure REST API 执行任意 Azure Resource Graph 查询，以发现资源、订阅 ID、资源组等。 * 重要性： 使大模型能够动态发现 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 服务的主要“用户”是大模型客户端应用。交互流程如下：

1. 最终用户通过大模型应用请求创建自定义 Azure 策略（例如：“创建一项策略，以强制 App Services 使用 HTTPS”）。
2. 大模型应用与 Azure Policy MCP Server 交互。
3. 大模型调用 get_builtin_policies（可选择提供查询），查找相关策略类别。
4. 大模型针对选定的类别路径调用 get_policies_in_category（可选择提供查询），查找相关策略文件。
5. 大模型使用一个或多个策略的下载 URL 调用 get_policy_content，获取示例。
6. 大模型可以对 schema://azurepolicy 调用 read_resource（如果已实现），以了解所需的结构。
7. 大模型与用户交互（可由 create_policy_prompt 引导），澄清意图（审计／阻止还是修正），并确定合适的策略效果。
8. 大模型根据用户请求、已澄清的意图以及检索到的示例／架构，生成自定义策略 JSON。
9. 大模型应当调用 verify_policy_structure（启用后）验证生成的 JSON。
10. 如果有效，大模型会与用户确认部署范围和参数。
11. 大模型使用经过验证的策略定义和分配详情调用 deploy_policy_assignment。
12. 大模型可选择使用 query_policy_compliance 查询合规状态。
13. 大模型可选择使用 delete_policy_assignment 删除策略分配。
14. 大模型向最终用户展示部署结果（成功或失败及详细信息）。
15. 如果验证（步骤 9）或部署（步骤 11）失败，大模型会利用错误反馈修正策略／参数，并重新验证／尝试部署。

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 中，也可使用托管标识）。

开发路线图

• 阶段 1：MVP（核心功能）

  • 搭建基本的 FastMCP 服务端项目结构（server.py）。
  • 获取并在 schemas/ 中存储官方 Azure Policy JSON 架构。
  • 使用 jsonschema 和存储的架构实现并修复 verify_policy_structure 工具。（当前受阻/已禁用）
  • 使用 GitHub API（requests）实现 get_builtin_policies、get_policies_in_category、get_policy_content。
  • 为所有工具编写基本单元测试。
  • 编写基本的 README.md，说明设置和用法。
  • 实现 Azure Resource Graph API 工具（azure_resource_graph_query），以便大模型查询资源、获取订阅 ID 并发现环境详情。
  • 记录 Resource Graph 工具的用法并提供示例查询。
  • 如果未提供订阅 ID，则添加逻辑以便为策略部署工具建议或自动获取订阅 ID。

• 阶段 2：增强与可靠性

  • 实现 azure_policy_schema MCP 资源。
  • 实现 azure_resource_types MCP 资源（需要整理此列表）。
  • 实现 create_policy_prompt MCP 提示词，包括意图澄清指导。
  • 实现检查和更新架构文件的机制。
  • 改进工具中的错误处理和日志记录（已添加超时，还可进一步改进）。
  • 扩大测试覆盖范围。
  • 将 Resource Graph 工具结果集成到策略部署工作流中（例如，自动建议范围、验证资源是否存在）。

• 阶段 3：部署与高级功能（新增）

  • 实现可靠的 Azure 身份验证机制（例如，使用 azure-identity 和服务主体或托管标识）。
  • 实现 deploy_policy_assignment 工具，处理不同的范围和参数。
  • 如果简单的提示词不足以满足需求，则添加支持意图识别（审核/拒绝与修正）的逻辑/工具。
  • 支持分配需要托管标识的策略（适用于 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 存在一些细节问题（范围、参数、修正操作的身份管理）。
  • **缓解措施：**从较简单的分配场景开始（例如，在资源组范围内分配 Audit 策略）。逐步添加对参数和不同范围的支持。深入参考 Azure REST API 文档。针对 API 响应实现全面的错误处理。
• **（新增）风险：**大模型可能会误解用户对策略效果（审计/拒绝与修正）的意图。
  • **缓解措施：**设计清晰的提示词（create_policy_prompt）。提供示例。记录交互，以发现大模型常见的错误。如果仅靠提示词还不够，可考虑添加明确的检查或专用分析工具。
• **（新增）风险：**部署错误的策略或分配可能对 Azure 环境造成负面影响。
  • **缓解措施：**强调 verify_policy_structure 步骤的重要性。在 deploy_policy_assignment 中实现必需参数检查。鼓励用户在部署前确认。建议在非生产环境中测试。
• **风险：**GitHub API 速率限制或停机可能影响策略获取工具。
  • **缓解措施：**当前实现使用未经身份验证的请求（可能面临更低的速率限制）。记录此限制。考虑之后添加可选的 GitHub 令牌支持，以便发送经过身份验证的请求（速率限制更高）。如果瞬时错误变得常见，则实现合理的重试逻辑。必要时短暂缓存结果。
• **风险：**维护本地存储的架构（schemas/policyDefinition.json）保持最新需要投入精力。
  • **缓解措施：**将定期检查/手动更新流程添加到待办事项中（第 2 阶段）。记录当前架构的来源和日期。

附录

• Azure Policy 文档
• Azure Policy GitHub 仓库
• （新增） Azure Policy 分配 REST API
• Azure Resource Graph REST API
• Azure Resource Graph 查询语言
• Azure Resource Graph 查询示例
• MCP Python SDK 文档（引用自用户提供的 README.md）
• JSON Schema 规范
• Requests 库
• jsonschema 库
• （新增） azure-identity 库
• （新增） Azure Policy 定义 REST API
• （新增） MSAL Python 文档
• （新增） httpx 库