anthonyyu-verkada/dsh-mcp-client-plus

dsh-mcp-client-plus

一个用于 DeepSeek Harness（dsh）的 MCP 客户端桥接，派生自内置的 @deepseek-ai/dsh-mcp-client，并扩展了其自身文档中列为延后实现的能力。

上游桥接所做的一切，它依然照做：每个 MCP 服务器一个插件实例，工具注册为原生 mcp____ 工具，serverName 命名空间，工具列表变更刷新，以及带指数退避的重连。

它新增的内容：

| | 能力 | 上游 |
|---|---|---|
| 1 | OAuth 2.1 — 发现、RFC 7591 动态客户端注册、PKCE、刷新轮换、浏览器重定向 | 仅静态 headers |
| 2 | connectTimeoutMs — 限制 initialize | 继承 SDK 的 60 秒默认值 |
| 3 | discoveryTimeoutMs — 限制每个 tools/list 分页 | 完全不传超时 |
| 4 | 通过环境变量提供密钥 — tokenEnv、headerEnv | 在 cordis.yml 中内联原始值 |
| 5 | maxAttempts: 0 — 无限重连 | 10 次后永久放弃 |
| 6 | mcp_status 工具 — 从会话内部获取每个服务器的实时状态 | 仅日志输出 |

为什么是这六项

这些并非臆测的功能。每一项都对应上游桥接的一个具体故障，而且前五项在编写此分支之前已在真实 harness 上复现过。

上游桥接可能永久放弃且永不恢复。 启动失败时，它会以退避方式重试，然后注销并记录 giving up after 10 consecutive failed reconnect attempts — tools unregistered; reload the plugin or restart the Host to reconnect。没有任何自愈机制，而且该故障仅在宿主 stderr 中可见。在诊断出此问题的 harness 中，五个受 OAuth 保护的服务器就这样死掉了——凭据有效、端点可达、零工具——而两个没有 Authorization 头的服务器却工作正常。

OAuth 是其中大部分问题的根源。 由于上游只接受静态头，OAuth 服务器必须由带外桥接来提供令牌——通常是一个配置表达式，在每次加载时通过 shell 调用另一个 agent 的凭据存储。这条路径很脆弱（Keychain ACL 拒绝会被静默吞掉，变成一个空的 Bearer  头），而且无法刷新。auth: oauth 完全移除了这个桥接：SDK 执行发现、注册和刷新，首次连接时会打印一个授权 URL。

超时在两处都不受限制。 listToolsUncached 完全没有传 RequestOptions，因此每个 tools/list 分页都会等待 SDK 的 60 秒默认值，而 connect() 对 initialize 也是如此。单个无响应的服务器可能让插件激活停滞数分钟。现在两者都是显式且可配置的。

从会话内部看不到已死的服务器。 mcp_status 会报告每个已配置的服务器、其状态、已注册工具数量、重试位置以及最后的错误——因此“为什么这个工具不见了”无需阅读宿主日志即可回答。

安装

npx -p @deepseek-ai/dsh dsh plugin --profile web add github:anthonyyu-verkada/dsh-mcp-client-plus

然后在你的 profile 补丁（~/.dsh/profiles/web/cordis.patch.yml）中声明你的服务器，并重启 dsh。

随附的 cordis.patch.yml 有意留空：桥接器是每个服务器一个实例，因此打包的补丁无法得知你的服务器。请参阅该文件中的注释以获取可直接复制粘贴的行模板。

快速开始

受 OAuth 保护的远程服务器

- insert:
- id: mcp-linear
name: 'dsh-mcp-client-plus'
config:
transport: streamable-http
serverName: linear
url: https://mcp.linear.app/mcp
auth: oauth
reconnect:
maxAttempts: 0

首次连接时，宿主会记录一个授权 URL 并打开你的浏览器。同意后，回环监听器会捕获授权码，令牌被存储，工具随即注册。令牌会自动刷新，轮换也会被持久化。

凭据存放在 $DSH_HOME/.dsh/mcp-client-plus-oauth.json，权限模式为 0600，以资源服务器 URL 为键。请将该文件视为机密。

从环境变量获取令牌

- insert:
- id: mcp-tracecat
name: 'dsh-mcp-client-plus'
config:
transport: streamable-http
serverName: tracecat
url: https://tracecat.example.com/mcp
auth: bearer
tokenEnv: TRACECAT_MCP_TOKEN

令牌本身绝不会出现在配置中。auth: none 完全不发送 Authorization 头。

本地 stdio 服务器

- insert:
- id: mcp-terraform
name: 'dsh-mcp-client-plus'
config:
transport: stdio
serverName: terraform
command: /Users/you/go/bin/terraform-mcp-server
args: [stdio]
env:
TFE_ADDRESS: https://app.terraform.io
TFE_TOKEN: ''

从内置客户端迁移

替换每个现有行上的 name，并移除任何 header 表达式桥接：

- id: mcp-linear
-      name: '@deepseek-ai/dsh-mcp-client'
+      name: 'dsh-mcp-client-plus'
config:
transport: streamable-http
serverName: linear
url: https://mcp.linear.app/mcp
-        headers:
-          Authorization: !!js >-
-            (function () { try { return 'Bearer ' + ...keychain read... } catch (e) { return ''; } })()
+        auth: oauth

不要为同一个 serverName 同时运行两个桥接器：每个桥接器都持有自己的命名空间预留，第二次注册会因公共工具名重复而失败。

配置参考

两种传输方式共有的字段：

| 字段 | 默认值 | 含义 |
|---|---|---|
| serverName | 必填 | mcp____ 的命名空间；[A-Za-z0-9_-]{1,32}，在活动实例中唯一 |
| connectTimeoutMs | 15000 | 单次连接尝试的时限 |
| discoveryTimeoutMs | 30000 | 单页 tools/list 的时限 |
| toolCallTimeoutMs | 60000 | 单次工具调用的时限 |
| failOnStartupError | false | 首次尝试失败时拒绝插件激活 |
| reconnect.enabled | true | 连接丢失后重新连接 |
| reconnect.initialDelayMs | 500 | 首次退避延迟；每连续失败一次翻倍 |
| reconnect.maxDelayMs | 30000 | 退避上限，也是重置中断预算的正常运行时间 |
| reconnect.maxAttempts | 10 | 每次中断的上限。0 表示无限重试 |

仅适用于 transport: streamable-http：

| 字段 | 默认值 | 含义 |
|---|---|---|
| url | 必填 | MCP 端点 |
| auth | none | none、bearer 或 oauth |
| headers | {} | 字面量请求头值 |
| headerEnv | {} | 请求头名称 → 环境变量名称 |
| tokenEnv | — | 保存 bearer 令牌的环境变量 |
| oauth.scopes | — | 要请求的作用域 |
| oauth.callbackPath | /callback | 回环重定向路径 |
| oauth.authorizationTimeoutMs | 300000 | 等待人工操作的时间 |
| oauth.openBrowser | true | 启动平台浏览器 |
| oauth.storePath | $DSH_HOME/.dsh/mcp-client-plus-oauth.json | 凭据存储 |

对于无头或远程主机，请设置 oauth.openBrowser: false —— 授权 URL 始终会被记录，因此你可以在任何有浏览器的地方打开它。授权服务器必须接受 http://127.0.0.1:/... 回环重定向，这是 MCP 规范对本地客户端的要求。

mcp_status 工具

每个作用域注册一个 mcp_status 工具，报告每个服务器：

linear [connected] · 42 tools · auth=oauth · streamable-http
hex [failed] · 0 tools · auth=oauth · streamable-http · last error: giving up after 10 consecutive failed reconnect attempts …

传入 { "server": "hex" } 进行筛选，或不带参数调用以列出全部。

兼容性

- DeepSeek Harness >=0.1.5-rc.1 =24.0.0。
- 未声明任何 npm dependencies 或 peerDependencies，与其他 dsh 插件使用的约定一致：harness 自身的 @deepseek-ai/ 包和 @modelcontextprotocol/sdk 从配置文件的 node_modules 中解析。
- 上游 master（0.1.6-alpha.2）已迁移到 @modelcontextprotocol/client v2，并需要 @deepseek-ai/dsh-mcp-resources；此分支基于 dsh-v0.1.5-rc.2。参见 PROVENANCE.md。

与 dsh-mcp-manager 的关系

hyqhyq3/dsh-mcp-manager 是一个功能更全面的替代方案，如果你想要 GUI，它是一个不错的选择：设置 → MCP 页面、工作区作用域服务器，以及按需工具代理。此分支则保持为内置桥接的直接替代品 —— 相同的每服务器一行组合模型、相同的工具名称、没有客户端部分，也没有 GUI。

开发

npm run build      # tsc -> lib/  (lib/ is committed: dsh loads it directly)
npm test           # build first; runs node --test over tests//.test.js

由于该插件未声明任何依赖，构建和测试会解析
从 harness 安装中获取 @deepseek-ai/ 和 @modelcontextprotocol/sdk。构建前将
node_modules 指向其中一个：

ln -s "$(npm root -g)/@deepseek-ai/dsh/node_modules" node_modules

跨三个层级的 55 个测试：

- 单元测试 —— 配置与重连策略（包括 maxAttempts: 0）、请求头与密钥解析、OAuth 提供者的持久化与凭证失效，以及通过真实 HTTP 驱动的回环重定向监听器。
- 传输端到端 —— 通过传输工厂，经由 stdio 连接真实 MCP 服务器：连接、tools/list 和 tools/call。此外还断言无响应的服务器会在 connectTimeoutMs 内失败，而非 SDK 默认的 60 秒，并且 bearer 和 headerEnv 凭证能够到达传输层。
- OAuth 端到端 —— 一个 OAuth 2.1 受保护的 MCP 服务器夹具，它会自动批准授权、自行验证 PKCE S256，并记录每个请求。该测试套件驱动真实流程：401 触发发现、动态客户端注册和授权；授权码交换在服务端经过 PKCE 验证；随后存储的令牌无需重新授权即可连接；服务端返回 401 时通过刷新轮换后的 refresh token 恢复，而非重新提示。断言针对服务器自身的请求追踪运行。
- Harness 集成 —— 将 apply() 挂载到真实的 Cordis 上下文，并针对真实的 ctx.tools 注册表：工具注册与公开命名、mcp_status 报告与渲染、销毁时注销所有内容、重复 serverName 拒绝，以及 failOnStartupError 拒绝激活。

已知限制

- 仅支持工具。 MCP 的 resources 和 prompts 未被桥接，与上游相同。
- 新服务器每个进程仅一次授权。 重定向由插件实例拥有的回环监听器接收；如果主机是无头的，你需要在任何能访问所打印 URL 的浏览器中完成流程。
- OAuth 令牌以明文存储在 0600 权限的 JSON 文件中。静态 bearer 令牌从环境读取，从不持久化。
- connectTimeoutMs 限制的是 initialize，而非整个 TCP/TLS 建立过程；在请求计时器生效之前，挂起的 DNS 查询仍可能耗时更久。
- maxAttempts 默认为 10，与上游一致。 设置为 0 可获得永久重试行为；默认值被有意保留，以免该分支悄然改变现有部署的资源占用情况。

许可证

MIT。部分内容源自 DeepSeek Harness（packages/mcp/mcp-client，MIT），版本为 dsh-v0.1.5-rc.2。参见 LICENSE 和 PROVENANCE.md。