refactor: address review — kw_only dataclass, type Experimental properly, remove redundant guard

- RequestContext: use @DataClass(kw_only=True) instead of per-field kw_only
- RequestContext: type experimental as Experimental | None via TYPE_CHECKING
- Server.__init__: remove redundant 'if handlers:' guard
- Server: use keyword args for RequestContext construction

Author: maxisbey

src/mcp/server/lowlevel/server.py

@@ -140,18 +140,17 @@ def __init__(
         self._request_handlers["ping"] = RequestHandler("ping", handler=_ping_handler)
 
         # Process user-provided handlers with duplicate detection
-        if handlers:
-            for handler in handlers:
-                if isinstance(handler, RequestHandler):
-                    if handler.method in self._request_handlers:
-                        raise ValueError(f"Duplicate request handler for '{handler.method}'")
-                    self._request_handlers[handler.method] = handler
-                elif isinstance(handler, NotificationHandler):  # pyright: ignore[reportUnnecessaryIsInstance]
-                    if handler.method in self._notification_handlers:
-                        raise ValueError(f"Duplicate notification handler for '{handler.method}'")
-                    self._notification_handlers[handler.method] = handler
-                else:
-                    raise TypeError(f"Unknown handler type: {type(handler)}")
+        for handler in handlers:
+            if isinstance(handler, RequestHandler):
+                if handler.method in self._request_handlers:
+                    raise ValueError(f"Duplicate request handler for '{handler.method}'")
+                self._request_handlers[handler.method] = handler
+            elif isinstance(handler, NotificationHandler):  # pyright: ignore[reportUnnecessaryIsInstance]
+                if handler.method in self._notification_handlers:
+                    raise ValueError(f"Duplicate notification handler for '{handler.method}'")
+                self._notification_handlers[handler.method] = handler
+            else:
+                raise TypeError(f"Unknown handler type: {type(handler)}")
 
     def _add_handler(self, handler: Handler) -> None:
         """Add a handler, silently replacing any existing handler for the same method."""
@@ -376,8 +375,8 @@ async def _handle_request(
                 if hasattr(req, "params") and req.params is not None:
                     task_metadata = getattr(req.params, "task", None)
                 ctx = RequestContext(
-                    session,
-                    lifespan_context,
+                    session=session,
+                    lifespan_context=lifespan_context,
                     experimental=Experimental(
                         task_metadata=task_metadata,
                         _client_capabilities=client_capabilities,
@@ -424,8 +423,8 @@ async def _handle_notification(
                 client_capabilities = session.client_params.capabilities if session.client_params else None
                 task_support = self._experimental_handlers.task_support if self._experimental_handlers else None
                 ctx = RequestContext(
-                    session,
-                    lifespan_context,
+                    session=session,
+                    lifespan_context=lifespan_context,
                     experimental=Experimental(
                         task_metadata=None,
                         _client_capabilities=client_capabilities,

src/mcp/shared/context.py

@@ -1,20 +1,25 @@
 """Request context for MCP handlers."""
 
-from dataclasses import dataclass, field
-from typing import Any, Generic
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import TYPE_CHECKING, Any, Generic
 
 from typing_extensions import TypeVar
 
 from mcp.shared.message import CloseSSEStreamCallback
 from mcp.shared.session import BaseSession
 from mcp.types import RequestId, RequestParamsMeta
 
+if TYPE_CHECKING:
+    from mcp.server.experimental.request_context import Experimental
+
 SessionT = TypeVar("SessionT", bound=BaseSession[Any, Any, Any, Any, Any])
 LifespanContextT = TypeVar("LifespanContextT")
 RequestT = TypeVar("RequestT", default=Any)
 
 
-@dataclass
+@dataclass(kw_only=True)
 class RequestContext(Generic[SessionT, LifespanContextT, RequestT]):
     """Context passed to request and notification handlers.
 
@@ -24,13 +29,9 @@ class RequestContext(Generic[SessionT, LifespanContextT, RequestT]):
 
     session: SessionT
     lifespan_context: LifespanContextT
-    # NOTE: This is typed as Any to avoid circular imports. The actual type is
-    # mcp.server.experimental.request_context.Experimental, but importing it here
-    # triggers mcp.server.__init__ -> mcpserver -> tools -> back to this module.
-    # The Server sets this to an Experimental instance at runtime.
-    experimental: Any = field(default=None, kw_only=True)
-    request_id: RequestId | None = field(default=None, kw_only=True)
-    meta: RequestParamsMeta | None = field(default=None, kw_only=True)
-    request: RequestT | None = field(default=None, kw_only=True)
-    close_sse_stream: CloseSSEStreamCallback | None = field(default=None, kw_only=True)
-    close_standalone_sse_stream: CloseSSEStreamCallback | None = field(default=None, kw_only=True)
+    experimental: Experimental | None = None
+    request_id: RequestId | None = None
+    meta: RequestParamsMeta | None = None
+    request: RequestT | None = None
+    close_sse_stream: CloseSSEStreamCallback | None = None
+    close_standalone_sse_stream: CloseSSEStreamCallback | None = None