# Hermes MCP Bridge

Read-only MCP bridge exposing Hermes gateway tools to ChatGPT via HTTP/SSE.

## Endpoints

- **`/mcp`** — StreamableHTTP (primary, MCP spec standard)
- **`/sse`** — Server-Sent Events (fallback for legacy clients)
- **`/health`** — Health check (no auth)

## Read-Only Tools Exposed

| Tool | Description |
|------|-------------|
| `hermes_status` | Current Hermes agent status |
| `mission_control_summary` | Mission Control dashboard summary |
| `channels_list` | List messaging channels |
| `pending_approvals_list` | List pending approval requests |

**Blocked (never exposed):**
- `messages_send`
- `permissions_respond`
- Any write/execute/create/delete tools

## Local Development

```bash
# Install deps
pip install -r requirements.txt

# Run (requires Hermes gateway at http://127.0.0.1:8642)
PORT=8080 uvicorn app:app --host 0.0.0.0 --port 8080

# Or with custom Hermes URL
HERMES_GATEWAY_URL=http://localhost:8640 PORT=8080 uvicorn app:app --host 0.0.0.0
```

## Environment Variables

| Variable | Default | Description |
|----------|---------|-------------|
| `PORT` | `8080` | Bind port (Zeabur injects this) |
| `HERMES_GATEWAY_URL` | `http://127.0.0.1:8642` | Hermes gateway base URL |
| `MCP_BRIDGE_TOKEN` | *(unset)* | Optional Bearer token for auth |

## Zeabur Deployment

1. Push this repo to Git
2. In Zeabur dashboard: **Add Service → Git Repository**
3. Select this repo
4. **Important**: Disable "Public" toggle (private service)
5. Zeabur auto-detects Python, runs `uvicorn app:app --host 0.0.0.0 --port $PORT`
6. Service gets internal DNS: `http://hermes-mcp-bridge:8080`

### Phase 2 Network Note

On Zeabur, each service is a separate container. The bridge **cannot** reach Hermes at `127.0.0.1:8642`.

**Required for Phase 2:** Expose Hermes gateway as an **internal Zeabur Service** (no public toggle) on port 8642, then set:
```
HERMES_GATEWAY_URL=http://hermes-gateway:8642
```
in the bridge service environment.

## Auth

If `MCP_BRIDGE_TOKEN` is set, all `/mcp` and `/sse` requests require:
```
Authorization: Bearer <MCP_BRIDGE_TOKEN>
```

ChatGPT MCP config example:
```json
{
  "mcpServers": {
    "hermes": {
      "url": "https://hermes-mcp-bridge.zeabur.app/mcp",
      "headers": { "Authorization": "Bearer YOUR_TOKEN" }
    }
  }
}
```

## License

Internal tool — not for public distribution.