hermes-dsh-bridge

An MCP plugin specifically bridging Hermes ↔ DeepSeek Harness: it starts an MCP server inside Harness, letting external MCP clients (such as Hermes) drive Harness's Agent to perform real coding tasks.

Hermes is the brain, Harness is the hands.

Why it exists

Harness ships with a powerful Agent runtime (tools, LLM, agents, sessions), but it is a Cordis app, so other agents cannot drive it. This plugin turns Harness around: it starts a real MCP server (StreamableHTTP) inside Harness, bridging the Harness core services (ctx.agents / ctx.agentPresets / ctx.tools) so an external "brain" can hand the actual work to Harness's "hands".

Hermes (MCP client, 大脑)
   │  agent_run / task_inbox / fs_read / session_stats ... (HTTP)
   ▼
harness-mcp-server (MCP server, :8090)
   │  ctx.agents.create → mount 'standard' preset
   ▼
Harness agent — 完整工具集: bash, fs, todo, web…

Related MCP server: dsh-harness-mcp-server

Tools (19)

Tasks

Sessions

Files (constrained by the path jail)

Status and configuration

Presets

Meta

Structured results and statistics

Every agent_run returns a structured result along with the usage statistics for that round:

{
  "sessionId": "...",
  "assistantText": "最终回答",
  "toolCalls": [{ "name": "bash", "args": "..." }],
  "toolResults": ["命令输出"],
  "changes": "改了什么",
  "verification": "怎么验证的",
  "leftovers": "遗留问题",
  "stats": {
    "rounds": 1, "steps": 3,
    "llmTime": 13.9, "toolTime": 0.04,
    "ttft": 3349, "tokensPerSec": 40.7,
    "cacheHitRate": 1, "inputTokens": 8831, "outputTokens": 157
  }
}

Closed loop: the client feeds its memory into each task as context, then stores the result (changes/verification/leftovers) back into the client's memory for the next round.

Installation

Option A — Install from npm into the Harness profile

# 在 Harness profile 的 node_modules 下
cd ~/.dsh/profiles/<你的profile>/node_modules
npm install hermes-dsh-bridge

Option B — Build from source

git clone https://github.com/Emilia-awa/hermes-dsh-bridge.git
cd hermes-dsh-bridge
npm install && npm run build   # 产出 lib/index.js
# 把构建产物放进 Harness profile:
#   ~/.dsh/profiles/<你的profile>/node_modules/hermes-dsh-bridge

⚠️ dual-package hazard (required reading): Harness resolves @deepseek-ai/* from the global tree, while the plugin's own node_modules may have a parallel copy — two module instances ⇒ Symbol mismatch ⇒ the Agent silently loses all tools (shown as agent_run only outputting a `` <tool_calls> text and toolCalls always being an empty array). Fix: symlink the plugin's @deepseek-ai/* dependencies to the Harness global tree:

PROFILE=~/.dsh/profiles/<你的profile>/node_modules
GLOBAL=$(npm root -g)/@deepseek-ai/dsh/node_modules/@deepseek-ai
for pkg in cordis cosmokit dsh-agent dsh-llm dsh-session dsh-tools dsh-scope \
           dsh-agent-presets dsh-code-runtime dsh-system-prompt dsh-typert-protocol \
           dsh-attachment dsh-brand dsh-invariants dsh-timeout dsh-settings \
           dsh-home-paths dsh-atomic-write dsh-user-approval \
           cordis-plugin-include cordis-plugin-loader; do
  rm -rf "$PROFILE/@deepseek-ai/$pkg" && ln -sfn "$GLOBAL/$pkg" "$PROFILE/@deepseek-ai/$pkg"
done

(cordis-plugin-include/loader is not published to the npm registry; it lives only in the Harness global tree, so it must be symlinked.)

Patch configuration

Append this at the end of your Harness profile's cordis.patch.yml (or equivalent patch file):

- insert:
    - id: hermes-dsh-bridge
      name: 'hermes-dsh-bridge'
      config:
        http: true
        port: 8090
        host: 127.0.0.1        # 默认仅本机; 暴露前必须加认证
        # authToken: '你的随机长token'     # 可选: Bearer token 认证
        # workspaceRoots: ['/workspace']  # 可选: cwd 白名单
        # enableFsWrite: true             # 可选: 开启 fs_write(默认关)
        # ⚠️ 必须显式声明 provider/model, 否则 agent 组装会因空 {{model}} 崩溃:
        provider: opencode-go
        model: deepseek-v4-flash

Restart and verify

systemctl restart dsh.service        # 或你管理 Harness 的方式
# 验证 19 个工具全在线:
python3 examples/hermes_dsh_mcp.py list
python3 examples/hermes_dsh_mcp.py call status_get '{}'

🤖 One-click AI Installation Guide (instructions written for AI Agents)

The following steps are intended for another AI Agent: if you are an AI agent that needs to install this plugin into the Harness environment you manage, follow the numbered steps strictly and check the output after each step before continuing.

Pre-checks (do these 3 first)

1. Confirm Node ≥ 22.18: node --version (below 22.18 you'll get errors about missing zstd/stripTypeScriptTypes, so upgrade Node first).

2. Confirm the target Harness profile exists: ls ~/.dsh/profiles/ (find the profile name you want; <PROFILE> below refers to it).

3. Confirm the Harness global tree exists: npm root -g (referred to as $GLOBAL_TREE below in place of npm root -g).

Installation steps (copy-paste executable)

# ① 安装插件到 profile
cd ~/.dsh/profiles/<PROFILE>/node_modules
npm install hermes-dsh-bridge        # 未发布到 npm 前用方式 B（源码）

# ② 修复 dual-package hazard: 把所有 @deepseek-ai/* 和 cordis-plugin-* symlink 到全局树
GLOBAL_TREE=$(npm root -g)/@deepseek-ai/dsh/node_modules/@deepseek-ai
for pkg in cordis cosmokit dsh-agent dsh-llm dsh-session dsh-tools dsh-scope \
           dsh-agent-presets dsh-code-runtime dsh-system-prompt dsh-typert-protocol \
           dsh-attachment dsh-brand dsh-invariants dsh-timeout dsh-settings \
           dsh-home-paths dsh-atomic-write dsh-user-approval \
           cordis-plugin-include cordis-plugin-loader; do
  rm -rf "@deepseek-ai/$pkg" 2>/dev/null
  ln -sfn "$GLOBAL_TREE/$pkg" "@deepseek-ai/$pkg"
done

# ③ 在 profile 的 cordis patch 文件(cordis.patch.yml)末尾追加配置
cat >> ~/.dsh/profiles/<PROFILE>/cordis.patch.yml <<'EOF'
- insert:
    - id: hermes-dsh-bridge
      name: 'hermes-dsh-bridge'
      config:
        http: true
        port: 8090
        host: 127.0.0.1
        provider: opencode-go      # ← 换成你自己的 provider id
        model: deepseek-v4-flash   # ← 换成你自己的 model id
EOF

# ④ 重启 Harness(注意: 若你正跑在 Harness 里, 用 systemd-run 脱离进程树重启)
systemctl restart dsh.service

# ⑤ 验证: 等 8 秒后检查 MCP server 起来 + 工具列表
sleep 8
curl -s -X POST http://127.0.0.1:8090/mcp \
  -H 'Content-Type: application/json' -H 'Accept: application/json, text/event-stream' \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"ai-setup","version":"1.0"}}}' \
  | tail -1 | head -c 300
python3 examples/hermes_dsh_mcp.py list | grep -cE "agent_run|session_stats|preset_set"   # 期望 ≥ 3

Acceptance criteria

• dsh_mcp.py list outputs ≥ 19 tools, including agent_run, session_stats, preset_set, and fs_read.

• status_get returns version 0.3.0, with provider/model being the values you configured.

• Run a smoke task: python3 examples/hermes_dsh_mcp.py run '回复:安装成功' — the response contains the stats field.

Common failures and fixes (check when hit)

Full troubleshooting: docs/TROUBLESHOOTING.md.

Documentation

• docs/TOOLS.md — complete reference for the 19 tools (inputs/outputs/limits/error codes)

• docs/CONFIG.md — config fields, secure defaults

• docs/TROUBLESHOOTING.md — known pitfalls (SSE parsing, 8KB truncation, dual-package hazard…)

• docs/SECURITY.md — threat model

• examples/hermes_dsh_mcp.py — zero-dependency Python MCP client (standard library only)

Positioning

Best suited as a backup tool rather than daily main tool: for everyday code changes, drive your primary Agent directly. It's the one to reach for when you need context isolation (a large refactor would blow up client context) or parallel execution of unrelated tasks.

• Agent sessions are reused by cwd (avoid reloading project context on every invocation).

• Bash is sandboxed (workspace-write): install bubblewrap on the host machine, or write commands will be rejected.

• reasoning/thinking blocks are stripped before returning (two-layer filtering: plugin-side + text-level fallback).

License

GPL-3.0-only; upstream MIT portions retained — see NOTICE.md.