# HAProxy MCP Server Project Plan

## Overview

This document outlines the development plan for the `haproxy-mcp-server` Go project, leveraging the `haproxytech/client-native` SDK. The server will follow the Model Context Protocol (MCP) standard, similar to other MCP server implementations.

## Project Goals

* Develop a Go-based MCP server for HAProxy that allows interaction with HAProxy's runtime API
* Provide a standardized way for AI assistants to manage HAProxy configurations
* Support both TCP4 and Unix socket connections to HAProxy
* Ensure enterprise-grade security and reliability

## Key Design Principles

1. **API Focus**: The server will strictly interact with HAProxy through the Runtime API only.
2. **Standard Logging**: The project will use Go's standard library `log/slog` for logging.
3. **Configuration Flexibility**: Support for both TCP4 and Unix socket connections to HAProxy.
4. **Security**: Implement secure handling of connections and proper input validation.

## Core Components

### 1. Project Structure

The project will follow a standard Go project layout:

* `cmd/server`: Entry point for the application
* `internal/haproxy`: HAProxy client wrapper and implementation
* `internal/mcp/tools`: MCP tool definitions and implementations
* `internal/config`: Configuration management

### 2. HAProxy Client Wrapper

A client wrapper will abstract the HAProxy Runtime API communications:

* Support for both TCP4 connections and Unix socket access
* Error handling and retry mechanisms
* Method wrappers for all needed Runtime API operations

### 3. MCP Tools Implementation

MCP tools will expose HAProxy operations through the Model Context Protocol:

#### 3.1 Statistics & Process Info

* Runtime statistics retrieval
* Version and process information
* Counters management

#### 3.2 Topology Discovery

* Frontend, backend, and server discovery
* Configuration exploration
* Map and table inspection

#### 3.3 Dynamic Pool Management

* Server addition and removal
* Server enabling and disabling
* Weight and connection limit adjustments

#### 3.4 Session Control

* Session listing and management
* Session termination capabilities

#### 3.5 Maps & ACLs

* Map file management
* ACL list operations

#### 3.6 Health Checks & Agents

* Health check control
* Agent-based monitoring configuration

#### 3.7 Miscellaneous

* Error reporting
* Echo testing
* Help documentation

### 4. Server Implementation

The MCP server will handle the protocol communications:

* Support for both stdio and HTTP transports
* Tool registration and dispatch
* Error handling and logging

### 5. Configuration

Configuration will be handled through environment variables:

* `HAPROXY_HOST`: Host of the HAProxy instance
* `HAPROXY_PORT`: Port for the HAProxy Runtime API
* `HAPROXY_RUNTIME_MODE`: "tcp4" or "unix"
* `HAPROXY_RUNTIME_SOCKET`: Unix socket path
* `MCP_TRANSPORT`: Transport method (stdio/http)
* `MCP_PORT`: HTTP port for server
* `LOG_LEVEL`: Logging verbosity

### 6. Build and Packaging

The project will include:

* Makefile for common development operations
* Docker support for containerized deployment
* CI/CD configuration for automated builds and testing

### 7. Testing Strategy

Testing will focus on:

* Unit tests for all components
* Integration tests for the HAProxy client
* End-to-end tests for the MCP server

### 8. Documentation

Documentation will include:

* README with installation and usage instructions
* Configuration documentation
* MCP tools reference
* Integration examples

### 9. CI/CD Pipeline

The CI/CD pipeline will automate:

* Code linting and testing
* Security scanning
* Binary builds for multiple platforms
* Docker image building and publishing
* Release management

## Release Strategy

The project will follow semantic versioning, with releases published to:

* GitHub Releases
* Docker Hub/GitHub Container Registry
* Homebrew tap


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.tuannvm.com/haproxy-mcp-server/plan.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.