HiveMQ Pulse MCP Server

FastMCP-based MCP server for interacting with the HiveMQ Pulse REST API. Built for hackathon speed and debuggability.

Architecture

• Mock API Server: Flask-based mock API server (port 9000)
• MCP Server: FastMCP server exposing HiveMQ Pulse API tools (port 8000)
• Both run in Docker containers orchestrated via docker-compose

Quick Start

1. Build and Run with Docker Compose

docker-compose up --build

This will start:

• Mock API on http://localhost:9000
• MCP Server on http://localhost:8000

1.5. Verify Everything is Working

# Run health check
./health_check.sh

# Run automated tests
./run_tests.sh

2. Connect from Claude Desktop

For Claude Desktop, you'll use the MCP Connectors feature to connect to the containerized server.

Add to your Claude Desktop config (~/Library/Application Support/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "hivemq-pulse": {
      "command": "docker",
      "args": [
        "exec",
        "-i",
        "pulse-mcp-server",
        "python",
        "server.py"
      ]
    }
  }
}

Note: The MCP server must be running (docker-compose up) before Claude Desktop can connect.

3. Test the Mock API Directly

# Test mock API
curl http://localhost:9000/api/v1/projects

# Check logs
docker-compose logs -f mock-api
docker-compose logs -f mcp-server

Available MCP Tools

The server exposes these tools to Claude:

Project Management

• get_projects() - Get all projects
• create_project(name, description) - Create a new project
• get_project(project_id) - Get project details

Namespace & Node Operations

• search_namespace_nodes(project_id, search_term) - Search for nodes by name
• get_namespace_node(project_id, node_id) - Get details of a specific node
• get_node_relations(project_id, node_id) - Get parent and child relationships
• get_namespace_children(project_id, node_id) - Get child nodes (omit node_id for root)

Configuration

Environment Variables

• PULSE_API_BASE_URL - Base URL for the Pulse API (default: http://mock-api:9000/api)
• PULSE_USERNAME - Username for authentication (default: pulse)
• PULSE_PASSWORD - Password for authentication (default: verde)

Authentication

The MCP server automatically authenticates with the Pulse API using username/password credentials. Authentication is handled transparently - you just need to configure credentials.

Default credentials (for mock API):

• Username: pulse
• Password: verde

For detailed authentication setup and troubleshooting, see AUTHENTICATION.md.

Switching to Real API

Create a .env file:

cp .env.example .env

Edit .env with your real API credentials:

PULSE_API_BASE_URL=https://your-pulse-instance.com/api
PULSE_USERNAME=your-username
PULSE_PASSWORD=your-password

Then restart:

docker-compose down
docker-compose up -d --build

Development

Local Testing (without Docker)

# Terminal 1: Start mock API
cd mock-api
pip install -r requirements.txt
python mock_server.py

# Terminal 2: Start MCP server
cd mcp_server
pip install -r requirements.txt
export PULSE_API_BASE_URL=http://localhost:9000/api
python server.py

Adding New Tools

Edit mcp_server/server.py and add new tool functions:

@mcp.tool()
async def your_new_tool(param: str) -> dict:
    """Tool description"""
    async with httpx.AsyncClient(base_url=API_BASE_URL, timeout=30.0) as client:
        response = await client.get(f"/v1/your/endpoint")
        return response.json()

Debugging

The MCP server includes comprehensive instrumentation with emoji-prefixed logs for easy debugging:

# Quick health check
./health_check.sh

# View all logs with detailed instrumentation
docker logs -f pulse-mcp-server

# Filter for errors only
docker logs pulse-mcp-server | grep "✗"

# Track authentication flow
docker logs pulse-mcp-server | grep AUTH

# Watch specific tool execution
docker logs pulse-mcp-server | grep "TOOL:get_projects"

# Check mock API requests
docker logs -f pulse-mock-api

Log Categories:

• 🔐 [AUTH] - Authentication operations
• 📡 [CLIENT] - HTTP client creation
• 🔧 [TOOL:*] - Tool execution (with endpoint, status, response)
• ✓ - Success indicators
• ✗ - Error indicators

See CLAUDE.md for complete debugging guide.

Testing

# Run all tests (unit + integration)
./run_tests.sh

# Run only unit tests
pytest tests/test_mcp_server.py -v

# Run only integration tests
python3 tests/integration_test.py

Test Coverage:

• ✅ Authentication flow (valid/invalid credentials, cookie handling)
• ✅ All MCP tools (15+ test cases)
• ✅ Error handling and edge cases
• ✅ End-to-end API workflows

See tests/README.md for detailed testing documentation.

Project Structure

.
├── docker-compose.yml          # Container orchestration
├── health_check.sh             # Quick system health check
├── run_tests.sh                # Test runner (unit + integration)
├── CLAUDE.md                   # AI assistant documentation
├── FIXES_AND_IMPROVEMENTS.md   # Change log and improvements
├── mcp_server/                 # FastMCP server
│   ├── Dockerfile
│   ├── requirements.txt
│   └── server.py               # Main server with instrumentation
├── mock-api/                   # Mock API server
│   ├── Dockerfile
│   ├── requirements.txt
│   ├── mock_server.py
│   └── README.md
├── tests/                      # Automated test suite
│   ├── __init__.py
│   ├── test_mcp_server.py      # Unit tests
│   ├── integration_test.py     # Integration tests
│   ├── requirements.txt
│   └── README.md
└── openapi.yml                 # HiveMQ Pulse API spec

Troubleshooting

Claude Desktop can't connect

1. Ensure containers are running: docker ps
2. Check MCP server logs: docker-compose logs mcp-server
3. Verify the container name is correct: pulse-mcp-server

API calls failing

1. Check if mock-api is accessible from mcp-server:

   docker exec pulse-mcp-server curl http://mock-api:9000/api/v1/projects
   

2. Review docker network: docker network inspect fastmcp_pulse_pulse-network

Next Steps

• Add authentication support
• Implement more API endpoints as tools
• Add response validation
• Switch to real API endpoint when available