@deepseek-ai/dsh-mcp-client 0.0.1-rc.1

package/LICENSE

@@ -0,0 +1,28 @@
+BSD 3-Clause License
+
+Copyright (c) 2026, DeepSeek
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its
+   contributors may be used to endorse or promote products derived from
+   this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

package/README.i18n.yaml

@@ -0,0 +1,6 @@
+# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
+# side as of the last confirmed-consistent state. Both languages carry equal authority;
+# after editing either side, bring the other along and re-record with:
+#   pnpm run verify-translation-pairing --write packages/mcp/mcp-client/README.md
+README.md: 76d1271f6f7a3e9c959bdcf5e969906f25563c56
+README.zh.md: b2da1119af3a8d52761a5040059e7a9d922aa567

package/README.md

@@ -0,0 +1,109 @@
+# @deepseek-ai/dsh-mcp-client
+
+English | [中文](README.zh.md)
+
+MCP client bridge plugin: connects to external [Model Context Protocol](https://modelcontextprotocol.io/) servers and registers their tools on `ctx.tools`, making them available to the model as native tools under server-qualified names (`mcp__<serverName>__<rawName>`).
+
+## Usage
+
+One plugin instance per MCP server in `cordis.yml`:
+
+```yaml
+- 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}`'
+```
+
+The model sees `mcp__github__create_issue`, `mcp__web__search`, … — the same server-qualified shape Claude Code and Codex use. HMR hot-swaps: editing the entry triggers disconnect + reconnect without process restart; an unchanged `serverName` reproduces identical tool names.
+
+## Config
+
+| Field | Transport | Required | Description |
+|---|---|---|---|
+| `transport` | both | yes | `"stdio"` or `"streamable-http"` |
+| `serverName` | both | yes | Namespace for this server's model-facing tool names; `[A-Za-z0-9_-]{1,32}`, unique across live instances |
+| `command` | stdio | yes | Executable to spawn |
+| `args` | stdio | no | Arguments passed to the command |
+| `env` | stdio | no | Extra env vars merged on top of scrubbed ambient env |
+| `cwd` | stdio | no | Working directory for the child process |
+| `url` | http | yes | MCP server URL |
+| `headers` | http | no | Extra headers (e.g. auth tokens) |
+| `toolCallTimeoutMs` | both | no | Timeout per `callTool` invocation (default 60000) |
+| `failOnStartupError` | both | no | Reject plugin activation when initial connection or tool synchronization fails (default `false`) |
+
+## Tool naming
+
+Every MCP tool has two names: the raw MCP name (sent on the wire in `tools/call`) and the public name `mcp__<serverName>__<rawName>` registered on `ctx.tools`. Public names are normalized to the DeepSeek function-name contract (64 chars, `[A-Za-z0-9_-]`); when replacement or truncation changes the name, a deterministic 12-hex-char hash of `(serverName, rawName)` is appended so distinct tools never collapse into one name. Names are pure functions of `(serverName, rawName)` — connection order, re-syncs, and other servers never rename a tool.
+
+- Two servers publishing the same raw name (e.g. `search`) coexist under their namespaces.
+- A duplicate `serverName` across live instances fails the later plugin instance at load.
+- A server listing the same tool name twice is rejected as an invalid tool list.
+- A foreign registration squatting on this server's namespace rolls back the whole generation (never a partial set), with a loud error.
+
+## Behavior
+
+- On connect: plugin activation awaits `listTools()` and registers each tool via `ctx.tools.register()` under its public name before the composition starts its first turn. Initial connection, discovery, or registration failure is always logged; it rejects activation when `failOnStartupError` is true and otherwise activates with no tools.
+- Listens for `notifications/tools/list_changed` → re-syncs; a fetch-phase failure keeps the previous generation registered, while a registration conflict rolls back the attempted generation and leaves no tools from that server.
+- Tool execute: `client.callTool({ name: rawName, arguments }, { signal })` with timeout + abort support—the public name is never sent to the server.
+- Canonical success is `{ content: JsonValue[], structuredContent? }`; complete JSON MCP blocks survive for programmatic callers. A supported advertised `outputSchema` validates `structuredContent`; unsupported schema vocabulary falls back to unconstrained `JsonValue`.
+- Native/model rendering keeps the existing text projection: text blocks join with newlines while image, audio, resource, and unsupported blocks become placeholders.
+- On disconnect/crash: no auto-reconnect. Registered tools remain until plugin disposal or a successful re-sync, and calls can fail against the closed transport; reload with HMR or restart the Host to reconnect.
+
+## Services consumed
+
+| Service | Usage |
+|---|---|
+| `ctx.tools` | Register/unregister MCP tools |
+
+## Model Experience
+
+### Discovered MCP tools
+
+#### What the model sees
+
+After initial discovery succeeds, each advertised MCP tool appears as a native tool named `mcp__<serverName>__<rawName>` (or its deterministic normalized form), with the server-provided description and input schema. A successful re-sync replaces the generation; plugin disposal removes it.
+
+#### Token effect
+
+Data-dependent schema cost is paid on every request while the tools are registered. Re-sync replaces rather than accumulates schemas, and the server-qualified name adds tokens to every tool definition and call.
+
+#### KV Cache effect
+
+Prefix-stable while the discovered tool set and schemas are unchanged. A re-sync that adds, removes, renames, or changes a tool replaces definitions and may invalidate reuse from the first changed schema token.
+
+### Tool-call history and results
+
+#### What the model sees
+
+The public tool name and JSON arguments remain in assistant history. Text result blocks are joined with newlines into one retained Native text result; image, audio, resource, and unsupported blocks become short placeholders there. Their full JSON blocks and optional structured content remain in the execution-local canonical value, and MCP `isError` rejects the call through the registry's error path.
+
+#### Token effect
+
+Arguments and mapped text are retained until compaction. Binary and resource payloads are discarded rather than added to context.
+
+#### KV Cache effect
+
+Append-only; newly visible content follows the reusable request prefix and does not invalidate existing KV-cache entries.
+
+## Known Limitations and Deferred Work
+
+- **Tools are the only bridged MCP capability** — Resources and Prompts have no harness consumption surface and are deferred.
+- **Startup timeout is inherited from the MCP SDK** — DSH does not yet expose a connection/discovery timeout. Each initialize or paginated `tools/list` request uses the SDK's 60-second default, so an unresponsive server or cursor chain can delay both activation and teardown while the initial synchronization settles.
+- **Crash recovery is manual** — transport closure does not auto-reconnect; registered tools can remain visible but fail against the closed transport until an HMR reload or Host restart.
+- **Native non-text rendering is lossy** — image, audio, and resource payloads become placeholders in model context even though the execution-local canonical value preserves their JSON blocks. Richer Native multimedia projection is deferred.
+- **Unsupported MCP output schemas are not enforced** — `structuredContent` falls back to `JsonValue` when the advertised schema uses vocabulary outside the harness subset.

package/README.zh.md

@@ -0,0 +1,109 @@
+# @deepseek-ai/dsh-mcp-client
+
+[English](README.md) | 中文
+
+MCP 客户端桥接插件：连接外部 [Model Context Protocol](https://modelcontextprotocol.io/) 服务器，把它们的工具注册到 `ctx.tools`，使模型能够通过服务器限定名称（`mcp__<serverName>__<rawName>`）将其作为原生工具使用。
+
+## 用法
+
+`cordis.yml` 中每个 MCP 服务器使用一个插件实例：
+
+```yaml
+- 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） |
+| `failOnStartupError` | 两者 | 否 | 初始连接或工具同步失败时拒绝插件激活（默认 `false`） |
+
+## 工具命名
+
+每个 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()` 以公开名称注册每个工具。初始连接、发现或注册失败始终会记录日志；`failOnStartupError` 为 true 时拒绝激活，否则插件仍会激活但不注册工具。
+- 监听 `notifications/tools/list_changed` → 重新同步；获取阶段失败时保留上一世代的注册，注册冲突则会回滚本次尝试的世代，并且不保留该服务器的任何工具。
+- 工具执行：`client.callTool({ name: rawName, arguments }, { signal })`，支持超时 + 中止；公开名称绝不会发给服务器。
+- 规范成功值是 `{ content: JsonValue[], structuredContent? }`；完整的 JSON MCP 块会保留给编程调用方。受支持且已声明的 `outputSchema` 会验证 `structuredContent`；不受支持的 schema 词汇会回退为不受约束的 `JsonValue`。
+- Native／模型渲染保留现有文本投影：文本块以换行连接，图片、音频、资源和不受支持的块会变成占位符。
+- 断开／崩溃时：不自动重新连接。已注册工具会一直保留到对插件执行 dispose（资源释放）或成功重新同步，针对已关闭传输的调用可能失败；请通过 HMR 重新加载或重启 Host 来重新连接。
+
+## 消费的服务
+
+| 服务 | 用途 |
+|---|---|
+| `ctx.tools` | 注册／注销 MCP 工具 |
+
+## 模型体验
+
+### 已发现的 MCP 工具
+
+#### 模型看到的内容
+
+初始发现成功后，每个已声明的 MCP 工具都会显示为名为 `mcp__<serverName>__<rawName>`（或其确定性规范化形式）的原生工具，并携带服务器提供的描述和输入 schema。成功的重新同步会替换整个世代；对插件执行 dispose 会移除该世代。
+
+#### Token 影响
+
+工具注册期间，每次请求都会承担数据相关的 schema 成本。重新同步会替换而非累积 schema，服务器限定名称也会为每个工具定义和调用增加 token。
+
+#### KV Cache 影响
+
+只要已发现工具集合及其 schema 不变，前缀就保持稳定。增加、移除、重命名或更改工具的重新同步会替换定义，并可能使从第一个变化的 schema token 起的复用失效。
+
+### 工具调用历史与结果
+
+#### 模型看到的内容
+
+公开工具名称和 JSON 参数会保留在 assistant 历史中。文本结果块会以换行连接为一个保留的 Native 文本结果；图片、音频、资源和不受支持的块在其中变为简短占位符。它们的完整 JSON 块及可选结构化内容保留在执行局部的规范值中；MCP `isError` 会通过注册表的错误路径拒绝调用。
+
+#### Token 影响
+
+参数和映射后的文本会保留到压缩（compaction）发生时。二进制与资源载荷会被丢弃，而不会加入上下文。
+
+#### KV Cache 影响
+
+仅追加；新可见内容位于可复用请求前缀之后，不会使现有 KV-cache 条目失效。
+
+## 已知限制与暂缓事项
+
+- **只桥接 MCP 的工具能力**：资源和提示词没有 harness 消费接口，暂缓实现。
+- **启动超时继承自 MCP SDK**：DSH 尚未公开连接／发现超时。每次 initialize 请求或分页 `tools/list` 请求都使用 SDK 默认的 60 秒，因此在初始同步完成期间，无响应的 server 或 cursor chain 可能同时延迟激活与 teardown。
+- **崩溃恢复需要手动触发**：传输关闭后不会自动重新连接；已注册工具可能仍然可见，但会因传输已关闭而调用失败，直到 HMR 重载或重启 Host。
+- **Native 非文本渲染有损**：图片、音频与资源载荷在模型上下文中会变成占位符，即使执行局部的规范值保留了其 JSON 块。更丰富的 Native 多媒体投影暂缓实现。
+- **不强制执行不受支持的 MCP 输出 schema**：已声明 schema 使用 harness 子集之外的词汇时，`structuredContent` 会回退到 `JsonValue`。

package/lib/index.js

@@ -0,0 +1,381 @@
+import z from "@deepseek-ai/schemastery";
+import { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import { ListToolsResultSchema, ToolListChangedNotificationSchema } from "@modelcontextprotocol/sdk/types.js";
+import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";
+import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";
+import { scrubbedParentEnv } from "@deepseek-ai/dsh-subprocess";
+import { createHash } from "node:crypto";
+import { z as z$1 } from "zod";
+import { assertSupportedJsonSchema } from "@deepseek-ai/dsh-tools";
+//#region lib/types/transport.js
+/**
+* Transport factory: creates the appropriate MCP transport based on the
+* plugin's resolved config. Stdio spawns a child process (with credential
+* scrubbing); Streamable HTTP connects to a URL.
+*
+* @module
+*/
+/**
+* The subprocess seam's scrubbed parent env (credential-shaped and stale
+* `DSH_*` names dropped), plus the spec's explicit env. The MCP SDK owns the
+* actual spawn, so this transport shares the scrub definition rather than the
+* spawn path.
+*/
+function buildChildEnv(extra) {
+	return {
+		...scrubbedParentEnv(),
+		...extra
+	};
+}
+/**
+* Create an MCP transport from the resolved plugin config.
+*
+* @param config - Resolved plugin config discriminated on `transport`.
+* @returns A connected-ready MCP Transport (stdio or Streamable HTTP).
+*/
+function createTransport(config) {
+	switch (config.transport) {
+		case "stdio": return new StdioClientTransport({
+			command: config.command,
+			args: config.args,
+			env: buildChildEnv(config.env),
+			cwd: config.cwd
+		});
+		case "streamable-http": return new StreamableHTTPClientTransport(new URL(config.url), { requestInit: { headers: config.headers } });
+	}
+}
+//#endregion
+//#region lib/types/tools.js
+/**
+* Tool bridge: discovers MCP tools, registers them on the harness ToolRegistry
+* under deterministic server-qualified public names, and handles re-sync when
+* the server's tool list changes.
+*
+* Naming contract (see the mcp-client Agent Note "Naming invariants"): every MCP tool
+* has the stable identity `(serverName, rawName)`; the model-facing public name
+* is `mcp__<serverName>__<rawName>`, normalized to the DeepSeek function-name
+* constraints. The raw name is only ever sent on the wire (`tools/call`); the
+* public name is never parsed to recover it.
+*
+* @module
+*/
+/**
+* DeepSeek function-name contract: at most 64 characters. Wire-protocol
+* constant, not configuration.
+*/
+const MAX_PUBLIC_NAME_LENGTH = 64;
+/** DeepSeek function-name contract: only `[A-Za-z0-9_-]` is allowed. */
+const INVALID_NAME_CHARS = /[^A-Za-z0-9_-]/g;
+/** Hex chars of the SHA-256 identity hash appended on lossy normalization. */
+const HASH_LENGTH = 12;
+/** Raw result record: the bridge owns JSON-value validation after transport. */
+const RawCallToolResultSchema = z$1.record(z$1.string(), z$1.unknown());
+/** List without mutating the SDK's per-page output-validator cache. */
+function listToolsUncached(client, cursor) {
+	return client.request({
+		method: "tools/list",
+		...cursor === void 0 ? {} : { params: { cursor } }
+	}, ListToolsResultSchema);
+}
+/** Call without the SDK pre-validating an output schema the bridge may not support. */
+function callToolUncached(client, rawName, args, exec, opts) {
+	return client.request({
+		method: "tools/call",
+		params: {
+			name: rawName,
+			arguments: args
+		}
+	}, RawCallToolResultSchema, {
+		signal: exec.signal,
+		timeout: opts.toolCallTimeoutMs
+	});
+}
+/**
+* Derive the model-facing public name for one MCP tool.
+*
+* Deterministic pure function of `(serverName, rawName)`: the clean case is
+* `mcp__<serverName>__<rawName>` verbatim. When character replacement or
+* truncation to the DeepSeek function-name contract (64 chars,
+* `[A-Za-z0-9_-]`) changes the name, a 12-hex-char SHA-256 hash of the
+* identity is appended so distinct MCP identities never collapse into the
+* same public name.
+*
+* @param serverName - Stable local namespace from plugin config.
+* @param rawName - The MCP server's own tool name.
+* @returns The globally unique, model-facing ToolRegistry name.
+*/
+function publicToolName(serverName, rawName) {
+	const joined = `mcp__${serverName}__${rawName}`;
+	const normalized = joined.replace(INVALID_NAME_CHARS, "_");
+	if (normalized === joined && normalized.length <= MAX_PUBLIC_NAME_LENGTH) return normalized;
+	const hash = createHash("sha256").update(`${serverName}\0${rawName}`).digest("hex").slice(0, HASH_LENGTH);
+	return `${normalized.slice(0, MAX_PUBLIC_NAME_LENGTH - HASH_LENGTH - 1)}_${hash}`;
+}
+/**
+* Sync the MCP server's tool list into the harness ToolRegistry.
+*
+* Two phases keep the swap safe:
+*
+* 1. Fetch: drain uncached `tools/list` pagination and build the full next
+*    generation of `ToolDefinition`s under public names. Any failure here
+*    (network error, duplicate raw name in the server's list) rejects and
+*    leaves the previous generation registered untouched.
+* 2. Swap: dispose the previous generation, register the new one. A registry
+*    conflict here can only mean a foreign registration squats on this
+*    server's `mcp__<serverName>__` namespace — the partial generation is
+*    rolled back (zero tools from this server) and logged. Initial strict
+*    synchronization may propagate the conflict so its parent transaction
+*    rejects; ordinary clients and later re-syncs return an empty map.
+*
+* @param client - Connected MCP Client instance used to list and call tools.
+* @param ctx - Cordis context providing the `tools` service for registration.
+* @param opts - Bridge options: server namespace and per-call timeout.
+* @param previous - Disposer map from the prior sync generation; disposed
+*   during the swap phase (only after the fetch phase succeeded).
+* @returns A map of registered public tool names to their unregister
+*   disposers — the exact set of live registrations owned by this server.
+*/
+async function syncTools(client, ctx, opts, previous) {
+	const definitions = /* @__PURE__ */ new Map();
+	let cursor;
+	do {
+		const response = await listToolsUncached(client, cursor);
+		for (const tool of response.tools) {
+			const publicName = publicToolName(opts.serverName, tool.name);
+			if (definitions.has(publicName)) throw new Error(`mcp-client(${opts.serverName}): server listed tool "${tool.name}" more than once — invalid tool list`);
+			definitions.set(publicName, {
+				name: publicName,
+				description: tool.description ?? "",
+				parameters: tool.inputSchema,
+				output: createOutput(tool.name, supportedOutputSchema(tool.outputSchema)),
+				execute: createExecutor(client, tool.name, tool.execution?.taskSupport === "required", opts)
+			});
+		}
+		cursor = response.nextCursor;
+	} while (cursor);
+	for (const dispose of previous.values()) dispose();
+	const disposers = /* @__PURE__ */ new Map();
+	try {
+		for (const [publicName, definition] of definitions) disposers.set(publicName, ctx.tools.register(definition));
+	} catch (error) {
+		for (const dispose of disposers.values()) dispose();
+		ctx.logger.error(`mcp-client(${opts.serverName}): tool registration failed, no tools registered: ${String(error)}`);
+		if (opts.registrationFailure === "throw") throw error;
+		return /* @__PURE__ */ new Map();
+	}
+	return disposers;
+}
+/** Keep a supported advertised schema; unsupported MCP vocabulary falls back to JsonValue. */
+function supportedOutputSchema(candidate) {
+	if (candidate === void 0) return void 0;
+	try {
+		assertSupportedJsonSchema(candidate);
+		return candidate;
+	} catch {
+		return;
+	}
+}
+/** Build the canonical result schema and existing Native text projection. */
+function createOutput(rawName, structuredSchema) {
+	return {
+		schema: {
+			type: "object",
+			properties: {
+				content: {
+					type: "array",
+					items: {}
+				},
+				structuredContent: structuredSchema ?? {}
+			},
+			required: structuredSchema === void 0 ? ["content"] : ["content", "structuredContent"],
+			additionalProperties: false
+		},
+		render(_args, value) {
+			return [{
+				type: "text",
+				text: extractText(value.content, rawName)
+			}];
+		}
+	};
+}
+/**
+* Create an execute function for one MCP tool. The executor closes over the
+* raw MCP tool name and sends an uncached `tools/call` request with it (never
+* the public name), with abort signal and timeout, then maps the result to
+* harness ContentBlocks. Owning the raw request prevents the SDK's internal
+* per-page schema cache from pre-validating a different contract.
+*
+* When the MCP server returns `isError: true`, the executor throws so that
+* the ToolRegistry's catch path produces an `isError` result for the model.
+*/
+function createExecutor(client, rawName, taskRequired, opts) {
+	return async (args, exec) => {
+		if (taskRequired) throw new Error(`Tool "${rawName}" requires task-based execution, which this bridge does not support`);
+		const result = await callToolUncached(client, rawName, typeof args === "object" && args !== null ? args : {}, exec, opts);
+		if (!Array.isArray(result.content)) {
+			const rendered = "toolResult" in result ? JSON.stringify(result.toolResult) : "(no output)";
+			const text = typeof rendered === "string" ? rendered : "(no output)";
+			if (result.isError === true) throw new Error(text);
+			return {
+				content: [{
+					type: "text",
+					text
+				}],
+				...result.structuredContent !== void 0 ? { structuredContent: result.structuredContent } : {}
+			};
+		}
+		const content = result.content;
+		const text = extractText(content, rawName);
+		if (result.isError === true) throw new Error(text);
+		return {
+			content,
+			...result.structuredContent !== void 0 ? { structuredContent: result.structuredContent } : {}
+		};
+	};
+}
+/**
+* Extract text from an MCP content array into a single string.
+* - text blocks: join with '\n'
+* - image/audio/resource blocks: replaced with a placeholder
+*
+* Defensive: fields that the MCP spec declares required (mimeType, text) are
+* guarded with fallbacks because this is a network trust boundary.
+*/
+function extractText(mcpContent, toolName) {
+	const parts = [];
+	for (const value of mcpContent) {
+		if (typeof value !== "object" || value === null || Array.isArray(value)) {
+			parts.push("[unsupported content type: unknown]");
+			continue;
+		}
+		const block = value;
+		switch (block.type) {
+			case "text":
+				if (block.text !== void 0) parts.push(block.text);
+				break;
+			case "image":
+				parts.push(`[image: ${block.mimeType ?? "unknown"}, content discarded]`);
+				break;
+			case "audio":
+				parts.push(`[audio: ${block.mimeType ?? "unknown"}, content discarded]`);
+				break;
+			case "resource":
+			case "resource_link":
+				parts.push("[resource: content discarded]");
+				break;
+			default: parts.push(`[unsupported content type: ${block.type}]`);
+		}
+	}
+	return parts.join("\n") || `(${toolName} returned no text content)`;
+}
+//#endregion
+//#region lib/types/index.js
+/**
+* MCP client bridge plugin: connects to an external MCP server and registers
+* its tools on `ctx.tools` under server-qualified public names
+* (`mcp__<serverName>__<rawName>`). Each plugin instance connects to one MCP
+* server; load multiple instances in `cordis.yml` for multiple servers.
+*
+* Namespace plugin (named exports, no default export). Lifecycle is
+* effect-scoped: disposal disconnects from the server, unregisters all tools,
+* and releases the `serverName` namespace reservation. HMR hot-swaps by
+* disposing the old instance and creating a new one; identical `serverName`
+* reproduces identical public tool names.
+*
+* @module @deepseek-ai/dsh-mcp-client
+*/
+/** Cordis plugin name used by loader diagnostics. */
+const name = "mcp-client";
+/** Services required by this plugin. */
+const inject = ["tools"];
+/** Default timeout for individual MCP tool calls (ms). */
+const DEFAULT_TOOL_CALL_TIMEOUT_MS = 6e4;
+/** Valid `serverName`, kept below the public tool-name budget. */
+const SERVER_NAME_PATTERN = /^[A-Za-z0-9_-]{1,32}$/;
+/**
+* Live `serverName` reservations per app, keyed off `ctx.root` (multiple apps
+* in one process — tests — must not see each other's names). A duplicate
+* namespace is a configuration error surfaced at plugin load, never silent
+* shadowing.
+*/
+const activeServerNames = /* @__PURE__ */ new WeakMap();
+const Config = z.union([z.object({
+	transport: z.const("stdio"),
+	serverName: z.string().required().pattern(SERVER_NAME_PATTERN),
+	command: z.string().required(),
+	args: z.array(String).default([]),
+	env: z.dict(String).default({}),
+	cwd: z.string().default(""),
+	toolCallTimeoutMs: z.number().default(DEFAULT_TOOL_CALL_TIMEOUT_MS),
+	failOnStartupError: z.boolean().default(false)
+}), z.object({
+	transport: z.const("streamable-http"),
+	serverName: z.string().required().pattern(SERVER_NAME_PATTERN),
+	url: z.string().required(),
+	headers: z.dict(String).default({}),
+	toolCallTimeoutMs: z.number().default(DEFAULT_TOOL_CALL_TIMEOUT_MS),
+	failOnStartupError: z.boolean().default(false)
+})]);
+/**
+* Connect one MCP server and publish its initial tool generation before activation.
+* This entry remains explicitly `async`: Cordis treats a prototype-bearing
+* ordinary function as a constructor, whose returned Promise is not startup work.
+* @param ctx - plugin context carrying the tool registry.
+* @param config - resolved transport and server namespace configuration.
+* @returns startup readiness after connection and initial tool discovery settle.
+*/
+async function apply(ctx, config) {
+	ctx.effect(() => {
+		let names = activeServerNames.get(ctx.root);
+		if (!names) {
+			names = /* @__PURE__ */ new Set();
+			activeServerNames.set(ctx.root, names);
+		}
+		if (names.has(config.serverName)) throw new Error(`mcp-client: serverName "${config.serverName}" is already in use by another mcp-client instance — pick a unique serverName in cordis.yml`);
+		names.add(config.serverName);
+		return () => void names.delete(config.serverName);
+	}, "mcp-client.serverName");
+	const transport = createTransport(config);
+	const client = new Client({
+		name: "dsh-mcp-client",
+		version: "0.0.1"
+	}, { capabilities: {} });
+	const opts = {
+		registrationFailure: "contain",
+		serverName: config.serverName,
+		toolCallTimeoutMs: config.toolCallTimeoutMs
+	};
+	const ready = (async () => {
+		await client.connect(transport);
+		let disposers = await syncTools(client, ctx, {
+			...opts,
+			registrationFailure: config.failOnStartupError ? "throw" : "contain"
+		}, /* @__PURE__ */ new Map());
+		client.setNotificationHandler(ToolListChangedNotificationSchema, async () => {
+			ctx.logger.info(`mcp-client(${config.serverName}): tool list changed, re-syncing`);
+			try {
+				disposers = await syncTools(client, ctx, opts, disposers);
+			} catch (error) {
+				ctx.logger.error(`mcp-client(${config.serverName}): tool re-sync failed: ${String(error)}`);
+			}
+		});
+		return { getDisposers: () => disposers };
+	})().catch((error) => {
+		ctx.logger.error(`mcp-client(${config.serverName}): startup failed: ${String(error)}`);
+		return {
+			getDisposers: () => /* @__PURE__ */ new Map(),
+			error
+		};
+	});
+	ctx.effect(() => async () => {
+		const outcome = await ready;
+		for (const dispose of outcome.getDisposers().values()) dispose();
+		try {
+			await client.close();
+		} catch {}
+	}, "mcp-client.connection");
+	const outcome = await ready;
+	if ("error" in outcome && config.failOnStartupError) throw new Error(`mcp-client(${config.serverName}): initial connection or tool synchronization failed`, { cause: outcome.error });
+}
+//#endregion
+export { Config, apply, inject, name };

package/lib/invariant.js

@@ -0,0 +1,23 @@
+//#region lib/types/invariant.js
+/**
+* Package-owned invariant companion for `@deepseek-ai/dsh-mcp-client`.
+* @module @deepseek-ai/dsh-mcp-client/invariant
+*/
+const PACKAGE_NAME = "@deepseek-ai/dsh-mcp-client";
+/** Cordis companion plugin name. */
+const name = "mcp-client-invariant";
+/** Service required before the companion can reserve package ownership. */
+const inject = ["invariants"];
+/**
+* No runtime invariant: MCP generations contribute through the tool registry, but the bridge
+* exposes no independent server-to-tool snapshot after an asynchronous resync.
+*/
+const install = () => {};
+/**
+* Register this package's invariant companion.
+* @param ctx - Cordis context carrying the invariant service.
+* @returns the installed registration's disposer after setup succeeds.
+*/
+const apply = (ctx) => Promise.resolve(ctx.invariants.register(PACKAGE_NAME, install));
+//#endregion
+export { apply, inject, name };

package/lib/types/index.d.ts

@@ -0,0 +1,76 @@
+/**
+ * MCP client bridge plugin: connects to an external MCP server and registers
+ * its tools on `ctx.tools` under server-qualified public names
+ * (`mcp__<serverName>__<rawName>`). Each plugin instance connects to one MCP
+ * server; load multiple instances in `cordis.yml` for multiple servers.
+ *
+ * Namespace plugin (named exports, no default export). Lifecycle is
+ * effect-scoped: disposal disconnects from the server, unregisters all tools,
+ * and releases the `serverName` namespace reservation. HMR hot-swaps by
+ * disposing the old instance and creating a new one; identical `serverName`
+ * reproduces identical public tool names.
+ *
+ * @module @deepseek-ai/dsh-mcp-client
+ */
+import type { Context } from '@deepseek-ai/cordis';
+import z from '@deepseek-ai/schemastery';
+export type { McpResult } from './tools.ts';
+/** Cordis plugin name used by loader diagnostics. */
+export declare const name = "mcp-client";
+/** Services required by this plugin. */
+export declare const inject: string[];
+/** Config for connecting to an MCP server via a spawned child process over stdio. */
+export interface StdioConfig {
+    /** Selects child-process stdio transport. */
+    transport: 'stdio';
+    /**
+     * Stable local namespace for this server's model-facing tool names
+     * (`mcp__<serverName>__<rawName>`). Must match `[A-Za-z0-9_-]{1,32}` and be
+     * unique across live mcp-client instances.
+     */
+    serverName: string;
+    /** Executable used to start the server. */
+    command: string;
+    /** Arguments passed directly, without shell interpolation. */
+    args: string[];
+    /** Extra env vars merged on top of scrubbed ambient env. */
+    env: Record<string, string>;
+    /** Working directory for the child process. */
+    cwd: string;
+    /** Per-tool-call timeout in milliseconds. */
+    toolCallTimeoutMs: number;
+    /** Fail plugin activation when the initial connection or tool synchronization fails. */
+    failOnStartupError: boolean;
+}
+/** Config for connecting to an MCP server over Streamable HTTP (SSE). */
+export interface StreamableHttpConfig {
+    /** Selects Streamable HTTP transport. */
+    transport: 'streamable-http';
+    /**
+     * Stable local namespace for this server's model-facing tool names
+     * (`mcp__<serverName>__<rawName>`). Must match `[A-Za-z0-9_-]{1,32}` and be
+     * unique across live mcp-client instances.
+     */
+    serverName: string;
+    /** MCP endpoint URL. */
+    url: string;
+    /** Additional headers attached to MCP requests. */
+    headers: Record<string, string>;
+    /** Per-tool-call timeout in milliseconds. */
+    toolCallTimeoutMs: number;
+    /** Fail plugin activation when the initial connection or tool synchronization fails. */
+    failOnStartupError: boolean;
+}
+/** Configuration for one stdio or Streamable HTTP MCP server. */
+export type Config = StdioConfig | StreamableHttpConfig;
+export declare const Config: z<Config>;
+/**
+ * Connect one MCP server and publish its initial tool generation before activation.
+ * This entry remains explicitly `async`: Cordis treats a prototype-bearing
+ * ordinary function as a constructor, whose returned Promise is not startup work.
+ * @param ctx - plugin context carrying the tool registry.
+ * @param config - resolved transport and server namespace configuration.
+ * @returns startup readiness after connection and initial tool discovery settle.
+ */
+export declare function apply(ctx: Context, config: Config): Promise<void>;
+//# sourceMappingURL=index.d.ts.map

package/lib/types/invariant.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Package-owned invariant companion for `@deepseek-ai/dsh-mcp-client`.
+ * @module @deepseek-ai/dsh-mcp-client/invariant
+ */
+import type { Context } from '@deepseek-ai/cordis';
+/** Cordis companion plugin name. */
+export declare const name = "mcp-client-invariant";
+/** Service required before the companion can reserve package ownership. */
+export declare const inject: string[];
+/**
+ * Register this package's invariant companion.
+ * @param ctx - Cordis context carrying the invariant service.
+ * @returns the installed registration's disposer after setup succeeds.
+ */
+export declare const apply: (ctx: Context) => Promise<() => void>;
+//# sourceMappingURL=invariant.d.ts.map

package/lib/types/tools.d.ts

@@ -0,0 +1,71 @@
+/**
+ * Tool bridge: discovers MCP tools, registers them on the harness ToolRegistry
+ * under deterministic server-qualified public names, and handles re-sync when
+ * the server's tool list changes.
+ *
+ * Naming contract (see the mcp-client Agent Note "Naming invariants"): every MCP tool
+ * has the stable identity `(serverName, rawName)`; the model-facing public name
+ * is `mcp__<serverName>__<rawName>`, normalized to the DeepSeek function-name
+ * constraints. The raw name is only ever sent on the wire (`tools/call`); the
+ * public name is never parsed to recover it.
+ *
+ * @module
+ */
+import type { Client } from '@modelcontextprotocol/sdk/client/index.js';
+import type { Context } from '@deepseek-ai/cordis';
+import type { JsonValue } from '@deepseek-ai/dsh-tools';
+/** Resolved options relevant to tool bridging. */
+export interface ToolBridgeOptions {
+    /** Whether a registry conflict is contained or rejects this synchronization. */
+    registrationFailure: 'contain' | 'throw';
+    serverName: string;
+    toolCallTimeoutMs: number;
+}
+/** State for one sync generation: the current set of disposers keyed by public name. */
+export type ToolDisposers = Map<string, () => void>;
+/** Canonical MCP result exposed to Code Mode without discarding protocol blocks. */
+export type McpResult<Structured extends JsonValue = JsonValue> = {
+    content: JsonValue[];
+    structuredContent?: Structured;
+};
+/**
+ * Derive the model-facing public name for one MCP tool.
+ *
+ * Deterministic pure function of `(serverName, rawName)`: the clean case is
+ * `mcp__<serverName>__<rawName>` verbatim. When character replacement or
+ * truncation to the DeepSeek function-name contract (64 chars,
+ * `[A-Za-z0-9_-]`) changes the name, a 12-hex-char SHA-256 hash of the
+ * identity is appended so distinct MCP identities never collapse into the
+ * same public name.
+ *
+ * @param serverName - Stable local namespace from plugin config.
+ * @param rawName - The MCP server's own tool name.
+ * @returns The globally unique, model-facing ToolRegistry name.
+ */
+export declare function publicToolName(serverName: string, rawName: string): string;
+/**
+ * Sync the MCP server's tool list into the harness ToolRegistry.
+ *
+ * Two phases keep the swap safe:
+ *
+ * 1. Fetch: drain uncached `tools/list` pagination and build the full next
+ *    generation of `ToolDefinition`s under public names. Any failure here
+ *    (network error, duplicate raw name in the server's list) rejects and
+ *    leaves the previous generation registered untouched.
+ * 2. Swap: dispose the previous generation, register the new one. A registry
+ *    conflict here can only mean a foreign registration squats on this
+ *    server's `mcp__<serverName>__` namespace — the partial generation is
+ *    rolled back (zero tools from this server) and logged. Initial strict
+ *    synchronization may propagate the conflict so its parent transaction
+ *    rejects; ordinary clients and later re-syncs return an empty map.
+ *
+ * @param client - Connected MCP Client instance used to list and call tools.
+ * @param ctx - Cordis context providing the `tools` service for registration.
+ * @param opts - Bridge options: server namespace and per-call timeout.
+ * @param previous - Disposer map from the prior sync generation; disposed
+ *   during the swap phase (only after the fetch phase succeeded).
+ * @returns A map of registered public tool names to their unregister
+ *   disposers — the exact set of live registrations owned by this server.
+ */
+export declare function syncTools(client: Client, ctx: Context, opts: ToolBridgeOptions, previous: ToolDisposers): Promise<ToolDisposers>;
+//# sourceMappingURL=tools.d.ts.map

package/lib/types/transport.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Transport factory: creates the appropriate MCP transport based on the
+ * plugin's resolved config. Stdio spawns a child process (with credential
+ * scrubbing); Streamable HTTP connects to a URL.
+ *
+ * @module
+ */
+import type { Transport } from '@modelcontextprotocol/sdk/shared/transport.js';
+import type { Config } from './index.ts';
+/**
+ * Create an MCP transport from the resolved plugin config.
+ *
+ * @param config - Resolved plugin config discriminated on `transport`.
+ * @returns A connected-ready MCP Transport (stdio or Streamable HTTP).
+ */
+export declare function createTransport(config: Config): Transport;
+//# sourceMappingURL=transport.d.ts.map

package/package.json

@@ -0,0 +1,55 @@
+{
+  "name": "@deepseek-ai/dsh-mcp-client",
+  "description": "MCP client bridge: connects to MCP servers and registers their tools on ctx.tools",
+  "version": "0.0.1-rc.1",
+  "publishConfig": {
+    "access": "restricted"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/deepseek-ai/deepseek-harness.git",
+    "directory": "packages/mcp/mcp-client"
+  },
+  "type": "module",
+  "main": "lib/index.js",
+  "types": "lib/types/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/types/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./invariant": {
+      "types": "./lib/types/invariant.d.ts",
+      "default": "./lib/invariant.js"
+    },
+    "./src/*": "./src/*",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "lib/index.js",
+    "lib/invariant.js",
+    "lib/types/**/*.d.ts"
+  ],
+  "license": "BSD-3-Clause",
+  "peerDependencies": {
+    "@deepseek-ai/dsh-invariants": "^0.0.1-rc.1",
+    "@deepseek-ai/dsh-llm": "^0.0.1-rc.1",
+    "@deepseek-ai/dsh-subprocess": "^0.0.1-rc.1",
+    "@deepseek-ai/dsh-tools": "^0.0.1-rc.1",
+    "@deepseek-ai/cordis": "^4.0.1-rc.1"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.12.0",
+    "zod": "^4.4.3",
+    "@deepseek-ai/schemastery": "^3.18.1-rc.1"
+  },
+  "devDependencies": {
+    "@modelcontextprotocol/server-everything": "^2026.7.4",
+    "@modelcontextprotocol/server-filesystem": "^2026.7.4",
+    "@deepseek-ai/dsh-invariants": "^0.0.1-rc.1",
+    "@deepseek-ai/dsh-llm": "^0.0.1-rc.1",
+    "@deepseek-ai/cordis": "^4.0.1-rc.1",
+    "@deepseek-ai/dsh-tools": "^0.0.1-rc.1",
+    "@deepseek-ai/dsh-subprocess": "^0.0.1-rc.1"
+  }
+}