MCP 会话自愈 MaxHou-infinity/dsh-mcp-session-recovery

dsh-mcp-session-recovery

一个仓外补丁，让 @deepseek-ai/dsh-mcp-client 在带状态的 Streamable HTTP MCP 服务端不再认识会话时恢复过来——不管服务端是重启了，还是服务一直在线、只是会话因空闲超时被清理了。

没有它，该服务端的所有工具会永久失败——只能重启 DSH。有了它，客户端会发现会话已死，并在一两秒内自行重建连接。

中文摘要：当带会话状态的 MCP 服务端（Streamable HTTP）不再认识 DSH 手里那个 mcp-session-id 时（服务端重启，或会话因空闲超时被清理），该服务端的所有工具调用会永久失败，只能靠重启 DSH 恢复。本仓库是一个仓外补丁，让客户端自己发现会话失效并重连，1~2 秒内自愈。

⚠️ 注意一个常见误解：并不需要服务端重启。实测有服务端把会话持久化到磁盘、重启完全无损，但设有 12 小时空闲超时 —— 只要 DSH 挂着超过 12 小时没有 MCP 调用，同样会中招。详见下文。

上游已知（见下方链接），官方暂不接受外部 PR，故以此形式发布。

这个 bug

dsh-mcp-client 有一套完整重连监管机制——有界指数退避、按故障区间计算的尝试预算、重连后重新同步工具。它只接了一个信号：

generation.onclose = () => { ... if (attemptSettled) generationDown(generation) }

会话丢失从不触发 close。MCP SDK 把它报成请求级错误：传输层抛出 SdkHttpError，status: 404，只调用 onerror，onclose 一声不吭。那个已死的 mcp-session-id 会被留着，因为 SDK 只在握手成功时才改写它——而握手只发生在 connectGeneration() 里，这个函数只在启动时或重连后运行。

于是：

服务端不再认识我们的 mcp-session-id → 客户端还攥着旧 id → 下次工具调用 → HTTP 404 → SDK 触发 onerror（不是 onclose） → dsh-mcp-client 没订阅 onerror → 信号被丢掉 → 不重连，不重新握手，session id 永远不换 ⇒ Host 进程活着一天，就永久失败一天

开新会话没用：MCP 桥接是进程级的，每个 Host 一个插件实例，所有会话共用。只有重启 Host 才行。

有个很说明问题的对比：连接尝试失败 能走到监管机制（settleFailedGeneration → generationDown → scheduleReconnect），所以启动时就挂掉的服务端会一直重试。只有已建立连接上的会话失效会掉进这个缝里。

什么会让会话失效，取决于服务端

两种情形都产生同样的 404、同样的永久失败，所以补丁也一样——但触发条件值得了解，因为它决定你多久撞上一次：

| 服务端行为 | 触发条件 | 说明 |
| 会话存在内存里 | 进程重启 | 经典情形 |
| 会话持久化并恢复 | 空闲超时 | 重启无害；长时间空闲才有害 |

第二种情形是这里端到端验证过的。Nowledge Mem 的后端日志写着

MCP session idle timeout and restart restore store configured
seconds=43200 # 12 hours
store_path=…/co.nowledge.mem.desktop/mcp-sessions.json

而且会话确实能在服务端反复重启后存活（已确认：连续两次重启应用之前创建的 MCP 会话，之后仍然返回 200），而超过 43200s 的会话会被清理，并以 404 Not Found: Session not found 拒绝。

实际后果： DSH 连续运行超过 12 小时且没有发起 MCP 调用，就足以断开连接——没有崩溃，没有重启，什么都看不出来。这比服务端崩溃容易触发得多，而正是这种形态的故障，不打补丁就完全不可见。

受影响的版本

lib/index.js 在这些版本之间逐字节相同，所以同一个补丁对两者都适用：

| 版本 | lib/index.js sha256 | 是否受影响 |
| @deepseek-ai/dsh-mcp-client@0.2.0-rc.2 | 758d8fc4…f5dd | 是 |
| @deepseek-ai/dsh-mcp-client@0.2.1-alpha.4 | 758d8fc4…f5dd | 是 |

grep -c onerror lib/index.js → 两者都是 0。

安装

git clone https://github.com/MaxHou-infinity/dsh-mcp-session-recovery
cd dsh-mcp-session-recovery
./apply.sh

脚本会找到已安装的插件，如果文件与补丁所基于的版本不匹配就拒绝继续（除非你确认），把原文件备份到 ~/.dsh/backups/dsh-mcp-client-pre-onerror-fix/，在临时仓库里应用补丁，这样部分应用不会落地，并对结果做语法检查。脚本是幂等的。

然后重启 DSH：

kill $(lsof -ti tcp:3080 -sTCP:LISTEN); dsh web

验证

离线复现 bug 和修复，不用重启 DSH，也不用真实 MCP 服务端——一个假的有状态服务端会在中途让会话失效：

node test/run.mjs /path/to/.../dsh-mcp-client/lib/index.js

它会打印 RECOVERED（已打补丁）或 STUCK（未打补丁）。对着备份跑一遍就能看到对照组。

验证真实环境——DSH 正在运行、MCP 工具正常工作时，让会话失效，然后调用工具：

- 第一次调用失败，报 404 Session not found（预期如此——这就是触发点）
- 一两秒内，调用再次成功，无需重启 DSH

打这个补丁之前，第二步从不会发生。

这个补丁所基于的端到端运行结果

对着真实 DSH 主机（0.2.0-rc.2）和真实 Nowledge Mem 后端，让会话超过服务端 43200s 空闲超时来使其失效：

| 步骤 | 观察到的现象 |
| 第一次工具调用 | Error POSTing to endpoint: Not Found: Session not found |
| 约 8s 后，服务端会话存储 | 出现一个新的 dsh-mcp-client 会话 id |
| 第二次工具调用 | 成功 |

中间没有重启 DSH。服务端会话存储在这里是有用的见证者：新条目自己冒出来，就证明发生了一次全新的 initialize 握手，而只有重连后的那一代才会执行这个握手。

要用同样的方式让持久化会话的服务端会话失效，就停掉服务端，让它会话存储里的条目过期，再启动它——改动一个活跃的存储没有意义，因为运行中的服务器把会话保存在内存里。

补丁改了什么

两处新增，约 35 行，其他路径行为不变：

1. isSessionLostError(error) —— 一个刻意收窄的判断函数：status === 404（传输层只会在请求携带会话 id 时产生这个状态码），加上 400 且响应体指明会话缺失／无效／未知／过期。其他情况原样抛出，所以普通的请求错误永远不会回收一个健康的 generation。
2. generation.onerror = (error) => { if (attemptSettled && isSessionLostError(error)) generationDown(generation) }
—— 把会话丢失导入 onclose 已经在用的同一条断连路径。下游的一切（退避、重新握手、工具重新同步）都是现有机制，未作改动。

卸载

./revert.sh # restores from the newest backup

重新安装或升级 DSH 也会还原它 —— 这个补丁位于全局安装的 @deepseek-ai/dsh 包内部，不会在 DSH 升级后保留。升级后如果 bug 仍在，重新运行 ./apply.sh（用 grep -c onerror lib/index.js 检查）。

为什么这不是上游 PR

官方仓库不接受 PR。摘自 CONTRIBUTING.md：

We are sorry that we cannot accept external pull requests at the moment.

而且仓库的 PR API 返回 404 —— pull request 已关闭，issue 也一样。政策转而把贡献者引向 Discussions 和生态：

We do not believe that packages in the official repository are inherently more
important than packages created by the community.

所以这里以树外补丁的形式发布，而不是 fork。上游报告在 deepseek-ai/deepseek-harness#9740；如果维护者采纳了修复，这个仓库就会退役。

许可证

MIT。补丁修改的是 MIT 许可的代码，Copyright (c) 2026 DeepSeek；这里的补丁文件和脚本按相同条款提供。