ModelContextProtocol C SDK 中状态化 HTTP 流式会话的生命周期管理

问题背景

在使用 ModelContextProtocol C# SDK 开发基于 ASP.NET 的服务端应用时，开发者发现当客户端断开连接后，状态化 HTTP 流式会话(Stateful HttpStreamable)的 RunAsync 方法不会立即返回，导致会话资源无法及时释放。这与 SSE(Server-Sent Events)传输模式下的行为不同，在 SSE 模式下，客户端断开连接会立即触发会话终止。

核心机制解析

流式 HTTP 与 SSE 的差异

1. 会话保持特性
   流式 HTTP 规范允许客户端保持会话开放而不需要持续发送请求，这是与 SSE 传输模式的本质区别。在 SSE 模式下，连接断开意味着会话终止；而在流式 HTTP 中，会话可以保持活跃状态。

2. 空闲会话管理
   SDK 通过 IdleTrackingBackgroundService 实现空闲会话管理，提供两个关键配置参数：

   • IdleTimeout：默认 2 小时的空闲超时
   • MaxIdleSessionCount：默认 100,000 个空闲会话上限

通知机制工作原理

1. 服务器到客户端通知
   当客户端关闭服务器到客户端的流时，服务器仍可通过以下方式发送通知：

   • 客户端可主动发起 GET 请求建立新的 SSE 流
   • 如果客户端不主动请求，则不会收到通知

2. 多连接支持
   单个流式 HTTP 会话可以包含多个并发的 SSE HTTP 响应流，服务器会选择其中一个流发送 JSON-RPC 消息，而不是在所有流上广播。

最佳实践建议

资源管理策略

1. 调整空闲参数
   对于需要严格管理资源的应用，建议适当降低空闲参数：

WithHttpTransport(o => {
    o.Stateless = false;
    o.IdleTimeout = TimeSpan.FromMinutes(30);
    o.MaxIdleSessionCount = 1000;
});

2. 会话清理机制
   在 RunSessionHandler 中实现健壮的资源清理：

internal async Task RunSessionHandlerAsync(HttpContext context, IMcpServer server, CancellationToken ct)
{
    var session = new StatefulSession();
    try
    {
        await server.RunAsync(ct);
    }
    finally
    {
        session.Dispose(); // 确保资源释放
    }
}

客户端兼容性考虑

1. 保持连接策略
   虽然流式 HTTP 不要求持续连接，但建议客户端保持一个 SSE 连接以：

   • 避免会话因空闲超时被终止
   • 确保及时接收服务器通知

2. 断线重连处理
   客户端应实现自动重连机制，特别是在调整了服务器端空闲超时参数的情况下。

技术实现细节

会话生命周期

1. 创建阶段
   当客户端首次连接时，服务器创建状态化会话并分配唯一标识符。

2. 活跃阶段
   会话保持开放状态，可以处理多个并发的请求/响应流。

3. 空闲阶段
   当没有活动请求时，会话进入空闲状态，开始计时等待超时。

4. 终止阶段
   满足以下任一条件时终止会话：

   • 达到空闲超时阈值
   • 超过最大空闲会话数限制
   • 显式调用终止方法

内存管理优化

1. 轻量级会话设计
   SDK 采用轻量级会话设计，即使保持大量空闲会话也不会显著增加内存压力。

2. 智能回收机制
   后台服务会优先回收最久未使用的会话，确保系统资源合理利用。

通过深入理解这些机制，开发者可以更好地平衡资源利用率和用户体验，构建稳定高效的 ModelContextProtocol 服务端应用。