# hermes-platform-mcp

A thin **MCP bridge** that connects **Hermes Agent** (Nous Research) to the
**Hermes Intelligence Platform** learning API (`/api/v1/agent/*`). It owns no
data — every tool call is forwarded over HTTP to the platform.

## Why this exists

The Signal Scout cron agents used to only `write_file` markdown briefs into the
vault and read **nothing** back at runtime. This bridge gives agents
first-class tools to **pull the live learning loop** (context pack, feedback,
examples, memory), **push structured findings** (`signal_submit`,
`memory_save`), and **answer questions about platform data** (`signals_get`,
`briefs_get`, `analytics_get`) — the last three power the platform's `/chat`.

## Where this fits

```mermaid
flowchart LR
    Gw["Hermes Gateway :8642\n(always-on)"] -->|"spawns per session\n(3 mcp_servers entries)"| Bridge
    Cron["Cron jobs\n(Reddit / X scouts)"] -.->|via gateway| Gw
    subgraph Bridge["hermes-platform-mcp (this repo)"]
        Srv["server.mjs\none stdio process per session"]
    end
    Bridge -->|"HTTP, Bearer hip_...\n/api/v1/agent/*"| Platform["Hermes Intelligence Platform\n:3050"]

    classDef gateway fill:#AB47BC,stroke:#6A1B9A,color:#ffffff,stroke-width:2px;
    classDef bridge fill:#26A69A,stroke:#00695C,color:#ffffff,stroke-width:2px;
    classDef platform fill:#42A5F5,stroke:#1565C0,color:#ffffff,stroke-width:2px;
    classDef agent fill:#7E57C2,stroke:#4527A0,color:#ffffff,stroke-width:2px;

    class Gw gateway;
    class Srv bridge;
    class Platform platform;
    class Cron agent;
```

It owns no state and runs no daemon: every process is spawned fresh, bound to
one agent identity for its lifetime, and torn down when the session ends.

## Transport & auth model

**stdio.** Hermes Agent spawns one `node server.mjs` process per session and
tears it down when the session ends — there is no standing daemon. Because
stdio has no per-request headers, each process is bound to **one** agent
identity via env vars:

- `HIP_API_KEY` — the agent's `hip_` key (forwarded as the platform bearer;
  the platform resolves identity + per-agent scoping from it). **Required.**
- `HIP_PLATFORM` — default platform slug (`reddit` / `x`) so tool calls can
  omit it.
- `HIP_BASE_URL` — platform base URL (default `http://localhost:3050`).

So two agents = two `mcp_servers` entries, each launching the server with its
own key (see `hermes-config-snippet.yaml`).

## Tools

| Tool | Loop stage | Maps to |
|------|-----------|---------|
| `ping` | — | `GET /ping` |
| `context_pack_get` | **read** | `GET /context-pack` |
| `feedback_get` | **read** | `GET /feedback` |
| `examples_get` | **read** | `GET /examples` |
| `memory_search` | **read** | `GET /memory` |
| `signals_get` | **read** | `GET /signals` |
| `briefs_get` | **read** | `GET /briefs` |
| `analytics_get` | **read** | `GET /analytics` |
| `memory_save` | **write** | `POST /memory` |
| `signal_submit` | **write** | `POST /signals` |
| `brief_submit` | **write** | `POST /briefs` |
| `signal_status_update` | **write** | `PATCH /signals` |

Each `mcp_servers` entry picks its subset via `tools.include` — the chat entry
(`hermes_platform`) gets reads + `memory_save` + `signal_status_update`; the
scout entries (`hermes_reddit`, `hermes_x`) get reads + `signal_submit` +
`memory_save`.

### A tool call, end to end

```mermaid
%%{init: {'theme':'base', 'themeVariables': {'primaryColor':'#42A5F5','primaryTextColor':'#ffffff','primaryBorderColor':'#1565C0','lineColor':'#5C6BC0','secondaryColor':'#AB47BC','secondaryTextColor':'#ffffff','secondaryBorderColor':'#6A1B9A','tertiaryColor':'#FFCA28','tertiaryTextColor':'#000000','tertiaryBorderColor':'#F57F17','actorBkg':'#42A5F5','actorBorder':'#1565C0','actorTextColor':'#ffffff','actorLineColor':'#5C6BC0','signalColor':'#333333','signalTextColor':'#000000','labelBoxBkgColor':'#FFCA28','labelBoxBorderColor':'#F57F17','labelTextColor':'#000000','noteBkgColor':'#FFF59D','noteBorderColor':'#F9A825','noteTextColor':'#000000','activationBorderColor':'#26A69A','activationBkgColor':'#B2DFDB','sequenceNumberColor':'#000000'}}}%%
sequenceDiagram
    participant Ag as Hermes Agent
    participant Sv as server.mjs (this process)
    participant Pl as Platform :3050

    Ag->>Sv: call tool "signal_submit" {title, external_url, pain_md, ...}
    Sv->>Sv: platformFetch(): attach Bearer HIP_API_KEY,\ndefault platform to HIP_PLATFORM
    Sv->>Pl: POST /api/v1/agent/signals\n(15s timeout via AbortSignal)
    Pl-->>Sv: 201 {id, deduped}
    Sv-->>Ag: tool result (raw JSON passed through)
```

No business logic lives here — `platformFetch()` is the only moving part,
shared by all 12 tools.

## Run (manual debugging only)

Hermes launches this itself; you only run it by hand to test. It speaks MCP
over stdin/stdout, so drive it by piping JSON-RPC frames:

```bash
HIP_API_KEY=hip_r_... HIP_PLATFORM=reddit ./run.sh   # then type/pipe MCP frames
```

The old always-on HTTP service (port 3060) and the `hermes-platform-mcp.service`
systemd unit are no longer needed under stdio.

## Connect Hermes Agent

Three stdio entries are live in `~/.hermes/config.yaml` under `mcp_servers:`
(keys in `~/.hermes/.env`): `hermes_reddit` (`HIP_REDDIT_KEY`), `hermes_x`
(`HIP_X_KEY`), and `hermes_platform` (`HIP_CHAT_KEY`, cross-platform, used by
the platform's `/chat`). After config changes: `/reload-mcp` inside Hermes or
`systemctl --user reload hermes-gateway`. Tools appear as
`mcp_hermes_reddit_*` / `mcp_hermes_x_*` / `mcp_hermes_platform_*`.