[Bug] mcp-client: activeServerNames 生命周期泄漏导致无法创建新会话

[tang-zhilei]

问题描述

@deepseek-ai/dsh-mcp-client 插件的 activeServerNames 注册表存在生命周期泄漏。当会话关闭后创建新会话时，旧会话的 MCP 客户端实例没有被正确销毁，导致 serverName 仍然保留在全局的 activeServerNames WeakMap 中，阻止 agent preset 在新会话中加载。

错误信息

SessionCreateError: session create failed: agent-preset-invalid: agent-presets: preset "work" failed to mount: loader entries failed to apply
- failed to apply loader entry context7 (@deepseek-ai/dsh-mcp-client): mcp-client: serverName "context7" is already in use by another mcp-client instance — pick a unique serverName in cordis.yml
- failed to apply loader entry idea (@deepseek-ai/dsh-mcp-client): mcp-client: serverName "idea" is already in use by another mcp-client instance — pick a unique serverName in cordis.yml

复现步骤

1. 在 agent preset 中配置 MCP 服务器（~/.dsh/.agent-presets/work/agent.cordis.yml）：

- id: context7
  name: '@deepseek-ai/dsh-mcp-client'
  config:
    serverName: context7
    transport: stdio
    command: cmd
    args: ['/c', 'npx', '-y', '@upstash/context7-mcp']

- id: idea
  name: '@deepseek-ai/dsh-mcp-client'
  config:
    serverName: idea
    transport: streamable-http
    url: http://127.0.0.1:64342/stream

2. 启动 DSH Web GUI，使用 "work" preset 创建新会话
3. 正常使用会话（MCP 工具工作正常）
4. 关闭会话
5. 立即创建新会话
6. 报错：serverName "context7" is already in use

期望行为

关闭会话后，应该能立即创建新会话，不会报错。MCP 客户端实例应该在会话关闭时被正确销毁。

实际行为

activeServerNames 注册表保留了已关闭会话的 serverName 条目，导致新会话无法加载同一个 agent preset。

临时解决方案

• 重启 DSH（清空内存中的 activeServerNames WeakMap）
• 或者等待约 30 秒再创建新会话（不稳定）

根因分析

在 packages/mcp/mcp-client/src/index.ts 中：

// 第45行：全局注册表，用 ctx.root 作为 key
const activeServerNames = new WeakMap<Context, Set<string>>()

// 第148-161行：effect 清理函数应该删除 serverName
ctx.effect(() => {
    let names = activeServerNames.get(ctx.root)
    if (!names) {
      names = 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')

effect 清理函数 () => void names.delete(config.serverName) 已注册但在会话关闭时未被调用。可能原因：

1. Cordis 在会话关闭时没有正确销毁 agent preset 的插件实例
2. effect 清理函数的执行顺序有问题
3. ctx.root 在不同会话之间发生变化，导致 WeakMap 查找失败

环境信息

• 操作系统：Windows 11
• Node.js：v24.18.0
• DSH 版本：master 分支最新代码
• MCP 服务器：context7（stdio）、idea（streamable-http）

建议修复方案

方案1：在注册前检查并清理残留的旧注册：

ctx.effect(() => {
    let names = activeServerNames.get(ctx.root)
    if (!names) {
      names = new Set()
      activeServerNames.set(ctx.root, names)
    }
    // 防御性清理：如果有残留的旧条目，先删除
    names.delete(config.serverName)
    
    if (names.has(config.serverName)) {
      throw new Error(/*...*/)
    }
    names.add(config.serverName)
    return () => void names.delete(config.serverName)
}, 'mcp-client.serverName')

方案2：确保会话关闭时 agent preset 插件的销毁被正确触发。

[yamingmou]

我们针对这个问题做了独立的深度分析，已发布为单独的分析帖（含源码级根因修正、设计层审视与方案评估）：

分析帖：[Analysis] mcp-client activeServerNames: root cause is a scope mismatch, not a missed cleanup — and the proposed "defensive cleanup" is unsafe
🔗 #4025

三个补充结论（详见分析帖）：

1. 根因修正：「清理从未被调用」与复现数据存在矛盾——「等待约 30 秒再创建能成功」说明清理最终执行了，只是延迟。缺陷在上游（会话关闭 → preset 插件实例 fiber 的销毁链），不在 mcp-client 内部；dispose() 本身是完整异步链（:678-696），cleanup 是同步的（:775）。
2. 设计层问题（原报告未提及）：activeServerNames 以 ctx.root（进程级）为 key（:731/:768），而工具注册表是 per-agent 作用域（dsh-tools 基于 ScopedLayers）——作用域不匹配。即使清理即时且完美，两个并行会话挂同一个 serverName 也会被唯一性检查拒绝。
3. 方案评估：方案 1「先删后查」不建议采纳——并行场景下第二个实例会先删除第一个实例的注册再通过检查，导致同一 serverName 静默双活，把确定性报错变成静默故障。方案 2 方向正确，但需先定位上游销毁链的延迟点（约 30 秒）。

验证环境：@deepseek-ai/dsh 0.1.1-rc.2（源码与 master 快照一致）。

---

EN (short version)

We published a separate follow-up analysis on this issue (root-cause correction, design-level scope mismatch, and a caution on the proposed fix):

[Analysis] mcp-client activeServerNames: root cause is a scope mismatch, not a missed cleanup — and the proposed "defensive cleanup" is unsafe
🔗 #4025

Key points:

1. "Cleanup never runs" contradicts the repro data — "waiting ~30s works" means cleanup eventually runs; the defect is upstream (session close → preset fiber teardown chain), not inside mcp-client.
2. Design-level: activeServerNames is keyed on ctx.root (process-level) while the tool registry is per-agent scoped — even perfect teardown would reject two parallel sessions sharing a serverName.
3. Caution on the proposed Fix 1 (defensive delete-then-check): in the concurrent case it lets the second instance pass and silently allows dual-live connections on one serverName.

Verified on @deepseek-ai/dsh 0.1.1-rc.2.