# hermes-fleet-mcp

MCP (Model Context Protocol) server that routes Docker operations across a fleet of Docker hosts via the [Scotty](https://github.com/peterldowns/scotty) API.

## Overview

Provides two MCP tools:

- **`fleet_route`** — Route a Docker operation through Scotty (Arcane MCP → target Docker host).
- **`fleet_hosts`** — List all known Docker hosts in the fleet.

## Quick Start

### Install

```bash
pip install hermes-fleet-mcp
```

Or run from source:

```bash
pip install -e .
```

### Configure

Set environment variables (all optional):

| Variable | Default | Description |
|----------|---------|-------------|
| `SCOTTY_BASE_URL` | `http://127.0.0.1:8644/v1` | Scotty API endpoint |
| `DOCKER_HOSTS` | `["hostinger-01", "oci-01"]` | JSON array of host identifiers |

### Run

```bash
python -m hermes_fleet_mcp
```

The server communicates via stdio JSON-RPC.

## Tool: `fleet_route`

Route a Docker operation through Scotty.

### Parameters

| Parameter | Required | Default | Description |
|-----------|----------|---------|-------------|
| `action` | Yes | — | The Docker operation to perform (e.g. "List all running containers", "Show container logs for nginx") |
| `host` | No | `null` | Target host identifier. Use `"all"` to fan out to all hosts. |
| `params` | No | `{}` | Optional context parameters (passed as additional context to Scotty) |

### Examples

```json
{
  "tool": "fleet_route",
  "arguments": {
    "action": "List all running containers",
    "host": "hostinger-01"
  }
}
```

```json
{
  "tool": "fleet_route",
  "arguments": {
    "action": "Show container logs for plex",
    "host": "all"
  }
}
```

## Tool: `fleet_hosts`

List all known hosts.

```json
{
  "tool": "fleet_hosts",
  "arguments": {}
}
```

## Docker Deployment

```bash
docker build -t hermes-fleet-mcp .
docker run --rm -e SCOTTY_BASE_URL=http://scotty:8644/v1 hermes-fleet-mcp
```

## Hermes Agent Registration

Add to `~/.hermes/profiles/<profile>/config.yaml`:

```yaml
mcp_servers:
  fleet-mcp:
    command: "python"
    args: ["-m", "hermes_fleet_mcp"]
    timeout: 120
    connect_timeout: 15
```

## Architecture

```
MCP Client → hermes-fleet-mcp (stdio)
                ↓ POST /v1/chat/completions
            Scotty (Hermes profile)
                ↓ Arcane MCP
            Target Docker host(s)
```

The server proxies Docker operation requests to Scotty's chat API. Scotty then routes through Arcane MCP to the appropriate Docker host(s). This means the server doesn't need direct Docker access — it delegates to the existing fleet management infrastructure.

## Development

```bash
python3 -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"
```

Run tests:

```bash
python3 tests/test_fleet_mcp.py
```

## License

MIT