feat: absent params reach handlers as the model with defaults, never None

A message with no params member now validates {} against the registered
params_type: models with required fields reject it as INVALID_PARAMS
before the handler runs, and all-optional models reach the handler with
their defaults. Previously the validated instance was discarded and the
handler got None, which contradicted the registered handler type for
all-optional models. Matches the Go SDK's non-nil params guarantee.

Intentional behavior change: the roots list_changed interaction snapshot
is updated from None to NotificationParams().

Author: maxisbey

docs/migration.md

@@ -817,7 +817,7 @@ If you need to check whether a handler is registered, track this yourself — th
 
 ### Lowlevel `Server`: `add_request_handler` is now public and takes `params_type`
 
-The private `_add_request_handler(method, handler)` escape hatch is now the public `add_request_handler(method, params_type, handler)`, alongside a matching `add_notification_handler`. Each takes a `params_type` model that incoming params are validated against before the handler runs.
+The private `_add_request_handler(method, handler)` escape hatch is now the public `add_request_handler(method, params_type, handler)`, alongside a matching `add_notification_handler`. Each takes a `params_type` model that incoming params are validated against before the handler runs. A message with no `params` member validates `{}` against the model, so handlers never receive `None`: all-optional models arrive with their defaults, and models with required fields reject the message as `INVALID_PARAMS` before the handler runs (matching the Go SDK).
 
 ```python
 # Before (v1 / earlier v2 prereleases)

src/mcp/server/lowlevel/server.py

@@ -258,10 +258,13 @@ def add_request_handler(
 
         `params_type` is the model incoming params are validated against
         before the handler is invoked. It should subclass `RequestParams` so
-        `_meta` parses uniformly. Replaces any existing handler for the same
-        method, except `initialize`, which is reserved: the runner owns the
-        handshake, so registering it raises `ValueError`. Use
-        `Server.middleware` to observe or wrap initialization.
+        `_meta` parses uniformly. A message with no `params` member validates
+        `{}` against `params_type`: models with required fields reject it as
+        INVALID_PARAMS, all-optional models reach the handler with their
+        defaults - the handler never receives `None`. Replaces any existing
+        handler for the same method, except `initialize`, which is reserved:
+        the runner owns the handshake, so registering it raises `ValueError`.
+        Use `Server.middleware` to observe or wrap initialization.
         """
         if method == "initialize":
             raise ValueError(
@@ -279,7 +282,9 @@ def add_notification_handler(
         """Register a notification handler for `method`.
 
         `params_type` should subclass `NotificationParams` so `_meta`
-        parses uniformly. Replaces any existing handler. A handler for
+        parses uniformly. Absent params follow the same contract as requests:
+        `{}` is validated, so the handler receives the model with its defaults,
+        never `None`. Replaces any existing handler. A handler for
         `notifications/initialized` runs after the runner has marked the
         connection initialized.
         """

src/mcp/server/runner.py

@@ -245,13 +245,9 @@ async def _inner() -> HandlerResult:
             entry = self.server.get_request_handler(method)
             if entry is None:
                 raise MCPError(code=METHOD_NOT_FOUND, message="Method not found")
-            # Absent params reach the handler as None; the empty-dict validate
-            # still enforces required fields (pinned compat).
-            if params is None:
-                entry.params_type.model_validate({}, by_name=False)
-                typed_params = None
-            else:
-                typed_params = entry.params_type.model_validate(params, by_name=False)
+            # Absent params validate as {} (required fields still reject), so
+            # the handler receives the model with its defaults, never None.
+            typed_params = entry.params_type.model_validate({} if params is None else params, by_name=False)
             result = await entry.handler(ctx, typed_params)
             if isinstance(result, ErrorData):
                 # Raise inside the chain so middleware observes the failure.
@@ -295,11 +291,7 @@ async def _inner() -> None:
                 return
             # Same absent-params contract as requests.
             try:
-                if params is None:
-                    entry.params_type.model_validate({}, by_name=False)
-                    typed_params = None
-                else:
-                    typed_params = entry.params_type.model_validate(params, by_name=False)
+                typed_params = entry.params_type.model_validate({} if params is None else params, by_name=False)
             except ValidationError:
                 logger.warning("dropped %r: malformed params", method)
                 return

tests/interaction/lowlevel/test_roots.py

@@ -163,4 +163,4 @@ async def list_roots(context: ClientRequestContext) -> ListRootsResult:
         with anyio.fail_after(5):
             await delivered.wait()
 
-    assert received == snapshot([None])
+    assert received == snapshot([types.NotificationParams()])

tests/server/test_runner.py

@@ -332,8 +332,8 @@ async def on_roots_changed(ctx: Ctx, params: NotificationParams | None) -> None:
         await client.notify("notifications/roots/list_changed", {})
         await delivered.wait()
     assert isinstance(seen[0][0], ServerRequestContext)
-    # Absent wire params reach the handler as None; present-but-empty validates.
-    assert seen[0][1] is None
+    # Absent and present-but-empty wire params both validate to the defaults model.
+    assert seen[0][1] == NotificationParams()
     assert isinstance(seen[1][1], NotificationParams)
 
 
@@ -394,9 +394,9 @@ async def on_progress(ctx: Ctx, params: ProgressNotificationParams) -> None:
 
 
 @pytest.mark.anyio
-async def test_runner_absent_wire_params_reaches_request_handler_as_none():
+async def test_runner_absent_wire_params_reaches_request_handler_as_defaults_model():
     """A request with no `params` member on the wire reaches the handler as
-    `None`, matching the previous server and the `| None` handler annotation.
+    the params model with its defaults, never `None`.
 
     The in-SDK client always attaches `_meta`, so a dispatch middleware
     forwards `params=None` to model what an external client sends.
@@ -416,7 +416,7 @@ async def wrapped(dctx: DispatchContext[Any], method: str, params: Any) -> dict[
     server: SrvT = Server(name="s", on_list_tools=list_tools)
     async with connected_runner(server, dispatch_middleware=[drop_params]) as (client, _):
         await client.send_raw_request("tools/list", None)
-    assert seen == [None]
+    assert seen == [PaginatedRequestParams()]
 
 
 @pytest.mark.anyio
@@ -458,7 +458,7 @@ async def on_roots(ctx: Ctx, params: NotificationParams | None) -> None:
         await client.notify("notifications/unknown", None)  # no handler: dropped
         await client.notify("notifications/roots/list_changed", None)  # post-init: delivered
         await anyio.wait_all_tasks_blocked()
-    assert seen == [None]  # only the post-init one reached the handler
+    assert seen == [NotificationParams()]  # only the post-init one reached the handler
 
 
 @pytest.mark.anyio