refactor: replace lowlevel Server decorators with on_* constructor kwargs (#1985)

src/mcp/shared/_context.py

@@ -13,8 +13,12 @@ SessionT = TypeVar("SessionT", bound=BaseSession[Any, Any, Any, Any, Any])
 
 @dataclass(kw_only=True)
 class RequestContext(Generic[SessionT]):
-    """Common context for handling incoming requests."""
+    """Common context for handling incoming requests.
+
+    For request handlers, request_id is always populated.
+    For notification handlers, request_id is None.
+    """
 
-    request_id: RequestId
-    meta: RequestParamsMeta | None
     session: SessionT
+    request_id: RequestId | None = None
+    meta: RequestParamsMeta | None = None

src/mcp/shared/experimental/tasks/helpers.py

@@ -72,9 +72,8 @@ async def cancel_task(
             - Task is already in a terminal state (completed, failed, cancelled)
 
     Example:
-        @server.experimental.cancel_task()
-        async def handle_cancel(request: CancelTaskRequest) -> CancelTaskResult:
-            return await cancel_task(store, request.params.taskId)
+        async def handle_cancel(ctx, params: CancelTaskRequestParams) -> CancelTaskResult:
+            return await cancel_task(store, params.task_id)
     """
     task = await store.get_task(task_id)
     if task is None:

src/mcp/shared/message.py

@@ -6,6 +6,7 @@ to support transport-specific features like resumability.
 
 from collections.abc import Awaitable, Callable
 from dataclasses import dataclass
+from typing import Any
 
 from mcp.types import JSONRPCMessage, RequestId
 
@@ -30,8 +31,10 @@ class ServerMessageMetadata:
     """Metadata specific to server messages."""
 
     related_request_id: RequestId | None = None
-    # Request-specific context (e.g., headers, auth info)
-    request_context: object | None = None
+    # Transport-specific request context (e.g. starlette Request for HTTP
+    # transports, None for stdio). Typed as Any because the server layer is
+    # transport-agnostic.
+    request_context: Any = None
     # Callback to close SSE stream for the current request without terminating
     close_sse_stream: CloseSSEStreamCallback | None = None
     # Callback to close the standalone GET SSE stream (for unsolicited notifications)