daemon-mcp-server-setup
Wire a local daemon-backed stdio MCP server into an agent.
- License 许可
- MIT
- 最近更新
- 2026-10-14
- Stars
- ★ 0
- Forks
- 0
01 前言 Front Matter
- name
- daemon-mcp-server-setup
- author
- Hermes Agent
- license
- MIT
- version
- 1.0.0
- metadata
- { "hermes": { "tags": [ "mcp", "open-design", "od", "daemon", "node", "native-modules", "setup" ] } }
- platforms
- [ "linux", "macos" ]
- description
- Wire a local daemon-backed stdio MCP server into an agent.
02 资源文件 1
- 参考文档references/open-design-example.md3.0 KB
03 SKILL.md 正文
Daemon-backed MCP Server Setup
When to Use
- The user wants to
mcp install/ wire a local MCP server that proxies to a running local daemon (Open Design /od, or any Node-based local service with an MCP entry). - You have a pasted MCP config block and must register it in
~/.hermes/config.yamlwithout clobbering existing servers or using the wrong launcher binary.
Use when the user wants to install/wire an MCP server that is a stdio proxy to a
local daemon (Open Design / od is the canonical case, but the pattern fits any
Node-based local service that exposes an MCP entrypoint). The server process talks
to a separate long-running daemon over HTTP; if the daemon isn't up, the MCP tools
will register but return nothing.
Workflow
- Inventory existing config before editing.
Grep
~/.hermes/config.yamlfor^mcp_servers:and list current servers. You must append, never clobber. (Hermes already had zapier_youtube, lightpanda, substack-api, nova3d, mcp-cli in this user's setup.) - Resolve the real launcher binary — do NOT trust the name in a pasted config.
A pasted
command: "od"is almost certainly wrong:/usr/bin/odis GNU coreutils' octal dump, not Open Design. Find the real CLI:command -v opendesign,which <alias>, or trace the symlink withls -la. Prefer the alias the user already set up over re-inventing the entrypoint. - Start the daemon first (needed for an exact install spec and for the tools
to actually work). Run it in the background (
terminal(background=true)), then verify it bound the port — see Verification below. Do not declare success untilcurl /api/healthreturns 200. - Prefer the server's own built-in installer when one exists. For Open Design:
opendesign mcp install hermes --dry-run --jsonresolves the byte-exact launch command from the running daemon's/api/mcp/install-infoendpoint. That endpoint returns{command, args, env, daemonUrl, ...}— use those exact values in config rather than guessing. (Falls back to a minimalod mcp --daemon-url <url>if the daemon is down, but a running daemon gives the precise match.) - Register in config via surgical Python insertion (never
patch/write_fileon~/.hermes/config.yaml— both are blocked as security-sensitive). Insert the block as raw YAML text before the next top-level key;yaml.safe_dumpwould strip comments/reorder keys. After insertion,python3 -c "import yaml; yaml.safe_load(open(path))"to validate. (The insertion pattern + whyyaml.safe_dumpis forbidden is detailed in the native-mcp skill'sreferences/verify-and-edit-mcp.md.) - Verify the MCP server with a real stdio JSON-RPC handshake (initialize + tools/list) before claiming installed — see native-mcp skill.
Critical Pitfalls
P1 — write_file/patch FOLLOW symlinks to the real target
If the launcher path is a symlink (e.g. opendesign -> node_modules/.bin/od -> apps/daemon/bin/od.mjs), writing to it overwrites the underlying file, not the
symlink. In this session that corrupted OD's actual entrypoint (od.mjs) and made
opendesign hang.
Fix: always ls -la the target first. If it's a symlink, move it to trash
(mv to ~/.trash/..., never hard rm -rf), then write a real file (e.g. a
Node-24-pinned bash wrapper) at that path. Restore any corrupted target via
git checkout or its known-good content.
P2 — Node native-module ABI mismatch (ERR_DLOPEN_FAILED)
A Node app with native deps (e.g. better-sqlite3) compiled for one Node ABI will
crash on another: was compiled against a different Node.js version using NODE_MODULE_VERSION 137. This version of Node.js requires NODE_MODULE_VERSION 141.
This happens when the active node on PATH differs from the Node the module was
built for (the user has v20/v24/v25 installed via nvm; the repo targets ~24).
Fix (pick one):
- Pin the launcher to the Node the module was built for: a wrapper that does
export PATH="/path/to/node/v24.x/bin:$PATH"; exec node <entry> "$@". - Or rebuild the module for the active Node:
cd <repo> && export PATH=<nodeX>/bin:$PATH && pnpm rebuild better-sqlite3(verify withnode -e "require('better-sqlite3')"). Never runpnpm rebuildunder a Node version other than the one that will actually run the app — it recompiles the module for that Node and can make things worse.
P3 — Silent daemon != dead daemon
When stdout is piped/redirected, Node buffers output, so a daemon that prints
nothing can still be healthy and listening. Also, the daemon may take 30–60s to bind
after launch; an early ss | grep <port> can race and falsely report "nothing".
Fix: confirm binding with ss -tlnp | grep <pid> (the daemon's PID owns the
LISTEN socket) rather than grepping the port string. If you need to know what it's
doing: cat /proc/<pid>/task/*/wchan (main thread in do_epoll_wait = idle/healthy);
strace is often absent on minimal systems, so use /proc/<pid>/net/tcp to confirm
a LISTEN socket exists. For a JS-level hang, kill -USR1 <pid> opens the inspector
on :9229 (curl http://127.0.0.1:9229/json).
Notes
- The MCP server config must use the entrypoint the daemon reports, e.g.
command: /path/to/node/v24/bin/node,args: [dist/cli.js, mcp, --daemon-url, http://127.0.0.1:7456]— NOTod(coreutils) and NOT a barenpxguess. - After registering, MCP tools only work while the daemon is running. The OD MCP server re-discovers the daemon URL at each spawn, so restarts are tolerated.
References
references/open-design-example.md— full worked example: exact paths, ports, the launch spec the daemon reports, the Node-24-pinned launcher, and the gotchas (symlink corruption, ABI mismatch, silent-but-healthy daemon) from a real install.
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.