AAP Enterprise MCP Server

Un servidor MCP que permite a los asistentes de IA interactuar con la infraestructura de Ansible Automation Platform (AAP) y Event-Driven Ansible (EDA).

GitHub

Documentación

AAP Enterprise MCP Server

Un conjunto completo de servidores de Model Context Protocol (MCP) para el ecosistema de automatización e infraestructura de Red Hat, que permite a los asistentes de IA interactuar con Ansible Automation Platform (AAP), Event-Driven Ansible (EDA), las herramientas de calidad de código ansible-lint y la documentación oficial de Red Hat con validación segura de dominios.

Características

Integración con Ansible Automation Platform (AAP)

Gestión de Inventarios: Listar, crear, actualizar inventarios y gestionar hosts/grupos
Gestión de Trabajos: Ejecutar plantillas de trabajo, monitorear el estado de los trabajos y recuperar registros
Gestión de Proyectos: Crear y gestionar proyectos basados en SCM
Gestión de Plantillas: Crear y gestionar plantillas de trabajo
Operaciones con Hosts: Agregar/eliminar hosts, gestionar variables y hechos de hosts
Comandos Ad-hoc: Ejecutar comandos de ansible directamente en los hosts del inventario

Integración con Event-Driven Ansible (EDA)

Gestión de Activaciones: Listar, crear, habilitar/deshabilitar activaciones de EDA
Gestión de Rulebooks: Gestionar y consultar rulebooks
Gestión de Entornos de Decisión: Gestionar entornos de decisión
Monitoreo de Flujos de Eventos: Monitorear flujos de eventos

Integración con Ansible Galaxy

Búsqueda de Colecciones: Buscar y descubrir colecciones de Ansible por nombre, espacio de nombres o palabras clave
Búsqueda de Roles: Encontrar roles de la comunidad por palabra clave, autor o criterios específicos
Detalles de Contenido: Obtener información completa sobre colecciones y roles, incluyendo versiones, dependencias e instrucciones de instalación
Sugerencias Inteligentes: Recomendaciones de contenido impulsadas por IA basadas en descripciones de casos de uso
Integración con AAP: Sugerencias inteligentes que consideran la infraestructura e inventarios existentes de AAP

Integración con Ansible Lint

Validación de Playbooks: Linting en tiempo real del contenido de playbooks de Ansible con perfiles de calidad configurables
Análisis de Archivos: Análisis integral de archivos de Ansible, roles y estructuras completas de proyectos
Aplicación de Mejores Prácticas: Verificación automatizada contra los estándares y mejores prácticas de la comunidad de Ansible
Validación de Sintaxis: Verificación rápida de sintaxis para retroalimentación inmediata durante el desarrollo
Soporte Multi-Perfil: Mejora progresiva de la calidad con perfiles desde básico hasta listo para producción
Gestión de Reglas: Listar, filtrar y comprender las reglas de ansible-lint con explicaciones detalladas

Integración con la Documentación de Red Hat (Optimizada)

Descubrimiento Eficiente: Descubrimiento de contenido basado en búsqueda web utilizando dominios oficiales de Red Hat
Obtención Inteligente de Contenido: Estrategia PDF-primero que maneja los problemas de renderizado de JavaScript de Red Hat
Seguridad de Dominios: Valida el acceso a más de 50 dominios oficiales de Red Hat para un acceso seguro a la documentación
Sobrecarga Mínima de MCP: Enfoque optimizado de 2 herramientas que reduce las llamadas API en un 75%
Generación de Consultas de Búsqueda: Crea consultas de búsqueda optimizadas para uso externo de la herramienta WebSearch MCP
Manejo de Autenticación: Detección inteligente de contenido que requiere suscripción vs. contenido público

Instalación

Requisitos Previos

Python 3.11 o superior
Gestor de paquetes UV (recomendado) o pip
Acceso a una instancia de Ansible Automation Platform
Token API válido de AAP

Configuración

Clonar el repositorio:

git clone https://github.com/sibilleb/AAP-Enterprise-MCP-Server.git
cd AAP-Enterprise-MCP-Server

Instalar dependencias:

# Using UV (recommended)
uv sync

# Or using pip
pip install -e .

Configurar variables de entorno:

# Required for AAP/EDA servers
export AAP_TOKEN="your-aap-api-token"
export AAP_URL="https://your-aap-server.com/api/controller/v2"
export EDA_TOKEN="your-eda-api-token"  # Can be same as AAP_TOKEN
export EDA_URL="https://your-aap-server.com/api/eda/v1"

# Optional for Red Hat Customer Portal access
export REDHAT_USERNAME="your-redhat-username"
export REDHAT_PASSWORD="your-redhat-password"

Cómo Obtener su Token API

Método 1: Interfaz Web de AAP

Inicie sesión en la interfaz web de AAP
Haga clic en su nombre de usuario en la esquina superior derecha
Seleccione "Configuración de Usuario" o "Mi Perfil"
Navegue a la sección "Tokens"
Haga clic en "Agregar" o "Crear Token"
Establezca el alcance en "Escritura" para funcionalidad completa
Copie el token generado inmediatamente (no se mostrará nuevamente)

Método 2: Línea de Comandos

curl -k -X POST \
  "https://your-aap-server.com/api/v2/tokens/" \
  -H "Content-Type: application/json" \
  -u "username:password" \
  -d '{
    "description": "MCP Server Token",
    "application": null,
    "scope": "write"
  }'

Configuración

Configuración del Cliente MCP

Agregue lo siguiente a la configuración de su cliente MCP (por ejemplo, Claude Desktop, Cursor):

{
  "mcpServers": {
    "ansible": {
      "command": "uv",
      "args": [
        "--directory",
        "/path/to/AAP-Enterprise-MCP-Server",
        "run",
        "ansible.py"
      ],
      "env": {
        "AAP_TOKEN": "your-aap-api-token",
        "AAP_URL": "https://your-aap-server.com/api/controller/v2"
      }
    },
    "eda": {
      "command": "uv",
      "args": [
        "--directory",
        "/path/to/AAP-Enterprise-MCP-Server",
        "run",
        "eda.py"
      ],
      "env": {
        "EDA_TOKEN": "your-eda-api-token",
        "EDA_URL": "https://your-aap-server.com/api/eda/v1"
      }
    },
    "ansible-lint": {
      "command": "uv",
      "args": [
        "--directory",
        "/path/to/AAP-Enterprise-MCP-Server",
        "run",
        "ansible-lint.py"
      ]
    },
    "redhat-docs": {
      "command": "uv",
      "args": [
        "--directory",
        "/path/to/AAP-Enterprise-MCP-Server",
        "run",
        "redhat_docs.py"
      ],
      "env": {
        "REDHAT_USERNAME": "your-username",
        "REDHAT_PASSWORD": "your-password"
      }
    }
  }
}

Configuración SSL/TLS

Para entornos de laboratorio con certificados autofirmados, los servidores automáticamente:

Deshabilitan advertencias SSL
Omiten la verificación de certificados
Manejan conexiones inseguras de manera elegante

Para entornos de producción, asegúrese de que los certificados SSL estén configurados correctamente en su instancia de AAP.

Arquitectura del Servidor

Este proyecto implementa una arquitectura MCP de cuatro servidores para una cobertura integral del ecosistema de Red Hat:

Servidor	Archivo	Propósito	Características Clave
Ansible Automation Platform	`ansible.py`	Integración con AAP y búsqueda en Galaxy	Gestión de trabajos, control de inventarios, descubrimiento en Galaxy (855 líneas)
Event-Driven Ansible	`eda.py`	Integración con EDA	Gestión de activaciones, manejo de rulebooks (96 líneas)
Ansible Lint	`ansible-lint.py`	Calidad de código y mejores prácticas	Perfiles de calidad progresivos, análisis de proyectos (502 líneas)
Documentación de Red Hat	`redhat_docs.py`	Acceso a la documentación oficial de Red Hat	Validación de dominios, búsqueda híbrida, acceso PDF

Capacidades Combinadas

Ciclo de Vida Completo de Automatización: Desde el descubrimiento de documentación hasta la implementación con aseguramiento de calidad
Seguridad: El acceso validado por dominio asegura que solo se utilicen fuentes oficiales de Red Hat
Inteligencia: Recomendaciones impulsadas por IA y orientación especializada para telecomunicaciones/borde
Escalabilidad: Servidores independientes permiten funcionalidad enfocada y escalamiento

Herramientas Disponibles

Herramientas de Ansible Automation Platform

Herramienta	Descripción
`list_inventories`	Listar todos los inventarios
`get_inventory`	Obtener detalles del inventario por ID
`create_inventory`	Crear un nuevo inventario
`list_hosts`	Listar hosts en un inventario
`add_host_to_inventory`	Agregar un host al inventario
`run_job`	Ejecutar una plantilla de trabajo
`job_status`	Verificar el estado de ejecución del trabajo
`job_logs`	Recuperar registros de ejecución del trabajo
`list_job_templates`	Listar plantillas de trabajo disponibles
`create_job_template`	Crear una nueva plantilla de trabajo
`create_project`	Crear un nuevo proyecto
`run_adhoc_command`	Ejecutar comandos ad-hoc de ansible
`list_projects`	Listar todos los proyectos
`get_project`	Obtener detalles del proyecto por ID
`list_project_updates`	Listar trabajos de actualización de proyectos (sincronización SCM)
`get_project_update`	Obtener el estado del trabajo de actualización del proyecto
`get_project_update_logs`	Obtener registros del trabajo de actualización del proyecto
`update_project`	Activar la actualización del proyecto (sincronización SCM)

Herramientas de Búsqueda en Ansible Galaxy

Herramienta	Descripción
`search_galaxy_collections`	Buscar colecciones de Ansible Galaxy por consulta, etiquetas o espacio de nombres
`search_galaxy_roles`	Buscar roles de Ansible Galaxy por palabra clave, nombre o autor
`get_collection_details`	Obtener información detallada sobre una colección específica
`get_role_details`	Obtener información detallada sobre un rol específico
`suggest_ansible_content`	Sugerir inteligentemente colecciones y roles basados en la descripción del caso de uso

Herramientas de Ansible Lint

Herramienta	Descripción
`lint_playbook`	Aplicar lint al contenido de playbooks de Ansible con perfiles y reglas configurables
`lint_file`	Aplicar lint a archivos específicos de Ansible en disco
`lint_role`	Validación integral de directorios de roles de Ansible
`validate_syntax`	Validación rápida solo de sintaxis para retroalimentación inmediata
`check_best_practices`	Verificación de mejores prácticas consciente del contexto (dev/staging/producción)
`analyze_project`	Analizar la estructura completa del proyecto de Ansible con informes integrales
`list_rules`	Listar reglas disponibles de ansible-lint, opcionalmente filtradas por etiquetas
`list_tags`	Listar todas las etiquetas disponibles para reglas de ansible-lint
`get_ansible_lint_version`	Obtener información de versión para ansible-lint instalado

Herramientas de Event-Driven Ansible

Herramienta	Descripción
`list_activations`	Listar activaciones de EDA
`get_activation`	Obtener detalles de activación
`create_activation`	Crear nueva activación
`enable_activation`	Habilitar una activación
`disable_activation`	Deshabilitar una activación
`restart_activation`	Reiniciar una activación
`list_rulebooks`	Listar rulebooks disponibles
`get_rulebook`	Obtener detalles del rulebook
`list_decision_environments`	Listar entornos de decisión

Herramientas de Documentación de Red Hat

Herramienta	Descripción
`read_documentation`	Leer documentación de Red Hat con validación de dominio y acceso PDF-primero
`list_products`	Listar todos los productos y versiones disponibles de Red Hat
`search_documentation`	Buscar documentación de Red Hat con priorización de versiones
`search_documentation_enhanced`	NUEVO: Búsqueda híbrida que combina sitemap + descubrimiento por búsqueda web
`search_with_web_guidance`	NUEVO: Obtener resultados directos + consultas de búsqueda web optimizadas restringidas a dominios de Red Hat
`smart_documentation_finder`	NUEVO: Descubrimiento inteligente de documentación de múltiples fuentes
`get_product_guides`	Obtener guías de productos con ordenamiento semántico de versiones (13 guías para OpenShift 4.18)
`recommend_content`	Recomendaciones inteligentes con especialización en telecomunicaciones/borde/CNF

Ejemplos de Uso

Ejecutar una Plantilla de Trabajo

# List available job templates
templates = await list_job_templates()

# Run a specific job template with variables
result = await run_job(
    template_id=5,
    extra_vars={"target_env": "production", "app_version": "1.2.3"}
)

# Check job status
status = await job_status(result["job"])

Gestionar Inventario

# List all inventories
inventories = await list_inventories()

# Add a new host to inventory
await add_host_to_inventory(
    inventory_id=1,
    hostname="web-server-01.example.com",
    variables={"ansible_host": "192.168.1.100", "role": "webserver"}
)

# Run ad-hoc command on inventory
await run_adhoc_command(
    inventory_id=1,
    module_name="setup",
    limit="web-server-01.example.com"
)

Descubrimiento de Contenido en Galaxy

# Get intelligent suggestions for a specific use case
suggestions = await suggest_ansible_content(
    use_case="I am developing a playbook that spins up and down EC2 servers on AWS using ansible",
    check_aap_inventory=True
)

# Search for AWS-related collections
collections = await search_galaxy_collections(query="aws", limit=10)

# Search for EC2-specific roles
roles = await search_galaxy_roles(keyword="ec2", limit=5)

# Get detailed information about a specific collection
details = await get_collection_details(namespace="amazon", name="aws")

# Get detailed information about a specific role
role_info = await get_role_details(role_id=12345)

Aseguramiento de Calidad con Ansible Lint

# Lint playbook content with different quality profiles
playbook_content = """
---
- hosts: all
  tasks:
    - name: install package
      yum: name=nginx state=present
"""

# Basic linting for development
basic_results = await lint_playbook(
    content=playbook_content,
    profile="basic",
    format_type="json"
)

# Production-ready validation
production_results = await lint_playbook(
    content=playbook_content,
    profile="production",
    format_type="json"
)

# Quick syntax validation
syntax_check = await validate_syntax(content=playbook_content)

# Context-aware best practices checking
best_practices = await check_best_practices(
    content=playbook_content,
    context="production"
)

# Analyze entire project structure
project_analysis = await analyze_project(
    project_path="/path/to/ansible/project",
    profile="moderate"
)

# List available rules and tags
rules = await list_rules(tags="idempotency,syntax")
tags = await list_tags()

Gestión de Activaciones de EDA

# List all activations
activations = await list_activations()

# Enable a specific activation
await enable_activation(activation_id=3)

# Check activation details
details = await get_activation(activation_id=3)

Acceso a Documentación de Red Hat

# Access OpenShift documentation with PDF preference
content = await read_documentation(
    "https://docs.redhat.com/en/documentation/openshift_container_platform/4.18/html/updating_clusters/index",
    format_preference="pdf"  # Ensures reliable content extraction
)

# Search for telco edge content with hybrid approach
guidance = await search_with_web_guidance(
    "openshift telco edge cluster upgrade", 
    product="openshift_container_platform"
)
# Returns direct results + 5 Red Hat domain-restricted web search queries

# Get comprehensive telco/edge recommendations
recommendations = await recommend_content(
    "telco edge CNF cluster upgrade", 
    role="administrator"
)
# Returns specialized edge computing and cluster update recommendations

# Get latest OpenShift guides (auto-detects 4.18, not 3.x)
guides = await get_product_guides("openshift_container_platform", version="latest")
# Returns 13 specialized guides including Updating Clusters, Edge Computing, etc.

# Domain-validated web search workflow
guidance = await search_with_web_guidance("kubernetes edge computing")
# Use generated queries like: "site:docs.redhat.com openshift 4.18 kubernetes edge computing"
# Then feed discovered URLs back:
content = await read_documentation(discovered_url, format_preference="pdf")

Desarrollo

Ejecutar Pruebas

# Install development dependencies
uv sync --group dev

# Run tests
pytest

# Run with coverage
pytest --cov=.

Formato de Código

# Format code
black .

# Lint code
ruff check .

# Type checking
mypy .

Solución de Problemas

Problemas Comunes

Errores de Certificado SSL: El servidor maneja certificados autofirmados automáticamente. Si encuentra problemas SSL, verifique la configuración de su servidor AAP.
Fallos de Autenticación: Asegúrese de que su token API tenga permisos suficientes (se recomienda alcance de Escritura).
Tiempos de Espera de Conexión: Verifique la conectividad de red a su servidor AAP y confirme el formato de la URL.
Herramienta No Encontrada: Reinicie su cliente MCP después de los cambios de configuración.

Modo de Depuración

Establezca la variable de entorno para registro detallado:

export MCP_DEBUG=1

Contribuciones

Haga un fork del repositorio
Cree una rama de características
Realice sus cambios
Agregue pruebas para la nueva funcionalidad
Asegúrese de que todas las pruebas pasen
Envíe una solicitud de extracción

Licencia

Este proyecto está licenciado bajo la Licencia MIT - consulte el archivo LICENSE para más detalles.

Logros Clave

🎯 Métricas de Éxito de Documentación de Red Hat

✅ Detección de Versiones: OpenShift 4.18 correctamente identificado como la más reciente (no 3.x)
✅ Acceso PDF: Archivos PDF de más de 1.4MB accesibles exitosamente
✅ Relevancia de Búsqueda: Las consultas de borde de telecomunicaciones devuelven documentación especializada
✅ Seguridad de Dominios: Validación 100% de dominios de Red Hat (más de 50 dominios probados)
✅ Integración de Búsqueda Web: Enfoque híbrido con restricción de fuentes oficiales

📊 Mejoras de Rendimiento

Métrica	Antes	Después	Estado
Detección de Versión Más Reciente	❌ Versiones 3.x	✅ Versiones 4.18+	Corregido
Tasa de Éxito de Acceso PDF	❌ Errores 301/404	✅ Respuestas 200 OK	100%
Validación de Dominios	❌ Sin filtrado	✅ Más de 50 dominios oficiales	Asegurado
Guías Disponibles de OpenShift	8 genéricas	13 especializadas	+62%

Soporte

Repositorio: AAP Enterprise MCP Server
Problemas: GitHub Issues
Documentación: README | README de Documentación de Red Hat
Comunidad de Ansible: Foro de la Comunidad de Ansible

Proyectos Relacionados

¡Listo para uso en producción con acceso seguro y validado por dominio al ecosistema de Red Hat! 🚀