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
- 参考文档references/open-design-example.md2.9 KB
- 脚本scripts/verify-mcp-stdio.py2.8 KB
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:
- Rebuild the native module against the Node you will pin:
PATH=<node24>/bin:$PATH pnpm rebuild better-sqlite3(from repo root); confirm withnode -e "require('<module>')"under that Node. - 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/listover 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
blocked-page-recovery
Use when a fetch fails: 403/429, paywall, WAF, bot wall.
gemini-vision-fallback
Vision fallback: Gemini REST API if vision_analyze blocked.
twitter-cli
Use twitter-cli for ALL Twitter/X operations — reading tweets, posting, replying, quoting, liking, retweeting, following, searching, user lookups. Invoke whenever user requests any Twitter interaction.
prism-scan
Structural analysis through dynamically generated cognitive lenses. Generates the optimal analytical lens for the specific code/artifact, then executes it. Finds conservation laws, structural invariants, and concrete bugs that vanilla analysis misses. Use on any code file, system design, or text artifact.
prism-reflect
Constraint transparency: analyzes an artifact structurally, then analyzes what its own analysis concealed. Produces a conservation law AND a constraint report showing what was maximized, what was sacrificed, and what to investigate next. The only AI skill that knows what it can't see.
prism-full
Full Prism: multi-pass structural analysis with mandatory adversarial self-correction. Designs custom analytical passes, executes them with chaining, then attacks its own findings before synthesizing. Use for maximum depth on important code or artifacts.