MCP-Ambari-API

Automatize operações do Apache Ambari com IA/LLM: comandos em linguagem natural para gerenciamento de cluster Hadoop, controle de serviços, monitoramento de configuração e rastreamento de status em tempo real por meio das ferramentas do Model Context Protocol (MCP).

GitHub
1
Experimente este MCPPatrocinado

Documentação

MCP Ambari API - Automação de Gerenciamento de Cluster Apache Hadoop

🚀 Automatize operações do Apache Ambari com IA/LLM: Controle conversacional para gerenciamento de cluster Hadoop, monitoramento de serviços, inspeção de configuração e consultas precisas de métricas do Ambari via ferramentas do Model Context Protocol (MCP).

License: MIT Python Docker Pulls BuyMeACoffee

Deploy to PyPI with tag PyPI PyPI - Downloads

Arquitetura e Internos (DeepWiki)

Ask DeepWiki

📋 Visão Geral

MCP Ambari API é um poderoso servidor Model Context Protocol (MCP) que permite gerenciamento contínuo de clusters Apache Ambari por meio de comandos em linguagem natural. Construído para engenheiros de DevOps, engenheiros de dados e administradores de sistemas que trabalham com ecossistemas Hadoop.

Recursos

  • ✅ Hub Interativo de Operações Ambari – Fornece uma base baseada em MCP para consultar e gerenciar serviços por meio de linguagem natural em vez de interfaces de console ou UI.
  • ✅ Visibilidade de Cluster em Tempo Real – Visão abrangente de métricas-chave, incluindo status de serviços, detalhes de hosts, histórico de alertas e solicitações em andamento em uma única interface.
  • ✅ Pipeline de Inteligência de Métricas – Descobre e filtra dinamicamente appIds e nomes de métricas do AMS, conectando-se diretamente a fluxos de trabalho de análise de séries temporais.
  • ✅ Fluxo de Trabalho de Operações Automatizadas – Consolida operações repetitivas de iniciar/parar, verificações de configuração, consultas de usuários e rastreamento de solicitações em cenários consistentes.
  • ✅ Relatórios Operacionais Integrados – Entrega instantaneamente relatórios HDFS no estilo dfsadmin, resumos de serviços e métricas de capacidade por meio de interfaces LLM ou CLI.
  • ✅ Proteções e Salvaguardas de Segurança – Exige confirmação do usuário antes de operações em larga escala e fornece orientação clara para comandos arriscados por meio de modelos de prompt.
  • ✅ Otimização de Integração LLM – Inclui exemplos de linguagem natural, mapeamento de parâmetros e guias de uso para garantir operações estáveis de agentes de IA.
  • ✅ Modelos de Implantação Flexíveis – Suporta transporte stdio/streamable-http, Docker Compose e autenticação por token para implantação em ambientes de desenvolvimento e produção.
  • ✅ Arquitetura de Cache Orientada a Desempenho – Cache de metadados AMS integrado e registro de solicitações garantem respostas rápidas mesmo em clusters de grande escala.
  • ✅ Arquitetura de Código Escalável – HTTP assíncrono, registro estruturado e camadas de ferramentas modularizadas permitem fácil adição de novos recursos.
  • ✅ Validado em Produção – Baseado em ferramentas validadas em clusters Ambari de teste, pronto para uso imediato em ambientes de produção.
  • ✅ Canais de Implantação Diversificados – Disponível por meio de pacotes PyPI, imagens Docker e outros métodos de implantação preferidos.

Documentação para Airflow REST-API

Tópicos

apache-ambari hadoop-cluster mcp-server cluster-automation devops-tools big-data infrastructure-management ai-automation llm-tools python-mcp

Exemplos de Consultas - Informações/Status do Cluster

Ir para Mais Exemplos de Consultas

Example: Querying Ambari Cluster(1)

Example: Querying Ambari Cluster(2)

🚀 Guia de Início Rápido /w Docker

Nota: As instruções a seguir pressupõem que você está usando o modo streamable-http para o Servidor MCP.

Diagrama de Fluxo do Início Rápido/Tutorial

Flow Diagram of Quickstart/Tutorial

1. Preparar Cluster Ambari (Alvo de Teste)

Para configurar um cluster de demonstração Ambari, siga o guia em: Instalar Ambari 3.0 com Docker

Example: Ambari Demo Cluster

2. Executar Docker-Compose

Inicie o MCP-Server, MCPO(MCP-Proxy para OpenAPI) e OpenWebUI.

  1. Certifique-se de que Docker e Docker Compose estejam instalados no seu sistema.
  2. Clone este repositório e navegue até seu diretório raiz.
  3. Configure a configuração do ambiente: 
    # Copy environment template and configure your settings
cp .env.example .env
# Edit .env with your Ambari cluster information
  4. Configure sua conexão Ambari no arquivo .env: 
    # Ambari cluster connection
AMBARI_HOST=host.docker.internal
AMBARI_PORT=7070
AMBARI_USER=admin
AMBARI_PASS=admin
AMBARI_CLUSTER_NAME=TEST-AMBARI

# Ambari Metrics (AMS) collector
AMBARI_METRICS_HOST=host.docker.internal
AMBARI_METRICS_PORT=16188
AMBARI_METRICS_PROTOCOL=http
AMBARI_METRICS_TIMEOUT=15

# (Optional) Enable authentication for streamable-http mode
# Recommended for production environments
REMOTE_AUTH_ENABLE=false
REMOTE_SECRET_KEY=your-secure-secret-key-here
  5. Execute: 
    docker-compose up -d
  • O OpenWebUI estará disponível em: http://localhost:${DOCKER_EXTERNAL_PORT_OPENWEBUI} (padrão: 3001)
  • O MCPO-Proxy estará acessível em: http://localhost:${DOCKER_EXTERNAL_PORT_MCPO_PROXY} (padrão: 8001)
  • A Documentação da API MCPO: http://localhost:${DOCKER_EXTERNAL_PORT_MCPO_PROXY}/mcp-ambari-api/docs

Example: MCPO-Proxy

3. Registrando a Ferramenta no OpenWebUI

📌 Nota: As instruções de configuração da Web-UI são baseadas no OpenWebUI v0.6.22. Os locais de menu e configurações podem diferir em versões mais recentes.

  1. Faça login no OpenWebUI com uma conta de administrador
  2. Vá para "Configurações" → "Ferramentas" no menu superior.
  3. Insira o endereço da Ferramenta mcp-ambari-api (por exemplo, http://localhost:8000/mcp-ambari-api) para conectar as Ferramentas MCP ao seu cluster Ambari.

4. Mais Exemplos: Usando Ferramentas MCP para Consultar o Cluster Ambari

Abaixo está um exemplo de captura de tela mostrando como consultar o cluster Ambari usando Ferramentas MCP no OpenWebUI:

Exemplo de Consulta - Revisão e Recomendações de Configuração do Cluster

Example: Querying Ambari Cluster(2)

Exemplo de Consulta - Reiniciar Serviço HDFS

Example: Querying Ambari Cluster(3) Example: Querying Ambari Cluster(3)

📈 Métricas e Tendências

  • Referência rápida de terminologia

    • appId: O Ambari Metrics Service agrupa cada métrica sob um identificador de aplicação (por exemplo, namenode, datanode, ambari_server, HOST). Pense nele como o componente ou serviço que emite essa série temporal.
    • nome da métrica: A string totalmente qualificada que o Ambari usa para cada série temporal (por exemplo, jvm.JvmMetrics.MemHeapUsedM, dfs.datanode.BytesWritten). Nomes exatos são necessários ao consultar o AMS.

  • list_common_metrics_catalog: pesquisa por palavra-chave no catálogo de métricas com suporte de metadados ao vivo (armazenado em cache localmente). Use search="heap" ou similar para restringir sugestões antes de executar uma consulta de série temporal.
    Exemplo: "Mostre as métricas relacionadas a heap disponíveis para o appId NameNode."

  • list_ambari_metric_apps: lista os valores de appId do AMS descobertos, opcionalmente incluindo contagens de métricas; passe refresh=true ou limit para controlar a saída.
    Exemplo: "Liste todos os appIds atualmente expostos pelo AMS."

  • A consulta em linguagem natural "AMS에서 사용 가능한 appId 목록만 보여줘" mapeia para list_ambari_metric_apps e retorna os identificadores exatos que você pode copiar para outras ferramentas.

  • list_ambari_metrics_metadata: explorador de metadados AMS bruto (suporta app_id, metric_name_filter, host_filter, search, limit ajustável, padrão 50).
    Exemplo: "Forneça-me metadados de métricas relacionados a CPU sob HOST."

  • query_ambari_metrics: busca dados de série temporal; a ferramenta seleciona automaticamente nomes de métricas selecionados, recorre à pesquisa de metadados quando necessário e respeita a precisão padrão do Ambari, a menos que você forneça explicitamente precision="SECONDS", etc.
    Exemplos: "Plote os últimos 30 minutos de jvm.JvmMetrics.MemHeapUsedM para o NameNode." / "Compare jvm.JvmMetrics.MemHeapUsedM para hosts DataNode bigtop-hostname0.demo.local e bigtop-hostname1.demo.local nos últimos 30 minutos."

  • hdfs_dfadmin_report: produz um resumo de capacidade/DataNode no estilo DFSAdmin (espelha hdfs dfsadmin -report).

Catálogo de Métricas ao Vivo (via metadados AMS)

  • Os nomes de métricas são descobertos sob demanda a partir de /ws/v1/timeline/metrics/metadata e armazenados em cache para reutilização rápida.
  • Use list_common_metrics_catalog ou o recurso ambari-metrics://catalog/all (anexe ?refresh=true para ignorar o cache) para inspecionar o mapeamento mais recente de appId → metric. Consulte ambari-metrics://catalog/apps para listar appIds ou ambari-metrics://catalog/<appId> para um único aplicativo.
  • Os appIds típicos incluem ambari_server, namenode, datanode, nodemanager, resourcemanager e HOST, mas a lista se adapta ao que o serviço Ambari Metrics anuncia em seu cluster.

🔍 Requisitos de Consulta de Métricas do Ambari (Fluxo de Trabalho de Correspondência Exata)

Atualizações recentes removeram a adivinhação de métricas em linguagem natural em favor de consultas determinísticas orientadas por catálogo. Mantenha as seguintes regras em mente quando você (ou um agente LLM) chamar query_ambari_metrics:

  1. Sempre passe um app_id explícito. Se estiver ausente ou não for suportado, a ferramenta retorna uma lista de appIds válidos e aborta para que você possa escolher um manualmente.
  2. Especifique nomes exatos de métricas. Use list_common_metrics_catalog(app_id="<target>", search="keyword"), list_ambari_metric_apps (para descobrir appIds) ou o recurso ambari-metrics://catalog/<appId> para navegar pelo conjunto de métricas por aplicativo ao vivo e copiar o identificador (por exemplo, jvm.JvmMetrics.MemHeapUsedM).
  3. Comportamento de escopo de host: Quando hostnames é omitido, a API retorna agregados de todo o cluster. Forneça um ou mais hosts (separados por vírgula) para focar em nós específicos.
  4. Sem correspondências difusas. O servidor agora chama o Ambari exatamente como solicitado. Se a métrica estiver errada ou vazia, o Ambari simplesmente retornará sem pontos de dados—verifique novamente o identificador via /ws/v1/timeline/metrics/metadata.

Exemplo de invocação:

query_ambari_metrics(
  metric_names="jvm.JvmMetrics.MemHeapUsedM",
  app_id="nodemanager",
  duration="1h",
  group_by_host=true
)

Para consultas de múltiplas métricas, passe uma lista separada por vírgulas de nomes exatos. As respostas documentam quaisquer filtros de host aplicados automaticamente para que você possa copiá-los/colá-los em solicitações subsequentes.

🐛 Uso e Configuração

Este servidor MCP suporta dois modos de conexão: stdio (tradicional) e streamable-http (baseado em Docker). Você pode configurar o modo de transporte usando argumentos de CLI ou variáveis de ambiente.

Prioridade de Configuração: Argumentos de CLI > Variáveis de ambiente > Valores padrão

Argumentos de CLI

  • --type (-t): Tipo de transporte (stdio ou streamable-http) - Padrão: stdio
  • --host: Endereço de host para transporte HTTP - Padrão: 127.0.0.1
  • --port (-p): Número da porta para transporte HTTP - Padrão: 8000
  • --auth-enable: Ativar autenticação por token Bearer para modo streamable-http - Padrão: false
  • --secret-key: Chave secreta para autenticação por token Bearer (necessária quando a autenticação está ativada)

Variáveis de Ambiente

VariávelDescriçãoPadrãoPadrão do Projeto
PYTHONPATHCaminho de busca do módulo Python para importações do servidor MCP-/app/src
MCP_LOG_LEVELNível de verbosidade do registro do servidor (DEBUG, INFO, WARNING, ERROR)INFOINFO
FASTMCP_TYPEProtocolo de transporte MCP (stdio para CLI, streamable-http para web)stdiostreamable-http
FASTMCP_HOSTEndereço de bind do servidor HTTP (0.0.0.0 para todas as interfaces)127.0.0.10.0.0.0
FASTMCP_PORTPorta do servidor HTTP para comunicação MCP80008000
REMOTE_AUTH_ENABLEAtivar autenticação por token Bearer para modo streamable-http
Padrão: false (se indefinido, vazio ou nulo)		falsefalse
REMOTE_SECRET_KEYChave secreta para autenticação por token Bearer
Necessária quando REMOTE_AUTH_ENABLE=true		-your-secret-key-here
AMBARI_HOSTNome de host ou endereço IP do servidor Ambari127.0.0.1host.docker.internal
AMBARI_PORTNúmero da porta do servidor Ambari80808080
AMBARI_USERNome de usuário para autenticação no servidor Ambariadminadmin
AMBARI_PASSSenha para autenticação no servidor Ambariadminadmin
AMBARI_CLUSTER_NAMENome do cluster Ambari alvoTEST-AMBARITEST-AMBARI
DOCKER_EXTERNAL_PORT_OPENWEBUIMapeamento de porta do host para contêiner Open WebUI80803001
DOCKER_EXTERNAL_PORT_MCP_SERVERMapeamento de porta do host para contêiner do servidor MCP808018001
DOCKER_EXTERNAL_PORT_MCPO_PROXYMapeamento de porta do host para contêiner proxy MCPO80008001

Nota: AMBARI_CLUSTER_NAME serve como o cluster alvo padrão para operações quando nenhum cluster específico é especificado. Todas as variáveis de ambiente podem ser configuradas por meio do arquivo .env.

Lógica de Seleção de Transporte:

Prioridade de Configuração: Argumentos de CLI > Variáveis de ambiente > Valores padrão

Lógica de Seleção de Transporte:

  • Prioridade de CLI: --type streamable-http --host 0.0.0.0 --port 18001
  • Prioridade de Ambiente: FASTMCP_TYPE=streamable-http FASTMCP_HOST=0.0.0.0 FASTMCP_PORT=18001
  • Suporte Legado: FASTMCP_PORT=18001 (ativa automaticamente o modo streamable-http)
  • Padrão: modo stdio quando nenhuma configuração é fornecida

Configuração do Ambiente

# 1. Clone the repository
git clone https://github.com/call518/MCP-Ambari-API.git
cd MCP-Ambari-API

# 2. Set up environment configuration
cp .env.example .env

# 3. Configure your Ambari connection in .env file
AMBARI_HOST=your-ambari-host
AMBARI_PORT=your-ambari-port  
AMBARI_USER=your-username
AMBARI_PASS=your-password
AMBARI_CLUSTER_NAME=your-cluster-name

🔐 Segurança e Autenticação

Autenticação por Token Bearer

Para o modo streamable-http, este servidor MCP suporta autenticação via token Bearer para proteger o acesso remoto. Isso é especialmente importante ao executar o servidor em ambientes de produção.

Configuração

Habilitar Autenticação:

# In .env file
REMOTE_AUTH_ENABLE=true
REMOTE_SECRET_KEY=your-secure-secret-key-here

Ou via CLI:

python -m mcp_ambari_api --type streamable-http --auth-enable --secret-key your-secure-secret-key-here

Níveis de Segurança

  1. Modo stdio (Padrão): Acesso apenas local, sem necessidade de autenticação
  2. streamable-http + REMOTE_AUTH_ENABLE=false/indefinido: Acesso remoto sem autenticação ⚠️ NÃO RECOMENDADO para produção
  3. streamable-http + REMOTE_AUTH_ENABLE=true: Acesso remoto com autenticação via token Bearer ✅ RECOMENDADO para produção

🔒 Política Padrão: REMOTE_AUTH_ENABLE assume o valor padrão false se indefinido, vazio ou nulo. Isso garante que o servidor inicie mesmo sem configuração explícita de autenticação.

Configuração do Cliente

Quando a autenticação está habilitada, os clientes MCP devem incluir o token Bearer no cabeçalho Authorization:

{
  "mcpServers": {
    "mcp-ambari-api": {
      "type": "streamable-http",
      "url": "http://your-server:8000/mcp",
      "headers": {
        "Authorization": "Bearer your-secure-secret-key-here"
      }
    }
  }
}

Boas Práticas de Segurança

  • Sempre habilite a autenticação ao usar o modo streamable-http em produção
  • Use chaves secretas fortes e geradas aleatoriamente (32+ caracteres recomendados)
  • Use HTTPS quando possível (configure um proxy reverso com SSL/TLS)
  • Restrinja o acesso à rede usando firewalls ou políticas de rede
  • Rotacione as chaves secretas regularmente para maior segurança
  • Monitore os logs de acesso para tentativas de acesso não autorizado

Tratamento de Erros

Quando a autenticação falha, o servidor retorna:

  • 401 Não Autorizado para tokens ausentes ou inválidos
  • Mensagens de erro detalhadas em formato JSON para depuração

Método 1: MCP Local (transport="stdio")

{
  "mcpServers": {
    "mcp-ambari-api": {
      "command": "uvx",
      "args": ["--python", "3.12", "mcp-ambari-api"],
      "env": {
        "AMBARI_HOST": "host.docker.internal",
        "AMBARI_PORT": "8080",
        "AMBARI_USER": "admin",
        "AMBARI_PASS": "admin",
        "AMBARI_CLUSTER_NAME": "TEST-AMBARI",
        "MCP_LOG_LEVEL": "INFO"
      }
    }
  }
}

Método 2: MCP Remoto (transport="streamable-http")

No Host do Cliente MCP:

{
  "mcpServers": {
    "mcp-ambari-api": {
      "type": "streamable-http",
      "url": "http://localhost:18001/mcp"
    }
  }
}

Com Autenticação via Token Bearer (Recomendado para produção):

{
  "mcpServers": {
    "mcp-ambari-api": {
      "type": "streamable-http", 
      "url": "http://localhost:18001/mcp",
      "headers": {
        "Authorization": "Bearer your-secure-secret-key-here"
      }
    }
  }
}

Exemplo de uso: Claude-Desktop

claude_desktop_config.json

{
  "mcpServers": {
    "mcp-ambari-api": {
      "command": "uvx",
      "args": ["--python", "3.12", "mcp-ambari-api"],
      "env": {
        "AMBARI_HOST": "localhost",
        "AMBARI_PORT": "7070",
        "AMBARI_USER": "admin",
        "AMBARI_PASS": "admin",
        "AMBARI_CLUSTER_NAME": "TEST-AMBARI",
        "MCP_LOG_LEVEL": "INFO"
      }
    }
  }
}

Example: Claude-Desktop(3)

(Opcional) Configurar Múltiplos Clusters Ambari

{
  "mcpServers": {
    "Ambari-Cluster-A": {
      "command": "uvx",
      "args": ["--python", "3.12", "mcp-ambari-api"],
      "env": {
        "AMBARI_HOST": "a.foo.com",
        "AMBARI_PORT": "8080",
        "AMBARI_USER": "admin-user",
        "AMBARI_PASS": "admin-pass",
        "AMBARI_CLUSTER_NAME": "AMBARI-A",
        "MCP_LOG_LEVEL": "INFO"
      }
    },
    "Ambari-Cluster-B": {
      "command": "uvx",
      "args": ["--python", "3.12", "mcp-ambari-api"],
      "env": {
        "AMBARI_HOST": "b.bar.com",
        "AMBARI_PORT": "8080",
        "AMBARI_USER": "admin-user",
        "AMBARI_PASS": "admin-pass",
        "AMBARI_CLUSTER_NAME": "AMBARI-B",
        "MCP_LOG_LEVEL": "INFO"
      }
    }
  }
}

Acesso Remoto com Autenticação (Claude Desktop):

{
  "mcpServers": {
    "mcp-ambari-api-remote": {
      "type": "streamable-http",
      "url": "http://your-server-ip:18001/mcp",
      "headers": {
        "Authorization": "Bearer your-secure-secret-key-here"
      }
    }
  }
}

🎯 Principais Recursos e Capacidades

Operações de Serviço

  • Gerenciamento de Serviços Hadoop: Iniciar, parar, reiniciar HDFS, YARN, Spark, HBase e outros
  • Operações em Lote: Controlar todos os serviços do cluster simultaneamente
  • Monitoramento de Status: Saúde do serviço e acompanhamento de desempenho em tempo real

Gerenciamento de Configuração

  • Ferramenta de Configuração Unificada: Interface única para todos os tipos de configuração (yarn-site, hdfs-site, etc.)
  • Configuração em Lote: Exportar e gerenciar múltiplas configurações com filtros
  • Validação de Configuração: Verificação de sintaxe e validação antes de aplicar alterações

Monitoramento e Alertas

  • Alertas em Tempo Real: Alertas atuais e históricos do cluster com filtros
  • Rastreamento de Solicitações: Monitore operações de longa duração com progresso detalhado
  • Monitoramento de Hosts: Métricas de hardware, estados de componentes e utilização de recursos

Administração

  • Gerenciamento de Usuários: Verifique a administração de usuários do cluster
  • Gerenciamento de Hosts: Registro de nós, atribuições de componentes e monitoramento de saúde

Ferramentas MCP Disponíveis

Este servidor MCP fornece as seguintes ferramentas para gerenciamento de clusters Ambari:

Gerenciamento de Cluster

  • get_cluster_info - Recuperar informações básicas do cluster e status
  • get_active_requests - Listar operações atualmente ativas/em execução
  • get_request_status - Verificar status e progresso de solicitações específicas
  • get_request_tasks - Obter detalhamento de tarefas por host/papel para uma solicitação específica. Suporta filtragem por status (status_filter="FAILED", "not:COMPLETED", etc.) e por substring do nome do host (host_filter="node01")

Gerenciamento de Serviços

  • get_cluster_services - Listar todos os serviços com seus status
  • get_service_status - Obter status detalhado de um serviço específico
  • get_service_components - Listar componentes e atribuições de host para um serviço
  • get_service_details - Obter informações abrangentes do serviço
  • start_service - Iniciar um serviço específico
  • stop_service - Parar um serviço específico
  • restart_service - Reiniciar um serviço específico
  • start_all_services - Iniciar todos os serviços no cluster
  • stop_all_services - Parar todos os serviços no cluster
  • restart_all_services - Reiniciar todos os serviços no cluster

Ferramentas de Configuração

  • dump_configurations - Ferramenta de configuração unificada (substitui get_configurations, list_configurations e o antigo dump_all_configurations interno). Suporta:
    • Tipo único: dump_configurations(config_type="yarn-site")
    • Resumo em lote: dump_configurations(summarize=True)
    • Filtrar por substring (tipo ou chave): dump_configurations(filter="memory")
    • Filtro de serviço (restringir tipos por substring): dump_configurations(service_filter="yarn", summarize=True)
    • Apenas chaves (sem valores): dump_configurations(include_values=False)
    • Limitar número de tipos: dump_configurations(limit=10, summarize=True)

Mudança de Quebra: get_configurations e list_configurations foram removidos em favor desta ferramenta única e mais capaz.

Gerenciamento de Hosts

  • list_hosts - Listar todos os hosts no cluster
  • get_host_details - Obter informações detalhadas para hosts específicos ou todos (inclui estados de componentes, métricas de hardware e atribuições de serviço)

Gerenciamento de Usuários

  • list_users - Listar todos os usuários no sistema Ambari com seus nomes de usuário e links de API
  • get_user - Obter informações detalhadas sobre um usuário específico, incluindo:
    • Perfil básico (ID, nome de usuário, nome de exibição, tipo de usuário)
    • Informações de status (privilégios de administrador, status ativo, falhas de login)
    • Detalhes de autenticação (status de usuário LDAP, fontes de autenticação)
    • Associações de grupo, privilégios e layouts de widgets

Gerenciamento de Alertas

  • get_alerts_history - Ferramenta de alerta unificada para alertas atuais e históricos:
    • Modo atual (mode="current"): Recuperar alertas atuais/ativos com status em tempo real
      • Estados de alerta atuais em todo o cluster, serviços ou hosts
      • Filtragem por modo de manutenção (LIGADO/DESLIGADO)
      • Formatos de resumo: resumo básico e agrupado por definição
      • Informações detalhadas de alerta, incluindo carimbos de data/hora e descrições
    • Modo histórico (mode="history"): Recuperar eventos de alerta históricos do cluster
      • Filtragem por escopo: alertas em todo o cluster, específicos de serviço ou específicos de host
      • Filtragem por intervalo de tempo: suporte a carimbos de data/hora de início/fim
      • Suporte a paginação para grandes conjuntos de dados
    • Recursos comuns (ambos os modos):
      • Filtragem por estado: alertas CRÍTICOS, DE AVISO, OK, DESCONHECIDOS
      • Filtragem por definição: filtrar por nomes específicos de definição de alerta
      • Múltiplos formatos de saída: detalhado, resumo, compacto
      • API unificada para experiência consistente de consulta de alertas

🤝 Contribuindo e Suporte

Como Contribuir

Tecnologias Utilizadas

  • Linguagem: Python 3.12
  • Framework: Model Context Protocol (MCP)
  • API: Apache Ambari REST API
  • Transporte: stdio (local) e streamable-http (remoto)
  • Implantação: Docker, Docker Compose, PyPI

Ambiente de Desenvolvimento

  • WSL2(networkingMode = bridged) + Docker-Desktop

    • .wslconfig: testado com networkingMode = bridged

  • Python 3.12 venv

    ### Option-1: with uv
uv venv --python 3.12 --seed

### Option-2: with pip
python3.12 -m venv .venv
source .venv/bin/activate
pip install -U pip

🛠️ Adicionando Ferramentas Personalizadas

Depois de explorar a fundo a funcionalidade existente, você pode querer adicionar suas próprias ferramentas personalizadas para necessidades específicas de monitoramento ou gerenciamento. Este servidor MCP foi projetado para fácil extensibilidade.

Guia Passo a Passo

1. Adicionar Funções Auxiliares (Opcional)

Adicione funções de dados reutilizáveis em src/mcp_ambari_api/functions.py:

async def get_your_custom_data(target_resource: str = None) -> List[Dict[str, Any]]:
    """Your custom data retrieval function."""
    # Example implementation - adapt to your Ambari service
    endpoint = f"/clusters/{AMBARI_CLUSTER_NAME}/your_custom_endpoint"
    if target_resource:
        endpoint += f"/{target_resource}"
    
    response_data = await make_ambari_request(endpoint)
    
    if response_data is None or "items" not in response_data:
        return []
    
    return response_data["items"]

2. Criar Sua Ferramenta MCP

Adicione sua função de ferramenta em src/mcp_ambari_api/mcp_main.py:

@mcp.tool()
@log_tool
async def get_your_custom_analysis(limit: int = 50, target_name: Optional[str] = None) -> str:
    """
    [Tool Purpose]: Brief description of what your tool does
    
    [Core Functions]:
    - Feature 1: Data aggregation and analysis
    - Feature 2: Resource monitoring and insights
    - Feature 3: Performance metrics and reporting
    
    [Required Usage Scenarios]:
    - When user asks "your specific analysis request"
    - Your business-specific monitoring needs
    
    Args:
        limit: Maximum results (1-100)
        target_name: Target resource/service name (optional)
    
    Returns:
        Formatted analysis results (success: formatted data, failure: English error message)
    """
    try:
        limit = max(1, min(limit, 100))  # Always validate input
        
        results = await get_your_custom_data(target_resource=target_name)
        
        if not results:
            return f"No custom analysis data found{' for ' + target_name if target_name else ''}."
        
        # Apply limit
        limited_results = results[:limit]
        
        # Format output
        result_lines = [
            f"Custom Analysis Results{' for ' + target_name if target_name else ''}",
            "=" * 50,
            f"Found: {len(limited_results)} items (total: {len(results)})",
            ""
        ]
        
        for i, item in enumerate(limited_results, 1):
            # Customize this formatting based on your data structure
            name = item.get("name", "Unknown")
            status = item.get("status", "N/A")
            result_lines.append(f"[{i}] {name}: {status}")
        
        return "\n".join(result_lines)
        
    except Exception as e:
        return f"Error: Exception occurred while retrieving custom analysis - {str(e)}"

3. Atualizar Importações

Adicione sua função auxiliar à seção de importações em src/mcp_ambari_api/mcp_main.py:

from mcp_ambari_api.functions import (
    format_timestamp,
    format_single_host_details,
    make_ambari_request,
    # ... existing imports ...
    get_your_custom_data,  # Add your new function here
)

4. Atualizar o Modelo de Prompt (Recomendado)

Adicione a descrição da sua ferramenta em src/mcp_ambari_api/prompt_template.md para melhor reconhecimento pela IA:

### Custom Analysis Tools

**get_your_custom_analysis**
- "Show me custom analysis results"
- "Get custom analysis for target_name"
- "Display custom monitoring data"
- 📋 **Features**: Custom data aggregation, resource monitoring, performance insights

5. Testar Sua Ferramenta

# Local testing with MCP Inspector
./run-mcp-inspector-local.sh

# Or test with Docker environment
docker-compose up -d
docker-compose logs -f mcp-server

# Test with natural language queries:
# "Show me custom analysis results"
# "Get custom analysis for my_target"

Notas Importantes

  • Sempre use os decoradores @mcp.tool() e @log_tool para registro e log adequados
  • Siga os padrões de tratamento de erros existentes - retorne mensagens de erro em inglês começando com "Error:"
  • Use a função make_ambari_request() para todas as chamadas de API Ambari para garantir autenticação e tratamento de erros consistentes
  • Valide todos os parâmetros de entrada antes de usá-los em chamadas de API
  • Teste minuciosamente com entradas válidas e inválidas

Exemplos de Casos de Uso

  • Verificações personalizadas de saúde de serviços além do monitoramento padrão do Ambari
  • Validação de configuração especializada para os padrões da sua organização
  • Agregação de alertas personalizada e formatos de relatório
  • Integração com sistemas de monitoramento externos via dados do Ambari
  • Verificação automatizada de conformidade para configurações de cluster

❓ Perguntas Frequentes

P: Quais versões do Ambari são suportadas?

R: Ambari 2.7+ é recomendado. Versões anteriores podem funcionar, mas não são oficialmente testadas.

P: Posso usar isso com clusters Hadoop gerenciados em nuvem?

R: Sim, desde que os endpoints da API Ambari estejam acessíveis, funciona com implantações locais, em nuvem e híbridas.

P: Como soluciono problemas de conexão?

R: Verifique seu AMBARI_HOST, AMBARI_PORT e a conectividade de rede. Habilite o log de depuração com MCP_LOG_LEVEL=DEBUG.

P: Como isso se compara à Interface Web do Ambari?

R: Isso fornece acesso programático via comandos de IA/LLM, perfeito para automação, scripts e integração com fluxos de trabalho DevOps modernos.

Contribuindo

🤝 Tem ideias? Encontrou bugs? Quer adicionar recursos interessantes?

Estamos sempre animados em receber novos colaboradores! Seja corrigindo um erro de digitação, adicionando uma nova ferramenta de monitoramento ou melhorando a documentação - cada contribuição torna este projeto melhor.

Formas de contribuir:

  • 🐛 Reportar problemas ou bugs
  • 💡 Sugerir novos recursos de monitoramento do Ambari
  • 📝 Melhorar a documentação
  • 🚀 Enviar pull requests
  • ⭐ Marque o repositório com estrela se achar útil!

Dica profissional: O código foi projetado para ser super amigável para adicionar novas ferramentas. Confira as funções @mcp.tool() existentes em mcp_main.py e siga o guia Adicionando Ferramentas Personalizadas acima.

📄 Licença

Este projeto é licenciado sob a Licença MIT.