HAProxy MCP Server

Interactúa con la API en tiempo real de HAProxy para administración, monitoreo y análisis de tráfico.

Documentación

Servidor MCP de HAProxy

GitHub release (latest SemVer) License Docker Pulls

Un servidor de Protocolo de Contexto de Modelo (MCP) para HAProxy implementado en Go, que aprovecha la API de tiempo de ejecución de HAProxy y mcp-go.

Descripción general

El servidor MCP de HAProxy proporciona una forma estandarizada para que los LLM interactúen con la API de tiempo de ejecución de HAProxy a través del Protocolo de Contexto de Modelo (MCP). Esto permite que los LLM realicen tareas de administración de HAProxy, supervisen el estado del servidor, gestionen servidores backend y analicen patrones de tráfico, todo a través de interfaces de lenguaje natural.

Screenshot-1 Screenshot-2 Screenshot-3

Características

Soporte completo de la API de tiempo de ejecución de HAProxy: Cobertura integral de los comandos de la API de tiempo de ejecución de HAProxy
Operaciones conscientes del contexto: Todas las operaciones admiten un manejo adecuado de tiempos de espera y cancelación
Integración con la página de estadísticas: Soporte para la página web de estadísticas de HAProxy para métricas mejoradas y visualización
Autenticación segura: Soporte para conexiones seguras a la API de tiempo de ejecución de HAProxy
Múltiples opciones de transporte: Admite transportes stdio y HTTP para flexibilidad en diferentes entornos
Listo para empresas: Diseñado para uso en producción en entornos empresariales
Soporte para Docker: Imágenes de Docker preconstruidas para una implementación fácil

Instalación

Homebrew

# Add the tap
brew tap tuannvm/tap

# Install the package
brew install haproxy-mcp-server

Desde binario

Descargue el último binario para su plataforma desde la página de versiones.

Usando Go

go install github.com/tuannvm/haproxy-mcp-server/cmd/server@latest

Usando Docker

docker pull ghcr.io/tuannvm/haproxy-mcp-server:latest
docker run -it --rm \
  -e HAPROXY_HOST=your-haproxy-host \
  -e HAPROXY_PORT=9999 \
  ghcr.io/tuannvm/haproxy-mcp-server:latest

Integración con MCP

Para usar este servidor con LLM compatibles con MCP, configure el asistente con los siguientes detalles de conexión:

API de tiempo de ejecución de HAProxy sobre TCP4:

{
  "mcpServers": {
    "haproxy": {
      "command": "haproxy-mcp-server",
      "env": {
        "HAPROXY_HOST": "localhost",
        "HAPROXY_PORT": "9999",
        "HAPROXY_RUNTIME_MODE": "tcp4",
        "HAPROXY_RUNTIME_TIMEOUT": "10",
        "MCP_TRANSPORT": "stdio"
      }
    }
  }
}

API de tiempo de ejecución de HAProxy sobre socket Unix:

{
  "mcpServers": {
    "haproxy": {
      "command": "haproxy-mcp-server",
      "env": {
        "HAPROXY_RUNTIME_MODE": "unix",
        "HAPROXY_RUNTIME_SOCKET": "/var/run/haproxy/admin.sock",
        "HAPROXY_RUNTIME_TIMEOUT": "10",
        "MCP_TRANSPORT": "stdio"
      }
    }
  }
}

HAProxy con soporte de página de estadísticas:

{
  "mcpServers": {
    "haproxy": {
      "command": "haproxy-mcp-server",
      "env": {
        "HAPROXY_STATS_ENABLED": "true",
        "HAPROXY_STATS_URL": "http://localhost:8404/stats",
        "HAPROXY_STATS_TIMEOUT": "5",
        "MCP_TRANSPORT": "stdio"
      }
    }
  }
}

Cuando se utiliza solo la funcionalidad de la página de estadísticas, no es necesario definir parámetros de la API de tiempo de ejecución como host y puerto. Puede usar tanto la API de tiempo de ejecución como la página de estadísticas simultáneamente para capacidades complementarias, o usar solo una de ellas según las restricciones de su entorno.

Nota: Para obtener instrucciones detalladas sobre cómo configurar HAProxy para exponer la API de tiempo de ejecución y la página de estadísticas, consulte la Guía de configuración de HAProxy.

Herramientas MCP disponibles

El servidor MCP de HAProxy expone herramientas que se asignan directamente a los comandos de la API de tiempo de ejecución de HAProxy, organizadas en las siguientes categorías:

Estadísticas e información del proceso: Recupere estadísticas, información del servidor y gestione contadores
Descubrimiento de topología: Liste frontends, backends, estados de servidores y detalles de configuración
Gestión dinámica de grupos: Agregue, elimine, habilite/deshabilite servidores y ajuste sus propiedades
Control de sesiones: Vea y gestione sesiones activas
Mapas y ACL: Gestione mapas de HAProxy y archivos ACL
Verificaciones de salud y agentes: Controle verificaciones de salud y monitoreo basado en agentes
Varios: Vea errores, ejecute pruebas de eco y obtenga información de ayuda

Para obtener una lista completa de todas las herramientas compatibles con sus entradas, salidas y comandos correspondientes de la API de tiempo de ejecución de HAProxy, consulte la documentación tools.md.

Configuración

El servidor se puede configurar usando las siguientes variables de entorno:

Variable	Descripción	Predeterminado
HAPROXY_HOST	Host de la instancia de HAProxy (solo modo TCP4)	127.0.0.1
HAPROXY_PORT	Puerto para la API de tiempo de ejecución de HAProxy (solo modo TCP4)	9999
HAPROXY_RUNTIME_MODE	Modo de conexión: "tcp4" o "unix"	tcp4
HAPROXY_RUNTIME_SOCKET	Ruta del socket (solo modo Unix)	/var/run/haproxy/admin.sock
HAPROXY_RUNTIME_URL	URL directa a la API de tiempo de ejecución (opcional, anula otras configuraciones de tiempo de ejecución)
HAPROXY_RUNTIME_TIMEOUT	Tiempo de espera para operaciones de la API de tiempo de ejecución en segundos	10
HAPROXY_STATS_ENABLED	Habilitar soporte de página de estadísticas de HAProxy	true
HAPROXY_STATS_URL	URL de la página de estadísticas de HAProxy (p. ej., http://localhost:8404/stats)	http://127.0.0.1:8404/stats
HAPROXY_STATS_TIMEOUT	Tiempo de espera para operaciones de la página de estadísticas en segundos	5
MCP_TRANSPORT	Método de transporte MCP (stdio/http)	stdio
MCP_PORT	Puerto para transporte HTTP (cuando se usa http)	8080
LOG_LEVEL	Nivel de registro (debug/info/warn/error)	info

Nota: Puede usar la API de tiempo de ejecución (modo TCP4 o socket Unix), la API de estadísticas, o ambas simultáneamente. Al menos una debe estar configurada correctamente para que el servidor funcione.

Consideraciones de seguridad

Autenticación: Conéctese a la API de tiempo de ejecución de HAProxy usando métodos seguros
Seguridad de red: Cuando use el modo TCP4, restrinja la conectividad al puerto de la API de tiempo de ejecución
Permisos del socket Unix: Cuando use el modo de socket Unix, asegure los permisos adecuados del archivo de socket
Validación de entradas: Todas las entradas se validan para prevenir ataques de inyección

Para obtener prácticas recomendadas integrales de seguridad y ejemplos de configuración, consulte la Guía de configuración de HAProxy.

Desarrollo

Pruebas

# Run all tests
go test ./...

# Run tests excluding integration tests
go test -short ./...

# Run integration tests with specific HAProxy instance
export HAPROXY_HOST="your-haproxy-host"
export HAPROXY_PORT="9999"
go test ./internal/haproxy -v -run Test

Puede probar el servidor MCP de HAProxy localmente de varias maneras:

Pruebas directas de CLI

Compile y ejecute el servidor directamente con variables de entorno:

# Build the server
go build -o bin/haproxy-mcp-server cmd/server/main.go

# Option 1: Test with TCP connection mode
HAPROXY_HOST=<your-haproxy-host> HAPROXY_PORT=9999 HAPROXY_RUNTIME_MODE=tcp4 HAPROXY_RUNTIME_TIMEOUT=10 LOG_LEVEL=debug MCP_TRANSPORT=stdio ./bin/haproxy-mcp-server

# Option 2: Test with Unix socket mode
HAPROXY_RUNTIME_MODE=unix HAPROXY_RUNTIME_SOCKET=/path/to/haproxy.sock HAPROXY_RUNTIME_TIMEOUT=10 LOG_LEVEL=debug MCP_TRANSPORT=stdio ./bin/haproxy-mcp-server

# Option 3: Test with Stats page integration
HAPROXY_STATS_ENABLED=true HAPROXY_STATS_URL="http://localhost:8404/stats" HAPROXY_STATS_TIMEOUT=5 LOG_LEVEL=debug MCP_TRANSPORT=stdio ./bin/haproxy-mcp-server

# Option 4: Test with both Runtime API and Stats page
HAPROXY_HOST=<your-haproxy-host> HAPROXY_PORT=9999 HAPROXY_RUNTIME_MODE=tcp4 HAPROXY_RUNTIME_TIMEOUT=10 HAPROXY_STATS_ENABLED=true HAPROXY_STATS_URL="http://localhost:8404/stats" HAPROXY_STATS_TIMEOUT=5 LOG_LEVEL=debug MCP_TRANSPORT=stdio ./bin/haproxy-mcp-server

Probar herramientas MCP individuales

Puede probar herramientas MCP específicas con llamadas JSON-RPC:

# Test show_info tool
echo '{"jsonrpc":"2.0","id":1,"method":"callTool","params":{"name":"show_info","arguments":{}}}' | HAPROXY_HOST=<your-haproxy-host> HAPROXY_PORT=9999 HAPROXY_RUNTIME_MODE=tcp4 LOG_LEVEL=debug ./bin/haproxy-mcp-server

# Test show_stat tool
echo '{"jsonrpc":"2.0","id":2,"method":"callTool","params":{"name":"show_stat","arguments":{"filter":""}}}' | HAPROXY_HOST=<your-haproxy-host> HAPROXY_PORT=9999 HAPROXY_RUNTIME_MODE=tcp4 LOG_LEVEL=debug ./bin/haproxy-mcp-server

Implementación técnica

El servidor MCP de HAProxy incluye varias mejoras técnicas diseñadas para confiabilidad y robustez:

Operaciones conscientes del contexto: Todas las llamadas a la API admiten tiempos de espera y cancelación basados en contexto, lo que permite la terminación elegante de operaciones de larga duración.
Mecanismos de respaldo: Respaldo automático a socat si la conexión directa falla, asegurando compatibilidad en diferentes implementaciones de HAProxy.
Manejo unificado de sockets: Código común para conexiones de socket TCP y Unix, reduciendo duplicación y mejorando el mantenimiento.
Gestión resiliente de conexiones: Gestión dinámica de búfer para respuestas grandes y limpieza adecuada de recursos con manejo de plazos.
Manejo integral de errores: Manejo estructurado de errores y registro para facilitar la resolución de problemas.

Contribuciones

¡Las contribuciones son bienvenidas! No dude en enviar una Solicitud de extracción.

Licencia

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