Hermes

Why this agent

Hermes Agent 是 Nous Research 出品的自我改进 AI agent,原生支持 MCP(见 website/docs/user-guide/features/mcp.md)。配置文件 ~/.hermes/config.yaml,MCP 服务在 mcp_servers: (snake_case,跟 Nanobot 的 mcpServers 形态一致只是顶层 key 拼写不同)下声明。两种传输都支持:stdio + HTTP;还能按服务过滤工具、开启 sampling、按服务 opt-in 并行调用。

Prerequisites

已安装 Hermes(一行命令:curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash)。
espctl 已安装在磁盘上某个稳定位置。
(可选,用于远程构建)Aegis 构建服务器地址 + MCP_AUTH_SECRET。

Install snippet (or alternative)

编辑 ~/.hermes/config.yaml,把这段并入 mcp_servers:(文件不存在就新建 —— hermes setup 会先填好其他 key,在它们旁边追加 mcp_servers 即可):

mcp_servers:
  espctl:
    command: /path/to/espctl
    args:
      - mcp
      - serve
    env:
      CONTROL_BASE_URL: https://esphome.cloud
      MCP_AUTH_SECRET: your-access-key

替换:

/path/to/espctl —— 你电脑上 espctl 的完整路径。
CONTROL_BASE_URL —— 你的 Aegis 构建服务器地址。
MCP_AUTH_SECRET —— 构建服务器给你的访问密钥。

或者 —— 拿到预填好的代码片段:

读取 install://hermes 资源。

改完配置后,在 Hermes 内热加载:

/reload-mcp

不用重启。

First-run verification

hermes

在 Hermes TUI 里:

你有哪些 espctl 工具?

预期:Hermes 列出约 40 个 espctl 工具,统一带 mcp_espctl_<tool_name> 前缀(Hermes 的命名空间约定)。

Troubleshooting

启动时 config.yaml 解析错 —— 检查 2 空格缩进、command: 是字符串(不是数组)、args: 是列表(一行一个,前面带 -)、 env: 是 map(key-value 对)。
列出了工具但每次调用返回 “auth required” —— MCP_AUTH_SECRET 缺失或已失效。回到控制面重新签发一份访问密钥再填进配置。
想用 HTTP 传输不走 stdio? 把 command 块替换为 url: https://esphome.cloud/mcp/esp-idf,加 headers: { Authorization: "Bearer your-access-key" }。Hermes 两种传输都用同一份 mcp_servers: map。
想过滤暴露的工具? Hermes 支持 tools.include: / tools.exclude:, 按服务粒度。比如 tools: { include: [build, flash, monitor] } 就只暴露这三个。
想并行调用? espctl 工具多数是只读枚举 + 远程构建启动;如果你能接受并发,在服务条目加 supports_parallel_tool_calls: true。

Tested as-of 2026-05-19

Hermes 特有注意事项

schema 还支持每服务 sampling:(Hermes 让 MCP 服务反过来请求 Hermes 做 LLM 推理);本套 MCP 用不到,这块留空就行。
Hermes 自己也能当 MCP 服务用 —— hermes mcp serve 启动后, Claude Code / Cursor 等可以反过来驱动 Hermes 的消息能力。方向相反, 跟上面把 espctl 作 MCP 服务的配置不冲突。
工具名自动加 mcp_espctl_* 前缀,避免跟 Hermes 内置工具冲突。

Keyboard shortcuts

ESP-IDF MCP 用户手册