# hermes-mcp

An MCP server for controlling a Hermes agent deployment over its HTTP API —
from Claude Code, Claude Desktop, or any other MCP client.

It exposes the four things you actually do to a running agent: check on it,
read its logs, give it work, and deploy or reconfigure it.

## Status

The tool surface, transport, auth, and error handling are complete and tested.
**The endpoint paths are conventional defaults and have not been verified
against a live Hermes deployment.** You should not have to fix them by hand —
run `hermes-mcp doctor` and it will work out the real ones and print the
overrides to paste. See [Pointing it at your deployment](#pointing-it-at-your-deployment).

## Install

Requires Python 3.10+ and [uv](https://docs.astral.sh/uv/).

```bash
git clone git@github.com:Stratfiy/hermes-mcp.git
cd hermes-mcp
uv sync
```

## Configure

Only `HERMES_BASE_URL` is required.

| Variable | Default | What it does |
| --- | --- | --- |
| `HERMES_BASE_URL` | — | **Required.** Root URL of the deployment, e.g. `https://hermes.example.com`. |
| `HERMES_API_KEY` | — | Credential. Setting it alone turns on bearer auth. |
| `HERMES_AUTH_STYLE` | `bearer` when a key is set, else `none` | `bearer`, `header`, `query`, or `none`. |
| `HERMES_API_KEY_HEADER` | `X-API-Key` | Header (or query parameter) name when style is `header`/`query`. |
| `HERMES_EXTRA_HEADERS` | — | Static headers, `Name: value` per line. Useful for Cloudflare Access. |
| `HERMES_TIMEOUT` | `30` | Per-request timeout in seconds. |
| `HERMES_VERIFY_TLS` | `true` | Set false only for a self-signed staging host. |
| `HERMES_READ_ONLY` | `false` | Blocks every tool that changes the deployment. |
| `HERMES_MAX_RESPONSE_CHARS` | `20000` | Truncation ceiling, so a log dump can't swamp the context window. |
| `HERMES_MCP_TRANSPORT` | `stdio` | `stdio`, `http`, or `sse`. |
| `HERMES_ROUTES_FILE` | — | JSON file of route overrides. |
| `HERMES_ROUTE_<NAME>` | — | Override one route, e.g. `HERMES_ROUTE_STATUS="GET /v1/state"`. |

## Pointing it at your deployment

Set the URL and credential, then let it work the rest out:

```bash
export HERMES_BASE_URL=https://hermes.example.com
export HERMES_API_KEY=your-token

uv run hermes-mcp doctor
```

`doctor` checks the host is reachable, checks your credentials are accepted,
reads the deployment's OpenAPI schema, and compares every route it intends to
call against what the deployment actually publishes. Output looks like:

```
Route check
-----------
[  ok  ] Matched against the deployment's OpenAPI schema.
[ warn ] not found: deploy, metrics, start, stop

Add these to your MCP server config:

  HERMES_ROUTE_STATUS="GET /api/v1/state"
  HERMES_ROUTE_TASK_CREATE="POST /api/v1/jobs"
  HERMES_ROUTE_TASK_GET="GET /api/v1/jobs/{task_id}"
  ...
```

Paste those in and every tool works against your paths. The same thing is
available as the `detect_routes` tool once the server is registered, and
`describe_api` reports it as part of a wider picture.

If the deployment publishes no schema, `detect_routes` falls back to probing
candidate paths — **using GET only**. Discovering `POST /stop` by calling it
would mean stopping your agent to learn that stopping it works, so mutating
routes are never probed and must be set by hand.

## Register with Claude Code

User scope, so it is available in every project:

```bash
claude mcp add --scope user hermes \
  --env HERMES_BASE_URL=https://hermes.example.com \
  --env HERMES_API_KEY=your-token \
  -- uv run --directory /absolute/path/to/hermes-mcp hermes-mcp

claude mcp list   # verify
```

To start read-only while you confirm the routes are right, add
`--env HERMES_READ_ONLY=1`.

## Tools

**Lifecycle** — `health`, `status`, `start`, `stop`, `restart`

**Diagnostics** — `logs` (filter by `lines`, `level`, `since`, `search`),
`metrics`, `describe_api`, `detect_routes`

**Work** — `send_task`, `get_task`, `list_tasks`, `cancel_task`

**Deploy and config** — `deploy`, `get_config`, `set_config`

**Escape hatch** — `request`, for any endpoint the named tools don't model

`stop`, `restart`, `cancel_task`, `deploy`, and `set_config` are annotated
destructive, so clients that surface that hint will ask before running them.

## The route table

Prefer `hermes-mcp doctor` over editing this by hand. The defaults assume
conventional REST paths:

```
GET  /health          GET  /logs         POST /tasks
GET  /status          GET  /metrics      GET  /tasks
POST /start           POST /deploy       GET  /tasks/{task_id}
POST /stop            GET  /config       POST /tasks/{task_id}/cancel
POST /restart         PATCH /config      GET  /openapi.json
```

When your deployment disagrees, override the route rather than editing code.
One at a time:

```bash
export HERMES_ROUTE_TASK_CREATE="POST /agent/jobs"
export HERMES_ROUTE_STATUS="GET /v1/state"
```

Or all at once, with `HERMES_ROUTES_FILE=routes.json`:

```json
{
  "status": "GET /v1/state",
  "logs": "GET /v1/logs",
  "task_create": "POST /agent/jobs",
  "task_get": "GET /agent/jobs/{task_id}"
}
```

A 404 from a tool says so explicitly and points back here.

## Development

```bash
uv run pytest          # tests
uv run ruff check .    # lint
uv run ruff format .   # format
```

No test touches the network — HTTP is mocked with `respx`. CI runs the same
three commands on Python 3.10 and 3.12.

### CLI

```
hermes-mcp          # run the MCP server over stdio (what a client invokes)
hermes-mcp doctor   # check the deployment and print what it found
```