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. 安装

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

3. 配置

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. 启动

# 前台运行
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 中添加：

{
  "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

测试

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）减少重复请求

恢复

如果服务异常，检查：

# 服务状态
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