STARWARCLOUD STARWAR.AI
返回市场
HAProxy-MCP服务器

HAProxy-MCP服务器

作者：tuannvm6 星标更新：2025-11-24
安装使用来源：spider==github.com

项目介绍

HAProxy MCP 服务器

构建 发布 Go 报告卡 GitHub 发布 (最新 SemVer) 许可证 Docker 拉取次数

这是一个用 Go 实现的 HAProxy Model Context Protocol (MCP) 服务器，利用了 HAProxy 运行时 API 和 mcp-go。

概述

HAProxy MCP 服务器提供了一种标准化的方式，使大型语言模型（LLMs）能够通过 Model Context Protocol (MCP) 与 HAProxy 的运行时 API 进行交互。这使得 LLMs 能够执行 HAProxy 管理任务，监控服务器状态，管理后端服务器，并分析流量模式，所有这些都可以通过自然语言界面完成。

截图-1 截图-2 截图-3

特性

  • 全面支持 HAProxy 运行时 API：涵盖了 HAProxy 运行时 API 命令的全面覆盖
  • 上下文感知操作：所有操作都支持适当的超时和取消处理
  • 统计页面集成：支持 HAProxy 的基于 Web 的统计页面，以增强指标和可视化效果
  • 安全认证：支持与 HAProxy 运行时 API 的安全连接
  • 多种传输选项：支持 stdio 和 HTTP 传输，以适应不同环境的灵活性
  • 企业就绪：设计用于企业环境中的生产使用
  • Docker 支持：预构建的 Docker 镜像，便于部署

安装

Homebrew

# 添加 tap
brew tap tuannvm/tap

# 安装包
brew install haproxy-mcp-server

从二进制文件安装

从 发布页面 下载适用于您平台的最新二进制文件。

使用 Go 安装

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

使用 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

MCP 集成

要将此服务器与兼容 MCP 的 LLMs 结合使用，请使用以下连接详情配置助手：

HAProxy 运行时 API 通过 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"
      }
    }
  }
}

HAProxy 运行时 API 通过 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 支持统计页面：

{
  "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"
      }
    }
  }
}

仅使用统计页面功能时，无需定义运行时 API 参数如主机和端口。您可以同时使用运行时 API 和统计页面以获得互补能力，或者根据您的环境限制选择其中一个。

注意：有关如何配置 HAProxy 以暴露运行时 API 和统计页面的详细说明，请参阅 HAProxy 配置指南。

可用的 MCP 工具

HAProxy MCP 服务器提供了直接映射到 HAProxy 运行时 API 命令的工具，这些工具被组织成以下类别：

  • 统计信息及进程信息：获取统计信息、服务器信息并管理计数器
  • 拓扑发现：列出前端、后端、服务器状态和配置细节
  • 动态池管理：添加、移除、启用/禁用服务器并调整其属性
  • 会话控制：查看和管理活动会话
  • 映射及 ACL：管理 HAProxy 映射和 ACL 文件
  • 健康检查及代理：控制健康检查和基于代理的监控
  • 杂项：查看错误、运行回声测试并获取帮助信息

有关所有支持工具及其输入、输出和对应的 HAProxy 运行时 API 命令的完整列表，请参阅 tools.md 文档。

配置

服务器可以通过以下环境变量进行配置：

变量描述默认值
HAPROXY_HOSTHAProxy 实例的主机（仅限 TCP4 模式）127.0.0.1
HAPROXY_PORTHAProxy 运行时 API 的端口（仅限 TCP4 模式）9999
HAPROXY_RUNTIME_MODE连接模式："tcp4" 或 "unix"tcp4
HAPROXY_RUNTIME_SOCKET套接字路径（仅限 Unix 模式）/var/run/haproxy/admin.sock
HAPROXY_RUNTIME_URL运行时 API 的直接 URL（可选，覆盖其他运行时设置）
HAPROXY_RUNTIME_TIMEOUT运行时 API 操作的超时时间（秒）10
HAPROXY_STATS_ENABLED启用 HAProxy 统计页面支持true
HAPROXY_STATS_URLHAProxy 统计页面的 URL（例如，http://localhost:8404/stats）http://127.0.0.1:8404/stats
HAPROXY_STATS_TIMEOUT统计页面操作的超时时间（秒）5
MCP_TRANSPORTMCP 传输方法（stdio/http）stdio
MCP_PORTHTTP 传输的端口（当使用 http 时）8080
LOG_LEVEL日志级别（debug/info/warn/error）info

注意：您可以使用运行时 API（TCP4 或 Unix 套接字模式）、统计 API 或两者同时使用。至少需要正确配置一个以使服务器正常工作。

安全注意事项

  • 认证：使用安全方法连接到 HAProxy 的运行时 API
  • 网络安全：在使用 TCP4 模式时，限制对运行时 API 端口的访问
  • Unix 套接字权限：在使用 Unix 套接字模式时，确保正确的套接字文件权限
  • 输入验证：验证所有输入以防止注入攻击

有关全面的安全最佳实践和配置示例，请参阅 HAProxy 配置指南。

开发

测试

# 运行所有测试
go test ./...

# 运行排除集成测试的测试
go test -short ./...

# 使用特定 HAProxy 实例运行集成测试
export HAPROXY_HOST="your-haproxy-host"
export HAPROXY_PORT="9999"
go test ./internal/haproxy -v -run Test

您可以在本地以几种方式测试 HAProxy MCP 服务器：

直接 CLI 测试

使用环境变量直接构建并运行服务器：

# 构建服务器
go build -o bin/haproxy-mcp-server cmd/server/main.go

# 方案 1：使用 TCP 连接模式测试
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

# 方案 2：使用 Unix 套接字模式测试
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

# 方案 3：使用统计页面集成测试
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

# 方案 4：使用运行时 API 和统计页面同时测试
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

测试单个 MCP 工具

您可以使用 JSON-RPC 调用来测试特定的 MCP 工具：

# 测试 show_info 工具
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

# 测试 show_stat 工具
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

技术实现

HAProxy MCP 服务器包括了几项旨在提高可靠性和健壮性的技术改进：

  • 上下文感知操作：所有 API 调用都支持基于上下文的超时和取消，允许优雅地终止长时间运行的操作。
  • 自动回退机制：如果直接连接失败，自动回退到 socat，确保跨不同 HAProxy 部署的兼容性。
  • 统一套接字处理：针对 TCP 和 Unix 套接字连接的通用代码，减少重复并提高可维护性。
  • 弹性连接管理：动态缓冲区管理以应对大响应，并通过截止时间处理进行适当的资源清理。
  • 全面的错误处理：结构化的错误处理和日志记录，便于故障排查。

贡献

欢迎贡献！请随时提交 Pull Request。

许可证

本项目采用 MIT 许可证 - 详情见 LICENSE 文件。