HAProxy MCP Server

Interaja com a API de runtime do HAProxy para administração, monitoramento e análise de tráfego.

Documentação

Servidor MCP HAProxy

GitHub release (latest SemVer) License Docker Pulls

Um servidor Model Context Protocol (MCP) para HAProxy implementado em Go, utilizando a HAProxy Runtime API e mcp-go.

Visão Geral

O Servidor MCP HAProxy fornece uma forma padronizada para LLMs interagirem com a API de runtime do HAProxy através do Model Context Protocol (MCP). Isso permite que LLMs executem tarefas de administração do HAProxy, monitorem o status dos servidores, gerenciem servidores de backend e analisem padrões de tráfego, tudo por meio de interfaces em linguagem natural.

Screenshot-1 Screenshot-2 Screenshot-3

Recursos

Suporte Completo à API de Runtime do HAProxy: Cobertura abrangente dos comandos da API de runtime do HAProxy
Operações Sensíveis ao Contexto: Todas as operações suportam tratamento adequado de timeout e cancelamento
Integração com Página de Estatísticas: Suporte à página de estatísticas baseada na web do HAProxy para métricas aprimoradas e visualização
Autenticação Segura: Suporte a conexões seguras com a API de runtime do HAProxy
Múltiplas Opções de Transporte: Suporta transportes stdio e HTTP para flexibilidade em diferentes ambientes
Pronto para Empresas: Projetado para uso em produção em ambientes empresariais
Suporte a Docker: Imagens Docker pré-construídas para implantação facilitada

Instalação

Homebrew

# Add the tap
brew tap tuannvm/tap

# Install the package
brew install haproxy-mcp-server

A partir do Binário

Baixe o binário mais recente para sua plataforma na página de releases.

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

Integração MCP

Para usar este servidor com LLMs compatíveis com MCP, configure o assistente com os seguintes detalhes de conexão:

API de Runtime do HAProxy via 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 Runtime do HAProxy via 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 com Suporte à Página de Estatí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"
      }
    }
  }
}

Ao usar apenas a funcionalidade da página de estatísticas, não é necessário definir parâmetros da API de Runtime como host e porta. Você pode usar tanto a API de Runtime quanto a Página de Estatísticas simultaneamente para capacidades complementares, ou usar apenas uma delas com base nas restrições do seu ambiente.

Nota: Para instruções detalhadas sobre como configurar o HAProxy para expor a API de Runtime e a página de Estatísticas, consulte o Guia de Configuração do HAProxy.

Ferramentas MCP Disponíveis

O Servidor MCP HAProxy expõe ferramentas que mapeiam diretamente para os comandos da API de Runtime do HAProxy, organizadas nas seguintes categorias:

Estatísticas e Informações do Processo: Recuperar estatísticas, informações de servidores e gerenciar contadores
Descoberta de Topologia: Listar frontends, backends, estados de servidores e detalhes de configuração
Gerenciamento Dinâmico de Pool: Adicionar, remover, habilitar/desabilitar servidores e ajustar suas propriedades
Controle de Sessões: Visualizar e gerenciar sessões ativas
Mapas e ACLs: Gerenciar mapas e arquivos ACL do HAProxy
Verificações de Saúde e Agentes: Controlar verificações de saúde e monitoramento baseado em agentes
Diversos: Visualizar erros, executar testes de eco e obter informações de ajuda

Para uma lista completa de todas as ferramentas suportadas com suas entradas, saídas e comandos correspondentes da API de Runtime do HAProxy, consulte a documentação tools.md.

Configuração

O servidor pode ser configurado usando as seguintes variáveis de ambiente:

Variável	Descrição	Padrão
HAPROXY_HOST	Host da instância HAProxy (somente modo TCP4)	127.0.0.1
HAPROXY_PORT	Porta para a API de Runtime do HAProxy (somente modo TCP4)	9999
HAPROXY_RUNTIME_MODE	Modo de conexão: "tcp4" ou "unix"	tcp4
HAPROXY_RUNTIME_SOCKET	Caminho do socket (somente modo Unix)	/var/run/haproxy/admin.sock
HAPROXY_RUNTIME_URL	URL direta para a API de Runtime (opcional, substitui outras configurações de runtime)
HAPROXY_RUNTIME_TIMEOUT	Timeout para operações da API de runtime em segundos	10
HAPROXY_STATS_ENABLED	Habilitar suporte à página de estatísticas do HAProxy	true
HAPROXY_STATS_URL	URL para a página de estatísticas do HAProxy (ex.: http://localhost:8404/stats)	http://127.0.0.1:8404/stats
HAPROXY_STATS_TIMEOUT	Timeout para operações da página de estatísticas em segundos	5
MCP_TRANSPORT	Método de transporte MCP (stdio/http)	stdio
MCP_PORT	Porta para transporte HTTP (ao usar http)	8080
LOG_LEVEL	Nível de registro (debug/info/warn/error)	info

Nota: Você pode usar a API de Runtime (modo TCP4 ou socket Unix), a API de Estatísticas, ou ambas simultaneamente. Pelo menos uma deve estar configurada corretamente para o servidor funcionar.

Considerações de Segurança

Autenticação: Conecte-se à API de Runtime do HAProxy usando métodos seguros
Segurança de Rede: Ao usar o modo TCP4, restrinja a conectividade à porta da API de Runtime
Permissões do Socket Unix: Ao usar o modo socket Unix, garanta permissões adequadas do arquivo de socket
Validação de Entrada: Todas as entradas são validadas para prevenir ataques de injeção

Para práticas recomendadas abrangentes de segurança e exemplos de configuração, consulte o Guia de Configuração do HAProxy.

Desenvolvimento

Testes

# 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

Você pode testar o servidor MCP HAProxy localmente de várias maneiras:

Teste Direto via CLI

Compile e execute o servidor diretamente com variáveis de ambiente:

# 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

Testar Ferramentas MCP Individuais

Você pode testar ferramentas MCP específicas com chamadas 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

Implementação Técnica

O Servidor MCP HAProxy inclui várias melhorias técnicas projetadas para confiabilidade e robustez:

Operações Sensíveis ao Contexto: Todas as chamadas de API suportam timeout e cancelamento baseados em contexto, permitindo a terminação graciosa de operações de longa duração.
Mecanismos de Fallback: Fallback automático para socat se a conexão direta falhar, garantindo compatibilidade em diferentes implantações do HAProxy.
Tratamento Unificado de Sockets: Código comum para conexões TCP e socket Unix, reduzindo duplicação e melhorando a manutenibilidade.
Gerenciamento Resiliente de Conexões: Gerenciamento dinâmico de buffer para respostas grandes e limpeza adequada de recursos com tratamento de prazos.
Tratamento Abrangente de Erros: Tratamento estruturado de erros e registro para facilitar a solução de problemas.

Contribuindo

Contribuições são bem-vindas! Sinta-se à vontade para enviar um Pull Request.

Licença

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