AAP Enterprise MCP Server

Um servidor MCP que permite que assistentes de IA interajam com a infraestrutura do Ansible Automation Platform (AAP) e do Event-Driven Ansible (EDA).

GitHub
33

Documentação

AAP Enterprise MCP Server

Um conjunto abrangente de servidores Model Context Protocol (MCP) para o ecossistema de automação e infraestrutura da Red Hat, permitindo que assistentes de IA interajam com Ansible Automation Platform (AAP), Event-Driven Ansible (EDA), ferramentas de qualidade de código ansible-lint e a documentação oficial da Red Hat com validação segura de domínio.

Recursos

Integração com Ansible Automation Platform (AAP)

  • Gerenciamento de Inventário: Listar, criar, atualizar inventários e gerenciar hosts/grupos
  • Gerenciamento de Jobs: Executar job templates, monitorar o status dos jobs e recuperar logs
  • Gerenciamento de Projetos: Criar e gerenciar projetos baseados em SCM
  • Gerenciamento de Templates: Criar e gerenciar job templates
  • Operações de Host: Adicionar/remover hosts, gerenciar variáveis e facts de hosts
  • Comandos Ad-hoc: Executar comandos ansible diretamente nos hosts do inventário

Integração com Event-Driven Ansible (EDA)

  • Gerenciamento de Ativações: Listar, criar, habilitar/desabilitar ativações EDA
  • Gerenciamento de Rulebooks: Gerenciar e consultar rulebooks
  • Gerenciamento de Ambientes de Decisão: Gerenciar ambientes de decisão
  • Monitoramento de Streams de Eventos: Monitorar streams de eventos

Integração com Ansible Galaxy

  • Busca de Collections: Buscar e descobrir collections Ansible por nome, namespace ou palavras-chave
  • Busca de Roles: Encontrar roles da comunidade por palavra-chave, autor ou critérios específicos
  • Detalhes de Conteúdo: Obter informações abrangentes sobre collections e roles, incluindo versões, dependências e instruções de instalação
  • Sugestões Inteligentes: Recomendações de conteúdo com IA baseadas em descrições de casos de uso
  • Integração com AAP: Sugestões inteligentes que consideram a infraestrutura e os inventários AAP existentes

Integração com Ansible Lint

  • Validação de Playbooks: Linting em tempo real do conteúdo de playbooks Ansible com perfis de qualidade configuráveis
  • Análise de Arquivos: Análise abrangente de arquivos Ansible, roles e estruturas completas de projetos
  • Aplicação de Boas Práticas: Verificação automatizada contra os padrões e boas práticas da comunidade Ansible
  • Validação de Sintaxe: Verificação rápida de sintaxe para feedback imediato durante o desenvolvimento
  • Suporte a Múltiplos Perfis: Melhoria progressiva de qualidade com perfis do básico ao pronto para produção
  • Gerenciamento de Regras: Listar, filtrar e entender as regras do ansible-lint com explicações detalhadas

Integração com Documentação Red Hat (Otimizada)

  • Descoberta Eficiente: Descoberta de conteúdo baseada em busca na web usando domínios oficiais da Red Hat
  • Busca Inteligente de Conteúdo: Estratégia PDF-first para lidar com problemas de renderização JavaScript da Red Hat
  • Segurança de Domínio: Valida o acesso a mais de 50 domínios oficiais da Red Hat para acesso seguro à documentação
  • Overhead Mínimo de MCP: Abordagem otimizada com 2 ferramentas reduz chamadas de API em 75%
  • Geração de Consultas de Busca: Cria consultas de busca otimizadas para uso da ferramenta WebSearch MCP externa
  • Tratamento de Autenticação: Detecção inteligente de conteúdo que requer assinatura versus conteúdo público

Instalação

Pré-requisitos

  • Python 3.11 ou superior
  • Gerenciador de pacotes UV (recomendado) ou pip
  • Acesso a uma instância do Ansible Automation Platform
  • Token de API AAP válido

Configuração

  1. Clone o repositório:

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

  2. Instale as dependências:

    # Using UV (recommended)
uv sync

# Or using pip
pip install -e .

  3. Configure as variáveis de ambiente:

    # 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"

Obtendo seu Token de API

Método 1: Interface Web do AAP

  1. Faça login na interface web do seu AAP
  2. Clique no seu nome de usuário no canto superior direito
  3. Selecione "User Settings" ou "My Profile"
  4. Navegue até a seção "Tokens"
  5. Clique em "Add" ou "Create Token"
  6. Defina o escopo como "Write" para funcionalidade completa
  7. Copie o token gerado imediatamente (ele não será exibido novamente)

Método 2: Linha de Comando

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"
  }'

Configuração

Configuração do Cliente MCP

Adicione o seguinte à configuração do seu cliente MCP (por exemplo, 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"
      }
    }
  }
}

Configuração SSL/TLS

Para ambientes de laboratório com certificados autoassinados, os servidores automaticamente:

  • Desabilitam avisos SSL
  • Ignoram a verificação de certificados
  • Lidam com conexões inseguras de forma graciosa

Para ambientes de produção, certifique-se de que certificados SSL adequados estejam configurados na sua instância AAP.

Arquitetura do Servidor

Este projeto implementa uma arquitetura MCP de quatro servidores para cobertura abrangente do ecossistema Red Hat:

ServidorArquivoFinalidadePrincipais Recursos
Ansible Automation Platformansible.pyIntegração AAP com busca GalaxyGerenciamento de jobs, controle de inventário, descoberta Galaxy (855 linhas)
Event-Driven Ansibleeda.pyIntegração EDAGerenciamento de ativações, manipulação de rulebooks (96 linhas)
Ansible Lintansible-lint.pyQualidade de código e boas práticasPerfis de qualidade progressivos, análise de projetos (502 linhas)
Red Hat Documentationredhat_docs.pyAcesso à documentação oficial da Red HatValidação de domínio, busca híbrida, acesso PDF

Capacidades Combinadas

  • Ciclo de Vida Completo de Automação: Da descoberta de documentação à implementação com garantia de qualidade
  • Segurança: Acesso validado por domínio garante apenas fontes oficiais da Red Hat
  • Inteligência: Recomendações com IA e orientação especializada para telco/edge
  • Escalabilidade: Servidores independentes permitem funcionalidade focada e escalabilidade

Ferramentas Disponíveis

Ferramentas do Ansible Automation Platform

FerramentaDescrição
list_inventoriesListar todos os inventários
get_inventoryObter detalhes do inventário por ID
create_inventoryCriar um novo inventário
list_hostsListar hosts em um inventário
add_host_to_inventoryAdicionar um host ao inventário
run_jobExecutar um job template
job_statusVerificar o status de execução do job
job_logsRecuperar logs de execução do job
list_job_templatesListar job templates disponíveis
create_job_templateCriar um novo job template
create_projectCriar um novo projeto
run_adhoc_commandExecutar comandos ansible ad-hoc
list_projectsListar todos os projetos
get_projectObter detalhes do projeto por ID
list_project_updatesListar jobs de atualização de projeto (sincronização SCM)
get_project_updateObter status do job de atualização do projeto
get_project_update_logsObter logs do job de atualização do projeto
update_projectAcionar atualização do projeto (sincronização SCM)

Ferramentas de Busca Ansible Galaxy

FerramentaDescrição
search_galaxy_collectionsBuscar collections Ansible Galaxy por consulta, tags ou namespace
search_galaxy_rolesBuscar roles Ansible Galaxy por palavra-chave, nome ou autor
get_collection_detailsObter informações detalhadas sobre uma collection específica
get_role_detailsObter informações detalhadas sobre uma role específica
suggest_ansible_contentSugerir inteligentemente collections e roles com base na descrição do caso de uso

Ferramentas Ansible Lint

FerramentaDescrição
lint_playbookAplicar lint ao conteúdo de playbooks Ansible com perfis e regras configuráveis
lint_fileAplicar lint a arquivos Ansible específicos no disco
lint_roleValidação abrangente de diretórios de roles Ansible
validate_syntaxValidação rápida apenas de sintaxe para feedback imediato
check_best_practicesVerificação de boas práticas com consciência de contexto (dev/staging/production)
analyze_projectAnalisar a estrutura completa do projeto Ansible com relatórios abrangentes
list_rulesListar regras ansible-lint disponíveis, opcionalmente filtradas por tags
list_tagsListar todas as tags disponíveis para regras ansible-lint
get_ansible_lint_versionObter informações de versão do ansible-lint instalado

Ferramentas Event-Driven Ansible

FerramentaDescrição
list_activationsListar ativações EDA
get_activationObter detalhes da ativação
create_activationCriar nova ativação
enable_activationHabilitar uma ativação
disable_activationDesabilitar uma ativação
restart_activationReiniciar uma ativação
list_rulebooksListar rulebooks disponíveis
get_rulebookObter detalhes do rulebook
list_decision_environmentsListar ambientes de decisão

Ferramentas de Documentação Red Hat

FerramentaDescrição
read_documentationLer documentação Red Hat com validação de domínio e acesso PDF-first
list_productsListar todos os produtos e versões Red Hat disponíveis
search_documentationBuscar documentação Red Hat com priorização de versão
search_documentation_enhancedNOVO: Busca híbrida combinando sitemap + descoberta por busca na web
search_with_web_guidanceNOVO: Obter resultados diretos + consultas de busca web otimizadas restritas a domínios Red Hat
smart_documentation_finderNOVO: Descoberta inteligente de documentação multi-fonte
get_product_guidesObter guias de produtos com ordenação semântica de versões (13 guias para OpenShift 4.18)
recommend_contentRecomendações inteligentes com especialização em telco/edge/CNF

Exemplos de Uso

Executando um Job Template

# 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"])

Gerenciando Inventário

# 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"
)

Descoberta de Conteúdo 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)

Garantia de Qualidade com 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()

Gerenciamento de Ativações 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)

Acesso à Documentação 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")

Desenvolvimento

Executando Testes

# Install development dependencies
uv sync --group dev

# Run tests
pytest

# Run with coverage
pytest --cov=.

Formatação de Código

# Format code
black .

# Lint code
ruff check .

# Type checking
mypy .

Solução de Problemas

Problemas Comuns

  1. Erros de Certificado SSL: O servidor lida com certificados autoassinados automaticamente. Se você encontrar problemas de SSL, verifique a configuração do seu servidor AAP.

  2. Falhas de Autenticação: Certifique-se de que seu token de API tenha permissões suficientes (escopo Write recomendado).

  3. Timeouts de Conexão: Verifique a conectividade de rede com seu servidor AAP e confirme o formato da URL.

  4. Ferramenta Não Encontrada: Reinicie seu cliente MCP após alterações de configuração.

Modo de Depuração

Defina a variável de ambiente para logging detalhado:

export MCP_DEBUG=1

Contribuindo

  1. Faça um fork do repositório
  2. Crie um branch de funcionalidade
  3. Faça suas alterações
  4. Adicione testes para novas funcionalidades
  5. Certifique-se de que todos os testes passem
  6. Envie um pull request

Licença

Este projeto é licenciado sob a Licença MIT - consulte o arquivo LICENSE para detalhes.

Principais Conquistas

🎯 Métricas de Sucesso da Documentação Red Hat

  • ✅ Detecção de Versão: OpenShift 4.18 corretamente identificado como mais recente (não 3.x)
  • ✅ Acesso PDF: Arquivos PDF de 1.4MB+ acessíveis com sucesso
  • ✅ Relevância de Busca: Consultas telco edge retornam documentação especializada
  • ✅ Segurança de Domínio: 100% de validação de domínio Red Hat (mais de 50 domínios testados)
  • ✅ Integração de Busca Web: Abordagem híbrida com restrição a fontes oficiais

📊 Melhorias de Desempenho

MétricaAntesDepoisStatus
Detecção de Versão Mais Recente❌ Versões 3.x✅ Versões 4.18+Corrigido
Taxa de Sucesso de Acesso PDF❌ Erros 301/404✅ Respostas 200 OK100%
Validação de Domínio❌ Sem filtragem✅ Mais de 50 domínios oficiaisProtegido
Guias OpenShift Disponíveis8 genéricos13 especializados+62%

Suporte

Projetos Relacionados

Pronto para uso em produção com acesso seguro e validado por domínio ao ecossistema Red Hat! 🚀