MCP 编排器 AIMarshallLee/dsh-mcp-orchestrator

dsh-mcp-orchestrator

用于 DeepSeek Harness (DSH) 的 MCP 编排层——多服务器管理、健康监控、自动重启、带冲突处理的工具聚合、回退路由以及使用统计。

功能简介

DSH 内置了 MCP 客户端支持，但缺少编排能力：没有健康监控，崩溃时不会自动重启，没有工具冲突检测，没有回退路由，也没有统一的工具发现机制。本插件填补了这一空白。

核心能力：
- 同时连接多个 stdio MCP 服务器
- 通过周期性 ping 检查进行健康监控
- 在意外断开时以指数退避方式自动重启
- 跨所有服务器聚合工具并进行冲突检测
- 针对工具名称冲突提供三种命名空间模式（collision、server、dot）
- 回退路由：当某个服务器上的工具调用失败时，自动在提供同一工具的其他服务器上重试
- 优先级加权排序：服务器按成功率再按优先级排序
- 使用统计：按服务器、按工具以及整体调用跟踪，并记录响应时间
- 四个 DSH 管理工具，供 agent 发现、调用和监控 MCP 工具

状态：v0.2.0 — 编排

已验证能力

| 能力 | 状态 | 测试 |
| MCP SDK 客户端 API（connect、ping、listTools、callTool、close） | 通过 | test/spike.mjs |
| 多客户端支持（2 个及以上服务器） | 通过 | test/spike.mjs |
| 错误处理（不存在的工具、缺少参数） | 通过 | test/spike.mjs |
| ServerManager connect/disconnect/restart | 通过 | test/integration.mjs |
| 工具发现与调用 | 通过 | test/integration.mjs |
| 带指数退避的自动重启 | 通过 | test/integration.mjs |
| 工具冲突检测 | 通过 | test/integration.mjs |
| 命名空间模式（collision/server/dot） | 通过 | test/integration.mjs |
| 健康监控（基于 ping） | 通过 | test/integration.mjs |
| Zod 配置 schema 校验（含 Phase 3 字段） | 通过 | test/integration.mjs |
| 插件生命周期（apply、tools、system prompt、cleanup） | 通过 | test/integration.mjs |
| 带冲突处理的多服务器插件 | 通过 | test/integration.mjs |
| 服务器失败时的回退路由 | 通过 | test/integration.mjs |
| 优先级加权候选排序 | 通过 | test/integration.mjs |
| 基于成功率的服务器排序 | 通过 | test/integration.mjs |
| UsageTracker（record、stats、getRecent、clear） | 通过 | test/integration.mjs |
| mcp_stats 工具（summary/server/tool/all 详细模式） | 通过 | test/integration.mjs |
| 回退禁用模式（直接路由路径） | 通过 | test/integration.mjs |

测试结果

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

架构

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"（管理工具 + 工作流指南） ├─ Tool: mcp_list_servers（每个服务器的状态、健康状况、工具数量） ├─ Tool: mcp_list_tools（聚合工具、冲突信息、命名空间名称） ├─ Tool: mcp_call_tool（自动解析、回退路由、结果中的元数据） ├─ Tool: mcp_stats（使用统计：summary/server/tool/all） ├─ ServerManager │ ├─ 多服务器 stdio 连接（StdioClientTransport） │ ├─ 自动重启（指数退避、最大重启次数） │ ├─ 工具同步（连接/重连时调用 listTools） │ ├─ 健康 ping │ └─ findServerForTool（基于优先级的解析） ├─ ToolRegistry │ ├─ 跨所有服务器的工具聚合 │ ├─ 冲突检测（多个服务器上存在同名工具） │ └─ 命名空间模式：collision / server / dot ├─ HealthMonitor │ └─ 周期性 ping 检查（可配置间隔） ├─ UsageTracker │ ├─ 记录每次调用（成功/失败、响应时间、回退） │ ├─ 按服务器、按工具、整体统计 │ └─ 最近调用日志（可配置最大记录数） ├─ FallbackRouter │ ├─ 解析工具 → 查找所有提供该工具的服务器 │ ├─ 按成功率（若启用）再按优先级对候选进行排序 │ ├─ preferredServer 覆盖（优先尝试特定服务器） │ └─ 带最大尝试次数限制的顺序回退 └─ ctx.effect() 清理（停止监控、关闭所有服务器、清除跟踪器）

安装

前置条件

- Node.js >= 22.19（或 >= 24）
- 已安装 DSH：npm install -g @deepseek-ai/dsh
- 至少一个要连接的 MCP 服务器

构建

cd dsh-mcp-orchestrator
npm install
npm run build

安装到 DSH

方式 A：从 GitHub 安装（推荐）

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

方式 B：从本地克隆安装

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

配置

在 DSH 配置目录中创建或编辑 cordis.patch.yml：

- 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

配置模式（zod）

| 字段 | 类型 | 默认值 | 描述 |
| servers | array | [] | MCP 服务器配置 |
| servers[].name | string | — | 唯一服务器名称 |
| servers[].command | string | — | 要运行的可执行文件 |
| servers[].args | string[] | [] | 命令行参数 |
| servers[].env | Record | {} | 环境变量 |
| servers[].autoRestart | boolean | true | 崩溃时自动重启 |
| servers[].restartDelay | number | 2000 | 基础重启延迟（毫秒） |
| servers[].maxRestarts | number | 3 | 最大重启尝试次数 |
| servers[].priority | number | 0 | 工具解析优先级（数值越高越优先） |
| healthCheckInterval | number | 30000 | Ping 间隔（毫秒） |
| namespaceMode | enum | collision | 工具名称冲突处理 |
| enableFallback | boolean | true | 在工具调用失败时启用回退路由 |
| maxFallbackAttempts | number | 3 | 放弃前尝试的最大服务器数量 |
| preferHealthyServers | boolean | true | 按成功率对候选服务器排序（false = 仅按优先级） |
| enableStats | boolean | true | 注册 mcp_stats 工具并跟踪使用情况 |

命名空间模式

| 模式 | 行为 | 示例 |
| collision | 仅当相同工具名称存在于 2 个或更多服务器上时才添加命名空间 | echo → server1__echo（如果冲突） |
| server | 始终使用 serverName__toolName 添加命名空间 | echo → server1__echo |
| dot | 始终使用 serverName.toolName 添加命名空间 | echo → server1.echo |

项目结构

dsh-mcp-orchestrator/
├── src/
│ ├── index.ts # 插件入口：apply(ctx, config) 带 zod 模式 │ ├── server-manager.ts # MCP 服务器连接、自动重启、工具同步 │ ├── tool-registry.ts # 工具聚合、冲突检测、命名空间 │ ├── health-monitor.ts # 基于周期性 ping 的健康检查 │ ├── usage-tracker.ts # 工具调用统计（按服务器、按工具、总体） │ ├── fallback-router.ts # 带优先级和成功率排序的回退路由 │ └── tools/ │ ├── list-servers.ts # mcp_list_servers 工具 │ ├── list-tools.ts # mcp_list_tools 工具 │ ├── call-tool.ts # mcp_call_tool 工具（带回退路由） │ └── stats.ts # mcp_stats 工具（使用统计） ├── dist/ # 编译后的 JavaScript（tsc 输出） ├── test/ │ ├── mock-server.mjs # 模拟 MCP 服务器（echo、add、greet） │ ├── mock-server-2.mjs # 第二个模拟服务器（echo、subtract）用于冲突测试 │ ├── spike.mjs # Spike：MCP SDK API 验证（34 个测试） │ └── integration.mjs # 集成：完整插件测试（236 个测试） ├── cordis.patch.yml # 示例插件配置 ├── package.json ├── tsconfig.json ├── CHANGELOG.md └── LICENSE

路线图

| 阶段 | 范围 | 状态 |
| 阶段 1 — 技术验证 | MCP SDK 验证、connect/listTools/callTool、多客户端 | 已完成 |
| 阶段 2 — MVP | ServerManager、ToolRegistry、HealthMonitor、自动重启、3 个 DSH 工具 | 已完成 |
| 阶段 3 — 编排 | 回退路由、使用统计、优先级加权、mcp_stats 工具 | 已完成 |

许可证

MIT