Max Isbey
98bd125ddd
The 2026-07-28 protocol did not work over stdio: subscriptions/listen was hard-refused, a legacy initialize arriving during an in-flight modern request was accepted and re-locked the connection, and a peer cancel produced a trailing "Request cancelled" frame. All three share one root cause: the connection's era was derived from which requests had completed instead of being decided once, in wire order, from how the client opened the connection. Replace serve_dual_era_loop and serve_loop with a single serve_stream driver that decides the era synchronously in the dispatcher's read loop, before the request body is spawned. initialize (or any envelope-less request) opens the legacy era, an enveloped request opens the modern era, server/discover is answered without pinning, and a stray leading notification opens nothing. A conflicting era claim on a committed connection is refused (-32022 or -32600) rather than silently switching. Cancel silence is structural: each request answers through a one-shot channel whose write target becomes a powerless void on a peer cancel, so there is no cancelled-check at any write site. The generic JSON-RPC dispatcher loses the code-0 cancel frame, the code-0 str(exc) catch-all, and the inline_methods knob, and documents that handlers are invoked synchronously in receive order with the returned awaitable as the body. Add a Posture enum (DUAL default, LEGACY_ONLY, MODERN_ONLY) on the Server and MCPServer constructors, honoured by the stream driver and the streamable-HTTP manager alike. Server.run(read, write) now stands alone, Server.lifespan() is a bound context manager, and serve_listener / newline_json_transport / close_subscriptions() give a straightforward path for custom transports. See docs/migration.md for the full list of observable changes.
Python SDK examples
stories/— the canonical reference. One self-verifying example per protocol feature, each with its own README. Start withstories/tools/; the stories README has the full table and how to run them.snippets/— short extracts that were embedded into the v1 README (now on thev1.xbranch); superseded bydocs_src/, which the docs and README embed today. Retained pending consolidation intostories/.servers/everything-server/— the conformance target for the cross-SDK conformance suite. Exercises every server capability in one process.mcpserver/— single-file v1-era examples retained for the migration guide; superseded bystories/and slated for removal.clients/and the remainingservers/directories (simple-*,sse-polling-demo,structured-output-lowlevel) — standalone v1-era projects retained pending consolidation intostories/(thesimple-authpair is still linked fromdocs/run/authorization.mdanddocs/client/oauth-clients.md).
For real-world servers see the servers repository.