[Bug] mcp-client 工具注册静默失败：server 存活、资源可列，但 mcp__matlab__* 14 个工具整族消失（仅重启宿主可恢复）

[zrwangems]

环境

• DSH Desktop 0.2.0-rc.2（Windows 11 家庭中文版 10.0.22631，profile：desktop）
• 涉及插件：@deepseek-ai/dsh-mcp-client 0.2.0-rc.2（源码路径 packages/mcp/mcp-client）
• MCP server：MathWorks 官方 matlab-mcp-server v0.15.0（Windows x64 发布二进制，Go，stdio），额外用 --extension-file 挂了 9 个自定义工具，共 14 个 tool + 2 个 resource
• 会话预设：engineering（工程模式）。该预设的 resource-filter 只有 skillSeries，没有 toolPrefixes，即不存在任何"按前缀屏蔽工具"的逻辑

现象

同一会话内同时满足：

• MCP server 子进程存活（matlab-mcp-server-windows-x64.exe）；
• DSH 侧 resources/list 正常返回 2 个 resource；
• 用裸 MCP 握手（initialize → tools/list）直连同一个二进制，稳定返回 14 个 tool；
• 但 agent 运行时工具面里 mcp__matlab__* 是 0 个。

量化读数

状态	运行时工具面	mcp__matlab__*
异常	75	0
重启 DSH 宿主后（配置、预设、server、MATLAB 都没动）	84	14（全部到齐）

补充一句读数观察：75 → 84 差 9，而新增的 matlab 家族是 14，两者对不上，怀疑那一次丢的不止一个 MCP 家族；这点我没有别的证据，只记录读数。2026-10-16 当天"重启宿主即恢复"共出现两次。

从插件源码读到的行为（lib/index.js）

• syncTools()：遍历 tools/list 结果后逐个 ctx.tools.register(definition)；一旦抛错，先回滚本轮已注册的部分，打一条
  mcp-client(<serverName>): tool registration failed, no tools registered: <error>
  的 error 日志，然后按 registrationFailure: "contain" 吞掉并返回空 Map；
• failOnStartupError: true 时 registrationFailure 才由 "contain" 变为 "throw"；
• 另一处：初始连接 + 发现完成后若 outcome.error 非空且 failOnStartupError 为真，抛 initial connection or tool synchronization failed；
• 叠加 listChanged.autoRefresh: false，首次成功同步之后再发生的注册失败既没有重试也没有重同步，对使用者表现为"工具整族凭空消失"，只能重启宿主。

复现

没有稳定触发步骤：两次都发生在日常连续使用中，不是某个特定操作之后。能稳定复现的只有"恢复动作"——重启 DSH 宿主（或重载插件、重开会话）后工具恢复。裸 MCP 直连始终正常，说明故障在客户端的注册环节，不在 server。

期望

1. ctx.tools.register() 失败时按策略重试，或在下一轮请求前做一次强制重同步（把 listChanged 的 autoRefresh 做成可配置开关）；
2. 或把注册失败升级为会话可见状态（工具面板把该 server 标为 degraded／提示"该 server 当前 0 工具"），而不是只落一条日志；
3. 给一个可观测口径：运行时工具面及 MCP 家族列表在哪里读（我目前只能靠 run_code 里 Object.keys(tools) 自查）。

附：本机 mcp-matlab 配置（cordis.patch.yml）

- insert:
    - id: mcp-matlab
      name: '@deepseek-ai/dsh-mcp-client'
      config:
        serverName: matlab
        transport: stdio
        command: 'D:\AgentRelated\AgenticToolkits\matlab-mcp-server-windows-x64.exe'
        args:
          - '--matlab-session-mode=existing'
          - '--extension-file=D:\AgentRelated\AgenticToolkits\simulink-agentic-toolkit\tools\tools.json'
          - '--disable-telemetry=true'
        env:
          WINDIR: 'C:\Windows'
        toolCallTimeoutMs: 600000
        failOnStartupError: true
        reconnect:
          enabled: true
          initialDelayMs: 500
          maxDelayMs: 30000
          maxAttempts: 10

failOnStartupError 是事后加的缓解，只覆盖初次连接/同步路径，不改变本问题本身。

附：裸握手读数

initialize  → serverInfo: matlab-mcp-server v0.15.0；capabilities.resources.listChanged = true；tools.listChanged = true
tools/list  → 14 个：check_matlab_code, detect_matlab_toolboxes, evaluate_matlab_code, run_matlab_file,
              run_matlab_test_file, model_overview, model_read, model_query_params, model_resolve_params,
              model_edit, model_read_diagnostics, model_check, model_scan, model_test
resources/list → guidelines://coding, guidelines://plain-text-live-code

[argszero]

Your reading of syncTools is exact. The part that decides your symptom is one line you did not quote, and it is not in the contain branch itself.

The swap disposes the previous generation before it registers the new one (packages/mcp/mcp-client/src/tools.ts:145-160):

// Phase 2: swap generations.
for (const dispose of previous.values()) dispose()          // :146  old generation is gone from here on
const disposers: ToolDisposers = new Map()
try {
  for (const [publicName, definition] of definitions) {
    disposers.set(publicName, ctx.tools.register(definition))  // :150
  }
} catch (error) {
  for (const dispose of disposers.values()) dispose()          // rollback of the NEW generation only
  ctx.logger.error(`mcp-client(${opts.serverName}): tool registration failed, no tools registered: ${String(error)}`)
  if (opts.registrationFailure === 'throw') throw error
  return new Map()                                             // :159
}

So registrationFailure: 'contain' does not mean "this round changed nothing". It means this server ends the round with zero registered tools, because the previous generation was already disposed one line earlier. The docstring says so at :100-105 ("the partial generation is rolled back (zero tools from this server) and logged … later re-syncs return an empty map"), and the inline comment at :153-155 restates the intent as "the model sees either the full generation or none of it — never a partial set" — but the swap is not atomic in the other direction: the old set is already destroyed when the new one fails. That is the only path in this package that turns a connected, healthy server into 0 tools, so it is the first hypothesis to test against your logs, not the last.

Note the contrast with Phase 1 (:119-142). Fetching and building the definitions touches no registry, so a throw there (a server listing a raw name twice, :124-131, or a definition that fails schema assertion inside createMcpToolDefinition) propagates before the swap and leaves the previous generation registered. The two halves are distinguishable by exactly one log line each.

Which lines to grep, and what each one means

line	meaning
tool registration failed, no tools registered: <error> (tools.ts:157)	Phase 2 conflict. The family was registered and a failed swap removed it — and <error> names the conflicting public name. This is your case if it appears.
tool re-sync failed: <error> (connection.ts:302)	Phase 1 (or a fetch failure on a re-sync). The previous generation is untouched; the family should still be present, so a disappearance has another cause.
tool list changed, re-syncing (connection.ts:298)	a notification-driven re-sync happened at all.
reconnected and re-synced tools (attempt n/m) (connection.ts:342)	a reconnect's sync succeeded.
connection attempt failed: <error> (connection.ts:328)	the connect itself failed; the sync never ran.

If none of the first four appear near the disappearance, the family was never registered in that process at all, and the bridge is the wrong place to look — check the session surface instead (a developer/message with source.kind === 'tool-registry' is appended whenever the surface changes, packages/core/agent-loop/src/agent.ts:652-664) and your preset's tool restriction before touching MCP.

Why "only a host restart recovers" — two facts about the sync triggers make that outcome predictable:

• registrationFailure is 'contain' for every sync except the very first: startupOpts is only strict when failOnStartupError is true (connection.ts:131-140), and connectGeneration passes it only when startup is true (:323, await enqueueSync(generation, startup ? startupOpts : opts)). The comment at :135-137 states the design: "Re-syncs and reconnect syncs always contain conflicts." So a reconnect after a dropped transport can silently empty a server that started fine.
• The disposer map is shared across generations (connection.ts:150) and nothing disposes it when a generation goes down — generationDown (:180-186) only clears the client and schedules the reconnect; the only disposal sites are :229 (disposal) and :405 (plugin teardown). The previous generation's tools therefore stay live until the next sync's Phase 2 disposes them, which is precisely why a failed reconnect sync is destructive rather than a no-op.

On your resync ask, the state of the knobs is worth stating exactly, since it is the same area as the autoRefresh thread: listChanged.tools.autoRefresh is hardcoded false (connection.ts:263-269) while onChanged → refreshTools is wired (:267), and there is no config field for either; the notification path versus the reconnect path was measured in that thread, with the reconnect as the one that actually re-lists on 0.2.0-rc.2. Both of your asks — retry on failure, and a forced re-sync before the next request — are core changes in this one closure, not plugin work.

On the 75 → 84 arithmetic. It says the pre-restart process held five tools the post-restart one does not (84 − 14 = 70, but you counted 75). That is not the signature of a missing family; it is the signature of registrations surviving from an earlier generation, which the disposer lifetime above makes possible. It is worth one measurement rather than one inference: list the full runtime tool surface before and after the restart and diff the two sets by name, instead of comparing counts.

Plugin boundary, honestly. An out-of-tree plugin cannot reach refreshTools or the closure-local generation, and this package exposes no service (inject = ['tools'] only), so nothing on the plugin side can force a re-list or re-register a family. What a plugin can do is sit on ctx.tools.register — the instance is shadowable, which is where our published @argszero/dsh-mcp-tool-filter and @argszero/dsh-mcp-schema-normalizer already live. A wrapper that made a name conflict non-fatal would convert your failure mode from "the whole generation rolls back" into "only the conflicting name is missing" — 13 of 14 tools instead of 0. I would not ship that as a general package, because it trades away the atomicity the code chooses deliberately, but it is the only plugin-side lever that exists, and it is worth knowing that it exists while you wait for the core fix.