MCP-Ambari-API

Automatiza operaciones de Apache Ambari con IA/LLM: comandos en lenguaje natural para la gestión de clústeres Hadoop, control de servicios, monitoreo de configuración y seguimiento de estado en tiempo real a través de herramientas del Protocolo de Contexto de Modelo (MCP).

GitHub
1
Prueba este MCPPatrocinado

Documentación

MCP Ambari API - Automatización de Gestión de Clústeres Apache Hadoop

🚀 Automatiza operaciones de Apache Ambari con IA/LLM: Control conversacional para la gestión de clústeres Hadoop, monitoreo de servicios, inspección de configuración y consultas precisas de Ambari Metrics mediante herramientas del Protocolo de Contexto de Modelos (MCP).

License: MIT Python Docker Pulls BuyMeACoffee

Deploy to PyPI with tag PyPI PyPI - Downloads

Arquitectura e Internos (DeepWiki)

Ask DeepWiki

📋 Descripción General

MCP Ambari API es un potente servidor del Protocolo de Contexto de Modelos (MCP) que permite la gestión fluida de clústeres Apache Ambari mediante comandos en lenguaje natural. Diseñado para ingenieros de DevOps, ingenieros de datos y administradores de sistemas que trabajan con ecosistemas Hadoop.

Características

  • ✅ Centro Interactivo de Operaciones Ambari – Proporciona una base basada en MCP para consultar y gestionar servicios mediante lenguaje natural en lugar de interfaces de consola o UI.
  • ✅ Visibilidad del Clúster en Tiempo Real – Vista integral de métricas clave, incluyendo estado de servicios, detalles de hosts, historial de alertas y solicitudes en curso en una sola interfaz.
  • ✅ Pipeline de Inteligencia de Métricas – Descubre y filtra dinámicamente appIds y nombres de métricas de AMS, conectándose directamente a flujos de trabajo de análisis de series temporales.
  • ✅ Flujo de Trabajo de Operaciones Automatizadas – Consolida operaciones repetitivas de inicio/detención, verificaciones de configuración, consultas de usuarios y seguimiento de solicitudes en escenarios consistentes.
  • ✅ Informes Operativos Integrados – Entrega instantáneamente informes HDFS estilo dfsadmin, resúmenes de servicios y métricas de capacidad a través de interfaces LLM o CLI.
  • ✅ Guardas y Salvaguardas de Seguridad – Requiere confirmación del usuario antes de operaciones a gran escala y proporciona orientación clara para comandos riesgosos mediante plantillas de prompt.
  • ✅ Optimización de Integración LLM – Incluye ejemplos de lenguaje natural, mapeo de parámetros y guías de uso para garantizar operaciones estables de agentes de IA.
  • ✅ Modelos de Despliegue Flexibles – Soporta transporte stdio/streamable-http, Docker Compose y autenticación por token para despliegue en entornos de desarrollo y producción.
  • ✅ Arquitectura de Caché Orientada al Rendimiento – Caché integrada de metadatos AMS y registro de solicitudes garantizan respuestas rápidas incluso en clústeres a gran escala.
  • ✅ Arquitectura de Código Escalable – HTTP asíncrono, registro estructurado y capas de herramientas modularizadas permiten añadir nuevas funcionalidades fácilmente.
  • ✅ Validado en Producción – Basado en herramientas validadas en clústeres Ambari de prueba, listo para uso inmediato en entornos de producción.
  • ✅ Canales de Despliegue Diversificados – Disponible a través de paquetes PyPI, imágenes Docker y otros métodos de despliegue preferidos.

Documentación para Airflow REST-API

Temas

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

Consultas de Ejemplo - Información/Estado del Clúster

Ir a Más Consultas de Ejemplo

Example: Querying Ambari Cluster(1)

Example: Querying Ambari Cluster(2)

🚀 Guía de Inicio Rápido con Docker

Nota: Las siguientes instrucciones asumen que estás utilizando el modo streamable-http para el Servidor MCP.

Diagrama de Flujo de Inicio Rápido/Tutorial

Flow Diagram of Quickstart/Tutorial

1. Preparar el Clúster Ambari (Objetivo de Prueba)

Para configurar un clúster de demostración Ambari, sigue la guía en: Instalar Ambari 3.0 con Docker

Example: Ambari Demo Cluster

2. Ejecutar Docker-Compose

Inicia MCP-Server, MCPO (MCP-Proxy para OpenAPI) y OpenWebUI.

  1. Asegúrate de que Docker y Docker Compose estén instalados en tu sistema.
  2. Clona este repositorio y navega a su directorio raíz.
  3. Configura la configuración del entorno: 
    # Copy environment template and configure your settings
cp .env.example .env
# Edit .env with your Ambari cluster information
  4. Configura tu conexión Ambari en el archivo .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. Ejecuta: 
    docker-compose up -d
  • OpenWebUI estará disponible en: http://localhost:${DOCKER_EXTERNAL_PORT_OPENWEBUI} (predeterminado: 3001)
  • El MCPO-Proxy será accesible en: http://localhost:${DOCKER_EXTERNAL_PORT_MCPO_PROXY} (predeterminado: 8001)
  • Los Documentos de la API MCPO: http://localhost:${DOCKER_EXTERNAL_PORT_MCPO_PROXY}/mcp-ambari-api/docs

Example: MCPO-Proxy

3. Registro de la Herramienta en OpenWebUI

📌 Nota: Las instrucciones de configuración de la interfaz web se basan en OpenWebUI v0.6.22. Las ubicaciones de menús y configuraciones pueden diferir en versiones más recientes.

  1. Inicia sesión en OpenWebUI con una cuenta de administrador
  2. Ve a "Configuración" → "Herramientas" desde el menú superior.
  3. Ingresa la dirección de la Herramienta mcp-ambari-api (por ejemplo, http://localhost:8000/mcp-ambari-api) para conectar las Herramientas MCP con tu clúster Ambari.

4. Más Ejemplos: Uso de Herramientas MCP para Consultar el Clúster Ambari

A continuación se muestra una captura de pantalla de ejemplo que muestra cómo consultar el clúster Ambari usando Herramientas MCP en OpenWebUI:

Consulta de Ejemplo - Revisión y Recomendaciones de Configuración del Clúster

Example: Querying Ambari Cluster(2)

Consulta de Ejemplo - Reiniciar Servicio HDFS

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

📈 Métricas y Tendencias

  • Referencia rápida de terminología

    • appId: El Servicio de Métricas de Ambari agrupa cada métrica bajo un identificador de aplicación (por ejemplo, namenode, datanode, ambari_server, HOST). Piénsalo como el componente o servicio que emite esa serie temporal.
    • nombre de métrica: La cadena totalmente calificada que Ambari usa para cada serie temporal (por ejemplo, jvm.JvmMetrics.MemHeapUsedM, dfs.datanode.BytesWritten). Se requieren nombres exactos al consultar AMS.

  • list_common_metrics_catalog: búsqueda por palabras clave en el catálogo de métricas respaldado por metadatos en vivo (almacenado en caché localmente). Usa search="heap" o similar para reducir sugerencias antes de ejecutar una consulta de series temporales.
    Ejemplo: "Muestra las métricas relacionadas con heap disponibles para el appId NameNode."

  • list_ambari_metric_apps: lista los valores de appId de AMS descubiertos, opcionalmente incluyendo conteos de métricas; pasa refresh=true o limit para controlar la salida.
    Ejemplo: "Lista cada appId actualmente expuesto por AMS."

  • La consulta en lenguaje natural "AMS에서 사용 가능한 appId 목록만 보여줘" se asigna a list_ambari_metric_apps y devuelve los identificadores exactos que puedes copiar en otras herramientas.

  • list_ambari_metrics_metadata: explorador de metadatos AMS en bruto (soporta app_id, metric_name_filter, host_filter, search, limit ajustable, predeterminado 50).
    Ejemplo: "Dame metadatos de métricas relacionadas con CPU bajo HOST."

  • query_ambari_metrics: obtiene datos de series temporales; la herramienta selecciona automáticamente nombres de métricas curadas, recurre a la búsqueda de metadatos cuando es necesario y respeta la precisión predeterminada de Ambari a menos que proporciones explícitamente precision="SECONDS", etc.
    Ejemplos: "Grafica los últimos 30 minutos de jvm.JvmMetrics.MemHeapUsedM para el NameNode." / "Compara jvm.JvmMetrics.MemHeapUsedM para los hosts DataNode bigtop-hostname0.demo.local y bigtop-hostname1.demo.local durante los últimos 30 minutos."

  • hdfs_dfadmin_report: produce un resumen de capacidad/DataNode estilo DFSAdmin (refleja hdfs dfsadmin -report).

Catálogo de Métricas en Vivo (vía metadatos AMS)

  • Los nombres de métricas se descubren bajo demanda desde /ws/v1/timeline/metrics/metadata y se almacenan en caché para reutilización rápida.
  • Usa list_common_metrics_catalog o el recurso ambari-metrics://catalog/all (agrega ?refresh=true para omitir la caché) para inspeccionar el mapeo más reciente de appId → metric. Consulta ambari-metrics://catalog/apps para listar appIds o ambari-metrics://catalog/<appId> para una sola aplicación.
  • Los appIds típicos incluyen ambari_server, namenode, datanode, nodemanager, resourcemanager y HOST, pero la lista se adapta a lo que el Servicio de Métricas de Ambari anuncie en tu clúster.

🔍 Requisitos de Consulta de Métricas de Ambari (Flujo de Trabajo de Coincidencia Exacta)

Las actualizaciones recientes eliminaron la adivinación de métricas en lenguaje natural en favor de búsquedas deterministas basadas en catálogo. Ten en cuenta las siguientes reglas cuando tú (o un agente LLM) llames a query_ambari_metrics:

  1. Siempre pasa un app_id explícito. Si falta o no es compatible, la herramienta devuelve una lista de appIds válidos y se aborta para que puedas elegir uno manualmente.
  2. Especifica nombres de métricas exactos. Usa list_common_metrics_catalog(app_id="<target>", search="keyword"), list_ambari_metric_apps (para descubrir appIds) o el recurso ambari-metrics://catalog/<appId> para explorar el conjunto de métricas por aplicación en vivo y copiar el identificador (por ejemplo, jvm.JvmMetrics.MemHeapUsedM).
  3. Comportamiento de ámbito de host: Cuando se omite hostnames, la API devuelve agregados a nivel de clúster. Proporciona uno o más hosts (separados por comas) para enfocarte en nodos específicos.
  4. Sin coincidencias difusas. El servidor ahora llama a Ambari exactamente como se solicita. Si la métrica es incorrecta o está vacía, Ambari simplemente devolverá sin puntos de datos—verifica el identificador mediante /ws/v1/timeline/metrics/metadata.

Invocación de ejemplo:

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

Para búsquedas de múltiples métricas, pasa una lista separada por comas de nombres exactos. Las respuestas documentan cualquier filtro de host aplicado automáticamente para que puedas copiarlos/pegarlos en solicitudes posteriores.

🐛 Uso y Configuración

Este servidor MCP soporta dos modos de conexión: stdio (tradicional) y streamable-http (basado en Docker). Puedes configurar el modo de transporte usando argumentos CLI o variables de entorno.

Prioridad de Configuración: Argumentos CLI > Variables de entorno > Valores predeterminados

Argumentos CLI

  • --type (-t): Tipo de transporte (stdio o streamable-http) - Predeterminado: stdio
  • --host: Dirección de host para transporte HTTP - Predeterminado: 127.0.0.1
  • --port (-p): Número de puerto para transporte HTTP - Predeterminado: 8000
  • --auth-enable: Habilitar autenticación por token Bearer para modo streamable-http - Predeterminado: false
  • --secret-key: Clave secreta para autenticación por token Bearer (requerida cuando la autenticación está habilitada)

Variables de Entorno

VariableDescripciónPredeterminadoPredeterminado del Proyecto
PYTHONPATHRuta de búsqueda de módulos Python para importaciones del servidor MCP-/app/src
MCP_LOG_LEVELVerbosidad de registro del servidor (DEBUG, INFO, WARNING, ERROR)INFOINFO
FASTMCP_TYPEProtocolo de transporte MCP (stdio para CLI, streamable-http para web)stdiostreamable-http
FASTMCP_HOSTDirección de enlace del servidor HTTP (0.0.0.0 para todas las interfaces)127.0.0.10.0.0.0
FASTMCP_PORTPuerto del servidor HTTP para comunicación MCP80008000
REMOTE_AUTH_ENABLEHabilitar autenticación por token Bearer para modo streamable-http
Predeterminado: false (si no está definido, vacío o nulo)		falsefalse
REMOTE_SECRET_KEYClave secreta para autenticación por token Bearer
Requerida cuando REMOTE_AUTH_ENABLE=true		-your-secret-key-here
AMBARI_HOSTNombre de host o dirección IP del servidor Ambari127.0.0.1host.docker.internal
AMBARI_PORTNúmero de puerto del servidor Ambari80808080
AMBARI_USERNombre de usuario para autenticación en el servidor Ambariadminadmin
AMBARI_PASSContraseña para autenticación en el servidor Ambariadminadmin
AMBARI_CLUSTER_NAMENombre del clúster Ambari objetivoTEST-AMBARITEST-AMBARI
DOCKER_EXTERNAL_PORT_OPENWEBUIMapeo de puerto de host para contenedor Open WebUI80803001
DOCKER_EXTERNAL_PORT_MCP_SERVERMapeo de puerto de host para contenedor del servidor MCP808018001
DOCKER_EXTERNAL_PORT_MCPO_PROXYMapeo de puerto de host para contenedor proxy MCPO80008001

Nota: AMBARI_CLUSTER_NAME sirve como clúster objetivo predeterminado para operaciones cuando no se especifica ningún clúster en particular. Todas las variables de entorno se pueden configurar mediante el archivo .env.

Lógica de Selección de Transporte:

Prioridad de Configuración: Argumentos CLI > Variables de entorno > Valores predeterminados

Lógica de Selección de Transporte:

  • Prioridad CLI: --type streamable-http --host 0.0.0.0 --port 18001
  • Prioridad de Entorno: FASTMCP_TYPE=streamable-http FASTMCP_HOST=0.0.0.0 FASTMCP_PORT=18001
  • Soporte Heredado: FASTMCP_PORT=18001 (habilita automáticamente el modo streamable-http)
  • Predeterminado: modo stdio cuando no se proporciona configuración

Configuración del Entorno

# 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

🔐 Seguridad y Autenticación

Autenticación por Token Bearer

Para el modo streamable-http, este servidor MCP admite autenticación mediante token Bearer para asegurar el acceso remoto. Esto es especialmente importante cuando se ejecuta el servidor en entornos de producción.

Configuración

Habilitar autenticación:

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

O mediante CLI:

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

Niveles de seguridad

  1. Modo stdio (predeterminado): Acceso solo local, no se necesita autenticación
  2. streamable-http + REMOTE_AUTH_ENABLE=false/undefined: Acceso remoto sin autenticación ⚠️ NO RECOMENDADO para producción
  3. streamable-http + REMOTE_AUTH_ENABLE=true: Acceso remoto con autenticación mediante token Bearer ✅ RECOMENDADO para producción

🔒 Política predeterminada: REMOTE_AUTH_ENABLE usa false por defecto si no está definido, está vacío o es nulo. Esto garantiza que el servidor se inicie incluso sin una configuración de autenticación explícita.

Configuración del cliente

Cuando la autenticación está habilitada, los clientes MCP deben incluir el token Bearer en el encabezado Authorization:

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

Buenas prácticas de seguridad

  • Habilite siempre la autenticación al usar el modo streamable-http en producción
  • Use claves secretas fuertes y generadas aleatoriamente (se recomiendan 32+ caracteres)
  • Use HTTPS cuando sea posible (configure un proxy inverso con SSL/TLS)
  • Restrinja el acceso a la red mediante firewalls o políticas de red
  • Rote las claves secretas regularmente para mayor seguridad
  • Supervise los registros de acceso para detectar intentos de acceso no autorizado

Manejo de errores

Cuando la autenticación falla, el servidor devuelve:

  • 401 No autorizado para tokens faltantes o inválidos
  • Mensajes de error detallados en formato JSON para depuración

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

En el host del cliente MCP:

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

Con autenticación mediante token Bearer (recomendado para producción):

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

Ejemplo 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últiples clústeres de 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"
      }
    }
  }
}

Acceso remoto con autenticación (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"
      }
    }
  }
}

🎯 Características y capacidades principales

Operaciones de servicios

  • Gestión de servicios Hadoop: Iniciar, detener, reiniciar HDFS, YARN, Spark, HBase y más
  • Operaciones masivas: Controlar todos los servicios del clúster simultáneamente
  • Monitoreo de estado: Seguimiento de salud y rendimiento de servicios en tiempo real

Gestión de configuración

  • Herramienta de configuración unificada: Interfaz única para todos los tipos de configuración (yarn-site, hdfs-site, etc.)
  • Configuración masiva: Exportar y gestionar múltiples configuraciones con filtrado
  • Validación de configuración: Verificación de sintaxis y validación antes de aplicar cambios

Monitoreo y alertas

  • Alertas en tiempo real: Alertas actuales e históricas del clúster con filtrado
  • Seguimiento de solicitudes: Monitoreo de operaciones de larga duración con progreso detallado
  • Monitoreo de hosts: Métricas de hardware, estados de componentes y utilización de recursos

Administración

  • Gestión de usuarios: Verificar la administración de usuarios del clúster
  • Gestión de hosts: Registro de nodos, asignación de componentes y monitoreo de salud

Herramientas MCP disponibles

Este servidor MCP proporciona las siguientes herramientas para la gestión de clústeres de Ambari:

Gestión del clúster

  • get_cluster_info - Obtener información básica del clúster y su estado
  • get_active_requests - Listar operaciones actualmente activas/en ejecución
  • get_request_status - Verificar el estado y progreso de solicitudes específicas
  • get_request_tasks - Obtener desglose de tareas por host/rol para una solicitud específica. Admite filtrado por estado (status_filter="FAILED", "not:COMPLETED", etc.) y por subcadena de nombre de host (host_filter="node01")

Gestión de servicios

  • get_cluster_services - Listar todos los servicios con su estado
  • get_service_status - Obtener estado detallado de un servicio específico
  • get_service_components - Listar componentes y asignaciones de hosts para un servicio
  • get_service_details - Obtener información completa del servicio
  • start_service - Iniciar un servicio específico
  • stop_service - Detener un servicio específico
  • restart_service - Reiniciar un servicio específico
  • start_all_services - Iniciar todos los servicios del clúster
  • stop_all_services - Detener todos los servicios del clúster
  • restart_all_services - Reiniciar todos los servicios del clúster

Herramientas de configuración

  • dump_configurations - Herramienta de configuración unificada (reemplaza a get_configurations, list_configurations y al antiguo dump_all_configurations interno). Admite:
    • Tipo único: dump_configurations(config_type="yarn-site")
    • Resumen masivo: dump_configurations(summarize=True)
    • Filtro por subcadena (tipo o clave): dump_configurations(filter="memory")
    • Filtro de servicio (restringir tipos por subcadena): dump_configurations(service_filter="yarn", summarize=True)
    • Solo claves (sin valores): dump_configurations(include_values=False)
    • Límite de número de tipos: dump_configurations(limit=10, summarize=True)

Cambio importante: get_configurations y list_configurations se eliminaron en favor de esta única herramienta más capaz.

Gestión de hosts

  • list_hosts - Listar todos los hosts del clúster
  • get_host_details - Obtener información detallada para hosts específicos o todos (incluye estados de componentes, métricas de hardware y asignaciones de servicios)

Gestión de usuarios

  • list_users - Listar todos los usuarios del sistema Ambari con sus nombres de usuario y enlaces de API
  • get_user - Obtener información detallada sobre un usuario específico, incluyendo:
    • Perfil básico (ID, nombre de usuario, nombre para mostrar, tipo de usuario)
    • Información de estado (privilegios de administrador, estado activo, fallos de inicio de sesión)
    • Detalles de autenticación (estado de usuario LDAP, fuentes de autenticación)
    • Membresías de grupo, privilegios y diseños de widgets

Gestión de alertas

  • get_alerts_history - Herramienta de alertas unificada para alertas actuales e históricas:
    • Modo actual (mode="current"): Obtener alertas actuales/activas con estado en tiempo real
      • Estados de alerta actuales en el clúster, servicios o hosts
      • Filtrado por modo de mantenimiento (ACTIVADO/DESACTIVADO)
      • Formatos de resumen: resumen básico y agrupado por definición
      • Información detallada de alertas, incluyendo marcas de tiempo y descripciones
    • Modo historial (mode="history"): Obtener eventos de alerta históricos del clúster
      • Filtrado por alcance: alertas de todo el clúster, específicas de servicio o específicas de host
      • Filtrado por rango de tiempo: soporte de marcas de tiempo desde/hasta
      • Soporte de paginación para conjuntos de datos grandes
    • Características comunes (ambos modos):
      • Filtrado por estado: alertas CRÍTICAS, DE ADVERTENCIA, OK, DESCONOCIDAS
      • Filtrado por definición: filtrar por nombres de definición de alerta específicos
      • Múltiples formatos de salida: detallado, resumen, compacto
      • API unificada para una experiencia de consulta de alertas consistente

🤝 Contribución y soporte

Cómo contribuir

Tecnologías utilizadas

  • Lenguaje: Python 3.12
  • Marco de trabajo: Model Context Protocol (MCP)
  • API: Apache Ambari REST API
  • Transporte: stdio (local) y streamable-http (remoto)
  • Despliegue: Docker, Docker Compose, PyPI

Entorno de desarrollo

  • WSL2(networkingMode = bridged) + Docker-Desktop

    • .wslconfig: probado con 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

🛠️ Añadir herramientas personalizadas

Después de explorar a fondo la funcionalidad existente, es posible que desee añadir sus propias herramientas personalizadas para necesidades específicas de monitoreo o gestión. Este servidor MCP está diseñado para una fácil extensibilidad.

Guía paso a paso

1. Añadir funciones auxiliares (opcional)

Añada funciones de datos reutilizables a 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. Crear su herramienta MCP

Añada su función de herramienta a 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. Actualizar importaciones

Añada su función auxiliar a la sección de importaciones en 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. Actualizar la plantilla de prompt (recomendado)

Añada la descripción de su herramienta a src/mcp_ambari_api/prompt_template.md para un mejor reconocimiento por 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. Probar su herramienta

# 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

  • Use siempre los decoradores @mcp.tool() y @log_tool para un registro y registro de eventos adecuados
  • Siga los patrones de manejo de errores existentes - devuelva mensajes de error en inglés que comiencen con "Error:"
  • Use la función make_ambari_request() para todas las llamadas a la API de Ambari para garantizar una autenticación y manejo de errores consistentes
  • Valide todos los parámetros de entrada antes de usarlos en llamadas a la API
  • Pruebe a fondo con entradas tanto válidas como inválidas

Casos de uso de ejemplo

  • Comprobaciones de salud de servicios personalizadas más allá del monitoreo estándar de Ambari
  • Validación de configuración especializada para los estándares de su organización
  • Agregación de alertas personalizadas y formatos de informes
  • Integración con sistemas de monitoreo externos mediante datos de Ambari
  • Verificación automatizada de cumplimiento para configuraciones de clúster

❓ Preguntas frecuentes

P: ¿Qué versiones de Ambari son compatibles?

R: Se recomienda Ambari 2.7+. Las versiones anteriores pueden funcionar pero no están probadas oficialmente.

P: ¿Puedo usar esto con clústeres Hadoop gestionados en la nube?

R: Sí, siempre que los endpoints de la API de Ambari sean accesibles, funciona con despliegues locales, en la nube e híbridos.

P: ¿Cómo soluciono problemas de conexión?

R: Verifique su AMBARI_HOST, AMBARI_PORT y la conectividad de red. Habilite el registro de depuración con MCP_LOG_LEVEL=DEBUG.

P: ¿Cómo se compara esto con la interfaz web de Ambari?

R: Esto proporciona acceso programático mediante comandos de IA/LLM, perfecto para automatización, scripting e integración con flujos de trabajo DevOps modernos.

Contribución

🤝 ¿Tiene ideas? ¿Encontró errores? ¿Quiere añadir funciones interesantes?

¡Siempre estamos encantados de dar la bienvenida a nuevos contribuyentes! Ya sea corrigiendo un error tipográfico, añadiendo una nueva herramienta de monitoreo o mejorando la documentación, cada contribución hace que este proyecto sea mejor.

Formas de contribuir:

  • 🐛 Reportar problemas o errores
  • 💡 Sugerir nuevas funciones de monitoreo de Ambari
  • 📝 Mejorar la documentación
  • 🚀 Enviar solicitudes de extracción
  • ⭐ ¡Marque el repositorio con una estrella si le resulta útil!

Consejo profesional: El código base está diseñado para ser muy amigable para añadir nuevas herramientas. Consulte las funciones @mcp.tool() existentes en mcp_main.py y siga la guía Añadir herramientas personalizadas anterior.

📄 Licencia

Este proyecto está licenciado bajo la Licencia MIT.