dsh-mcp-orchestrator

MCP orchestration layer for DeepSeek Harness (DSH) — multi-server management, health monitoring, auto-restart, and tool aggregation with collision handling.

What It Does

DSH has built-in MCP client support, but it lacks orchestration: there's no health monitoring, no auto-restart on crash, no tool collision detection, and no unified tool discovery. This plugin fills that gap.

Key capabilities:

  • Connect to multiple stdio MCP servers simultaneously
  • Health monitoring via periodic ping checks
  • Auto-restart with exponential backoff on unexpected disconnection
  • Tool aggregation across all servers with collision detection
  • Three namespace modes for tool name conflicts (collision, server, dot)
  • Three DSH management tools for the agent to discover and call MCP tools

Status: v0.1.0 — MVP

Verified Capabilities

Capability Status Test
MCP SDK Client API (connect, ping, listTools, callTool, close) Pass test/spike.mjs
Multi-client support (2+ servers) Pass test/spike.mjs
Error handling (non-existent tool, missing args) Pass test/spike.mjs
ServerManager connect/disconnect/restart Pass test/integration.mjs
Tool discovery and calling Pass test/integration.mjs
Auto-restart with exponential backoff Pass test/integration.mjs
Tool collision detection Pass test/integration.mjs
Namespace modes (collision/server/dot) Pass test/integration.mjs
Health monitoring (ping-based) Pass test/integration.mjs
Zod config schema validation Pass test/integration.mjs
Plugin lifecycle (apply, tools, system prompt, cleanup) Pass test/integration.mjs
Multi-server plugin with collision handling Pass test/integration.mjs

Test Results

Spike:         34 passed, 0 failed
Integration:  124 passed, 0 failed
Total:        158 passed, 0 failed

Architecture

DSH Agent (Node.js process)
  └─ Cordis Framework
       └─ dsh-mcp-orchestrator plugin (apply(ctx, config))
            ├─ Config Schema (zod: servers[], healthCheckInterval, namespaceMode)
            ├─ System Prompt: "mcp-orchestrator" (management tools + workflow guide)
            ├─ Tool: mcp_list_servers (status, health, tool count per server)
            ├─ Tool: mcp_list_tools (aggregated tools, collision info, namespaced names)
            ├─ Tool: mcp_call_tool (auto-resolve server or explicit, proxy call)
            ├─ ServerManager
            │    ├─ Multi-server stdio connections (StdioClientTransport)
            │    ├─ Auto-restart (exponential backoff, max restarts)
            │    ├─ Tool sync (listTools on connect/reconnect)
            │    ├─ Health ping
            │    └─ findServerForTool (priority-based resolution)
            ├─ ToolRegistry
            │    ├─ Tool aggregation across all servers
            │    ├─ Collision detection (same tool name on multiple servers)
            │    └─ Namespace modes: collision / server / dot
            ├─ HealthMonitor
            │    └─ Periodic ping checks (configurable interval)
            └─ ctx.effect() cleanup (stop monitor, close all servers)

Installation

Prerequisites

  • Node.js >= 22.19 (or >= 24)
  • DSH installed: npm install -g @deepseek-ai/dsh
  • At least one MCP server to connect to

Build

cd dsh-mcp-orchestrator
npm install
npm run build

Install into DSH

Option A: From GitHub (recommended)

dsh plugin --profile web add github:Daseanle/dsh-mcp-orchestrator
dsh web

Option B: From local clone

git clone https://github.com/Daseanle/dsh-mcp-orchestrator.git
cd dsh-mcp-orchestrator && npm install && npm run build
dsh plugin --profile web add file:./dsh-mcp-orchestrator
dsh web

Configuration

Create or edit cordis.patch.yml in your DSH config directory:

- id: dsh-mcp-orchestrator
  config:
    servers:
      - name: filesystem
        command: npx
        args: ["-y", "@modelcontextprotocol/server-filesystem", "/tmp"]
        autoRestart: true
        priority: 10

      - name: memory
        command: npx
        args: ["-y", "@modelcontextprotocol/server-memory"]
        autoRestart: true
        priority: 5

    healthCheckInterval: 30000
    namespaceMode: collision

Config Schema (zod)

Field Type Default Description
servers array [] MCP server configurations
servers[].name string — Unique server name
servers[].command string — Executable to run
servers[].args string[] [] Command line arguments
servers[].env Record<string, string> {} Environment variables
servers[].autoRestart boolean true Auto-restart on crash
servers[].restartDelay number 2000 Base restart delay (ms)
servers[].maxRestarts number 3 Max restart attempts
servers[].priority number 0 Priority for tool resolution (higher = preferred)
healthCheckInterval number 30000 Ping interval (ms)
namespaceMode enum collision Tool name collision handling

Namespace Modes

Mode Behavior Example
collision Namespace only when same tool name exists on 2+ servers echo → server1__echo (if collision)
server Always namespace with serverName__toolName echo → server1__echo
dot Always namespace with serverName.toolName echo → server1.echo

Project Structure

dsh-mcp-orchestrator/
├── src/
│   ├── index.ts              # Plugin entry: apply(ctx, config) with zod schema
│   ├── server-manager.ts     # MCP server connections, auto-restart, tool sync
│   ├── tool-registry.ts      # Tool aggregation, collision detection, namespacing
│   ├── health-monitor.ts     # Periodic ping-based health checks
│   └── tools/
│       ├── list-servers.ts   # mcp_list_servers tool
│       ├── list-tools.ts     # mcp_list_tools tool
│       └── call-tool.ts      # mcp_call_tool tool
├── dist/                      # Compiled JavaScript (tsc output)
├── test/
│   ├── mock-server.mjs       # Mock MCP server (echo, add, greet)
│   ├── mock-server-2.mjs     # Second mock server (echo, subtract) for collision tests
│   ├── spike.mjs             # Spike: MCP SDK API validation (34 tests)
│   └── integration.mjs       # Integration: full plugin tests (124 tests)
├── cordis.patch.yml          # Example plugin configuration
├── package.json
├── tsconfig.json
├── CHANGELOG.md
└── LICENSE

Roadmap

Phase Scope Status
Phase 1 — Spike MCP SDK validation, connect/listTools/callTool, multi-client Complete
Phase 2 — MVP ServerManager, ToolRegistry, HealthMonitor, auto-restart, 3 DSH tools Complete
Phase 3 — Orchestration Fallback routing, usage statistics, priority weighting, open source release Planned

License

MIT