modelcontextprotocol / modelcontextprotocol/python-sdk

Simplify and harden session lifecycle with an explicit state machine

未关闭
#1,691 2 条评论 0 个 reaction 已指派 0 人 在 GitHub 查看

还没有人认领这个 Issue。

enhancement P2 v2
主要语言
Python
星标
24.3k
派生
4k
平均合并
1 天 1 小时
30 天内合并 PR
31

描述

Description

Summary

Server and client sessions use an internal initialization state machine combined with various flags and manual AsyncExitStack management. Stateless mode complicates this further by setting an "Initialized" state early as a workaround.

This makes the lifecycle hard to reason about and contributes to subtle bugs (e.g., past issues like #756 in stateless mode).

Problems

  • Scattered state management: Initialization and teardown logic are spread across methods and files.
  • Special cases for stateless mode: Stateless HTTP sets the session as initialized even though no real protocol negotiation has occurred.
  • Resource management risk: If initialization fails midway, transport tasks and resources may not be cleaned up reliably.
  • Testing difficulty: Tests often bypass parts of the lifecycle using in-memory transports.

Proposal

  1. Introduce an explicit session state machine

    Represent distinct states as separate types, for example:

    • UninitializedSession
    • NegotiatingSession
    • ActiveSession
    • ClosedSession
    • StatelessSession (for per-request / ephemeral cases)

    Each state exposes only the operations that are valid in that state, and transitions return the next state type.

  2. Model stateless mode explicitly

    • Instead of marking a stateful session as "Initialized" prematurely, model stateless HTTP as a dedicated StatelessSession type with a simpler lifecycle.
    • Make behavior differences clear in code and docs.
  3. Centralize resource cleanup

    • Ensure that all lifecycle paths (happy path, error, cancellation) lead through code that:
      • cancels outstanding tasks,
      • closes transports,
      • releases resources stored in AsyncExitStack.

Why this matters

  • Reliability: Fewer edge cases and surprise states where messages can be processed incorrectly.
  • Debuggability: Easier to reason about what can happen in each state.
  • Extensibility: Adding new lifecycle behavior (e.g., resuming sessions) becomes more manageable.

Acceptance criteria

  • Session lifecycle is represented via explicit types or a clearly defined state machine.
  • Stateless HTTP mode uses a dedicated path rather than setting "Initialized" as a hack.
  • All entry/exit paths of sessions ensure proper cleanup of transports and tasks.
  • Tests cover state transitions, including error cases and stateless/stat eful differences.
References

No response

贡献指南

打开贡献指南

从这里开始

  1. 先读完整个 Issue,再读项目的贡献指南。
  2. 在 Issue 下留言说明你要接手 —— 这能避免两个人做同样的事。
  3. Fork 仓库,在一个分支上完成修改。
  4. 提交 Pull Request,并在描述里引用这个 Issue 编号。

调研方向

未指定文件或入口点;先定位现有的会话初始化、无状态 HTTP 路径和 AsyncExitStack 清理。查看 issue #756 以及 issue 中描述的内存传输测试。完成的标准是:具有明确的生命周期状态、专用的无状态路径、在每个退出路径上都能可靠清理,以及针对错误和有状态/无状态情况的状态转换测试。

由索引模型根据 Issue 内容生成。

评估

技术栈
python
领域
api, backend
Issue 类型
重构
难度
5/5
预计耗时
一周以上
活跃度
停滞
描述清晰度
需要澄清
新手友好度
25/100

把新 issue 发到你的邮箱

精选适合新手参与的 GitHub issue 摘要。