René's URL Explorer Experiment

Title: [v2] ClientSession runs on JSONRPCDispatcher; BaseSession removed by maxisbey · Pull Request #2838 · modelcontextprotocol/python-sdk · GitHub

Open Graph Title: [v2] ClientSession runs on JSONRPCDispatcher; BaseSession removed by maxisbey · Pull Request #2838 · modelcontextprotocol/python-sdk

X Title: [v2] ClientSession runs on JSONRPCDispatcher; BaseSession removed by maxisbey · Pull Request #2838 · modelcontextprotocol/python-sdk

Description: V2 client receive path: Transport -> JSONRPCDispatcher -> ClientSession callbacks, replacing the BaseSession receive loop. Companion to #2710, which did the same for the server seat; BaseSession is now deleted. Motivation and Context ClientSession was the last consumer of the v1 BaseSession engine. Moving it onto the dispatcher unifies both seats on one receive path and fixes the v1 client's structural problems: server-initiated requests were handled inline in the receive loop (a slow sampling callback blocked everything, a callback that sent a request deadlocked, and peer cancellation was unactionable), and a raising notification handler could take down the connection. ClientSession's public surface is unchanged: same constructor, same typed methods, manual initialize(), same context-manager lifecycle. A new keyword-only dispatcher= constructor argument accepts a pre-built dispatcher instead of the stream pair (e.g. DirectDispatcher for in-process embedding). What changed CallOptions.cancel_on_abandon + suppression: abandoning a request (timeout or caller cancellation) sends a courtesy notifications/cancelled, unless the caller opted out (initialize, which the spec forbids cancelling) or the request carries resumption hints (the peer's work must survive for the resume) The two shielded cancellation-path writes are bounded (5s), so a wedged transport write can no longer hang shutdown or a cancelled caller Spawned notification handlers and the new on_stream_exception observer are contained at the dispatcher: a raising handler costs itself, never the connection (matching the TypeScript/C#/Go engines) ClientSession internals rewritten over the dispatcher; mcp.shared.session shrinks to a compatibility module (ProgressFnT re-export, typing-only RequestResponder stub for MessageHandlerFnT annotations) The dispatcher constructor overloads collapsed via a defaulted TypeVar (PEP 696) Drive-by fix: the standalone SSE writer no longer logs an ERROR traceback when transport teardown closes its stream mid-listen Parity bar The transport-parametrized interaction suite passes. Three recorded divergences are now resolved and deleted from the requirements manifest (protocol:timeout:sends-cancellation, protocol:cancel:late-response-ignored, protocol:cancel:server-to-client), and the server-to-client cancellation requirement is pinned by a new test passing over all three transports. Breaking Changes Documented in docs/migration.md (one grouped entry): Request ids count from 1 (previously 0); progress tokens follow Timeout error text is now Request 'tools/call' timed out, and a timed-out or abandoned request sends notifications/cancelled, interrupting the server handler Server-initiated requests run concurrently; a server's cancellation now actually interrupts the client callback Notification callbacks are concurrent (no completion-before-response guarantee) Responses with unknown ids are ignored per spec instead of surfacing a RuntimeError to message_handler Unknown inbound methods are answered with METHOD_NOT_FOUND (carrying the method in data), completing #2836's contract on the client seat A raising request callback is answered with code=0 and the exception text (previously flattened to INVALID_PARAMS) send_request before entering the context manager raises RuntimeError immediately Fixes #2489. Fixes #2507. Supersedes #2490. Related, not closed here: #2673 (a raising request callback now answers the server with code=0 and the exception text instead of INVALID_PARAMS; the opt-in propagation of the exception to the local call_tool awaiter that the issue requests stays open as a separate decision) and #2610 (server-seat bug on a code path that no longer exists on main after #2710; still open for v1.x triage — not addressed here). How Has This Been Tested? Full suite (1741 tests) including the interaction suite over in-memory, SSE, and streamable HTTP; 100% branch coverage held on all changed files. New tests: courtesy-cancel wire pins and suppression, wedged-transport shutdown bound (trio virtual clock), notification-handler containment, stream-exception observer, the dispatcher= constructor over direct dispatch, server-seat timeout cancellation, abandoned-server-request cancellation, standalone-stream teardown ordering. Types of changes Bug fix (non-breaking change which fixes an issue) Breaking change (fix or feature that would cause existing functionality to change) Documentation update Checklist I have read the MCP Documentation My code follows the repository's style guidelines New and existing tests pass locally I have added appropriate error handling I have added or updated documentation as needed AI Disclaimer

Open Graph Description: V2 client receive path: Transport -> JSONRPCDispatcher -> ClientSession callbacks, replacing the BaseSession receive loop. Companion to #2710, which did the same for the server seat; BaseSess...

X Description: V2 client receive path: Transport -> JSONRPCDispatcher -> ClientSession callbacks, replacing the BaseSession receive loop. Companion to #2710, which did the same for the server seat; ...

Opengraph URL: https://github.com/modelcontextprotocol/python-sdk/pull/2838

X: @github

direct link

Domain: github.com

Links:

Viewport: width=device-width