Overview

This document outlines the requirements for an Azure Policy Model Context Protocol (MCP) Server. The primary goal of this server is to empower Large Language Models (LLMs) to assist users in generating, validating, and deploying Azure custom policies effectively. It solves the problem of LLMs generating potentially incorrect or non-compliant Azure policy JSON by providing tools to fetch relevant built-in policies as examples, validate the structure of generated policies against the official schema, and manage policy assignments via the Azure REST API. It also aims to assist the LLM in selecting the appropriate policy effect based on user intent (audit/deny vs. remediation). The target user is an LLM application (like a chatbot or code assistant) that needs to interact with Azure Policy definitions and assignments. The value lies in providing a standardized, reliable interface for LLMs to create, validate, and deploy accurate and compliant Azure policies based on user requests.

Core Features

1. get_builtin_policies Tool (Implemented):

   • What it does: Fetches the top-level categories of Azure built-in policies from the Azure/azure-policy GitHub repository. Can optionally filter categories by name.
   • Why it's important: Allows the LLM to discover the available policy categories (e.g., 'Storage', 'Compute', 'Network').
   • How it works: Uses the GitHub API to list directories within the built-in-policies/policyDefinitions path. Returns a list of category names and their corresponding paths.

2. get_policies_in_category Tool (Implemented):

   • What it does: Fetches the individual policy definition files (names, paths, download URLs) within a specified category path obtained from get_builtin_policies. Can optionally filter policies by filename.
   • Why it's important: Enables the LLM to drill down into a specific area and find relevant policy examples.
   • How it works: Uses the GitHub API to list files within the provided category path. Returns a list of JSON file names, their paths, and direct download URLs.

3. get_policy_content Tool (Implemented):

   • What it does: Fetches the raw JSON content of a specific policy definition using its direct download URL obtained from get_policies_in_category.
   • Why it's important: Provides the actual policy JSON, which the LLM can use as a concrete example or template.
   • How it works: Performs an HTTP GET request to the provided GitHub raw content URL. Returns the policy JSON as a string.

4. verify_policy_structure Tool (Temporarily Disabled):

   • What it does: Validates a given JSON string against the official Azure Policy definition schema.
   • Why it's important: Ensures that any custom policy generated by the LLM adheres to the correct syntax and structure required by Azure before being presented to the end-user, preventing deployment errors.
   • How it works (Intended): Takes a policy definition (as a JSON string) as input. Parses the JSON and validates it against a locally stored copy of the official Azure Policy JSON schema (schemas/policyDefinition.json) using the jsonschema library. Returns a success message or validation errors. (Currently commented out in server.py due to issues.)

5. deploy_policy_assignment Tool (New Requirement):

   • What it does: Creates or updates an Azure Policy Assignment using a provided policy definition (JSON or ID) and assignment parameters (scope, name, etc.).
   • Why it's important: Enables the LLM to complete the workflow by deploying the generated and validated policy into the target Azure environment.
   • How it works: Takes the policy definition details (potentially the JSON content or an ID of an existing definition), assignment scope (e.g., subscription, resource group), assignment name, display name, description, parameters, and potentially identity details (for remediation tasks) as input. Constructs and executes the appropriate Azure REST API call (PUT) to providers/Microsoft.Authorization/policyAssignments endpoint. Requires Azure authentication credentials configured for the server environment.

6. Intent Identification Support (New Requirement):

   • What it is: Functionality or guidance to help the LLM determine whether the user's goal is to audit/prevent non-compliant resources (using effects like Audit, Deny) or to remediate existing ones (using effects like DeployIfNotExists, Modify).
   • Why it's important: Selecting the correct policy effect is critical for achieving the user's desired outcome and correctly structuring the policyRule.
   • How it works: This might involve:
     • Enhancing the create_policy_prompt (Feature 9) to explicitly ask the LLM to clarify intent with the user.
     • Potentially adding a tool to analyze a draft policy definition and suggest appropriate effects based on keywords or structure.
     • Providing guidance (e.g., in a rule/resource) on common use cases for different effects.

7. (Optional Enhancement) azure_policy_schema Resource:

   • What it does: Exposes the official Azure Policy JSON schema via an MCP resource URI (e.g., schema://azurepolicy).
   • Why it's important: Allows the LLM client to fetch the schema definition directly, enabling it to better understand the target structure before attempting generation.
   • How it works: This is already implemented in the current version.

8. (Optional Enhancement) azure_resource_types Resource:

   • What it does: Provides a list of common Azure resource provider namespaces and types via an MCP resource URI (e.g., types://azure/resources).
   • Why it's important: Helps the LLM use the correct identifiers for resource types within policy rules.

9. (Optional Enhancement) create_policy_prompt Prompt:

   • What it does: Defines a reusable MCP prompt template to guide the LLM in the policy creation process, including intent clarification.
   • Why it's important: Standardizes the workflow for the LLM, prompting it to use the available tools and resources effectively (e.g., "Generate a policy for {resource_type} to enforce {requirement}. Clarify if this should audit/block new resources or remediate existing ones. Use the policy fetching tools for examples and verify_policy_structure before finalizing. Use deploy_policy_assignment to deploy.").

User Experience

The primary "user" of this MCP server is the LLM client application. The interaction flow is as follows:

1. End-user requests a custom Azure policy from the LLM application (e.g., "Create a policy to enforce HTTPS on App Services").
2. LLM application interacts with the Azure Policy MCP Server.
3. LLM calls get_builtin_policies (optionally with a query) to find relevant policy categories.
4. LLM calls get_policies_in_category for a chosen category path (optionally with a query) to find relevant policy files.
5. LLM calls get_policy_content using the download URL for one or more policies to get examples.
6. LLM may call read_resource on schema://azurepolicy (if implemented) to understand the required structure.
7. LLM interacts with the user (potentially guided by create_policy_prompt) to clarify intent (audit/block vs. remediate) and determine the appropriate policy effect.
8. LLM generates the custom policy JSON based on the user request, clarified intent, and retrieved examples/schema.
9. LLM should call verify_policy_structure (once enabled) with the generated JSON.
10. If valid, the LLM confirms the deployment scope and parameters with the user.
11. LLM calls deploy_policy_assignment with the validated policy definition and assignment details.
12. LLM presents the outcome (success or failure with details) of the deployment to the end-user.
13. If validation (step 9) or deployment (step 11) fails, the LLM uses the error feedback to correct the policy/parameters and re-validates/re-attempts deployment.