dsh-mcp-orchestrator

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

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, no fallback routing, 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)
• Fallback routing: when a tool call fails on one server, auto-retry on others providing the same tool
• Priority-weighted sorting: servers sorted by success rate then priority
• Usage statistics: per-server, per-tool, and overall call tracking with response times
• Four DSH management tools for the agent to discover, call, and monitor MCP tools

Status: v0.2.0 — Orchestration

Verified Capabilities

Test Results

Spike:         34 passed, 0 failed
Integration:  236 passed, 0 failed
Total:        270 passed, 0 failed

Architecture

DSH Agent (Node.js process)
  └─ Cordis Framework
       └─ dsh-mcp-orchestrator plugin (apply(ctx, config))
            ├─ Config Schema (zod: servers[], healthCheckInterval, namespaceMode,
            │    enableFallback, maxFallbackAttempts, preferHealthyServers, enableStats)
            ├─ 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, fallback routing, metadata in results)
            ├─ Tool: mcp_stats (usage statistics: summary/server/tool/all)
            ├─ 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)
            ├─ UsageTracker
            │    ├─ Records every call (success/failure, response time, fallback)
            │    ├─ Per-server, per-tool, overall statistics
            │    └─ Recent call log (configurable max records)
            ├─ FallbackRouter
            │    ├─ Resolves tool → finds all servers providing it
            │    ├─ Sorts candidates by success rate (if enabled) then priority
            │    ├─ preferredServer override (try specific server first)
            │    └─ Sequential fallback with max attempts limit
            └─ ctx.effect() cleanup (stop monitor, close all servers, clear tracker)

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)

Namespace Modes

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
│   ├── usage-tracker.ts      # Tool call statistics (per-server, per-tool, overall)
│   ├── fallback-router.ts    # Fallback routing with priority and success-rate sorting
│   └── tools/
│       ├── list-servers.ts   # mcp_list_servers tool
│       ├── list-tools.ts     # mcp_list_tools tool
│       ├── call-tool.ts      # mcp_call_tool tool (with fallback routing)
│       └── stats.ts          # mcp_stats tool (usage statistics)
├── 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 (236 tests)
├── cordis.patch.yml          # Example plugin configuration
├── package.json
├── tsconfig.json
├── CHANGELOG.md
└── LICENSE

Roadmap

License

MIT