AGENT SKILL

local-daemon-mcp-integration

Wire a local Node daemon into Hermes as an MCP server.

License 许可
MIT
最近更新
2026-10-14
Stars
★ 0
Forks
0

01 前言 Front Matter

name
local-daemon-mcp-integration
author
Hermes Agent
license
MIT
version
1.0.0
metadata
{ "hermes": { "tags": [ "MCP", "local-daemon", "node", "integration", "troubleshooting" ] } }
platforms
[ "linux", "macos" ]
description
Wire a local Node daemon into Hermes as an MCP server.

02 资源文件 2

03 SKILL.md 正文

Local Daemon → Hermes MCP Integration

Class of task: a developer tool ships as a local daemon + a stdio MCP server that proxies to it. You register the MCP server in ~/.hermes/config.yaml so Hermes gets its tools. This skill covers the full flow and the two failure modes that reliably bite: native-module/Node-ABI mismatch and write_file/patch following symlinks into the real entrypoint.

Read this alongside the native-mcp skill (Hermes' built-in MCP client).

When to use

  • "add <tool>'s MCP server to Hermes", "mcp install hermes", "wire <daemon> into my agent", or any local-first tool whose MCP entrypoint spawns a stdio server that talks to a running daemon.
  • The daemon is a Node monorepo / pnpm workspace build (Open Design, etc.).

Flow

1. Confirm the real CLI (binary-name collision)

Many tools expose a CLI name that collides with a system binary. Open Design's CLI is od, but /usr/bin/od is GNU coreutils' octal dump. A config command: "od" launches the wrong binary and hangs silently.

command -v od && od --version      # expect GNU coreutils, NOT the tool
command -v <alias> && <alias> --help

Use the non-colliding alias (e.g. opendesign) and, better, the resolved node-binary + entry script from step 3.

2. The MCP server is a proxy — start the daemon first

od mcp (and similar) spawns a stdio MCP server that forwards tool calls to the running daemon (e.g. http://127.0.0.1:7456). Tools return nothing / hang unless the daemon is up. Start it, then verify:

curl -s -o /dev/null -w "%{http_code}\n" --max-time 5 http://127.0.0.1:7456/api/health
# expect 200

3. Get the byte-exact launch spec — never hand-guess

Tooling usually resolves the correct command from the running daemon. Use it:

<cli> mcp install hermes --dry-run --json     # or GET /api/mcp/install-info

The returned launchSpec is authoritative, e.g.:

command: <node24>/bin/node
args:    [<repo>/apps/daemon/dist/cli.js, mcp, --daemon-url, http://127.0.0.1:7456]
env:     OD_DATA_DIR: <repo>/.od

Note: the tool may decline to edit Hermes config itself and print "manual setup required — add this under your Hermes MCP server configuration by hand." That's expected; splice it yourself in step 4.

4. Insert into config.yaml (surgical — never yaml.safe_dump)

~/.hermes/config.yaml cannot be edited with patch/write_file (agent write-block), and yaml.safe_dump strips comments and reorders keys. Insert via a Python script that splices raw YAML text before the next top-level key (e.g. plugins:), preserving comments/order. Back up first:

cp ~/.hermes/config.yaml ~/.hermes/config.yaml.bak.$(date +%s)

Block shape:

  open-design:
    command: "<node24>/bin/node"
    args:
      - "<repo>/apps/daemon/dist/cli.js"
      - "mcp"
      - "--daemon-url"
      - "http://127.0.0.1:7456"
    env:
      OD_DATA_DIR: "<repo>/.od"

Validate: python3 -c "import yaml; yaml.safe_load(open('/home/deeone/.hermes/config.yaml'))". Also confirm the daemon is still the sole listener on the port (ss -tlnp | grep 7456) — avoid duplicate daemons.

5. Verify with a real stdio JSON-RPC handshake

Config edit ≠ proof it runs. Spawn the exact command with the spec's env, send initialize then tools/list over newline-delimited JSON (one object per line — NOT LSP Content-Length framing, which makes the server hang). A live tools/call returning real data is the gold standard. See scripts/verify-mcp-stdio.py.

6. Make tools callable

MCP tools load at agent startup. Restart Hermes (relaunch, or /reset in a chat) to expose mcp_<server>_* tools inline. A reload notification may fire without refreshing this session's callable tool list — that's a presentation quirk, not a config problem; a fresh session exposes them.

Pitfalls (transferable)

Native module / Node ABI mismatch → ERR_DLOPEN_FAILED

A daemon built on Node 24 with a native module (better-sqlite3, etc.) crashes under a different Node (e.g. v25) with NODE_MODULE_VERSION 137 ... requires NODE_MODULE_VERSION 141. Fix:

  1. Rebuild the native module against the Node you will pin: PATH=<node24>/bin:$PATH pnpm rebuild better-sqlite3 (from repo root); confirm with node -e "require('<module>')" under that Node.
  2. Pin the launcher to that Node: replace the alias/symlink CLI with a wrapper that prepends the Node bin dir to PATH before exec node <entry>.

write_file / patch follow symlinks — trash the symlink first

write_file and patch RESOLVE symlinks and overwrite the target file. If the launcher is a symlink chain (~/.local/bin/opendesign → node_modules/.bin/od → apps/daemon/bin/od.mjs), writing to the launcher path corrupts the REAL entrypoint. Rule: move the symlink to trash first, then write the real wrapper file. (This has recurred across sessions — standing rule for launcher/entrypoint edits: trash symlink, then write file.)

Worked example: Open Design

See references/open-design-example.md for the end-to-end Open Design flow (164 skills, 150 plugins, the Hermes agent adapter via ACP, and the two directions of integration).

Support files

  • scripts/verify-mcp-stdio.py — runnable JSON-RPC handshake verifier (initialize + tools/list over newline-delimited JSON). Use it to prove any stdio MCP server actually works before declaring success.
  • references/open-design-example.md — concrete Open Design paths, ports, the byte-exact launch spec, and the Hermes ACP agent adapter.

04 同仓库更多 Skills