dsh-lazy-mcp

Lazy-start MCP stdio proxy for DSH (works with any newline-delimited JSON-RPC MCP host).

DSH's @deepseek-ai/dsh-mcp-client waits for every configured stdio server to connect and answer tools/list before the plugin activates, so a slow server (seconds of startup) gates the TUI input box. dsh-lazy-mcp sits between the host and each server: it answers initialize and tools/list instantly from a per-server metadata cache and only spawns the real server on the first request that actually needs it (tools/call, …).

Same idea as pi-mcp-adapter's default lifecycle: lazy: cached metadata keeps listing working without live connections; idle servers are shut down and respawned on demand.

Usage

dsh-lazy-mcp --name <server> [--idle-timeout-min N] -- <command> [args...]

DSH cordis.patch.yml MCP row example:

- id: mcp-serena
  name: '@deepseek-ai/dsh-mcp-client'
  config:
    serverName: serena
    transport: stdio
    command: !!js "process.env.HOME + '/Code/ai/dsh-ports/dsh-lazy-mcp/bin/dsh-lazy-mcp.js'"
    args: ['--name', 'serena', '--', 'serena', 'start-mcp-server', '--context=codex', '--project-from-cwd', '--enable-web-dashboard=false', '--open-web-dashboard=false']

Related MCP server: @qelos/better-mcp

Behaviour

• initialize, tools/list, prompts/list, resources/list, resources/templates/list are served from ~/.local/share/dsh/state/lazy-mcp/<name>.json without spawning the server.

• Cold cache (first run ever): the server is spawned synchronously once and the cache is populated; later launches are fast.

• First non-cacheable request spawns the server, performs the MCP initialize handshake (reusing the host's protocol version), then forwards requests, responses, notifications and cancellations transparently (ids untouched).

• While the live server is up, list requests go to it (authoritative). If the live tool list differs from the cached one, the cache is refreshed and notifications/tools/list_changed is emitted to the host.

• Idle timeout (default 10 min, 0 disables) kills the server; it respawns on the next request.

• Server stderr is appended to ~/.local/share/dsh/state/mcp-logs/<name>.log (replaces wrappers like mcp-quiet).

• stdin EOF, SIGTERM or SIGINT kills the whole process group; no orphans.

• Logs contain method names and timings only, never request payloads.

State/log dirs can be overridden with DSH_LAZY_MCP_STATE_DIR / DSH_LAZY_MCP_LOG_DIR.

Tests

npm test

Seven end-to-end tests against fixtures/fake-server.js: cold cache fill, warm start without spawn, lazy spawn + forwarding, list_changed on drift, idle kill/respawn, orphan cleanup, and slow-upstream warm start.

Licence

MIT, Copyright (c) 2026 Xiangzhe.