feat: add ClientRequestContext type alias for client-side handlers

Introduce a dedicated `ClientRequestContext` type alias in
`mcp.client.context` to provide a cleaner API for client-side callback
handlers (sampling, elicitation, list_roots).

This improves the developer experience by:
- Providing a concrete type instead of requiring `RequestContext[ClientSession]`
- Making the internal `RequestContext` private by moving it to `_context.py`
- Exporting `ClientRequestContext` from `mcp.client` for easy access

The migration guide has been updated to reflect these changes.

Author: Kludex

.github/actions/conformance/client.py

@@ -39,8 +39,8 @@
     SignedJWTParameters,
 )
 from mcp.client.streamable_http import streamable_http_client
+from mcp.shared._context import RequestContext
 from mcp.shared.auth import OAuthClientInformationFull, OAuthClientMetadata, OAuthToken
-from mcp.shared.context import RequestContext
 
 # Set up logging to stderr (stdout is for conformance test output)
 logging.basicConfig(

README.md

@@ -2120,8 +2120,8 @@ import asyncio
 import os
 
 from mcp import ClientSession, StdioServerParameters, types
+from mcp.client.context import ClientRequestContext
 from mcp.client.stdio import stdio_client
-from mcp.shared.context import RequestContext
 
 # Create server parameters for stdio connection
 server_params = StdioServerParameters(
@@ -2133,7 +2133,7 @@ server_params = StdioServerParameters(
 
 # Optional: create a sampling callback
 async def handle_sampling_message(
-    context: RequestContext[ClientSession, None], params: types.CreateMessageRequestParams
+    context: ClientRequestContext, params: types.CreateMessageRequestParams
 ) -> types.CreateMessageResult:
     print(f"Sampling request: {params.messages}")
     return types.CreateMessageResult(

README.v2.md

@@ -2122,7 +2122,7 @@ import os
 
 from mcp import ClientSession, StdioServerParameters, types
 from mcp.client.stdio import stdio_client
-from mcp.shared.context import RequestContext
+from mcp.shared._context import RequestContext
 
 # Create server parameters for stdio connection
 server_params = StdioServerParameters(

docs/migration.md

@@ -400,19 +400,18 @@ progress_ctx: ProgressContext[SendRequestT, SendNotificationT, SendResultT, Rece
 **After (v2):**
 
 ```python
-from mcp.shared.context import RequestContext
+from mcp.client.context import ClientRequestContext
+from mcp.server.context import ServerRequestContext, LifespanContextT, RequestT
 from mcp.shared.progress import ProgressContext
 
-# RequestContext with 1 type parameter
-ctx: RequestContext[ClientSession]
-
-# ProgressContext with 1 type parameter
-progress_ctx: ProgressContext[ClientSession]
+# For client-side context (sampling, elicitation, list_roots callbacks)
+ctx: ClientRequestContext
 
 # For server-specific context with lifespan and request types
-from mcp.server.context import ServerRequestContext, LifespanContextT, RequestT
-
 server_ctx: ServerRequestContext[LifespanContextT, RequestT]
+
+# ProgressContext with 1 type parameter
+progress_ctx: ProgressContext[ClientSession]
 ```
 
 ### Resource URI type changed from `AnyUrl` to `str`

examples/clients/simple-task-interactive-client/mcp_simple_task_interactive_client/main.py

@@ -11,7 +11,7 @@
 import click
 from mcp import ClientSession
 from mcp.client.streamable_http import streamable_http_client
-from mcp.shared.context import RequestContext
+from mcp.shared._context import RequestContext
 from mcp.types import (
     CallToolResult,
     CreateMessageRequestParams,

examples/snippets/clients/stdio_client.py

@@ -7,7 +7,7 @@
 
 from mcp import ClientSession, StdioServerParameters, types
 from mcp.client.stdio import stdio_client
-from mcp.shared.context import RequestContext
+from mcp.shared._context import RequestContext
 
 # Create server parameters for stdio connection
 server_params = StdioServerParameters(

examples/snippets/clients/url_elicitation_client.py

@@ -32,7 +32,7 @@
 
 from mcp import ClientSession, types
 from mcp.client.sse import sse_client
-from mcp.shared.context import RequestContext
+from mcp.shared._context import RequestContext
 from mcp.shared.exceptions import MCPError, UrlElicitationRequiredError
 from mcp.types import URL_ELICITATION_REQUIRED
 

src/mcp/client/__init__.py

@@ -2,6 +2,7 @@
 
 from mcp.client._transport import Transport
 from mcp.client.client import Client
+from mcp.client.context import ClientRequestContext
 from mcp.client.session import ClientSession
 
-__all__ = ["Client", "ClientSession", "Transport"]
+__all__ = ["Client", "ClientRequestContext", "ClientSession", "Transport"]

src/mcp/client/context.py

@@ -0,0 +1,16 @@
+"""Request context for MCP client handlers."""
+
+from mcp.client.session import ClientSession
+from mcp.shared._context import RequestContext
+
+ClientRequestContext = RequestContext[ClientSession]
+"""Context for handling incoming requests in a client session.
+
+This context is passed to client-side callbacks (sampling, elicitation, list_roots) when the server sends requests
+to the client.
+
+Attributes:
+    request_id: The unique identifier for this request.
+    meta: Optional metadata associated with the request.
+    session: The client session handling this request.
+"""

src/mcp/client/experimental/task_handlers.py

@@ -19,7 +19,7 @@
 from pydantic import TypeAdapter
 
 import mcp.types as types
-from mcp.shared.context import RequestContext
+from mcp.shared._context import RequestContext
 from mcp.shared.session import RequestResponder
 
 if TYPE_CHECKING: