mcp-azure-landing-zone

Servidor MCP (Model Context Protocol) que permite a un asistente de IA (Claude Desktop, Claude Code, o cualquier cliente MCP) inspeccionar y auditar una Azure Landing Zone:

• Inventariar los recursos desplegados en una subscripción.
• Auditar el gobierno de etiquetado (recursos sin tags).
• Evaluar el cumplimiento de Azure Policy vía Policy Insights.
• Detectar drift de infraestructura ejecutando terraform plan en local.

Todas las operaciones son de solo lectura: el servidor nunca crea, modifica ni elimina recursos, y nunca ejecuta terraform apply.

---

Índice de documentación

Documento	Contenido
docs/01-instalacion.md	Requisitos, instalación paso a paso, verificación
docs/02-configuracion.md	Llenado de config.yaml, variables de entorno, autenticación y permisos de Azure
docs/03-herramientas.md	Referencia de cada herramienta: parámetros, salida, ejemplos
docs/04-uso.md	Registro en Claude Desktop / Claude Code y prompts de ejemplo
docs/05-troubleshooting.md	Errores frecuentes y su solución

---

Arquitectura

┌──────────────────┐   stdio (JSON-RPC)   ┌─────────────────────────────┐
│  Claude Desktop  │ ───────────────────► │  server.py  (FastMCP)       │
│  / Claude Code   │ ◄─────────────────── │  "Azure Landing Zone Asst."  │
└──────────────────┘                      └──────────┬──────────────────┘
                                                     │
                        ┌────────────────────────────┼────────────────────────────┐
                        ▼                            ▼                            ▼
              ┌───────────────────┐      ┌────────────────────┐      ┌────────────────────┐
              │ tools/resources.py│      │  tools/policy.py   │      │ tools/terraform.py │
              │ ResourceMgmtClient│      │ PolicyInsightsClient│     │ subprocess: plan   │
              └─────────┬─────────┘      └──────────┬─────────┘      └─────────┬──────────┘
                        │  DefaultAzureCredential   │                          │
                        ▼                            ▼                          ▼
                 ┌──────────────────────────────────────┐        ┌──────────────────────┐
                 │     Azure Resource Manager (ARM)     │        │  Terraform + state   │
                 └──────────────────────────────────────┘        └──────────────────────┘

Estructura de ficheros

mcp-azure-landing-zone/
├── server.py                 # Punto de entrada MCP (FastMCP, transporte stdio)
├── config.yaml               # Configuración activa (NO subir a git si lleva datos reales)
├── config.example.yaml       # Plantilla de configuración
├── requirements.txt          # Dependencias
├── .env.example              # Plantilla de variables de entorno
├── terraform/                # Configuración Terraform de la Landing Zone
│   ├── versions.tf           # Versiones y backend
│   ├── providers.tf          # Provider azurerm
│   ├── variables.tf          # Variables de entrada
│   ├── main.tf               # Data sources y ejemplo de importación
│   └── outputs.tf            # Outputs de la configuración
├── tools/
│   ├── __init__.py
│   ├── resources.py          # get_full_subscription_topology / get_untagged_resources / list_resources
│   ├── policy.py             # get_policy_states
│   └── terraform.py          # run_terraform_plan
└── docs/                     # Documentación detallada

---

Inicio rápido (5 minutos)

cd /Users/juancarlosmartinez/PycharmProjects/mcp-azure-landing-zone

# 1. Dependencias
.venv/bin/pip install -r requirements.txt

# 2. Autenticación en Azure
az login
az account show --query id -o tsv          # copia este id

# 3. Configuración: pega el id en config.yaml -> azure.default_subscription_id
#    y ajusta terraform.working_dir

# 4. Verificación
.venv/bin/python -c "import server; print(server.get_server_configuration())"

# 5. Arranque manual (se queda esperando JSON-RPC por stdin: es lo correcto)
.venv/bin/python server.py

Registro en Claude Desktop (~/Library/Application Support/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "azure-landing-zone": {
      "command": "/Users/juancarlosmartinez/PycharmProjects/mcp-azure-landing-zone/.venv/bin/python",
      "args": ["/Users/juancarlosmartinez/PycharmProjects/mcp-azure-landing-zone/server.py"]
    }
  }
}

Detalles y alternativas en docs/04-uso.md.

---

Herramientas expuestas

Herramienta	Qué hace	Requiere
get_subscription_topology	Mapa jerárquico por resource group + resumen agregado, optimizado en tokens	Rol Reader en Azure
list_azure_resources	Inventario plano con id ARM completo (filtrable por resource group)	Rol Reader en Azure
list_untagged_resources	Recursos sin ninguna etiqueta, ordenados por grupo	Rol Reader en Azure
get_policy_compliance	Estado Compliant/NonCompliant por política y recurso	Lectura en Policy Insights
detect_infrastructure_drift	terraform plan -no-color -detailed-exitcode	Terraform en el PATH + backend accesible
get_server_configuration	Configuración activa del servidor (diagnóstico)	—

Eficiencia en tokens

get_subscription_topology está diseñada para que Claude pueda analizar toda la infraestructura sin saturar el contexto. Medido sobre una subscripción real de 42 resource groups y 1 634 recursos:

Modo	Tokens aprox.
include_resources=true (detalle completo)	~54 700
max_resources_per_group=5	~8 000
include_resources=false (solo resumen)	~3 076

Los contadores agregados son idénticos en los tres modos. La estrategia recomendada es empezar por el resumen y bajar al detalle solo del grupo que interese con list_azure_resources.

Referencia completa con formatos de entrada/salida en docs/03-herramientas.md.

---

Estado actual del entorno

Comprobado el 2026-07-28 en esta máquina:

Elemento	Estado
Dependencias Python	Instaladas en .venv (Python 3.14)
Azure CLI (az)	Instalado y con sesión iniciada
terraform	v1.15.8 instalado desde el tap hashicorp/tap
terraform/	Inicializado (terraform init) y con línea base aplicada → SIN DRIFT
config.yaml	Apuntando a la subscripción real y al directorio terraform/

Las cinco herramientas se han ejecutado con éxito contra la subscripción real.

---

Seguridad

• El servidor no almacena credenciales. Usa DefaultAzureCredential, que resuelve la identidad en cadena (variables de entorno → identidad administrada → Azure CLI → …).
• El navegador interactivo está deshabilitado (exclude_interactive_browser_credential=True) para que el proceso nunca se quede colgado esperando un login en un servidor sin interfaz.
• terraform plan se ejecuta con shell=False y lista de argumentos explícita: ninguna entrada del modelo puede inyectar comandos adicionales.
• Los logs van a stderr; stdout está reservado al protocolo MCP.
• config.yaml puede contener identificadores de subscripción: añádelo a .gitignore si el repositorio es público (ver config.example.yaml como plantilla versionable).