deepseek-harness/packages/mcp/mcp-client/README.zh.md

@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。