AGENT SKILL

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

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.yaml without 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

  1. Inventory existing config before editing. Grep ~/.hermes/config.yaml for ^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.)
  2. Resolve the real launcher binary — do NOT trust the name in a pasted config. A pasted command: "od" is almost certainly wrong: /usr/bin/od is GNU coreutils' octal dump, not Open Design. Find the real CLI: command -v opendesign, which <alias>, or trace the symlink with ls -la. Prefer the alias the user already set up over re-inventing the entrypoint.
  3. 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 until curl /api/health returns 200.
  4. Prefer the server's own built-in installer when one exists. For Open Design: opendesign mcp install hermes --dry-run --json resolves the byte-exact launch command from the running daemon's /api/mcp/install-info endpoint. That endpoint returns {command, args, env, daemonUrl, ...} — use those exact values in config rather than guessing. (Falls back to a minimal od mcp --daemon-url <url> if the daemon is down, but a running daemon gives the precise match.)
  5. Register in config via surgical Python insertion (never patch/write_file on ~/.hermes/config.yaml — both are blocked as security-sensitive). Insert the block as raw YAML text before the next top-level key; yaml.safe_dump would strip comments/reorder keys. After insertion, python3 -c "import yaml; yaml.safe_load(open(path))" to validate. (The insertion pattern + why yaml.safe_dump is forbidden is detailed in the native-mcp skill's references/verify-and-edit-mcp.md.)
  6. 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 with node -e "require('better-sqlite3')"). Never run pnpm rebuild under 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] — NOT od (coreutils) and NOT a bare npx guess.
  • 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