dsh-mcp 1.8.0 → 1.10.0

package/CHANGELOG.en.md

@@ -7,7 +7,23 @@ 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).
 
-## [Unreleased]
+## [1.10.0] - 2026-09-02
+
+### Added
+
+- **Actionable diagnosis when the host half is missing**: when the server-list load fails because of an HTTP 404 on `/api/mcpManager/*` (plugin host half not registered, or client/host version mismatch), the page now shows a troubleshooting hint next to the raw error (verify the `cordis.patch.yml` row → restart `dsh web` → hard-refresh → upgrade both sides); the README troubleshooting section is updated as well
+
+### Fixed
+
+- **Host-side copy internationalization**: the settings UI was fully bilingual but the host half (`lib/index.js`/`lib/oauth.js`/`lib/mcp-client.js`) kept model-visible copy and OAuth errors hardcoded in Chinese. The `mcp_tool_search` description/parameter docs, search-result text, the injected `mcp-tool-control` system prompt, and the OAuth authorization/callback page copy now follow the DSH `locale.preference` from the settings document (new `lib/host-locales.js` table; falls back to Chinese — the previous behavior — when the preference cannot be read)
+- **OAuth decisions no longer key on message text**: the tool-call OAuth preflight used `error.message.includes("授权")` to decide whether to re-throw the link-carrying error — translating the message would silently break OAuth error propagation. It now keys on a stable error code `MCP_OAUTH_REQUIRED` (`error.code`), decoupling control flow from display text
+- **Static-credential servers are no longer mistaken for OAuth**: only streamable-http servers configured for authorization-code + PKCE and WITHOUT a static `Authorization` request header get an OAuth provider; a static-token server facing a 401 now reports the authentication failure instead of starting a browser authorization flow
+
+## [1.9.0] - 2026-08-28
+
+### Added
+
+- **Tool-list stability (better prompt-cache hits)**: tool schemas are canonicalized (recursive key sorting) before registration, so servers reordering schema keys no longer triggers dispose/re-register churn; MCP tools in the system prompt are rendered in stable name order, so the same tool set renders byte-identically no matter the hot-set or `tools/list` order
 
 ## [1.8.0] - 2026-08-27
 

package/CHANGELOG.md

@@ -7,7 +7,23 @@
 格式基于 [Keep a Changelog](https://keepachangelog.com/zh-CN/1.1.0/)，
 版本号遵循 [语义化版本](https://semver.org/lang/zh-CN/)。
 
-## [Unreleased]
+## [1.10.0] - 2026-09-02
+
+### 新增
+
+- **设置页对 host 缺失给出可操作诊断**：服务器列表加载失败若源于 `/api/mcpManager/*` HTTP 404（插件 host 半未注册或 client/host 版本不匹配），页面除原始错误外额外显示排查指引（核对 `cordis.patch.yml` 注册行 → 重启 `dsh web` → 硬刷新 → 同步升级），README 故障排查同步补充
+
+### 修复
+
+- **host 端文案国际化**：设置页双语早已齐备，但 host 半部（`lib/index.js`/`lib/oauth.js`/`lib/mcp-client.js`）的模型可见文案与 OAuth 错误一直是硬编码中文——`mcp_tool_search` 描述与参数说明、检索结果文案、注入的 `mcp-tool-control` 系统提示、OAuth 授权/回调页文案现均按 DSH `locale.preference`（settings 文档）选择 zh/en（新增 `lib/host-locales.js` 文案表；读不到时回退中文，与旧行为一致）
+- **OAuth 判定不再依赖文本匹配**：`mcp-client` 的工具授权预检曾用 `error.message.includes("授权")` 决定是否重抛带链接的错误，翻译消息会静默破坏 OAuth 错误传播——现统一改用稳定的错误码 `MCP_OAUTH_REQUIRED`（`error.code`），控制流与显示文案解耦
+- **静态凭据服务器不再被误当作 OAuth**：只有配置了 OAuth 授权码 + PKCE 且**没有**静态 `Authorization` 请求头的 streamable-http 服务器才挂 OAuth provider；带静态 token 的服务器遇到 401 时直接呈现认证失败，不再触发浏览器授权流程
+
+## [1.9.0] - 2026-08-28
+
+### 新增
+
+- **工具列表稳定化增强（提升 prompt cache 命中）**：注册前对工具 schema 做规范化（递归排序键），服务器返回的键顺序变化不再导致工具被误判为变化而注销重注册；系统提示词中 MCP 工具按名称稳定排序，同一工具集合的渲染文本恒定——热注入集（search 模式每次调用都会变动）与服务器 `tools/list` 顺序不再影响提示词稳定性
 
 ## [1.8.0] - 2026-08-27
 

package/README.en.md

@@ -160,7 +160,12 @@ Check in order:
 - Check the `dsh web` process log for `mcp-manager` initialization errors;
 - After upgrading the plugin, restart and **hard-refresh** so the old client bundle does not
   mix with the new host (typical symptom: `client api: ... 404` or `env is not iterable` — both
-  come from mixing versions).
+  come from mixing versions);
+- An error shaped like `transport failure for /api/mcpManager/list: HTTP 404` means the host did
+  not register the `mcpManager` service: usually the plugin host half is not active (missing
+  cordis.patch.yml row / wrong profile) or the client and host versions disagree. Verify the
+  registration row per Q1, confirm the install targets the `web` profile, restart, and
+  hard-refresh; if it persists, upgrade both `dsh web` and the plugin to the latest versions.
 
 **Q3: MCP tools do not show up in an agent session?**
 
@@ -169,6 +174,16 @@ Check in order:
   so tools not searched are absent from the system prompt by design; switch to "Full injection"
   to verify.
 
+**Q4: A server with an `Authorization` header still asks for OAuth / fails to mount?**
+
+- When an `Authorization` (static bearer/token) header is configured, dsh-mcp does NOT treat the
+  server as OAuth: the authorization-code + PKCE flow is enabled only for servers WITHOUT a static
+  `Authorization` header, so a 401 is never mistaken for an OAuth challenge that opens the browser.
+  For a static-token server, make sure the request headers are correct;
+- If an HTTPS intranet host reports `fetch failed` / `unable to verify the first certificate`, the
+  host Node does not trust the internal CA: start `dsh web` with `NODE_OPTIONS=--use-system-ca`
+  (or add the root cert to `NODE_EXTRA_CA_CERTS`), then restart the host and hard-refresh.
+
 **Add a server**:
 
 1. Click **Add server** (the form expands inline above the list).

package/README.md

@@ -142,7 +142,11 @@ dsh plugin --profile web add link:<本仓库绝对路径>
 
 - 确认 `dsh web` 进程日志中 `mcp-manager` 没有初始化错误；
 - 若升级过插件，请重启后**硬刷新**，避免旧 client bundle 与新版 host 不匹配
-  （典型现象：操作报 `client api: ... 404` 或 `env is not iterable`，都是新旧版本混用所致）。
+  （典型现象：操作报 `client api: ... 404` 或 `env is not iterable`，都是新旧版本混用所致）；
+- 报错形如 `transport failure for /api/mcpManager/list: HTTP 404` 表示宿主端没有注册
+  `mcpManager` 服务：多半是插件 host 半未生效（漏了 cordis.patch.yml 注册行/装错 profile）或
+  client 与 host 版本不一致。请按 Q1 核对注册行、确认安装到了 `web` profile、重启后硬刷新；
+  仍不行则把 `dsh web` 与插件版本都升到最新再试。
 
 **Q3：MCP 工具没有出现在 agent 会话里？**
 
@@ -150,6 +154,16 @@ dsh plugin --profile web add link:<本仓库绝对路径>
 - 注入模式为「按需检索」时，模型会通过 `mcp_tool_search` 检索后热注入，未检索到的工具不在
   系统提示词中属正常现象；可切换到「全量注入」验证。
 
+**Q4：服务器配置了 Authorization 头却提示需要 OAuth 授权 / 挂载失败？**
+
+- 只要在请求头里配置了 `Authorization`（静态 Bearer/token），dsh-mcp 就不会把它当作 OAuth
+  服务器：真正的 OAuth（授权码 + PKCE）只对**没有静态 Authorization 头**的服务器启用，避免
+  401 被误当成 OAuth 挑战而打开浏览器授权。若你连的是需要静态 token 的服务器，确认请求头
+  正确即可；
+- 若 https 内网域名报 `fetch failed` / `unable to verify the first certificate`，是宿主 Node
+  不信任公司内网 CA：用 `NODE_OPTIONS=--use-system-ca` 启动 `dsh web`（或把根证书加入
+  `NODE_EXTRA_CA_CERTS`），再重启宿主与硬刷新浏览器。
+
 **添加服务器**：
 
 1. 点击「添加服务器」（表单在列表上方就地展开）

package/lib/client.js

@@ -15042,7 +15042,7 @@ var import_react4 = require("react");
 var import_react = require("react");
 
 // src/client/mcp-store.ts
-var import_client = require("@deepseek-ai/dsh-client-runtime/client");
+var import_dsh_client_store = require("@deepseek-ai/dsh-client-store");
 var DEFAULT_TOOL_CALL_TIMEOUT_MS = 6e4;
 function emptyDraft() {
   return {
@@ -15164,7 +15164,7 @@ function draftToSubmission(draft) {
   };
 }
 function createMcpManagerStore() {
-  return (0, import_client.defineStore)({
+  return (0, import_dsh_client_store.defineStore)({
     init: () => ({
       loadState: "loading",
       servers: [],
@@ -15934,6 +15934,7 @@ function McpSettingsSection(props) {
   const { setLoadState, setServers, beginCreate, beginEdit, cancelEdit, updateDraft, setBusy, setTestRunning, setTest } = props.actions;
   const t = props.t;
   const [loadErrorDetail, setLoadErrorDetail] = (0, import_react4.useState)(null);
+  const [hostMissing, setHostMissing] = (0, import_react4.useState)(false);
   const [tools, setTools] = (0, import_react4.useState)(null);
   const [toolsError, setToolsError] = (0, import_react4.useState)(null);
   const [expanded, setExpanded] = (0, import_react4.useState)(/* @__PURE__ */ new Set());
@@ -15960,7 +15961,9 @@ function McpSettingsSection(props) {
   };
   const fail = (error51) => {
     console.error("[dsh-mcp] list failed:", error51);
-    setLoadErrorDetail(String((error51 instanceof Error ? error51.message : error51) ?? error51));
+    const message = String((error51 instanceof Error ? error51.message : error51) ?? error51);
+    setLoadErrorDetail(message);
+    setHostMissing(/HTTP 404|transport failure/.test(message));
     setLoadState("error");
   };
   const load = () => {
@@ -15969,6 +15972,7 @@ function McpSettingsSection(props) {
         setServers(servers);
         setLoadState("ready");
         setLoadErrorDetail(null);
+        setHostMissing(false);
       },
       (error51) => fail(error51)
     );
@@ -15982,6 +15986,7 @@ function McpSettingsSection(props) {
         setServers(servers);
         setLoadState("ready");
         setLoadErrorDetail(null);
+        setHostMissing(false);
       },
       (error51) => {
         if (current) fail(error51);
@@ -16026,6 +16031,7 @@ function McpSettingsSection(props) {
         (servers) => {
           setServers(servers);
           setLoadState("ready");
+          setHostMissing(false);
         },
         () => {
         }
@@ -16074,6 +16080,7 @@ function McpSettingsSection(props) {
   if (state.loadState === "error") {
     return /* @__PURE__ */ (0, import_jsx_runtime4.jsxs)("div", { className: McpSettingsSection_default.failure, children: [
       /* @__PURE__ */ (0, import_jsx_runtime4.jsx)("p", { role: "alert", children: t("loadError") }),
+      hostMissing ? /* @__PURE__ */ (0, import_jsx_runtime4.jsx)("p", { className: McpSettingsSection_default.muted, children: t("loadErrorHostMissing") }) : null,
       loadErrorDetail !== null ? /* @__PURE__ */ (0, import_jsx_runtime4.jsx)("pre", { className: McpSettingsSection_default.muted, children: loadErrorDetail }) : null,
       /* @__PURE__ */ (0, import_jsx_runtime4.jsx)("button", { type: "button", onClick: () => {
         setLoadState("loading");
@@ -16254,6 +16261,7 @@ var zh = {
   nav: "MCP",
   loading: "\u6B63\u5728\u8BFB\u53D6 MCP \u670D\u52A1\u5668\u2026",
   loadError: "\u6682\u65F6\u65E0\u6CD5\u8BFB\u53D6 MCP \u670D\u52A1\u5668\u3002",
+  loadErrorHostMissing: "\u5BBF\u4E3B\u7AEF\u672A\u63D0\u4F9B mcpManager \u670D\u52A1\uFF08HTTP 404\uFF09\u3002\u901A\u5E38\u662F\u63D2\u4EF6 host \u534A\u672A\u6CE8\u518C\u6216 client/host \u7248\u672C\u4E0D\u5339\u914D\uFF1A\u8BF7\u786E\u8BA4 cordis.patch.yml \u5DF2\u6CE8\u518C dsh-mcp \u884C\u3001\u91CD\u542F dsh web \u5E76\u786C\u5237\u65B0\uFF08Cmd/Ctrl+Shift+R\uFF09\uFF1B\u82E5\u5347\u7EA7\u8FC7\u63D2\u4EF6\u8BF7\u540C\u6B65\u5347\u7EA7\u5BBF\u4E3B\u3002",
   retry: "\u91CD\u8BD5",
   empty: "\u8FD8\u6CA1\u6709\u914D\u7F6E MCP \u670D\u52A1\u5668\u3002",
   addServer: "\u6DFB\u52A0\u670D\u52A1\u5668",
@@ -16355,6 +16363,7 @@ var en = {
   nav: "MCP",
   loading: "Reading MCP servers\u2026",
   loadError: "MCP servers are temporarily unavailable.",
+  loadErrorHostMissing: "The host does not expose the mcpManager service (HTTP 404). Usually the plugin host half is not registered or the client/host versions mismatch: confirm the cordis.patch.yml dsh-mcp row, restart dsh web, and hard-refresh (Cmd/Ctrl+Shift+R); after upgrading the plugin, upgrade the host to match.",
   retry: "Retry",
   empty: "No MCP servers are configured yet.",
   addServer: "Add server",

package/lib/host-locales.js

@@ -0,0 +1,105 @@
+/**
+ * Host-side copy for dsh-mcp: the strings the Host renders for operators and
+ * the model. The settings UI already routes every client string through the
+ * browser locale service (`src/client/locales.ts`); this module gives the
+ * host half the same zh/en split, resolved from the same DSH settings
+ * document (`locale.preference`), so an English deployment reads English end
+ * to end — including the model-facing `mcp_tool_search` description, its
+ * search-result text, and the injected `mcp-tool-control` system prompt.
+ *
+ * Lookup is template-based: `{name}` placeholders are substituted from the
+ * caller's vars object. Unknown keys and any settings-read failure fall back
+ * to Simplified Chinese, which matches the pre-i18n behavior.
+ * @module
+ */
+
+/** Simplified Chinese host dictionary (source of truth). */
+const zh = {
+	// lib/index.js — model-facing copy.
+	toolSearchDesc: "按关键词检索当前启用的 MCP 工具，返回匹配工具的名称/描述/参数 schema，并将命中的工具加入热注入集（下一轮模型请求即可直接调用）。需要某个 MCP 工具但不知道确切名称时使用。",
+	toolSearchQuery: "检索关键词，如 gitlab merge request、feishu 文档、hive 表等",
+	toolSearchLimit: "最多返回条数，默认 8，最大 20",
+	searchHit: "匹配 MCP 工具（已热启用，下一轮可直接调用）：\n{lines}",
+	searchMiss: "未找到匹配的 MCP 工具，可换关键词重试。",
+	toolControlPrompt: "MCP 工具按需可用：需要某个 MCP 工具时先调用 mcp_tool_search(query) 检索，命中后该工具会自动注入当前对话；当前可用 MCP 服务器：{servers}。",
+	noServers: "(无)",
+	// lib/oauth.js — operator-facing OAuth copy.
+	oauthNeedLink: "服务器 \"{serverId}\" 需要 OAuth 授权，请在浏览器打开以下链接完成授权后重试（也可在 Settings → MCP 点击「测试连接」）：\n{url}",
+	oauthFailPage: "授权失败：{error}，可关闭此页面并返回 DSH。",
+	oauthOkPage: "授权成功，可关闭此页面并返回 DSH。",
+	oauthExchangeFail: "OAuth 授权失败：{error}",
+	// lib/mcp-client.js — operator-facing tool-call copy.
+	oauthToolLink: "服务器 \"{serverName}\" 需要 OAuth 授权，请在浏览器打开以下链接完成授权后重试：\n{url}",
+	oauthToolFallback: "服务器 \"{serverName}\" 需要 OAuth 授权：请在 Settings → MCP 编辑该服务器并点击「测试连接」完成授权后重试",
+};
+
+/** English host dictionary; every zh key must exist here. */
+const en = {
+	toolSearchDesc: "Search the enabled MCP tools by keyword and return matching tool names/descriptions/parameter schemas; matches are hot-injected for the next model request. Use when you need an MCP tool but do not know its exact name.",
+	toolSearchQuery: "Search keywords, e.g. gitlab merge request, feishu document, hive table",
+	toolSearchLimit: "Maximum number of results; default 8, max 20",
+	searchHit: "Matching MCP tools (hot-enabled, callable in the next request):\n{lines}",
+	searchMiss: "No matching MCP tools found; try different keywords.",
+	toolControlPrompt: "MCP tools are available on demand: when you need an MCP tool, first call mcp_tool_search(query); a hit is hot-injected into the current conversation. Enabled MCP servers: {servers}.",
+	noServers: "(none)",
+	oauthNeedLink: "Server \"{serverId}\" requires OAuth authorization — open the link below to authorize and retry (or edit the server in Settings → MCP and click \"Test connection\"):\n{url}",
+	oauthFailPage: "Authorization failed: {error}. You can close this page and return to DSH.",
+	oauthOkPage: "Authorization succeeded. You can close this page and return to DSH.",
+	oauthExchangeFail: "OAuth authorization failed: {error}",
+	oauthToolLink: "Server \"{serverName}\" requires OAuth authorization — open the link below to authorize and retry:\n{url}",
+	oauthToolFallback: "Server \"{serverName}\" requires OAuth authorization: edit the server in Settings → MCP and click \"Test connection\" to complete authorization",
+};
+
+/** Key table of every host copy key. */
+const KEYS = Object.keys(zh);
+
+/**
+ * Substitute `{name}` placeholders with the given vars.
+ * @param template - template text containing `{name}` tokens.
+ * @param vars - placeholder values; unknown tokens are left verbatim.
+ * @returns the rendered string.
+ */
+function render(template, vars) {
+	if (!vars) return template;
+	return template.replace(/\{([A-Za-z0-9_]+)\}/g, (match, name) => {
+		const value = vars[name];
+		return value === void 0 || value === null ? match : String(value);
+	});
+}
+
+/**
+ * Resolve the DSH locale preference from the Host settings document.
+ * @param ctx - optional Host context whose `settings` service owns the
+ *   `locale` section; when absent or unreadable, falls back to zh.
+ * @returns `'zh'` or `'en'`.
+ */
+export function hostLocale(ctx) {
+	try {
+		const settings = ctx && typeof ctx.get === "function" ? ctx.get("settings") : void 0;
+		if (settings && typeof settings.get === "function") {
+			const section = settings.get("locale");
+			const preference = section && typeof section === "object" ? section.preference : void 0;
+			if (preference === "en" || preference === "zh") return preference;
+		}
+	} catch {
+		// settings unavailable (tests, headless, provider detached): keep zh.
+	}
+	return "zh";
+}
+
+/**
+ * Render one host copy string for the current DSH locale.
+ * @param ctx - Host context used to resolve the locale preference.
+ * @param key - copy key (see KEYS).
+ * @param vars - optional `{name}` placeholder values.
+ * @returns the localized string; unknown keys fall back to the zh template.
+ */
+export function hostText(ctx, key, vars) {
+	const locale = hostLocale(ctx);
+	const table = locale === "en" ? en : zh;
+	const template = table[key] ?? zh[key] ?? "";
+	return render(template, vars);
+}
+
+export { en, zh };
+export const __hostLocaleKeys = KEYS;

package/lib/index.js

@@ -5,6 +5,7 @@ import * as mcpClient from "./mcp-client.js";
 import { createOAuthProvider } from "./oauth.js";
 import { probeConnection } from "./probe.js";
 import { Remote, TypertRemoteService } from "@deepseek-ai/dsh-typert-protocol";
+import { hostText } from "./host-locales.js";
 import z from "@deepseek-ai/schemastery";
 import { z as z$1 } from "zod";
 import { defineDomain, domainTable } from "@deepseek-ai/dsh-storage-domain";
@@ -605,6 +606,21 @@ let McpManagerService = (() => {
 			};
 		}
 		/**
+		* Whether one resolved client config needs an OAuth provider. Only
+		* streamable-http servers WITHOUT a static `Authorization` header do:
+		* a static bearer token means the server authenticates directly, and
+		* attaching an OAuth provider would make the SDK treat any 401 as an
+		* authorization-code challenge — opening the browser / blocking tool
+		* calls for servers that never intended OAuth. stdio never needs it.
+		* @param config - the resolved client config from {@link toClientConfig}.
+		* @returns true when OAuth (authorization-code + PKCE) should be enabled.
+		*/
+		wantsOAuthProvider(config) {
+			if (config.transport !== "streamable-http") return false;
+			const names = Object.keys(config.headers ?? {});
+			return !names.some((name) => name.toLowerCase() === "authorization");
+		}
+		/**
 		* Mount one server's mcp-client instance without awaiting activation, so a
 		* hung server cannot block a Remote call. The mount entry's phase flips via
 		* the fiber settlement callbacks.
@@ -623,14 +639,18 @@ let McpManagerService = (() => {
 				try {
 					const env = await this.resolveEnv(row);
 					const globalEnv = await this.resolveGlobalEnv();
-					// Every server gets an OAuth provider: servers that require
-					// OAuth (authorization-code flow) trigger browser auth on
-					// connect (unless allowBrowserOnMount is off, the default);
-					// servers that do not are unaffected. Tokens are keyed by
-					// serverName so a test-connection authorization is reused
-					// by the mount.
-					const authProvider = createOAuthProvider(row.serverName, this.ctx, { allowBrowser: this.allowBrowserOnMount, serverUrl: row.url });
-					handle = this.ctx.plugin(MCP_CLIENT_PLUGIN, { ...this.toClientConfig(row, env, globalEnv), authProvider });
+					const config = this.toClientConfig(row, env, globalEnv);
+					// OAuth servers (authorization-code flow) trigger browser
+					// auth on connect (unless allowBrowserOnMount is off, the
+					// default); static-credential servers get no provider so
+					// their 401s surface as authentication failures instead of
+					// an OAuth flow the server never asked for. Tokens are
+					// keyed by serverName so a test-connection authorization
+					// is reused by the mount.
+					const authProvider = this.wantsOAuthProvider(config)
+						? createOAuthProvider(row.serverName, this.ctx, { allowBrowser: this.allowBrowserOnMount, serverUrl: row.url })
+						: void 0;
+					handle = this.ctx.plugin(MCP_CLIENT_PLUGIN, { ...config, ...authProvider === void 0 ? {} : { authProvider } });
 				} catch (error) {
 					entry.phase = "failed";
 					entry.error = errorText(error);
@@ -1047,9 +1067,18 @@ let McpManagerService = (() => {
 			// opens the browser for authorization and the probe continues after
 			// tokens are stored (keyed by serverName, matching the mount path).
 			const globalEnv = await this.resolveGlobalEnv();
-			const probe = await probeConnection(this.toClientConfig(request.server, env, globalEnv), {
+			const probeConfig = this.toClientConfig(request.server, env, globalEnv);
+			// Test connection also supports OAuth: an OAuth-protected server
+			// opens the browser for authorization and the probe continues after
+			// tokens are stored (keyed by serverName, matching the mount path).
+			// Static-credential servers (configured Authorization header) skip
+			// the provider so a 401 probe reports the authentication failure
+			// instead of starting an OAuth flow the server never asked for.
+			const probe = await probeConnection(probeConfig, {
 				timeoutMs: this.probeTimeoutMs,
-				authProvider: createOAuthProvider(request.server.serverName, this.ctx, { serverUrl: request.server.url })
+				...(this.wantsOAuthProvider(probeConfig)
+					? { authProvider: createOAuthProvider(request.server.serverName, this.ctx, { serverUrl: request.server.url }) }
+					: {})
 			});
 			const elapsedMs = Date.now() - startedAt;
 			return {
@@ -1106,12 +1135,12 @@ let McpManagerService = (() => {
 		installToolControl() {
 			this.ctx.tools.register({
 				name: "mcp_tool_search",
-				description: "按关键词检索当前启用的 MCP 工具，返回匹配工具的名称/描述/参数 schema，并将命中的工具加入热注入集（下一轮模型请求即可直接调用）。需要某个 MCP 工具但不知道确切名称时使用。",
+				description: hostText(this.ctx, "toolSearchDesc"),
 				parameters: {
 					type: "object",
 					properties: {
-						query: { type: "string", description: "检索关键词，如 gitlab merge request、feishu 文档、hive 表等" },
-						limit: { type: "number", description: "最多返回条数，默认 8，最大 20" }
+						query: { type: "string", description: hostText(this.ctx, "toolSearchQuery") },
+						limit: { type: "number", description: hostText(this.ctx, "toolSearchLimit") }
 					},
 					required: ["query"],
 					additionalProperties: false
@@ -1151,8 +1180,8 @@ let McpManagerService = (() => {
 						content: [{
 							type: "text",
 							text: lines.length > 0
-								? "匹配 MCP 工具（已热启用，下一轮可直接调用）：\n" + lines.join("\n")
-								: "未找到匹配的 MCP 工具，可换关键词重试。"
+								? hostText(this.ctx, "searchHit", { lines: lines.join("\n") })
+								: hostText(this.ctx, "searchMiss")
 						}]
 					};
 				}
@@ -1178,10 +1207,20 @@ let McpManagerService = (() => {
 					assembly.sections = (assembly.sections || []).filter((section) => section.name !== "mcp-tool-control");
 					assembly.sections.push({
 						name: "mcp-tool-control",
-						text: "MCP 工具按需可用：需要某个 MCP 工具时先调用 mcp_tool_search(query) 检索，命中后该工具会自动注入当前对话；当前可用 MCP 服务器：" + (servers.join(", ") || "(无)") + "。"
+						text: hostText(this.ctx, "toolControlPrompt", { servers: servers.join(", ") || hostText(this.ctx, "noServers") })
 					});
 				}
 				assembly.tools = kept;
+				// Canonical tool order: render MCP tools sorted by name so the
+				// system prompt stays byte-stable for the same tool set no
+				// matter the registration or hot-set order (hot tools move on
+				// every call, and servers may reorder tools/list) — stable
+				// output is what preserves prompt-cache hits.
+				const mcpKept = [];
+				const otherKept = [];
+				for (const tool of assembly.tools) (tool.name.startsWith("mcp__") ? mcpKept : otherKept).push(tool);
+				mcpKept.sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0));
+				assembly.tools = [...otherKept, ...mcpKept];
 				return next();
 			});
 			this.ctx.on("tools/result", (exec) => {

package/lib/mcp-client.js

@@ -10,7 +10,8 @@ import { isDeepStrictEqual } from "node:util";
 import { z as z$1 } from "zod";
 import { isImageAdmissionError } from "@deepseek-ai/dsh-attachment";
 import { assertSupportedJsonSchema } from "@deepseek-ai/dsh-tools";
-import { createToolAuthorizationUrl } from "./oauth.js";
+import { createToolAuthorizationUrl, OAUTH_REQUIRED_CODE, oauthRequiredError } from "./oauth.js";
+import { hostText } from "./host-locales.js";
 //#region lib/types/transport.js
 /**
 * Transport factory: creates the appropriate MCP transport based on the
@@ -205,9 +206,22 @@ function toolPublicEqual(a, b) {
 	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). */
+/**
+* Recursively sort object keys so semantically identical JSON compares equal
+* regardless of key order (servers often reorder schema keys between lists).
+*/
+function canonicalize(value) {
+	if (Array.isArray(value)) return value.map(canonicalize);
+	if (value !== null && typeof value === "object") {
+		const out = {};
+		for (const key of Object.keys(value).sort()) out[key] = canonicalize(value[key]);
+		return out;
+	}
+	return value;
+}
+/** Deep equality of JSON-serializable values, ignoring object key order. */
 function jsonEqual(a, b) {
-	return JSON.stringify(a ?? null) === JSON.stringify(b ?? null);
+	return JSON.stringify(canonicalize(a ?? null)) === JSON.stringify(canonicalize(b ?? null));
 }
 /** Keep a supported advertised schema; unsupported MCP vocabulary falls back to JsonValue. */
 function supportedOutputSchema(candidate) {
@@ -225,7 +239,11 @@ function createDefinition(client, ctx, publicName, rawName, description, paramet
 	return {
 		name: publicName,
 		description,
-		parameters,
+		// Canonicalize before registration: servers often return JSON Schema
+		// with unstable key ordering; sorting keys keeps the model-visible tool
+		// list byte-stable across re-syncs and reconnects, which is what
+		// preserves prompt-cache hits.
+		parameters: canonicalize(parameters),
 		output: createOutput(rawName, structuredSchema),
 		execute: createExecutor(client, ctx, rawName, taskRequired, opts, projections),
 		finalizeContent(exec, result) {
@@ -249,7 +267,7 @@ function createOutput(rawName, structuredSchema) {
 					type: "array",
 					items: {}
 				},
-				structuredContent: structuredSchema ?? {}
+				structuredContent: canonicalize(structuredSchema ?? {})
 			},
 			required: structuredSchema === void 0 ? ["content"] : ["content", "structuredContent"],
 			additionalProperties: false
@@ -292,10 +310,15 @@ function createExecutor(client, ctx, rawName, taskRequired, opts, projections) {
 			if (expired) {
 				try {
 					const authUrl = await createToolAuthorizationUrl(opts.serverName, ctx, opts.url);
-					throw new Error(`服务器 "${opts.serverName}" 需要 OAuth 授权，请在浏览器打开以下链接完成授权后重试：\n${authUrl}`);
+					throw oauthRequiredError(hostText(ctx, "oauthToolLink", { serverName: opts.serverName, url: authUrl }));
 				} catch (error) {
-					if (error instanceof Error && error.message.includes("授权")) throw error;
-					throw new Error(`服务器 "${opts.serverName}" 需要 OAuth 授权：请在 Settings → MCP 编辑该服务器并点击「测试连接」完成授权后重试`);
+					// The link-carrying error thrown just above is the actionable
+					// outcome; anything else (discovery/registration failure) is
+					// reported as the generic Settings → MCP fallback. Keyed on
+					// the stable error code so localized message text never
+					// drives control flow.
+					if (error instanceof Error && error.code === OAUTH_REQUIRED_CODE) throw error;
+					throw oauthRequiredError(new Error(hostText(ctx, "oauthToolFallback", { serverName: opts.serverName })));
 				}
 			}
 		}

package/lib/oauth.js

@@ -21,6 +21,25 @@ import {
   startAuthorization,
 } from "@modelcontextprotocol/sdk/client/auth.js";
 import { credentialRef } from "@deepseek-ai/dsh-credentials";
+import { hostText } from "./host-locales.js";
+
+/**
+ * Error code marking an "OAuth authorization required" failure. Throwers set
+ * `error.code` to this value so control flow (re-throw decisions) keys on a
+ * stable code, never on localized message text.
+ */
+export const OAUTH_REQUIRED_CODE = "MCP_OAUTH_REQUIRED";
+
+/** Set the OAuth-required marker on an Error and return it. */
+function oauthRequired(error) {
+  error.code = OAUTH_REQUIRED_CODE;
+  return error;
+}
+
+/** Build a localized "authorization required" Error carrying the stable code. */
+export function oauthRequiredError(message) {
+  return oauthRequired(new Error(message));
+}
 
 /** Credential reference namespace prefix for per-server OAuth tokens. */
 const OAUTH_REF_PREFIX = "DSH_MCP_OAUTH_";
@@ -253,7 +272,7 @@ export function createOAuthProvider(serverId, ctx, options = {}) {
             // fail with the clickable authorization link. The shared
             // listener keeps running so opening the URL completes the flow.
             log.info(`${tag}: mount requires authorization, not opening browser`);
-            throw new Error(`服务器 "${serverId}" 需要 OAuth 授权，请在浏览器打开以下链接完成授权后重试（也可在 Settings → MCP 点击「测试连接」）：\n${url}`);
+            throw oauthRequired(new Error(hostText(ctx, "oauthNeedLink", { serverId, url })));
           }
           log.info(`${tag}: opening browser for authorization: ${url}`);
           openBrowser(url);
@@ -273,12 +292,12 @@ export function createOAuthProvider(serverId, ctx, options = {}) {
           const error = url.searchParams.get("error");
           res.setHeader("content-type", "text/html; charset=utf-8");
           if (error) {
-            res.end(`授权失败：${error}，可关闭此页面并返回 DSH。`);
+            res.end(hostText(ctx, "oauthFailPage", { error }));
             log.error(`${tag}: callback rejected: ${error}`);
             resolveResult({ error });
             return;
           }
-          res.end("授权成功，可关闭此页面并返回 DSH。");
+          res.end(hostText(ctx, "oauthOkPage"));
           log.info(`${tag}: authorization callback received (code)`);
           resolveResult({ code });
         });
@@ -291,7 +310,7 @@ export function createOAuthProvider(serverId, ctx, options = {}) {
         openBrowser(authorizationUrl.toString());
         try {
           const result = await resultPromise;
-          if (result.error) throw new Error(`OAuth 授权失败：${result.error}`);
+          if (result.error) throw oauthRequired(new Error(hostText(ctx, "oauthExchangeFail", { error: result.error })));
           const authServerUrl = new URL(authorizationUrl.origin);
           log.info(`${tag}: discovering authorization server metadata at ${authServerUrl}`);
           const metadata = await discoverAuthorizationServerMetadata(authServerUrl);
@@ -392,13 +411,13 @@ export async function createToolAuthorizationUrl(serverId, ctx, serverUrl) {
         const error = callbackUrl.searchParams.get("error");
         res.setHeader("content-type", "text/html; charset=utf-8");
         if (error) {
-          res.end(`授权失败：${error}，可关闭此页面并返回 DSH。`);
+          res.end(hostText(ctx, "oauthFailPage", { error }));
           log.error(`${tag}: callback rejected: ${error}`);
           resolve();
           server.close();
           return;
         }
-        res.end("授权成功，可关闭此页面并返回 DSH。");
+        res.end(hostText(ctx, "oauthOkPage"));
         log.info(`${tag}: tool-auth callback received (code)`);
         try {
           const authServerUrl = new URL(authorizationUrl.origin);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-mcp",
-  "version": "1.8.0",
+  "version": "1.10.0",
   "description": "MCP 管理界面 + tool search：可视化配置/启停/刷新 MCP 服务器与工具勾选，按需检索（tool search）热注入；工具列表稳定命中缓存、不撑爆上下文。DeepSeek Harness plugin: MCP management UI + tool search — stable tool list, cache-friendly, no context bloat.",
   "type": "module",
   "main": "lib/index.js",
@@ -22,7 +22,7 @@
   ],
   "scripts": {
     "build": "node scripts/build.mjs",
-    "test": "node --test test/mcp-image-projection.test.mjs"
+    "test": "node --test test/mcp-image-projection.test.mjs test/host-locales.test.mjs"
   },
   "author": "Arvin.qi <arvin.qi@qq.com>",
   "license": "MIT",
@@ -37,7 +37,6 @@
   "dsh": {
     "client": {
       "inject": [
-        "@deepseek-ai/dsh-client-runtime",
         "@deepseek-ai/dsh-api-remotes",
         "@deepseek-ai/dsh-client-ui-settings",
         "@deepseek-ai/dsh-client-locale"

package/scripts/build.mjs

@@ -50,12 +50,9 @@ const EXTERNALS = [
   'react-dom',
   'react-dom/client',
   '@deepseek-ai/cordis',
+  '@deepseek-ai/dsh-client-store',
   '@deepseek-ai/dsh-client-ui-slots',
-  '@deepseek-ai/dsh-client-web-react',
   '@deepseek-ai/dsh-client-ui-primitives',
-  '@deepseek-ai/dsh-client-ui-attachment',
-  '@deepseek-ai/dsh-client-schema-form',
-  '@deepseek-ai/dsh-client-runtime/client',
 ]
 
 /** Locate the esbuild package inside a pnpm checkout (store or hoisted). */

package/src/client/McpSettingsSection.tsx

@@ -79,6 +79,7 @@ export function McpSettingsSection(props: McpSettingsSectionProps): ReactNode {
   const t = props.t
 
   const [loadErrorDetail, setLoadErrorDetail] = useState<string | null>(null)
+  const [hostMissing, setHostMissing] = useState(false)
   const [tools, setTools] = useState<McpToolsState | null>(null)
   const [toolsError, setToolsError] = useState<string | null>(null)
   const [expanded, setExpanded] = useState<ReadonlySet<string>>(new Set())
@@ -107,7 +108,12 @@ export function McpSettingsSection(props: McpSettingsSectionProps): ReactNode {
     // The settings shell hides Remote failures behind a generic copy; surface
     // the real message here so a broken list() is diagnosable from the page.
     console.error('[dsh-mcp] list failed:', error)
-    setLoadErrorDetail(String((error instanceof Error ? error.message : error) ?? error))
+    const message = String((error instanceof Error ? error.message : error) ?? error)
+    setLoadErrorDetail(message)
+    // HTTP 404 on /api/mcpManager/* means the host did not register the
+    // mcpManager Typert service (host half missing or client/host version
+    // mismatch). Surface that distinctively instead of a bare transport error.
+    setHostMissing(/HTTP 404|transport failure/.test(message))
     setLoadState('error')
   }
 
@@ -117,6 +123,7 @@ export function McpSettingsSection(props: McpSettingsSectionProps): ReactNode {
         setServers(servers)
         setLoadState('ready')
         setLoadErrorDetail(null)
+        setHostMissing(false)
       },
       (error) => fail(error),
     )
@@ -131,6 +138,7 @@ export function McpSettingsSection(props: McpSettingsSectionProps): ReactNode {
         setServers(servers)
         setLoadState('ready')
         setLoadErrorDetail(null)
+        setHostMissing(false)
       },
       (error) => { if (current) fail(error) },
     )
@@ -169,7 +177,7 @@ export function McpSettingsSection(props: McpSettingsSectionProps): ReactNode {
     setRefreshing(prev => new Set(prev).add(serverName))
     void Promise.all([
       list().then(
-        (servers) => { setServers(servers); setLoadState('ready') },
+        (servers) => { setServers(servers); setLoadState('ready'); setHostMissing(false) },
         () => {},
       ),
       props.toolsList().then(setTools, () => {}),
@@ -225,6 +233,7 @@ export function McpSettingsSection(props: McpSettingsSectionProps): ReactNode {
     return (
       <div className={css.failure}>
         <p role="alert">{t('loadError')}</p>
+        {hostMissing ? <p className={css.muted}>{t('loadErrorHostMissing')}</p> : null}
         {loadErrorDetail !== null ? <pre className={css.muted}>{loadErrorDetail}</pre> : null}
         <button type="button" onClick={() => { setLoadState('loading'); load() }}>{t('retry')}</button>
       </div>

package/src/client/index.ts

@@ -95,7 +95,7 @@ function failureOf(error: { code: string; message: string }): McpManagerFailure
  * itself so it needs no modification to any in-box package.
  * @param ctx - Client Cordis root.
  */
-export async function apply(ctx: ClientContext): Promise<void> {
+export async function apply(ctx: Context): Promise<void> {
   await ctx.remote.$mount(remoteContribution)
 
   ctx.effect(() => ctx.locale.register(NS, { zh, en }), 'ui-settings-mcp: dictionaries')

package/src/client/locales.ts

@@ -5,6 +5,7 @@ export const zh = {
   nav: 'MCP',
   loading: '正在读取 MCP 服务器…',
   loadError: '暂时无法读取 MCP 服务器。',
+  loadErrorHostMissing: '宿主端未提供 mcpManager 服务（HTTP 404）。通常是插件 host 半未注册或 client/host 版本不匹配：请确认 cordis.patch.yml 已注册 dsh-mcp 行、重启 dsh web 并硬刷新（Cmd/Ctrl+Shift+R）；若升级过插件请同步升级宿主。',
   retry: '重试',
   empty: '还没有配置 MCP 服务器。',
   addServer: '添加服务器',
@@ -111,6 +112,7 @@ export const en = {
   nav: 'MCP',
   loading: 'Reading MCP servers…',
   loadError: 'MCP servers are temporarily unavailable.',
+  loadErrorHostMissing: 'The host does not expose the mcpManager service (HTTP 404). Usually the plugin host half is not registered or the client/host versions mismatch: confirm the cordis.patch.yml dsh-mcp row, restart dsh web, and hard-refresh (Cmd/Ctrl+Shift+R); after upgrading the plugin, upgrade the host to match.',
   retry: 'Retry',
   empty: 'No MCP servers are configured yet.',
   addServer: 'Add server',

package/src/client/mcp-store.ts

@@ -4,7 +4,7 @@
  * inject callbacks; the store only mirrors their results so components stay
  * pure presentational.
  */
-import { defineStore, type EngineStoreHandle } from '@deepseek-ai/dsh-client-runtime/client'
+import { defineStore, type EngineStoreHandle } from '@deepseek-ai/dsh-client-store'
 import type {
   McpProbeView, McpServerId, McpServerInput, McpServerView, McpTransportKind,
 } from './types.ts'