Scope the CreateTaskResult arm to the revision that defines it

Review follow-up, four corrections.

The arm goes back to `2025-11-25` alone. It was widened to all four pre-2026
rows on the reasoning that they share `v2025.CallToolRequest` and so already
parse `params.task`, which made refusing to answer at 2025-06-18 look like the
same incoherence one revision along. That was the wrong conclusion: the request
side accepting `task` at revisions that predate SEP-1686 is an artifact of the
shared schema era, and matching it on the response side propagates the artifact
instead of containing it. A client that sends `task` to a 2024-11-05 server is
already off-spec, and a clean INTERNAL_ERROR serves it better than a result
shape its revision cannot parse. The rows now say what each revision defines,
which is also what the requirement's `added_in` window claims.

`params.task` is not an era test, and the migration guide said it was. The
handler receives the version-free params model, which carries `task` at every
version, so a client can set it on a 2026-07-28 connection and drive a handler
straight into a result that revision rejects. The recipe now gates on
`ctx.protocol_version`.

The field cache moves from a `ClassVar` to a module-level cached function. The
`ClassVar` was inherited by every subclass, so correctness rested on the
serializer remembering to read `cls.__dict__` rather than the attribute; keying
a `cache` on the class removes the hazard along with twenty lines. The restored
key now also honours `serialize_by_alias`, not just the `by_alias` argument, so
a config-driven dump cannot come back mixed-convention.

`tests/types/test_parity.py` now shares `admits_none` with the runtime instead
of inlining a copy that had already drifted, and its docstring no longer calls
itself the authority: sharing the predicate makes it a consistency check between
the schema-side rule and the annotation-side one, which is what it actually is.
The generator's base patcher matches whatever bases codegen chose, so a `$def`
that composes through `allOf` no longer aborts regeneration.

Author: maxisbey

docs/migration.md

@@ -1663,7 +1663,7 @@ The task types stay, so a server can still serve Tasks ([SEP-1686](https://githu
 async def call_tool(
     ctx: ServerRequestContext, params: CallToolRequestParams
 ) -> CallToolResult | CreateTaskResult:
-    if params.task is None:
+    if params.task is None or ctx.protocol_version != "2025-11-25":
         return CallToolResult(content=[TextContent(text=run_now())])
     return CreateTaskResult(task=await store.submit(params))
 
@@ -1678,7 +1678,7 @@ server.add_request_handler("tasks/get", GetTaskRequestParams, get_task)
 
 Two things to know about handlers registered this way. They serve every negotiated version, so a server that also answers 2026-era clients should check `ctx.protocol_version` and reject anything outside 2025-11-25; the method names collide with the 2026 tasks extension but the payloads are not compatible. And their results are not validated against a per-version surface, so raise `MCPError` for the failure cases rather than letting an exception escape: an unhandled one reaches the client as an unmapped error carrying the exception text.
 
-The same era check belongs in `on_call_tool`. Its return type admits a `CreateTaskResult` at every version because the signature has no version to key on, but 2026-07-28 dropped tasks from the core protocol and rejects the shape, turning it into an opaque internal error. Returning one only when `params.task` is set keeps that unreachable for a well-behaved client, since a client that never learned the field never sets it.
+The same era check belongs in `on_call_tool`, and `params.task` is not a substitute for it. The handler receives the version-free params model, which carries `task` at every version, so a client can set the field on a 2026-07-28 connection and reach a handler that then answers with a `CreateTaskResult`, which that revision rejects as an opaque internal error. Gate on `ctx.protocol_version == "2025-11-25"` and treat `params.task` as the opt-in within that era, not as the era test.
 
 `Server.get_capabilities` does not derive a `tasks` capability from the registered handlers, and a spec-compliant client will not augment a request until it sees one, so build the advertisement explicitly:
 

scripts/gen_surface_types.py

@@ -255,21 +255,25 @@ def _admits_null(prop: dict[str, Any]) -> bool:
 
 
 def keep_required_nullable(source: str, classes: frozenset[str]) -> str:
-    """Give each of `classes` `KeepRequiredNullable` as a second base."""
+    """Append `KeepRequiredNullable` to each of `classes`'s base list.
+
+    Matches whatever bases codegen chose, since a `$def` that composes through `allOf` is
+    emitted with its composed bases rather than a bare `WireModel`.
+    """
     for name in sorted(classes):
         source, count = re.subn(
-            rf"^class {name}\(WireModel\):$",
-            f"class {name}(WireModel, KeepRequiredNullable):",
+            rf"^class {name}\((?P<bases>[^)]+)\):$",
+            rf"class {name}(\g<bases>, KeepRequiredNullable):",
             source,
             flags=re.MULTILINE,
         )
         if count != 1:
-            raise SystemExit(f"expected one `class {name}(WireModel)` to patch, found {count}")
+            raise SystemExit(f"expected one `class {name}(...)` to patch, found {count}")
     if classes:
-        source = source.replace(
-            "from mcp_types._wire_base import WireModel",
-            "from mcp_types._wire_base import KeepRequiredNullable, WireModel",
-        )
+        import_line = "from mcp_types._wire_base import WireModel"
+        if import_line not in source:
+            raise SystemExit(f"cannot import KeepRequiredNullable: {import_line!r} not found")
+        source = source.replace(import_line, "from mcp_types._wire_base import KeepRequiredNullable, WireModel")
     return source
 
 

src/mcp-types/mcp_types/_wire_base.py

@@ -1,54 +1,54 @@
 """Shared pydantic bases for the generated `mcp_types.v*` packages and the monolith."""
 
-from typing import Any, ClassVar, Final, get_args
+from functools import cache
+from typing import Any, get_args
 
 from pydantic import BaseModel, ConfigDict, SerializationInfo, SerializerFunctionWrapHandler, model_serializer
 
-_UNSET: Final[object] = object()
-"""Tells a field explicitly set to `None` apart from one that was never set."""
-
 
 class WireModel(BaseModel):
     """Base for generated wire models: enables `populate_by_name`; subclasses set `extra` themselves."""
 
     model_config = ConfigDict(populate_by_name=True)
 
 
+def admits_none(annotation: Any) -> bool:
+    """Whether a field's annotation accepts `None`, including a bare `Any`."""
+    return annotation is Any or annotation is None or type(None) in get_args(annotation)
+
+
+@cache
+def _nullable_required_fields(model: type[BaseModel]) -> tuple[tuple[str, str], ...]:
+    """The `(attribute, wire alias)` pairs `exclude_none` must not drop from `model`.
+
+    Resolved on first dump rather than at class creation: the generated modules use
+    `from __future__ import annotations` and finish with `model_rebuild()`, so a forward
+    reference is still a string while the class body runs and would resolve to nothing.
+    Keyed on the concrete class, since subclasses add fields (`GetTaskResult` is `Result`
+    plus `Task`).
+    """
+    return tuple(
+        (name, field.serialization_alias or field.alias or name)
+        for name, field in model.model_fields.items()
+        if field.is_required() and admits_none(field.annotation)
+    )
+
+
 class KeepRequiredNullable(BaseModel):
     """Base for models carrying a required nullable field, e.g. `Task.ttl` (`number | null`).
 
     Every dump path passes `exclude_none=True` to omit unset optionals, but that cannot tell an
     unset optional from a required field whose value is legitimately null, so it drops both and
     leaves a body that fails the schema it was just validated against. This puts the required
-    ones back, and only those: a field the caller filtered out with `include`/`exclude`, or one
-    that was never set at all, stays absent.
+    ones back, and only those: a field the caller filtered out with `include`/`exclude` stays
+    absent, because there `exclude_none` is not why it went.
 
-    Mixed in only where it is needed, since a wrap serializer costs per dump:
-    `scripts/gen_surface_types.py` derives the surface classes from the schema and the monolith
-    counterparts take it by hand, with `tests/types/test_parity.py` checking the set is complete.
+    Mixed in only where it is needed, since a wrap serializer costs per dump and pydantic walks
+    one per model in the tree: `scripts/gen_surface_types.py` derives the surface classes from
+    the schema and the monolith counterparts take it by hand, with `tests/types/test_parity.py`
+    checking the resulting set against every built model.
     """
 
-    _nullable_required_fields: ClassVar[tuple[tuple[str, str], ...] | None] = None
-    """`(attribute, wire alias)` per required nullable field; resolved on first dump, then cached."""
-
-    @classmethod
-    def _resolve_nullable_required(cls) -> tuple[tuple[str, str], ...]:
-        """Find the fields `exclude_none` must not drop, once per concrete class.
-
-        Deferred to first use rather than `__pydantic_init_subclass__`: the generated modules
-        use `from __future__ import annotations` and finish with `model_rebuild()`, so a forward
-        reference is still a string at class-creation time and would resolve to nothing. Each
-        class resolves its own set, since subclasses add fields (`GetTaskResult` is `Result`
-        plus `Task`).
-        """
-        resolved = tuple(
-            (name, field.serialization_alias or field.alias or name)
-            for name, field in cls.model_fields.items()
-            if field.is_required() and _admits_none(field.annotation)
-        )
-        cls._nullable_required_fields = resolved
-        return resolved
-
     @model_serializer(mode="wrap")
     def _keep_required_nullable(self, handler: SerializerFunctionWrapHandler, info: SerializationInfo):
         # The return is deliberately unannotated: pydantic builds the serialization JSON schema
@@ -57,25 +57,16 @@ def _keep_required_nullable(self, handler: SerializerFunctionWrapHandler, info:
         data = handler(self)
         if not info.exclude_none:
             return data
-        # `__dict__`, not attribute lookup: a subclass must resolve its own set rather than
-        # inherit whichever ancestor happened to be dumped first.
-        cls = type(self)
-        fields = cls.__dict__.get("_nullable_required_fields")
-        if fields is None:
-            fields = cls._resolve_nullable_required()
-        for name, alias in fields:
-            if self.__dict__.get(name, _UNSET) is not None:
+        # `serialize_by_alias` is the config-level spelling of the `by_alias` argument; reading
+        # only the argument would restore the one key under a spelling the rest of the dump did
+        # not use.
+        by_alias = info.by_alias or type(self).model_config.get("serialize_by_alias", False)
+        for name, alias in _nullable_required_fields(type(self)):
+            if getattr(self, name, None) is not None:
                 continue
             if (info.include is not None and name not in info.include) or (
                 info.exclude is not None and name in info.exclude
             ):
-                continue  # the caller filtered this field out; exclude_none is not why it is gone
-            data.setdefault(alias if info.by_alias else name, None)
+                continue
+            data.setdefault(alias if by_alias else name, None)
         return data
-
-
-def _admits_none(annotation: Any) -> bool:
-    """Whether a field's annotation accepts `None`, including a bare `Any`."""
-    if annotation is Any or annotation is None:
-        return True
-    return type(None) in get_args(annotation)

src/mcp-types/mcp_types/methods.py

@@ -244,7 +244,7 @@
         ("resources/subscribe", "2024-11-05"): v2025.EmptyResult,
         ("resources/templates/list", "2024-11-05"): v2025.ListResourceTemplatesResult,
         ("resources/unsubscribe", "2024-11-05"): v2025.EmptyResult,
-        ("tools/call", "2024-11-05"): v2025.AnyCallToolResult,
+        ("tools/call", "2024-11-05"): v2025.CallToolResult,
         ("tools/list", "2024-11-05"): v2025.ListToolsResult,
         # 2025-03-26
         ("completion/complete", "2025-03-26"): v2025.CompleteResult,
@@ -258,7 +258,7 @@
         ("resources/subscribe", "2025-03-26"): v2025.EmptyResult,
         ("resources/templates/list", "2025-03-26"): v2025.ListResourceTemplatesResult,
         ("resources/unsubscribe", "2025-03-26"): v2025.EmptyResult,
-        ("tools/call", "2025-03-26"): v2025.AnyCallToolResult,
+        ("tools/call", "2025-03-26"): v2025.CallToolResult,
         ("tools/list", "2025-03-26"): v2025.ListToolsResult,
         # 2025-06-18
         ("completion/complete", "2025-06-18"): v2025.CompleteResult,
@@ -272,7 +272,7 @@
         ("resources/subscribe", "2025-06-18"): v2025.EmptyResult,
         ("resources/templates/list", "2025-06-18"): v2025.ListResourceTemplatesResult,
         ("resources/unsubscribe", "2025-06-18"): v2025.EmptyResult,
-        ("tools/call", "2025-06-18"): v2025.AnyCallToolResult,
+        ("tools/call", "2025-06-18"): v2025.CallToolResult,
         ("tools/list", "2025-06-18"): v2025.ListToolsResult,
         # 2025-11-25
         ("completion/complete", "2025-11-25"): v2025.CompleteResult,

tests/types/test_methods.py

@@ -220,7 +220,7 @@
     ("resources/subscribe", "2024-11-05"): v2025.EmptyResult,
     ("resources/templates/list", "2024-11-05"): v2025.ListResourceTemplatesResult,
     ("resources/unsubscribe", "2024-11-05"): v2025.EmptyResult,
-    ("tools/call", "2024-11-05"): (v2025.CallToolResult, v2025.CreateTaskResult),
+    ("tools/call", "2024-11-05"): v2025.CallToolResult,
     ("tools/list", "2024-11-05"): v2025.ListToolsResult,
     ("completion/complete", "2025-03-26"): v2025.CompleteResult,
     ("initialize", "2025-03-26"): v2025.InitializeResult,
@@ -233,7 +233,7 @@
     ("resources/subscribe", "2025-03-26"): v2025.EmptyResult,
     ("resources/templates/list", "2025-03-26"): v2025.ListResourceTemplatesResult,
     ("resources/unsubscribe", "2025-03-26"): v2025.EmptyResult,
-    ("tools/call", "2025-03-26"): (v2025.CallToolResult, v2025.CreateTaskResult),
+    ("tools/call", "2025-03-26"): v2025.CallToolResult,
     ("tools/list", "2025-03-26"): v2025.ListToolsResult,
     ("completion/complete", "2025-06-18"): v2025.CompleteResult,
     ("initialize", "2025-06-18"): v2025.InitializeResult,
@@ -246,7 +246,7 @@
     ("resources/subscribe", "2025-06-18"): v2025.EmptyResult,
     ("resources/templates/list", "2025-06-18"): v2025.ListResourceTemplatesResult,
     ("resources/unsubscribe", "2025-06-18"): v2025.EmptyResult,
-    ("tools/call", "2025-06-18"): (v2025.CallToolResult, v2025.CreateTaskResult),
+    ("tools/call", "2025-06-18"): v2025.CallToolResult,
     ("tools/list", "2025-06-18"): v2025.ListToolsResult,
     ("completion/complete", "2025-11-25"): v2025.CompleteResult,
     ("initialize", "2025-11-25"): v2025.InitializeResult,

tests/types/test_parity.py

@@ -4,15 +4,14 @@
 
 import inspect
 from types import ModuleType
-from typing import Any, get_args
 
 import mcp_types as monolith
 import mcp_types._types as _types
 import mcp_types.jsonrpc as jsonrpc
 import mcp_types.v2025_11_25 as v2025_11_25
 import mcp_types.v2026_07_28 as v2026_07_28
 import pytest
-from mcp_types._wire_base import KeepRequiredNullable
+from mcp_types._wire_base import KeepRequiredNullable, admits_none
 from pydantic import BaseModel
 
 SURFACES: tuple[ModuleType, ...] = (v2025_11_25, v2026_07_28)
@@ -231,7 +230,7 @@ def _models_with_a_required_nullable_field() -> list[tuple[str, type[BaseModel],
             nullable_required = frozenset(
                 field.serialization_alias or field.alias or field_name
                 for field_name, field in obj.model_fields.items()
-                if field.is_required() and (field.annotation is Any or type(None) in get_args(field.annotation))
+                if field.is_required() and admits_none(field.annotation)
             )
             if nullable_required:
                 found.append((f"{module.__name__}.{name}", obj, nullable_required))
@@ -250,8 +249,11 @@ def test_models_with_a_required_nullable_field_survive_an_exclude_none_dump(
 ) -> None:
     """`exclude_none=True` would drop such a field, leaving a body that fails its own schema.
 
-    `KeepRequiredNullable` puts it back. This walk is over the built models, which is the
-    authority; `scripts/gen_surface_types.py` reaches the same set from the raw schema.
+    `KeepRequiredNullable` puts it back. This walk deliberately shares `admits_none` with the
+    runtime, so it is a consistency check rather than an oracle: what it catches is a model the
+    generator's independent schema-side rule (`_admits_null`) failed to give the base, or a
+    hand-written model nobody remembered. A spelling both rules miss is caught by neither, and
+    only an end-to-end test of that message would find it.
     """
     assert issubclass(cls, KeepRequiredNullable), (
         f"{qualname} needs the KeepRequiredNullable base. For a generated model, regenerate the "
@@ -260,7 +262,9 @@ def test_models_with_a_required_nullable_field_survive_an_exclude_none_dump(
         "in _types.py and jsonrpc.py take the base directly."
     )
     instance = cls.model_construct(**dict.fromkeys(cls.model_fields))
-    assert nullable_required <= instance.model_dump(by_alias=True, mode="json", exclude_none=True).keys()
+    dumped = instance.model_dump(by_alias=True, mode="json", exclude_none=True)
+    assert nullable_required <= dumped.keys()
+    assert all(dumped[alias] is None for alias in nullable_required)
 
 
 def test_every_surface_class_is_accounted_for() -> None: