aap-mcp

Plataforma de automatización Ansible 2.4 gestión mcp

GitHub

Documentación

Servidor AAP MCP

Un servidor de Model Context Protocol (MCP) para Ansible Automation Platform (AAP) 2.4. Proporciona herramientas para gestionar trabajos, plantillas, flujos de trabajo, inventario e infraestructura a través de Claude u otros clientes MCP.

Inicio Rápido

Requisitos Previos

  • Node.js ≥ 18.0.0
  • npm o yarn
  • Acceso a una instancia de AAP

Instalación

git clone <repo-url>
cd aap-mcp
npm install

Configuración

Opción 1: Configuración Interactiva

npm run setup-keychain

Esta configuración interactiva te guía a través de:

  • Elegir el método de autenticación (token de API o nombre de usuario/contraseña)
  • Ingresar las credenciales (con entrada de contraseña oculta)
  • Seleccionar el método de almacenamiento (Keychain de macOS, archivo .env o variables de entorno)
Note: Interactive should be all you need to get started unless you care to follow one of the other paths

Opción 2: Variables de Entorno (Recomendado para CI/CD)

export AAP_BASE_URL="https://aap.example.com"
export AAP_TOKEN="your-api-token"

Opción 3: Archivo .env (Solo para Desarrollo)

Crea ~/.config/aap-mcp/.env.aap:

AAP_BASE_URL=https://aap.example.com
AAP_TOKEN=your-api-token
AAP_USERNAME=admin

Luego:

npm start

Configuración

Variables de Entorno Requeridas

  • AAP_BASE_URL - URL de la instancia de AAP (ej., https://aap.example.com)
  • Una de las siguientes:
    • AAP_TOKEN - Token de autenticación de API, O
    • AAP_USERNAME y AAP_PASSWORD - Autenticación con nombre de usuario y contraseña

Variables de Entorno Opcionales

  • AAP_CONFIG_DIR - Directorio de configuración (predeterminado: ~/.config/aap-mcp)
  • AAP_DATA_DIR - Directorio de datos (predeterminado: ~/.data/aap-mcp)

Personalización del Keychain (macOS)

  • AAP_KEYCHAIN_SERVICE - Nombre del servicio (predeterminado: aap-mcp)
  • AAP_KEYCHAIN_TOKEN_ACCOUNT - Nombre de la cuenta de token (predeterminado: token)
  • AAP_KEYCHAIN_BASE_URL_ACCOUNT - Nombre de la cuenta de URL (predeterminado: base_url)
  • AAP_KEYCHAIN_USERNAME_ACCOUNT - Nombre de la cuenta de usuario (predeterminado: username)
  • AAP_KEYCHAIN_PASSWORD_ACCOUNT - Nombre de la cuenta de contraseña (predeterminado: password)

Desarrollo

Compilación

npm run build

Servidor de Desarrollo

npm run dev

Pruebas

npm test
npm run test:ui

Linting

npm run lint

Arquitectura

Componentes Principales

  • Cliente (src/client/): Cliente HTTP para la comunicación con la API de AAP
  • Herramientas (src/tools/): Implementaciones de herramientas MCP organizadas por dominio
    • system.ts - Salud del sistema y métricas
    • jobs.ts - Ejecución y monitoreo de trabajos
    • templates.ts - Plantillas de trabajos y flujos de trabajo
    • workflows.ts - Gestión de flujos de trabajo
    • inventory.ts - Gestión de inventario y hosts
    • projects.ts - Gestión de proyectos
    • infra.ts - Herramientas de infraestructura
  • Credenciales (src/credentials.ts): Gestión segura de credenciales con carga basada en prioridad
  • Rutas (src/paths.ts): Gestión de directorios de configuración y datos

Prioridad de Carga de Credenciales

  1. Variables de entorno (prioridad más alta)
  2. Keychain de macOS (si está disponible)
  3. Archivo .env
  4. Predeterminado o error (prioridad más baja)

Referencia de Herramientas

Herramientas del Sistema

  • get_system_info - Recuperar información del sistema AAP
  • get_platform_metrics - Obtener estadísticas de capacidad y trabajos de la plataforma

Herramientas de Trabajos

  • list_jobs - Listar trabajos de automatización con filtrado
  • get_job - Obtener detalles del trabajo
  • run_job - Lanzar una plantilla de trabajo
  • get_job_output - Recuperar registros de ejecución del trabajo

Herramientas de Plantillas

  • list_job_templates - Listar plantillas de trabajos disponibles
  • list_workflow_templates - Listar plantillas de trabajos de flujo de trabajo

Herramientas de Flujos de Trabajo

  • list_workflow_jobs - Listar ejecuciones de flujos de trabajo
  • get_workflow_job - Obtener detalles de ejecución del flujo de trabajo

Herramientas de Inventario

  • list_hosts - Listar hosts del inventario
  • list_groups - Listar grupos del inventario

Herramientas de Proyectos

  • list_projects - Listar proyectos
  • get_project - Obtener detalles del proyecto

Herramientas de Infraestructura

  • list_nodes - Listar nodos de control y ejecución
  • get_node_details - Obtener información del nodo

Solución de Problemas

"AAP_BASE_URL es requerido"

Credenciales no encontradas. Ejecuta:

npm run setup-keychain

O establece las variables de entorno:

export AAP_BASE_URL="https://aap.example.com"
export AAP_TOKEN="your-token"

"No se pudo inicializar el directorio de configuración"

Asegúrate de que la ruta del directorio de configuración sea escribible, o especifica una ruta personalizada:

export AAP_CONFIG_DIR="/path/to/config"
npm start

"La verificación de conexión falló"

Verifica que la instancia de AAP sea accesible:

curl https://aap.example.com/api/v2/ping/

Licencia

Consulta el archivo LICENCIA.

Documentación

Soporte

Para problemas y solicitudes de funciones, abre un issue en GitHub.