dsh-mcp 1.0.0 → 1.1.0

package/CHANGELOG.en.md

@@ -7,6 +7,12 @@ All notable changes to this project are documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [1.1.0] - 2026-08-15
+
+### Added
+
+- **Tool-list stabilization**: during a same-connection re-sync (e.g. a `tools/list_changed` notification), unchanged MCP tools keep their existing registration instead of being disposed and re-registered, keeping the system-prompt tool list stable to preserve prompt-cache hits (vendored `lib/mcp-client.js` extension)
+
 ## [1.0.0] - 2026-08-15
 
 First stable release.

package/CHANGELOG.md

@@ -7,6 +7,12 @@
 格式基于 [Keep a Changelog](https://keepachangelog.com/zh-CN/1.1.0/)，
 版本号遵循 [语义化版本](https://semver.org/lang/zh-CN/)。
 
+## [1.1.0] - 2026-08-15
+
+### 新增
+
+- **工具列表稳定化**：同一连接的 re-sync（如 `tools/list_changed` 通知）时，未变化的 MCP 工具保留原注册，不再反复注销/重注册，保持系统提示词工具列表稳定以提升 prompt cache 命中率（vendored `lib/mcp-client.js` 扩展）
+
 ## [1.0.0] - 2026-08-15
 
 首个正式版本。

package/README.en.md

@@ -1,6 +1,24 @@
 # dsh-mcp — MCP server management plugin for DeepSeek Harness (standalone)
 
-![Settings preview](static/snapshot.webp)
+[![dshfind](https://dshfind.com/api/badge/ArvinQi/dsh-mcp?lang=en)](https://dshfind.com/en/plugins/ArvinQi/dsh-mcp?ref=badge)
+
+![Settings preview](static/snapshot.en.webp)
+
+## Why dsh-mcp?
+
+**Problems it solves:**
+
+- **Full tool injection burns tokens**: with multiple MCP servers, the tool count can reach hundreds, and injecting all of them every request is expensive. The `search` mode lets the model hot-inject only the tools it needs via `mcp_tool_search`, saving tokens at scale.
+- **Re-syncs churn the tool list and break caches**: `tools/list_changed` notifications dispose and re-register same-named tools, jittering the system-prompt tool list and constantly invalidating the prompt cache. Tool-list stabilization keeps unchanged tools registered, maximizing cache hits.
+- **No visual management entry**: server config, enable/disable, and tool toggles used to require editing files by hand. Settings → MCP brings everything into one UI.
+
+**Highlights:**
+
+- **Visual management**: server list / create / edit / delete / test connection / enable-disable / refresh, all in the UI
+- **Fine-grained tool control**: expand each server to see its tools, all checked by default; uncheck to load only what you need
+- **Two injection modes**: `search` (on-demand, token-saving) and `full` (inject everything)
+- **Zero npm dependencies**: plugs into DeepSeek Harness internals, install and go
+- **Three install paths**: npm / GitHub git source / local link; bilingual UI and docs
 
 Migrated and merged from uncommitted MCP work in the `deepseek-harness` repository:
 
@@ -33,6 +51,7 @@ dsh-mcp/
 ├── package.json          name=dsh-mcp; dsh.client declaration; zero npm dependencies
 ├── lib/
 │   ├── index.js          host half (McpManagerService, built from mcp-manager)
+│   ├── mcp-client.js     vendored MCP client (from @deepseek-ai/dsh-mcp-client, with tool-list stability extension)
 │   ├── probe.js          vendored connection probe (from mcp-client/src/probe.ts)
 │   ├── transport.js      vendored transport factory (from mcp-client/src/transport.ts)
 │   └── client.js         browser half (esbuild bundle, ModuleLoader wire format)
@@ -53,15 +72,17 @@ node scripts/build.mjs
 - CSS Modules are handled by an esbuild onLoad plugin: styles are injected into a
   `<style data-plugin="dsh-mcp" data-file="…">` tag, and the module default-exports an identity class-name map.
 
-## Install
+## Install & Usage
+
+### 1. Install
 
-### Option 1: npm (after publishing)
+**Option 1: npm (after publishing)**
 
 ```sh
 dsh plugin --profile web add dsh-mcp
 ```
 
-### Option 2: GitHub git source
+**Option 2: GitHub git source**
 
 ```sh
 dsh plugin --profile web add github:ArvinQi/dsh-mcp
@@ -69,7 +90,7 @@ dsh plugin --profile web add github:ArvinQi/dsh-mcp
 dsh plugin --profile web add git+https://github.com/ArvinQi/dsh-mcp.git
 ```
 
-### Option 3: local development (link)
+**Option 3: local development (link)**
 
 ```sh
 dsh plugin --profile web add link:<absolute path to this repo>
@@ -79,7 +100,7 @@ dsh plugin --profile web add link:<absolute path to this repo>
 > symlink (development-only, not committed); otherwise the linked symlink is realpath-resolved and `@deepseek-ai/*`
 > cannot be resolved.
 
-### Registration (all install options)
+### 2. Registration (all install options)
 
 Append to `$DSH_HOME/profiles/web/cordis.patch.yml` (`$DSH_HOME` defaults to `~/.dsh`):
 
@@ -92,6 +113,38 @@ Append to `$DSH_HOME/profiles/web/cordis.patch.yml` (`$DSH_HOME` defaults to `~/
 Then **restart `dsh web`** (client roster changes require a restart); afterwards hard-refresh the browser
 (`Cmd/Ctrl + Shift + R`) to load the settings page.
 
+### 3. Usage
+
+**Open the management page**: after restart, open DSH Web → **Settings → MCP**.
+
+**Add a server**:
+
+1. Click **Add server**.
+2. Fill in: server name (`serverName`, determines the tool prefix `mcp__<serverName>__`), transport
+   (`streamable-http` → URL / `stdio` → command), headers, tool-call timeout, etc.
+3. Click **Test connection** to verify connectivity and the tool list, then **Save**.
+
+**Day-to-day management**:
+
+- **Enable / disable**: row button; disabling a server unregisters all of its tools immediately.
+- **Refresh**: re-pulls server status and the tool list (syncs new tools after a server restart).
+- **Test connection**: available in the edit form at any time.
+
+**Tool control (the key to saving tokens)**:
+
+- **Injection mode**: switch at the top of the page between `search` (on-demand, default) and `full` (inject everything).
+  - In `search` mode, the model calls `mcp_tool_search` to discover and hot-inject the MCP tools it needs.
+- **Tool toggles**: click **Expand tools** to see all tools of that server (all checked by default);
+  unchecking a tool keeps it out of injection, applied immediately without saving.
+
+**Verifying the effect**:
+
+- In any agent session, available tools include `mcp__<serverName>__<tool>`.
+- In `search` mode, tools not retrieved stay out of the system prompt, saving tokens and improving
+  prompt-cache hit rate.
+- When tool content is unchanged, `list_changed` notifications no longer dispose and re-register
+  same-named tools, keeping the tool list stable.
+
 ## Versioning notes
 
 - The host half `lib/index.js` is a **build artifact** of mcp-manager (spec/types inlined); edit the lib files
@@ -104,3 +157,5 @@ Then **restart `dsh web`** (client roster changes require a restart); afterwards
 ## Changelog
 
 See [CHANGELOG.md](CHANGELOG.md). Released under the [MIT License](LICENSE).
+
+[![dshfind](https://dshfind.com/api/card/ArvinQi/dsh-mcp?lang=en)](https://dshfind.com/en/plugins/ArvinQi/dsh-mcp?ref=badge)

package/README.md

@@ -2,8 +2,26 @@
 
 **[English](README.en.md) | 简体中文**
 
+[![dshfind](https://dshfind.com/api/badge/ArvinQi/dsh-mcp?lang=zh)](https://dshfind.com/zh/plugins/ArvinQi/dsh-mcp?ref=badge)
+
 ![设置页预览](static/snapshot.webp)
 
+## 为什么用 dsh-mcp？
+
+**解决的核心问题：**
+
+- **MCP 工具全量注入烧 token**：接入多个 MCP 服务器后工具可达上百个，每轮全量注入开销巨大。`search` 按需检索模式让模型通过 `mcp_tool_search` 热注入所需工具，大幅节省 token。
+- **工具列表反复更新破坏缓存**：`tools/list_changed` 通知会让同名工具被反复注销/重注册，系统提示词工具列表抖动、prompt cache 频繁失效。工具列表稳定化让未变化的工具保留原注册，最大化 cache 命中。
+- **没有可视化管理入口**：服务器配置、启停、工具勾选全靠手工改文件。Settings → MCP 一站式可视化完成。
+
+**功能优势：**
+
+- **可视化管理**：服务器列表 / 新建 / 编辑 / 删除 / 测试连接 / 启停 / 刷新，全 UI 操作
+- **工具级精细控制**：每个服务器展开工具列表，默认全选，可取消勾选只加载需要的部分
+- **双注入模式**：`search`（按需检索，省 token）与 `full`（全量注入）
+- **零 npm 依赖**：直接对接 DeepSeek Harness 内部能力，安装即用
+- **三种安装方式**：npm / GitHub git 源 / 本地 link；中英文界面与文档
+
 ## 功能
 
 - **托管 MCP 服务器注册表**（host）：持久化定义（storage-domain `mcp_servers`）、按服务器挂载
@@ -20,6 +38,7 @@ dsh-mcp/
 ├── package.json          name=dsh-mcp；dsh.client 声明；零 npm dependencies
 ├── lib/
 │   ├── index.js          host 半部（McpManagerService，源自 mcp-manager 构建产物）
+│   ├── mcp-client.js     vendored MCP 客户端（源自 @deepseek-ai/dsh-mcp-client，含工具列表稳定扩展）
 │   ├── probe.js          vendored 连接探测（源自 mcp-client/src/probe.ts）
 │   ├── transport.js      vendored 传输工厂（源自 mcp-client/src/transport.ts）
 │   └── client.js         浏览器半部（esbuild 打包，ModuleLoader wire format）
@@ -41,15 +60,17 @@ node scripts/build.mjs
 - CSS Modules 由 esbuild onLoad 插件处理：样式注入
   `<style data-plugin="dsh-mcp" data-file="…">`，默认导出 identity 类名映射。
 
-## 安装
+## 安装使用
+
+### 1. 安装
 
-### 方式一：npm（发布到 npm 后）
+**方式一：npm（发布到 npm 后）**
 
 ```sh
 dsh plugin --profile web add dsh-mcp
 ```
 
-### 方式二：GitHub git 源
+**方式二：GitHub git 源**
 
 ```sh
 dsh plugin --profile web add github:ArvinQi/dsh-mcp
@@ -57,7 +78,7 @@ dsh plugin --profile web add github:ArvinQi/dsh-mcp
 dsh plugin --profile web add git+https://github.com/ArvinQi/dsh-mcp.git
 ```
 
-### 方式三：本地开发（link）
+**方式三：本地开发（link）**
 
 ```sh
 dsh plugin --profile web add link:<本仓库绝对路径>
@@ -67,7 +88,7 @@ dsh plugin --profile web add link:<本仓库绝对路径>
 > symlink（本机开发用，不入库），否则 `link:` 安装的 symlink 被 realpath 后无法解析
 > `@deepseek-ai/*`。
 
-### 注册与生效（三种方式通用）
+### 2. 注册与生效（三种方式通用）
 
 在 `$DSH_HOME/profiles/web/cordis.patch.yml`（`$DSH_HOME` 默认 `~/.dsh`）追加：
 
@@ -80,6 +101,36 @@ dsh plugin --profile web add link:<本仓库绝对路径>
 然后**重启 `dsh web`**（client roster 变更需重启）；之后浏览器硬刷新（`Cmd/Ctrl + Shift + R`）
 加载设置页。
 
+### 3. 使用
+
+**打开管理页**：重启后浏览器打开 DSH Web → **设置（Settings）→ MCP**。
+
+**添加服务器**：
+
+1. 点击「添加服务器」
+2. 填写：服务器名称（`serverName`，决定工具前缀 `mcp__<serverName>__`）、传输方式
+   （`streamable-http` 填 URL / `stdio` 填命令）、请求头、工具调用超时等
+3. 点「测试连接」确认连通性与工具列表，点「保存」
+
+**日常管理**：
+
+- **启用 / 禁用**：列表行按钮，禁用后该服务器所有工具即时注销，不再注入
+- **刷新**：重新拉取服务器状态与工具列表（服务器重启后可同步新工具）
+- **测试连接**：编辑页可随时测试
+
+**工具控制（省 token 的关键）**：
+
+- **注入模式**：页面顶部切换 `search`（按需检索，默认）或 `full`（全量注入）
+  - `search` 模式下，模型需要某 MCP 工具时调用 `mcp_tool_search` 检索并热注入当前对话
+- **工具勾选**：点「展开工具」查看该服务器全部工具（默认全选），取消勾选 = 不注入该工具，
+  即时生效，无需保存
+
+**验证效果**：
+
+- 在任意 agent 会话中，可用工具应包含 `mcp__<服务器名>__<工具名>`
+- `search` 模式下未检索到的工具不占系统提示词，节省 token 并提升 prompt cache 命中率
+- 工具内容未变化时，`list_changed` 通知不会反复注销/重注册同名工具，工具列表保持稳定
+
 ## 版本注意
 
 - host 半部 `lib/index.js` 是 mcp-manager 的**构建产物**（spec/types 已内联），改动请直接编辑
@@ -87,3 +138,5 @@ dsh plugin --profile web add link:<本仓库绝对路径>
 - 浏览器半部改 `src/client/*` 后重新 `node scripts/build.mjs`；host 半部改动无需重装
   （link 安装直接生效）。
 - 配置变更（bundles 增删、新插件行）需重启 `dsh web` 才进入 client roster。
+
+[![dshfind](https://dshfind.com/api/card/ArvinQi/dsh-mcp?lang=zh)](https://dshfind.com/zh/plugins/ArvinQi/dsh-mcp?ref=badge)

package/lib/index.js

@@ -1,7 +1,7 @@
 import { randomBytes } from "node:crypto";
 import { Service } from "@deepseek-ai/cordis";
 import { credentialRef } from "@deepseek-ai/dsh-credentials";
-import * as mcpClient from "@deepseek-ai/dsh-mcp-client";
+import * as mcpClient from "./mcp-client.js";
 import { probeConnection } from "./probe.js";
 import { Remote, TypertRemoteService } from "@deepseek-ai/dsh-typert-protocol";
 import z from "@deepseek-ai/schemastery";

package/lib/mcp-client.js

@@ -0,0 +1,727 @@
+import z from "@deepseek-ai/schemastery";
+import { MAX_TIMER_DELAY_MS } from "@deepseek-ai/dsh-timeout";
+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 ToolRuntime
+* 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 ToolRuntime 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 ToolRuntime.
+*
+* 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);
+	// Tool-stability pass (dsh-mcp vendored extension): during a same-connection
+	// re-sync (e.g. a `tools/list_changed` notification) a tool whose public
+	// surface (name/description/parameters/output schema) is unchanged keeps its
+	// existing registration instead of being disposed and re-registered.
+	// Keeping the system-prompt tool list stable preserves prompt-cache hits;
+	// execution still calls the live MCP server, so server-side changes need no
+	// re-registration. A reconnected generation gets `stable: false` and rebuilds
+	// every tool because its executors bind the new client.
+	const kept = /* @__PURE__ */ new Set();
+	if (opts.stable !== false) {
+		for (const [publicName, definition] of definitions) {
+			if (!previous.has(publicName)) continue;
+			const existing = ctx.tools.get(publicName);
+			if (existing !== void 0 && toolPublicEqual(existing, definition)) kept.add(publicName);
+		}
+	}
+	for (const [publicName, dispose] of previous) {
+		if (!kept.has(publicName)) dispose();
+	}
+	const disposers = /* @__PURE__ */ new Map();
+	try {
+		for (const [publicName, definition] of definitions) {
+			if (kept.has(publicName)) {
+				disposers.set(publicName, previous.get(publicName));
+				continue;
+			}
+			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;
+}
+/** Compare the public, cache-relevant surface of two tool definitions (dsh-mcp vendored). */
+function toolPublicEqual(a, b) {
+	if (a.name !== b.name || a.description !== b.description) return false;
+	if (!jsonEqual(a.parameters, b.parameters)) return false;
+	return jsonEqual(a.output && a.output.schema, b.output && b.output.schema);
+}
+/** Deep equality of JSON-serializable values (schema objects). */
+function jsonEqual(a, b) {
+	return JSON.stringify(a ?? null) === JSON.stringify(b ?? null);
+}
+/** 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 ToolRuntime'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/connection.js
+/**
+* Connection supervisor: owns the MCP client/transport generations for one
+* plugin instance, keeps the harness tool registry in sync with the live
+* generation, and — when the connection drops — restarts the configured
+* server with bounded exponential backoff.
+*
+* One outage shares one attempt budget (`maxAttempts` consecutive failed
+* attempts, delays doubling from `initialDelayMs` up to `maxDelayMs`). A
+* connection that stays up past the stability window closes the outage, so
+* the next disconnect starts a fresh budget while a crash-looping server —
+* even one whose connects briefly succeed — still exhausts the cap instead of
+* restarting forever. Exhaustion unregisters the server's tools and stops;
+* disposal (including HMR) is the only way back from that state.
+*
+* @module
+*/
+/** Defaults shared by the Config schema and {@link resolveReconnectPolicy}. */
+const RECONNECT_DEFAULTS = Object.freeze({
+	enabled: true,
+	initialDelayMs: 500,
+	maxDelayMs: 3e4,
+	maxAttempts: 10
+});
+const GENERATION_CLOSE_TIMEOUT_MS = 5e3;
+/**
+* The one explicit resolve step from raw reconnect config to the policy the
+* supervisor runs. Programmatic construction may bypass Schemastery
+* normalization, so every default and bound is re-judged here — misconfiguration
+* fails the plugin instance at load.
+*
+* @param config - Raw `reconnect` config; omission uses the defaults.
+* @param path - Diagnostic prefix naming the config location in thrown messages.
+* @returns The frozen resolved policy.
+*/
+function resolveReconnectPolicy(config, path) {
+	if (config !== void 0) {
+		for (const key of Object.keys(config)) if (!Object.hasOwn(RECONNECT_DEFAULTS, key)) throw new Error(`${path}.${key} is not a reconnect option`);
+	}
+	const enabled = config?.enabled ?? RECONNECT_DEFAULTS.enabled;
+	const initialDelayMs = config?.initialDelayMs ?? RECONNECT_DEFAULTS.initialDelayMs;
+	const maxDelayMs = config?.maxDelayMs ?? RECONNECT_DEFAULTS.maxDelayMs;
+	const maxAttempts = config?.maxAttempts ?? RECONNECT_DEFAULTS.maxAttempts;
+	if (!Number.isFinite(initialDelayMs) || initialDelayMs <= 0 || initialDelayMs > MAX_TIMER_DELAY_MS) throw new Error(`${path}.initialDelayMs must be a positive finite number no greater than ${MAX_TIMER_DELAY_MS}`);
+	if (!Number.isFinite(maxDelayMs) || maxDelayMs <= 0 || maxDelayMs > MAX_TIMER_DELAY_MS) throw new Error(`${path}.maxDelayMs must be a positive finite number no greater than ${MAX_TIMER_DELAY_MS}`);
+	if (initialDelayMs > maxDelayMs) throw new Error(`${path}.initialDelayMs must be less than or equal to maxDelayMs`);
+	if (!Number.isInteger(maxAttempts) || maxAttempts < 1) throw new Error(`${path}.maxAttempts must be a positive integer`);
+	return Object.freeze({
+		enabled,
+		initialDelayMs,
+		maxDelayMs,
+		maxAttempts
+	});
+}
+/**
+* Start the supervised connection for one MCP server and keep it alive per
+* the reconnect policy.
+*
+* @param ctx - Cordis context providing the `tools` registry and logger.
+* @param config - Resolved plugin config selecting the transport and server identity.
+* @param policy - Resolved reconnect policy from {@link resolveReconnectPolicy}.
+* @returns Handle with a `ready` promise for startup-await and a `dispose` for teardown.
+*/
+function startConnection(ctx, config, policy) {
+	const label = `mcp-client(${config.serverName})`;
+	const opts = {
+		registrationFailure: "contain",
+		serverName: config.serverName,
+		toolCallTimeoutMs: config.toolCallTimeoutMs
+	};
+	const startupOpts = config.failOnStartupError ? {
+		...opts,
+		registrationFailure: "throw"
+	} : opts;
+	let disposed = false;
+	/** Current generation: the connecting or connected client; undefined during backoff waits and after final failure. */
+	let client;
+	/** Close signal paired with {@link client}; captured by dispose before current ownership is cleared. */
+	let clientClosed;
+	/** Live tool registrations owned by this server; only {@link enqueueSync} and dispose swap it. */
+	let disposers = /* @__PURE__ */ new Map();
+	let reconnectTimer;
+	/** Consecutive failed connection attempts within the current outage. */
+	let failedAttempts = 0;
+	/** When the current generation finished connect + initial sync; undefined while down. */
+	let connectedAt;
+	/** The real error from the first connection attempt, for startup-await diagnostics. */
+	let firstAttemptError;
+	/** A generation may act only while it is the current one on a live plugin. */
+	const isCurrent = (generation) => !disposed && client === generation;
+	/**
+	* Serializes every syncTools call — initial syncs and notification re-syncs
+	* across all generations — so two syncs can never interleave their
+	* dispose-previous/register-next swap (which would double-dispose one
+	* generation and leak another).
+	*/
+	let syncChain = Promise.resolve();
+	/** The client of the most recent sync (dsh-mcp vendored): a same-client re-sync may keep unchanged tools. */
+	let lastSyncedClient;
+	function enqueueSync(generation, syncOpts = opts) {
+		const run = syncChain.then(async () => {
+			if (!isCurrent(generation)) return;
+			// A same-client re-sync (notification) keeps unchanged tools; a fresh
+			// generation (reconnect) must rebuild executors for the new client.
+			const stable = generation === lastSyncedClient;
+			lastSyncedClient = generation;
+			disposers = await syncTools(generation, ctx, { ...syncOpts, stable }, disposers);
+		});
+		syncChain = run.catch(() => {});
+		return run;
+	}
+	/** One disconnect decision per generation: the isCurrent guard makes racing close/error signals idempotent. */
+	function generationDown(generation) {
+		if (!isCurrent(generation)) return;
+		client = void 0;
+		clientClosed = void 0;
+		scheduleReconnect();
+	}
+	/** Wait for the transport-owned close signal without letting a broken transport wedge teardown forever. */
+	function waitForClose(closed) {
+		return new Promise((resolve) => {
+			const timeout = setTimeout(() => {
+				resolve(false);
+			}, GENERATION_CLOSE_TIMEOUT_MS);
+			timeout.unref();
+			closed.then(() => {
+				clearTimeout(timeout);
+				resolve(true);
+			});
+		});
+	}
+	function scheduleReconnect() {
+		const lostEstablishedConnection = connectedAt !== void 0;
+		if (!policy.enabled) {
+			const message = lostEstablishedConnection ? "connection lost and reconnect is disabled — registered tools will fail until an HMR reload or Host restart" : "connection failed and reconnect is disabled — no tools were registered; reload the plugin or restart the Host to connect";
+			ctx.logger.error(`${label}: ${message}`);
+			return;
+		}
+		if (connectedAt !== void 0 && Date.now() - connectedAt >= policy.maxDelayMs) failedAttempts = 0;
+		connectedAt = void 0;
+		failedAttempts += 1;
+		if (failedAttempts > policy.maxAttempts) {
+			syncChain = syncChain.then(() => {
+				for (const dispose of disposers.values()) dispose();
+				disposers = /* @__PURE__ */ new Map();
+			});
+			ctx.logger.error(`${label}: giving up after ${policy.maxAttempts} consecutive failed reconnect attempts — tools unregistered; reload the plugin or restart the Host to reconnect`);
+			return;
+		}
+		const delayMs = Math.min(policy.maxDelayMs, policy.initialDelayMs * 2 ** (failedAttempts - 1));
+		const action = lostEstablishedConnection ? "connection lost; reconnecting" : "connection failed; retrying";
+		ctx.logger.warn(`${label}: ${action} in ${delayMs}ms (attempt ${failedAttempts}/${policy.maxAttempts})`);
+		reconnectTimer = setTimeout(() => {
+			reconnectTimer = void 0;
+			settling = connectGeneration(false);
+		}, delayMs);
+		reconnectTimer.unref();
+	}
+	/**
+	* One connection attempt: fresh transport + client (the MCP SDK binds a
+	* Protocol to one transport for life), connect, then queue the initial tool
+	* sync. The startup flag belongs to the attempt rather than the shared sync
+	* queue, so an early notification cannot consume strict startup semantics.
+	* Every failure funnels through {@link generationDown}; success arms the
+	* onclose-driven disconnect path. Never rejects.
+	*
+	* @param startup - Whether this is the plugin's activation attempt.
+	*/
+	async function connectGeneration(startup) {
+		const generation = new Client({
+			name: "dsh-mcp-client",
+			version: "0.0.1"
+		}, { capabilities: {} });
+		const closed = Promise.withResolvers();
+		let attemptSettled = false;
+		let closeObserved = false;
+		const hasClosed = () => closeObserved;
+		client = generation;
+		clientClosed = closed.promise;
+		generation.onclose = () => {
+			closeObserved = true;
+			closed.resolve();
+			if (attemptSettled) generationDown(generation);
+		};
+		generation.setNotificationHandler(ToolListChangedNotificationSchema, async () => {
+			if (!isCurrent(generation)) return;
+			ctx.logger.info(`${label}: tool list changed, re-syncing`);
+			try {
+				await enqueueSync(generation);
+			} catch (error) {
+				if (!disposed) ctx.logger.error(`${label}: tool re-sync failed: ${String(error)}`);
+			}
+		});
+		try {
+			await generation.connect(createTransport(config));
+			if (hasClosed()) {
+				attemptSettled = true;
+				generationDown(generation);
+				return;
+			}
+			await enqueueSync(generation, startup ? startupOpts : opts);
+		} catch (error) {
+			if (firstAttemptError === void 0) firstAttemptError = error;
+			if (isCurrent(generation)) ctx.logger.warn(`${label}: connection attempt failed: ${String(error)}`);
+			try {
+				await generation.close();
+			} catch {}
+			const quiesced = hasClosed() || await waitForClose(closed.promise);
+			attemptSettled = true;
+			if (!isCurrent(generation)) return;
+			if (!quiesced) {
+				client = void 0;
+				clientClosed = void 0;
+				ctx.logger.error(`${label}: failed generation did not close within ${GENERATION_CLOSE_TIMEOUT_MS}ms — reconnect stopped to avoid overlapping server processes; reload the plugin or restart the Host to retry`);
+				return;
+			}
+			generationDown(generation);
+			return;
+		}
+		attemptSettled = true;
+		if (hasClosed()) {
+			generationDown(generation);
+			return;
+		}
+		if (!isCurrent(generation)) return;
+		connectedAt = Date.now();
+		if (failedAttempts > 0) ctx.logger.info(`${label}: reconnected and re-synced tools (attempt ${failedAttempts}/${policy.maxAttempts})`);
+	}
+	/** The in-flight (or last settled) connection attempt; dispose awaits it for quiescence. */
+	let settling = connectGeneration(true);
+	return {
+		ready: settling.then(() => {
+			if (client !== void 0) return {};
+			/* v8 ignore next -- defensive: firstAttemptError is always set when connect/sync fails */
+			return { error: firstAttemptError ?? /* @__PURE__ */ new Error(`${label}: initial connection failed`) };
+		}),
+		async dispose() {
+			disposed = true;
+			if (reconnectTimer !== void 0) {
+				clearTimeout(reconnectTimer);
+				reconnectTimer = void 0;
+			}
+			const current = client;
+			const currentClosed = clientClosed;
+			client = void 0;
+			clientClosed = void 0;
+			if (current !== void 0) {
+				try {
+					await current.close();
+				} catch {}
+				if (currentClosed !== void 0 && !await waitForClose(currentClosed)) ctx.logger.error(`${label}: generation did not close within ${GENERATION_CLOSE_TIMEOUT_MS}ms during disposal — server shutdown may be incomplete`);
+			}
+			await settling;
+			await syncChain;
+			for (const dispose of disposers.values()) dispose();
+			disposers = /* @__PURE__ */ new Map();
+		}
+	};
+}
+//#endregion
+//#region lib/types/probe.js
+/**
+* One-shot connection probe: connects to an MCP server, lists its tools, and
+* closes the transport. Registers nothing — management surfaces use it to test
+* a server configuration before it is kept or mounted, so a probe must never
+* touch `ctx.tools` or any plugin lifecycle.
+*
+* @module
+*/
+/** Default overall deadline for one probe (ms). */
+const DEFAULT_PROBE_TIMEOUT_MS = 15e3;
+/** Keep a thrown value readable for a management UI. */
+function probeErrorMessage(error) {
+	return error instanceof Error ? error.message : String(error);
+}
+/**
+* Connect, drain the server's `tools/list` pagination, then close.
+*
+* @param client - Fresh, unconnected MCP Client for this probe.
+* @param config - Resolved plugin config selecting transport and server identity.
+* @returns The discovered tool summary.
+*/
+async function runProbe(client, config) {
+	await client.connect(createTransport(config));
+	const tools = [];
+	let cursor;
+	do {
+		const response = await client.request({
+			method: "tools/list",
+			...cursor === void 0 ? {} : { params: { cursor } }
+		}, ListToolsResultSchema);
+		for (const tool of response.tools) tools.push({
+			name: tool.name,
+			...tool.description === void 0 ? {} : { description: tool.description }
+		});
+		cursor = response.nextCursor;
+	} while (cursor);
+	return {
+		ok: true,
+		tools
+	};
+}
+/**
+* Probe one MCP server configuration without registering anything.
+*
+* The overall connect + list attempt races a deadline; a timeout returns a
+* failure rather than hanging the caller. The transport is always closed on
+* the way out — for stdio that terminates the probed child process.
+*
+* @param config - Transport and server identity to probe.
+* @param options - Optional probe deadline override.
+* @returns the tool listing, or a readable failure.
+*/
+async function probeConnection(config, options = {}) {
+	const timeoutMs = options.timeoutMs ?? DEFAULT_PROBE_TIMEOUT_MS;
+	if (!Number.isFinite(timeoutMs) || timeoutMs <= 0) throw new Error(`probeConnection: timeoutMs must be a positive finite number, received ${String(timeoutMs)}`);
+	const client = new Client({
+		name: "dsh-mcp-client",
+		version: "0.0.1"
+	}, { capabilities: {} });
+	const timeout = new Promise((_, reject) => {
+		setTimeout(() => reject(/* @__PURE__ */ new Error(`connection probe timed out after ${timeoutMs}ms`)), timeoutMs).unref();
+	});
+	try {
+		return await Promise.race([runProbe(client, config), timeout]);
+	} catch (error) {
+		return {
+			ok: false,
+			message: probeErrorMessage(error)
+		};
+	} finally {
+		try {
+			await client.close();
+		} catch {}
+	}
+}
+//#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 Reconnect = z.object({
+	enabled: z.boolean().default(RECONNECT_DEFAULTS.enabled),
+	initialDelayMs: z.number().min(1).max(MAX_TIMER_DELAY_MS).default(RECONNECT_DEFAULTS.initialDelayMs),
+	maxDelayMs: z.number().min(1).max(MAX_TIMER_DELAY_MS).default(RECONNECT_DEFAULTS.maxDelayMs),
+	maxAttempts: z.number().step(1).min(1).max(Number.MAX_SAFE_INTEGER).default(RECONNECT_DEFAULTS.maxAttempts)
+});
+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),
+	reconnect: Reconnect
+}), 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),
+	reconnect: Reconnect
+})]);
+/**
+* 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) {
+	const reconnect = resolveReconnectPolicy(config.reconnect, `mcp-client(${config.serverName}): reconnect`);
+	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 connection = startConnection(ctx, config, reconnect);
+	ctx.effect(() => {
+		return () => connection.dispose();
+	}, "mcp-client.connection");
+	const outcome = await connection.ready;
+	if (outcome.error !== void 0 && config.failOnStartupError) throw new Error(`mcp-client(${config.serverName}): initial connection or tool synchronization failed`, { cause: outcome.error });
+}
+//#endregion
+export { Config, apply, inject, name, probeConnection };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "dsh-mcp",
-  "version": "1.0.0",
-  "description": "MCP server 管理插件（独立版）：托管 MCP 服务器注册表（持久化定义、运行时挂载、环境变量注入、连接探测）+ Web 设置管理页。由 deepseek-harness 仓库内的 mcp-manager / ui-settings-mcp / web-mcp 迁移合并而来。MCP server registry with WebUI management for DeepSeek Harness.",
+  "version": "1.1.0",
+  "description": "MCP 服务器管理插件：可视化界面管理 MCP 服务器与工具（配置/启停/刷新/测试、工具级勾选），支持按需检索（tool search）热注入，省 token。DeepSeek Harness plugin: visual MCP server & tool management with on-demand tool search injection.",
   "type": "module",
   "main": "lib/index.js",
   "exports": {