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