aap-mcp

Gerenciamento do Ansible Automation Platform 2.4 mcp

GitHub

Documentação

Servidor MCP AAP

Um servidor Model Context Protocol (MCP) para Ansible Automation Platform (AAP) 2.4. Fornece ferramentas para gerenciar jobs, templates, workflows, inventário e infraestrutura por meio do Claude ou outros clientes MCP.

Início Rápido

Pré-requisitos

  • Node.js ≥ 18.0.0
  • npm ou yarn
  • Acesso a uma instância AAP

Instalação

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

Configuração

Opção 1: Configuração Interativa

npm run setup-keychain

Esta configuração interativa orienta você por:

  • Escolha do método de autenticação (token de API ou nome de usuário/senha)
  • Inserção de credenciais (com entrada de senha oculta)
  • Seleção do método de armazenamento (macOS Keychain, arquivo .env ou variáveis de ambiente)
Note: Interactive should be all you need to get started unless you care to follow one of the other paths

Opção 2: Variáveis de Ambiente (Recomendado para CI/CD)

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

Opção 3: Arquivo .env (Somente para Desenvolvimento)

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

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

Em seguida:

npm start

Configuração

Variáveis de Ambiente Obrigatórias

  • AAP_BASE_URL - URL da instância AAP (ex.: https://aap.example.com)
  • Uma das seguintes opções:
    • AAP_TOKEN - Token de autenticação da API, OU
    • AAP_USERNAME e AAP_PASSWORD - Autenticação por nome de usuário e senha

Variáveis de Ambiente Opcionais

  • AAP_CONFIG_DIR - Diretório de configuração (padrão: ~/.config/aap-mcp)
  • AAP_DATA_DIR - Diretório de dados (padrão: ~/.data/aap-mcp)

Personalização do Keychain (macOS)

  • AAP_KEYCHAIN_SERVICE - Nome do serviço (padrão: aap-mcp)
  • AAP_KEYCHAIN_TOKEN_ACCOUNT - Nome da conta do token (padrão: token)
  • AAP_KEYCHAIN_BASE_URL_ACCOUNT - Nome da conta da URL (padrão: base_url)
  • AAP_KEYCHAIN_USERNAME_ACCOUNT - Nome da conta do usuário (padrão: username)
  • AAP_KEYCHAIN_PASSWORD_ACCOUNT - Nome da conta da senha (padrão: password)

Desenvolvimento

Build

npm run build

Servidor de Desenvolvimento

npm run dev

Testes

npm test
npm run test:ui

Lint

npm run lint

Arquitetura

Componentes Principais

  • Client (src/client/): Cliente HTTP para comunicação com a API AAP
  • Tools (src/tools/): Implementações de ferramentas MCP organizadas por domínio
    • system.ts - Saúde e métricas do sistema
    • jobs.ts - Execução e monitoramento de jobs
    • templates.ts - Templates de jobs e workflows
    • workflows.ts - Gerenciamento de workflows
    • inventory.ts - Gerenciamento de inventário e hosts
    • projects.ts - Gerenciamento de projetos
    • infra.ts - Ferramentas de infraestrutura
  • Credentials (src/credentials.ts): Gerenciamento seguro de credenciais com carregamento baseado em prioridade
  • Paths (src/paths.ts): Gerenciamento de diretórios de configuração e dados

Prioridade de Carregamento de Credenciais

  1. Variáveis de ambiente (prioridade mais alta)
  2. macOS Keychain (se disponível)
  3. Arquivo .env
  4. Padrão ou erro (prioridade mais baixa)

Referência de Ferramentas

Ferramentas do Sistema

  • get_system_info - Recuperar informações do sistema AAP
  • get_platform_metrics - Obter estatísticas de capacidade e jobs da plataforma

Ferramentas de Jobs

  • list_jobs - Listar jobs de automação com filtros
  • get_job - Obter detalhes do job
  • run_job - Executar um template de job
  • get_job_output - Recuperar logs de execução do job

Ferramentas de Templates

  • list_job_templates - Listar templates de jobs disponíveis
  • list_workflow_templates - Listar templates de jobs de workflow

Ferramentas de Workflow

  • list_workflow_jobs - Listar execuções de workflows
  • get_workflow_job - Obter detalhes da execução do workflow

Ferramentas de Inventário

  • list_hosts - Listar hosts do inventário
  • list_groups - Listar grupos do inventário

Ferramentas de Projetos

  • list_projects - Listar projetos
  • get_project - Obter detalhes do projeto

Ferramentas de Infraestrutura

  • list_nodes - Listar nós de controle e execução
  • get_node_details - Obter informações do nó

Solução de Problemas

"AAP_BASE_URL é obrigatório"

Credenciais não encontradas. Execute:

npm run setup-keychain

Ou defina as variáveis de ambiente:

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

"Falha ao inicializar o diretório de configuração"

Garanta que o caminho do diretório de configuração tenha permissão de escrita, ou especifique um caminho personalizado:

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

"Falha na verificação de conexão"

Verifique se a instância AAP está acessível:

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

Licença

Consulte o arquivo LICENSE.

Documentação

Suporte

Para problemas e solicitações de recursos, abra uma issue no GitHub.