内容
<p align="center">
<img src="https://img.shields.io/badge/Python-3.11%2B-blue" alt="Python">
<img src="https://img.shields.io/badge/传输方式-stdio-green" alt="传输方式">
<img src="https://img.shields.io/badge/依赖-mcp%20%7C%20httpx%20%7C%20pydantic-lightgrey" alt="依赖">
<img src="https://img.shields.io/badge/许可证-Apache--2.0-yellow" alt="许可证">
</p>
# hermes-mcp-bridge
> 一个零摩擦的stdio MCP桥接器，连接Cursor Desktop到本地Hermes Agent —
> 无需OAuth，无需隧道，无需动态客户端注册。
---
## 1. 架构
```
Cursor Desktop hermes-mcp-bridge Hermes Gateway
┌──────────────┐ stdio ┌─────────────────────┐ HTTP ┌──────────────┐
│ mcp.json │ ─────────→ │ FastMCP │ ───────→ │ 127.0.0.1 │
│ 命令: │ │ ├ hermes_ask() │ Bearer │ :8642 │
│ /home/... │ ←───────── │ ├ hermes_check() │ ←─────── │ /v1/chat/ │
└──────────────┘ stdio │ ├ hermes_cancel() │ JSON │ completions │
│ └ hermes_reset() │ └──────────────┘
└─────────────────────┘
X-Hermes-Session-Id → REPL上下文
```
### 1.1 与mlennie/hermes-mcp的比较
| | `mlennie/hermes-mcp` | `hermes-mcp-bridge` |
| ---------------- | ------------------------ | --------------------: |
| 传输方式 | 流式HTTP | **stdio** |
| 认证 | OAuth 2.1 + DCR | **Bearer头部** |
| 外部依赖 | cloudflared / ngrok | **无** |
| 进程模型 | 独立守护进程 | **Cursor子进程** |
| 部署文件 | 5个配置文件 + systemd单元 | **2个文件** |
---
## 2. 配置文件感知
桥接器连接到与**相同的Hermes配置文件**，您的网关正在提供服务。
它继承了该配置文件加载的所有内容 — 技能、内存、工具、会话。
您可以通过**两种方式**选择要使用的配置文件：
| 方法 | 您需要做的操作 | 何时使用 |
| ---------------------- | ------------------------------------------------------------------------ | -------------------------- |
| **设置默认值** | 编辑`~/.config/hermes-mcp-bridge/config.toml` | 您主要使用一个配置文件 |
| **在聊天中提及** | 在Cursor聊天输入框中说_"使用Hermes与默认配置文件..."_ | 您经常切换配置文件 |
两种方法都不需要触摸`mcp.json`或重启Cursor。
### 2.1 默认配置文件（config.toml）
```toml
# ~/.config/hermes-mcp-bridge/config.toml
model = "general_researcher" # ← 在未传递配置文件参数时使用
```
### 2.2 在Cursor中切换配置文件
`hermes_ask`工具公开了一个可选的`profile`参数。只需提及
您想要的配置文件 — Cursor的LLM读取工具签名并传递它。
```
┌─────────────────────────────────────────────────────────┐
│ 您在Cursor中说 │
├─────────────────────────────────────────────────────────┤
│ "使用Hermes与默认配置文件发送电子邮件" │
│ → hermes_ask(prompt="发送电子邮件", │
│ profile="default") │
│ │
│ "要求Hermes在arXiv上搜索MCP论文" │
│ → hermes_ask(prompt="搜索arXiv...") │
│ # 无配置文件 → 使用config.toml默认值 │
└─────────────────────────────────────────────────────────┘
```
无需更改mcp.json，无需编辑配置文件，无需重启。只需说出配置文件名称。
### 2.3 发现可用配置文件
```bash
curl -s http://127.0.0.1:8642/v1/models \
-H "Authorization: Bearer change...-dev"
# → {"data": [{"id": "general_researcher", ...}, {"id": "default", ...}]}
```
> 如果您的网关只运行一个配置文件，则只会出现一个`id`。在不同的端口上启动其他网关实例，以同时提供多个配置文件。
---
## 3. 为什么存在这个问题
`mlennie/hermes-mcp` v0.4.0 遇到了三个现实世界的障碍：
1. **OAuth 2.1 需要HTTPS隧道** — 即使Cursor和Hermes在同一台机器上运行。
2. **不支持动态客户端注册** — `mcp-remote`崩溃并出现`Incompatible auth server`错误。
3. **Cursor的本地OAuth回调已损坏** — 其内置的MCP HTTP客户端在`localhost`上返回`ERR_EMPTY_RESPONSE`。
此桥接器完全放弃了HTTP传输层，作为一个stdio子进程运行，并绕过了这三个问题。
---
## 4. 快速入门
### 4.1 安装
```bash
git clone https://github.com/<your-org>/hermes-mcp-bridge.git
cd hermes-mcp-bridge
uv tool install --editable .
```
### 4.2 配置
```bash
mkdir -p ~/.config/hermes-mcp-bridge
cat > ~/.config/hermes-mcp-bridge/config.toml << 'EOF'
api_url = "http://127.0.0.1:8642"
api_key = "change-me-local-dev" # 必须与~/.hermes/.env中的API_SERVER_KEY匹配
model = "general_researcher"
timeout_seconds = 300
EOF
chmod 600 ~/.config/hermes-mcp-bridge/config.toml
```
### 4.3 在Cursor中注册
添加到`~/.cursor/mcp.json`:
```json
{
"mcpServers": {
"hermes": {
"command": "/home/nirvana/.local/bin/hermes-mcp-bridge"
}
}
}
```
### 4.4 重启Cursor
设置 → MCP → `hermes` 应该显示 **已连接**。
---
## 5. 工具
| 工具 | 签名 | 目的 |
| --------------- | --------------------------------------- | ------------------------------- |
| `hermes_ask` | `(prompt, session_id?, profile?) → str` | 委托任务给Hermes Agent |
| `hermes_check` | `(job_id) → str` | 轮询异步任务状态（存根） |
| `hermes_cancel` | `(job_id) → str` | 取消异步任务（存根） |
| `hermes_reset` | `() → str` | 清除任务队列（存根） |
> 最后三个工具是为了API对齐而保留的。`hermes-mcp-bridge`同步运行 —
> `hermes_ask`阻塞直到完整的Agent响应准备就绪。
---
## 6. REPL上下文（会话连续性）
Hermes记住您之前告诉它的内容 — 只需在同一个
Cursor聊天中继续对话。Cursor自动在回合之间重用相同的`session_id`。
```
┌─────────────────────────────────────────────────────────┐
│ 您在Cursor中说 │
├─────────────────────────────────────────────────────────┤
│ "使用Hermes记住我的幸运数字是42" │
│ → Hermes记住42 │
│ │
│ "要求Hermes我的幸运数字是什么" │
│ → Hermes回答42 │
│ （相同的session_id — 上下文保留） │
└─────────────────────────────────────────────────────────┘
```
桥接器通过`X-Hermes-Session-Id` HTTP头部将`session_id`传递给网关。
网关使用它来维护调用之间的上下文。
无需特殊语法。无需跟踪会话ID。只需正常对话 — Hermes
记住。
---
## 7. 配置参考
`~/.config/hermes-mcp-bridge/config.toml`
| 键 | 默认 | 描述 |
| ----------------- | ----------------------- | ----------------------------------------------- |
| `api_url` | `http://127.0.0.1:8642` | Hermes网关HTTP API地址 |
| `api_key` | — | 必须与`~/.hermes/.env`中的`API_SERVER_KEY`匹配 |
| `model` | `general_researcher` | 必须与网关`/v1/models`中的模型ID匹配 |
| `timeout_seconds` | `300` | 每个`hermes_ask`调用的最大等待时间 |
环境变量覆盖（优先级更高）：`HERMES_BRIDGE_API_URL`，`HERMES_BRIDGE_API_KEY`。
---
## 8. 安全
- 所有网络流量都局限在`127.0.0.1`环回接口上。
- API密钥存储在`~/.config/hermes-mcp-bridge/config.toml`（模式`600`）中。
- 仓库本身**不包含密钥、秘密或凭证**。
- Cursor通过stdio启动桥接器 — 不暴露端口。
---
## 9. 许可证
Apache-2.0
