adf-mcp-server

Servidor MCP (Model Context Protocol) de solo lectura para la monitorización y el análisis de causa raíz de Azure Data Factory, diseñado para usarse desde VS Code / Claude Code.

Estado: Paso 1 (esqueleto + comprobación de salud). Aún no hay conectividad con Azure; eso se añade en el Paso 2 (autenticación) y el Paso 3 (herramientas de ADF).

Requisitos

• Python 3.11+

• Un registro de aplicación de Azure AD (Service Principal) con el rol Lector en el/los recurso(s) de Data Factory que quieras inspeccionar (Lector es suficiente; este servidor es de solo lectura de principio a fin, por lo que nunca necesita Colaborador).

Related MCP server: mcp-azure-landing-zone

Configuración local

cd adf-mcp-server
python -m venv .venv
source .venv/bin/activate        # Windows: .venv\Scripts\activate
pip install -e ".[dev]"
cp .env.example .env

Creación del Service Principal (una sola vez, mediante az-cli)

az ad sp create-for-rbac \
  --name "adf-mcp-server-reader" \
  --role "Reader" \
  --scopes "/subscriptions/<SUBSCRIPTION_ID>/resourceGroups/<RG_NAME>/providers/Microsoft.DataFactory/factories/<FACTORY_NAME>"

Esto imprime appId, password y tenant; asígnalos en .env como AZURE_CLIENT_ID, AZURE_CLIENT_SECRET y AZURE_TENANT_ID respectivamente. Limita la asignación de roles a la fábrica específica (o, como máximo, al grupo de recursos) en lugar de a toda la suscripción: privilegio mínimo, y este SPN nunca necesita tocar nada fuera de ADF.

Ejecución del servidor

python -m adf_mcp.server
# or, after `pip install -e .`:
adf-mcp-server

El servidor se comunica a través de stdio; ejecutarlo directamente en una terminal parecerá que se cuelga; eso es lo esperado, está esperando que un cliente MCP (extensión de VS Code, Claude Code, mcp dev, etc.) se conecte mediante stdin/stdout.

Configuración en VS Code

Apunta la configuración del servidor de tu extensión compatible con MCP a:

{
  "command": "python",
  "args": ["-m", "adf_mcp.server"],
  "cwd": "/absolute/path/to/adf-mcp-server"
}

Una vez conectado:

1. Llama a health_check; debería devolver {"status": "ok", ...} sin tocar Azure en absoluto.

2. Llama a check_auth; esto hace una llamada real a Azure AD para adquirir un token de ARM. El éxito se ve así:

   {"authenticated": true, "auth_mode": "service_principal", "token_expires_on": 1735000000}

   El fallo devuelve una explicación estructurada (no un stack trace), por ejemplo, variables de entorno faltantes o un secreto no válido; consulta Solución de problemas más abajo.

3. Llama a list_factories; esto hace una llamada real a Azure Data Factory. Devuelve el resource_group de cada fábrica, que todas las demás herramientas siguientes necesitan como entrada:

   {"factories": [{"name": "shell-prod-adf", "resource_group": "rg-shell-prod", "location": "eastus"}]}

Herramientas disponibles (Paso 3)

Todas las herramientas son de solo lectura; ninguna puede crear, modificar, activar o eliminar nada en Azure Data Factory.

Ejemplo de flujo de RCA para un agente: list_factories → list_pipeline_runs(status="Failed") → get_failed_activity_details(run_id=...) para el desglose de errores directamente.

Herramientas disponibles (adiciones del Paso 4)

Flujo completo de RCA para una canalización fallida: list_pipeline_runs(status="Failed") → get_failed_activity_details(run_id=...) para el error, y por separado get_trigger_status(trigger_name=...) para descartar "ni siquiera se disparó".

Ejecución de pruebas

pip install -e ".[dev]" pytest-asyncio
pytest -v

Estructura del proyecto

Consulta src/adf_mcp/; server.py (transporte MCP), config.py (ajustes), logging_config.py (registro estructurado). La lógica de dominio y la conectividad con Azure se añaden en src/adf_mcp/domain/ a partir del Paso 3.

Solución de problemas

• El cliente muestra "servidor desconectado" inmediatamente: comprueba que python -m adf_mcp.server se ejecuta correctamente por sí solo primero; una excepción de inicio matará el proceso antes de que el cliente se conecte.

• El cliente no puede analizar las respuestas / salida distorsionada: algo escribió en stdout además del propio protocolo MCP (por ejemplo, un print() suelto). Todo el registro de este proyecto va a stderr precisamente por esta razón.

• check_auth devuelve "Faltan ajustes requeridos del Service Principal": una de AZURE_TENANT_ID / AZURE_CLIENT_ID / AZURE_CLIENT_SECRET está vacía en .env. Ten en cuenta que estos tres NO usan el prefijo ADF_MCP_.

• check_auth devuelve "Error de autenticación de Azure": normalmente un secreto de cliente caducado/rotado, un registro de aplicación deshabilitado o un error tipográfico en el ID de inquilino. Vuelve a verificarlo con az ad sp show --id <AZURE_CLIENT_ID>.

• ClientAuthenticationError: AADSTS7000215: secreto de cliente no válido; regenéralo en el registro de aplicación y actualiza .env.

• Una herramienta devuelve {"error": "AZURE_SUBSCRIPTION_ID no está configurado..."}: añade AZURE_SUBSCRIPTION_ID a .env; es necesario para todas las herramientas de ADF (no para check_auth, que solo necesita tenant/client/secret).

• Una herramienta devuelve {"error": "Error de API de Azure (403): ..."}: el Service Principal carece de acceso de Lector a esa fábrica/grupo de recursos; revisa la asignación az ad sp create-for-rbac --role Reader --scopes ... de la configuración.

• Una herramienta devuelve {"error": "Error de API de Azure (404): ..."}: comprueba la ortografía de resource_group/factory_name/pipeline_name; distinguen entre mayúsculas y minúsculas y deben coincidir exactamente con lo que devolvieron list_factories/list_pipelines.

• get_failed_activity_details devuelve una lista vacía pero sabes que la canalización falló: el fallo puede estar a nivel de canalización (por ejemplo, un parámetro no válido) en lugar de en una sola actividad; comprueba el message de la ejecución principal mediante get_pipeline_run.

• Una canalización "simplemente no se ejecutó" sin ejecuciones fallidas: comprueba get_trigger_status para su desencadenador; runtime_state: "Stopped" significa que el desencadenador estaba deshabilitado y nunca se disparó, lo que no aparecerá como una ejecución fallida porque nunca se creó ninguna.