6.0 KiB
@deepseek-ai/dsh-mcp-client
English | 中文
MCP 客户端桥接插件：连接外部 Model Context Protocol 服务器，把它们的工具注册到 ctx.tools，使模型能够通过服务器限定名称（mcp__<serverName>__<rawName>）将其作为原生工具使用。
用法
cordis.yml 中每个 MCP 服务器使用一个插件实例：
- id: mcp-github
name: '@deepseek-ai/dsh-mcp-client'
config:
serverName: github
transport: stdio
command: npx
args: ['-y', '@modelcontextprotocol/server-github']
env:
GITHUB_TOKEN: !!js process.env.GITHUB_TOKEN
- id: mcp-web
name: '@deepseek-ai/dsh-mcp-client'
config:
serverName: web
transport: streamable-http
url: http://localhost:3000/mcp
headers:
Authorization: !!js '`Bearer ${process.env.MCP_TOKEN}`'
模型会看到 mcp__github__create_issue、mcp__web__search 等工具，这与 Claude Code 和 Codex 使用的服务器限定形状相同。HMR 会热替换：编辑配置项会触发断开 + 重新连接，无需重启进程；serverName 不变时会生成完全相同的工具名称。
配置
| 字段 | 传输 | 必填 | 描述 |
|---|---|---|---|
transport |
两者 | 是 | "stdio" 或 "streamable-http" |
serverName |
两者 | 是 | 该服务器面向模型工具名称的 namespace；[A-Za-z0-9_-]{1,32}，在存活实例中唯一 |
command |
stdio | 是 | 要 spawn 的可执行文件 |
args |
stdio | 否 | 传给命令的参数 |
env |
stdio | 否 | 合并到已清理环境之上的额外环境变量 |
cwd |
stdio | 否 | 子进程工作目录 |
url |
http | 是 | MCP 服务器 URL |
headers |
http | 否 | 额外标头（例如认证 token） |
toolCallTimeoutMs |
两者 | 否 | 每次 callTool 调用的超时（默认 60000） |
工具命名
每个 MCP 工具都有两个名称：通过 tools/call 在协议上传送的原始 MCP 名称，以及公开名称 mcp__<serverName>__<rawName>，后者注册到 ctx.tools。公开名称会规范化为 DeepSeek 函数名称契约（64 个字符、[A-Za-z0-9_-]）；如果替换或截断改变名称，就会追加 (serverName, rawName) 的确定性 12 位十六进制 hash，确保不同工具绝不会折叠为同一个名称。名称是 (serverName, rawName) 的纯函数：连接顺序、重新同步和其他服务器永远不会重命名工具。
- 发布相同原始名称（例如
search）的两个服务器会在各自 namespace 下共存。 - 存活实例中的重复
serverName会使后加载的插件实例失败。 - 服务器在工具列表中两次列出同一工具名称时，该列表会作为无效工具列表被拒绝。
- 外部注册抢占该服务器 namespace 时，会回滚整个世代（绝不保留部分集合），并高声报错。
行为
- 连接时：
listTools()→ 通过ctx.tools.register()使用各自公开名称注册每个工具。 - 监听
notifications/tools/list_changed→ 重新同步；同步失败时保留上一世代的注册。 - 工具执行：
client.callTool({ name: rawName, arguments }, { signal })，支持超时 + 中止；公开名称绝不会发给服务器。 - 规范成功值是
{ content: JsonValue[], structuredContent? }；完整的 JSON MCP 块会保留给编程调用方。受支持且已声明的outputSchema会验证structuredContent；不受支持的 schema 词汇会回退为不受约束的JsonValue。 - 原生／模型渲染保留现有文本投影：文本块以换行连接，图片、音频、资源和不受支持的块会变成占位符。
- 断开／崩溃时：注销所有工具；不自动重新连接。
消费的服务
| 服务 | 用途 |
|---|---|
ctx.tools |
注册／注销 MCP 工具 |
模型体验
已发现的 MCP 工具
模型看到的内容
初始发现成功后，每个已声明的 MCP 工具都会显示为名为 mcp__<serverName>__<rawName>（或其确定性规范化形式）的原生工具，并携带服务器提供的描述和输入 schema。成功的重新同步会替换整个世代；插件释放会移除它。
Token 影响
工具注册期间，每次请求都会承担数据相关的 schema 成本。重新同步会替换而非累积 schema，服务器限定名称也会为每个工具定义和调用增加 token。
KV Cache 影响
只要已发现工具集合及其 schema 不变，前缀就保持稳定。增加、移除、重命名或更改工具的重新同步会替换定义，并可能使从第一个变化的 schema token 起的复用失效。
工具调用历史与结果
模型看到的内容
公开工具名称和 JSON 参数会保留在 assistant 历史中。文本结果块会以换行连接为一个保留的原生文本结果；图片、音频、资源和不受支持的块在其中变为简短占位符。它们的完整 JSON 块及可选结构化内容保留在执行局部的规范值中；MCP isError 会通过注册表的错误路径拒绝调用。
Token 影响
参数和映射后的文本会保留到压缩发生时。二进制与资源载荷会被丢弃，而不会加入上下文。
KV Cache 影响
仅追加；新可见内容位于可复用请求前缀之后，不会使现有 KV-cache 配置项失效。
已知限制与暂缓事项
- 初始发现是异步的：插件加载不会等待连接和
listTools()，因此在启动或 HMR 后立即开始的轮次可能在 MCP 工具注册前完成组装。 - 只桥接 MCP 的工具能力：资源和提示词没有 harness 消费表层，暂缓实现。
- 崩溃恢复需要手动触发：传输关闭会注销服务器工具，但重新连接需要 HMR 重载或重启 harness。
- 原生非文本渲染有损：图片、音频与资源载荷在模型上下文中会变成占位符，即使执行局部的规范值保留了其 JSON 块。更丰富的原生多媒体投影暂缓实现。
- 不强制执行不受支持的 MCP 输出 schema：已声明 schema 使用 harness 子集之外的词汇时，
structuredContent会回退到JsonValue。