# Hermes MCP Server

基于 MCP（Model Context Protocol）的轻量级服务端程序，实现 AI 客户端与 Hermes 消息中间件之间的双向实时通信。

## 架构

```
┌─────────────────┐   Streamable HTTP    ┌──────────────────┐
│  MCP Client     │ ←─────────────────→ │  MCP Server      │
│  (Claude/AI)    │  POST /mcp (请求)     │  (Node.js:9120)  │
│                 │  GET  /mcp (SSE推送)  └────────┬─────────┘
└─────────────────┘  DELETE /mcp (终止)            │
                                          ┌─────────┼─────────┐
                                          │         │         │
                                          ▼         ▼         ▼
                                   ┌────────┐ ┌────────┐ ┌──────┐
                                   │Hermes  │ │SQLite  │ │缓存  │
                                   │HTTP API│ │state.db│ │(内存)│
                                   │:9119   │ │轮询    │ │      │
                                   └────────┘ └────────┘ └──────┘
```

- **MCP 客户端 → MCP Server**：公网 9120 端口，Bearer API Key 认证
- **MCP Server → Hermes**：仅内网 `127.0.0.1:9119`（不走公网）
- **事件推送**：200ms 轮询 Hermes 的 SQLite `state.db`，变化时通过 SSE 推送

## MCP 工具（10 个）

| 工具 | 功能 |
|------|------|
| `conversations_list` | 列出所有活跃会话（支持平台/关键词过滤） |
| `conversation_get` | 获取会话详情 |
| `messages_read` | 读取消息历史 |
| `attachments_fetch` | 获取消息附件 |
| `events_poll` | 轮询新事件 |
| `events_wait` | 长轮询等待事件 |
| `messages_send` | 发送消息到平台 |
| `channels_list` | 列出可用频道 |
| `permissions_list_open` | 列出待审批请求 |
| `permissions_respond` | 响应审批 |

## 资源与提示词

**资源**：
- `hermes://status` — Hermes 运行状态
- `hermes://channels` — 已连接频道列表
- `hermes://sessions` — 活跃会话列表

**提示词**：
- `summarize-conversations` — 总结所有会话状态
- `check-health` — Hermes 健康检查

## 部署

### 1. 环境要求

- Node.js 20+
- Hermes Agent 已安装并运行
- 端口 9120 可用

### 2. 安装

```bash
git clone https://github.com/Swcmb/hermes-mcp-server.git
cd hermes-mcp-server
npm install
```

### 3. 配置

```bash
cp .env.example .env
# 编辑 .env 填写实际值
```

关键配置项：

| 变量 | 说明 | 默认值 |
|------|------|--------|
| `MCP_PORT` | 监听端口 | 9120 |
| `MCP_API_KEY` | API Key（客户端认证用） | 必填 |
| `HERMES_API_URL` | Hermes API 地址 | http://127.0.0.1:9119 |
| `HERMES_GATEWAY_TOKEN` | Hermes Gateway Token | 从 Hermes .env 读取 |
| `HERMES_STATE_DB` | state.db 路径 | /home/admin/.hermes/state.db |
| `MCP_MAX_SESSIONS` | 最大并发会话 | 5 |

### 4. 启动

```bash
# 前台运行
npm start

# 或用 systemd（推荐生产环境）
sudo cp hermes-mcp-server.service /etc/systemd/system/
sudo systemctl daemon-reload
sudo systemctl enable --now hermes-mcp-server
```

### 5. 开放端口

在阿里云安全组中开放 TCP 9120 端口。

## 客户端配置

### Claude Desktop

在 `claude_desktop_config.json` 中添加：

```json
{
  "mcpServers": {
    "hermes": {
      "url": "http://YOUR_SERVER_IP:9120/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY"
      }
    }
  }
}
```

### 其他 MCP 客户端

MCP 端点：`http://YOUR_SERVER_IP:9120/mcp`
认证头：`Authorization: Bearer YOUR_API_KEY`

## 测试

```bash
npm test
```

## 低资源优化

- `--max-old-space-size=256`：限制 Node.js 堆内存 256MB
- `nice -n 19` + `ionice -c 3`：最低 CPU/IO 优先级
- 200ms 轮询 + mtime 短路：state.db 无变化时零开销
- 最大 5 个并发 SSE 会话
- 进程内缓存（60s TTL）减少重复请求

## 恢复

如果服务异常，检查：

```bash
# 服务状态
systemctl status hermes-mcp-server

# 日志
journalctl -u hermes-mcp-server -f

# 手动测试
curl -H "Authorization: Bearer YOUR_KEY" http://127.0.0.1:9120/mcp -X POST \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"test","version":"1.0"}},"id":1}'
```

## License

MIT