Repository navigation
Refactor handler context to be transport- and handler-type-aware #2021
Description
The current RequestContext / ServerRequestContext design has a few rough edges that warrant a dedicated refactor:
-
Request vs notification context — Request handlers have
request_idandmeta, notification handlers do not. Currentlyrequest_idis optional (RequestId | None) on a single shared type, which loses type safety. Ideally these would be distinct types so request handlers get a context whererequest_idis always present, and notification handlers get one where it does not exist. -
Transport-specific context — The
request_contextfield onServerMessageMetadatais typed asAnybecause the server layer is transport-agnostic (e.g. it is a StarletteRequestfor HTTP transports,Nonefor stdio). A better design would let transports provide their own typed context that handlers can access without casting.
These two concerns are related — both point toward making the context type more precise depending on how and where a handler is invoked.
Activity
maxisbey commentedon Feb 18, 2026
Adding context from #2038 / #953 / #2001: the
related_request_idpattern is a concrete example of the problem described in this issue.Every
Contextmethod that sends a notification must manually threadrelated_request_id=self.request_id:report_progress()— was missing it, causing silent notification drops on streamable HTTP (the bug in context.report_progress not sending notifications on streamable-http #953/Progress notifications not delivered via SSE in stateless HTTP mode #2001, open for 8 months)log()elicit()elicit_url()Same bug exists unfixed in:
ProgressContext.progress()— norelated_request_idTaskContext._send_notification()— potentially missing itThe fix in #2038 is a band-aid (adding the missing kwarg). The architectural fix would be to centralize
related_request_idbinding inContext(e.g., a request-scoped session wrapper or asend_notificationhelper) so individual methods do not need to remember to pass it.refactor: remove unused mcp.shared.progress module