双向 MCP 桥接 helibeiqi/dsh-cordis-universal-adapter

dsh-cordis-universal-adapter

面向 DeepSeek Harness 的双向桥接插件：消费外部 MCP 服务器与 Agent Plugins 1.0 包，并把 DSH 原生工具反向暴露为标准 MCP 服务器。

CI
npm version
License: MIT

一句话描述

在 DSH（DeepSeek Harness）的 Host 组合层 上，把 MCP 生态（服务器、Agent Plugins 1.0 包）接入 ctx.tools，同时把 ctx.tools 导出为 MCP 服务器，让同一批工具同时以 DSH 原生与 MCP 两种形态暴露。

外部 MCP 服务器 ──▶ McpClientBridge ──▶ ctx.tools（DSH 工具） Agent Plugins 1.0 ─▶ PluginLoader ─────┘ │ ▼ 外部 MCP 客户端 ◀── McpServerBridge ◀── ctx.tools.schemas()

安装

三条安装命令（按场景选择）：

从 GitHub 仓库安装
dsh plugin --profile web add github:helibeiqi/dsh-cordis-universal-adapter

从 npm 安装
dsh plugin --profile web add dsh-cordis-universal-adapter

从本地目录安装（开发调试）
dsh plugin --profile web add "file:./dsh-cordis-universal-adapter"

平面说明：Host 组合层

本插件不是 Agent（不参与对话主循环），也不是工具本身——它是一个 Host 组合层的连接器：

- Inbound（正向）：连接外部 MCP 服务器（stdio / Streamable HTTP），listTools() 后把每个 MCP 工具
注册为 ctx.tools 中的 DSH 工具（命名 mcp::）；加载 Agent Plugins 1.0 包时，
解析 plugin.json + skills/*/SKILL.md + mcp.json，把 Skill 描述注入系统提示词扩展点。
- Outbound（反向）：通过 ctx.tools.schemas() 枚举已注册工具，注册到 McpServer，经 serveStdio（或 HTTP）暴露给任意 MCP 客户端（命名 dsh:）。
- 路由（可选）：语义路由通过 ctx.llm 的带 tools 参数的 chat 接口（function calling）为任务排序工具，失败退化为 prompt-based 选择；默认关闭，开启后每次路由产生一次 LLM 调用。
- 生命周期：所有连接由状态机（start / stop / update）管理，update 时"断开旧 → listTools → 注销旧 → 注册新"，与 DSH HMR 协同；卸载时经 ctx.effect 全部回收。

支持的 DSH 版本区间

| 依赖 | 版本区间 |
| @deepseek-ai/cordis | >=0.1.0（peerDependency） |
| @deepseek-ai/dsh-tools | >=0.1.0（peerDependency） |
| Node.js | >=22.19 |

⚠️ Developer Preview 破坏性变更警告：@deepseek-ai/dsh-tools 与 MCP 均处于 Developer Preview 阶段，接口可能破坏性变更。本插件在 0.1.x 内锁定已验证的 API 形态（见 docs/DESIGN.md §14 真实 API 对齐修正与 §15 真实运行时验证发现）；依赖升级导致签名变化时，请关注 CHANGELOG 中的迁移说明。

ℹ️ 已在 dsh 0.1.0-rc.6 实测通过：插件挂载进配置树、真实连接 filesystem MCP 服务器（注册 14 个工具）、 Agent 调用其工具返回真实结果、单服务器故障隔离。注意 dsh bundle 要求 package.json 中 dsh.bundle 为对象形式（{ "patch": "./cordis.patch.yml" }），且 patch 文件为顶层 YAML 数组语法。

配置字段表

cordis.patch.yml 插件段（完整示例见仓库内 cordis.patch.yml）：

| 字段 | 类型 | 默认值 | 必填 | 说明 |
| servers[] | array | [] | 否 | 外部 MCP 服务器列表 |
| servers[].id | string | — | 是 | 唯一标识（[A-Za-z0-9_-]），用于工具命名空间与状态跟踪 |
| servers[].transport | 'stdio' \| 'http' | — | 是 | 传输类型 |
| servers[].command | string | — | stdio 时必填 | 子进程命令（如 npx） |
| servers[].args | string[] | [] | 否 | 子进程参数 |
| servers[].env | record | — | 否 | 附加环境变量（凭据不落日志） |
| servers[].url | string | — | http 时必填 | Streamable HTTP 端点 |
| servers[].headers | record | — | 否 | 静态请求头（支持 ${ENV_VAR} 插值） |
| servers[].requestTimeoutMs | number | 30000 | 否 | callTool/listTools 超时 |
| servers[].connectTimeoutMs | number | 10000 | 否 | 连接握手超时 |
| pluginDirs[] | array | [] | 否 | Agent Plugins 1.0 包目录 |
| export.enabled | boolean | false | 否 | 是否反向导出 DSH 工具 |
| export.transport | 'stdio' \| 'http' | 'stdio' | 否 | 导出传输 |
| export.name | string | 'dsh-export' | 否 | 导出服务器名 |
| export.namespace | string | 'dsh' | 否 | Outbound 工具前缀 |
| export.httpPort | number | 0 | 否 | HTTP 端口（0=随机） |
| export.tools | string[] | — | 否 | 显式导出清单（仅当 schemas() 为空时生效的退化选项） |
| router.enabled | boolean | false | 否 | 语义路由开关（开启产生 LLM 开销） |
| router.mode | 'auto' \| 'tools' \| 'prompt' | 'auto' | 否 | auto=优先 tools 失败退 prompt |
| router.maxTools | number | 10 | 否 | 返回工具数上限 |
| router.minScore | number | 0 | 否 | 分数下限过滤 |
| router.provider / router.model | string | env DSH_ROUTER_PROVIDER / DSH_ROUTER_MODEL | 否 | 路由 LLM 路由 |
| naming.conflictStrategy | 'error' \| 'prefix' | 'prefix' | 否 | 工具名冲突策略 |
| naming.prefixSeparator | string | ':' | 否 | 命名空间分隔符 |
| schema.strict | boolean | false | 否 | true=无法转换的 JSON Schema 拒绝注册；false=降级宽松校验 |
| logging.level | 'silent' \| 'error' \| 'warn' \| 'info' \| 'debug' | 'info' | 否 | 日志级别 |

端到端示例：加载社区 filesystem MCP 服务器

cordis.patch.yml
plugins:
dsh-cordis-universal-adapter:
servers:
- id: filesystem
transport: stdio
command: npx
args: ["-y", "@modelcontextprotocol/server-filesystem", "/tmp"]

启动后，DSH 中将出现 mcp:filesystem:read_directory、mcp:filesystem:write_file 等工具， Agent 可以直接调用：

用户：读取 /tmp 目录下有哪些文件 Agent → 调用 mcp:filesystem:read_directory({ path: "/tmp" }) → 返回目录列表

dsh --profile web --dump-config # 确认插件正确挂载进配置树

反向导出示例：把 DSH 原生工具导出为 MCP 服务器

plugins:
dsh-cordis-universal-adapter:
export:
enabled: true
transport: stdio
namespace: dsh

DSH 中所有已注册工具（ctx.tools.schemas()）将以 dsh: 暴露。任意 MCP 客户端（Claude Desktop、其他 Harness、@modelcontextprotocol/inspector）连接该 stdio 端点后即可调用：

在 DSH 进程内加载本插件（export.enabled=true），然后在外部：
npx @modelcontextprotocol/inspector # 选择 stdio 模式连接 DSH 进程

独立调试可用仓库自带脚本（不依赖 DSH 运行时，演示转换链路）：

npx tsx scripts/export-mcp.ts # 启动 stdio 演示服务器（dsh:echo / dsh:add / dsh:fail）

开发调试

npm install
npm run typecheck # tsc --noEmit（含 tests/scripts）
npm run lint # ESLint（零警告）
npm run test # Vitest（核心模块覆盖率 ≥ 80%）
npm run build # 产出 lib/
npm pack --dry-run # 检查 tarball 只含 lib/ + README + LICENSE

调试要点：

- 日志脱敏：env / headers / URL 凭据永不写入日志；Authorization 用 ${ENV_VAR} 插值。
- 状态查看：监听 universal-adapter/status 事件（ctx.on）可跟踪每个 server 的连接状态机。
- 单服务器故障隔离：一个外部 MCP 服务器连接失败只影响自身（状态 error），不阻断其他服务器与导出。
- HMR：插件 apply 重跑时旧 ctx.effect cleanup 自动执行；配置热更优先走 update()。

已知限制

1. JSON Schema → DSH DSL 仅支持常用子集：$ref / 循环引用 / 复杂 oneOf 降级为宽松校验（schema.strict: false 时工具仍注册，入参不校验）。
2. Streamable HTTP 认证：仅支持静态头（Bearer token），OAuth 动态流程不在 0.1 范围。
3. 反向导出返回值：DSH 工具返回值必须是 JSON 可序列化值；二进制 / 流式输出不支持。
4. 路由开销：router.enabled: false 时零 LLM 开销；开启后每次路由一次 LLM 调用，且不缓存。
5. 跨 server 工具名唯一性：依赖 serverId 前缀保证；serverId 冲突会导致注册报错（按 naming.conflictStrategy 处理）。
6. 不实现沙箱：外部 MCP 服务器的隔离依赖其宿主进程边界（stdio 子进程 / 远程 HTTP 服务）。

GitHub 仓库发布步骤

1. 推送公开 GitHub 仓库（helibeiqi/dsh-cordis-universal-adapter）
2. 添加 topic：dsh-plugin、deepseek-harness、agent-plugin、mcp、cordis
3. npm login && npm publish
4. 在 DSH 社区 Discussions 宣布发布

License

MIT © dsh-cordis-universal-adapter contributors