fix(mcpserver): omit unreturned TypedDict keys from structuredContent

A tool annotated to return a TypedDict with `NotRequired` keys (or
`total=False`) published an outputSchema declaring those properties
non-nullable, while `convert_result` materialised every key the tool did
not return as an explicit `null`. The response therefore violated the
schema the same server had just advertised, and a conforming client -- the
SDK's own included -- rejected the call:

    RuntimeError: Invalid structured content returned by tool get_person:
    None is not of type 'string'

That made every such tool unusable, even though TypedDict is one of the
return shapes structured output documents. The unstructured text block and
structuredContent also disagreed, so a client skipping validation saw two
different answers.

`_create_model_from_typeddict` gives non-required keys a `None` default to
make them optional on the generated model; the file's own comment already
noted that such a model "should use exclude_unset=True when dumping to get
TypedDict semantics", but nothing did. Mark those models with a private
base class and honour it in `convert_result`, so an omitted key stays
omitted.

Scoped deliberately to TypedDict-derived models: `exclude_unset` applied
to every output shape would change payloads for BaseModel, dataclass and
wrapped returns, where emitting defaults is correct.

The published outputSchema is unchanged, so no existing expectation moves.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

Author: Sainikhil Juluri

src/mcp/server/mcpserver/utilities/func_metadata.py

@@ -139,7 +139,11 @@ def convert_result(self, result: Any) -> CallToolResult | InputRequiredResult:
 
         assert self.output_model is not None, "Output model must be set if output schema is defined"
         validated = self.output_model.model_validate(result)
-        structured_content = validated.model_dump(mode="json", by_alias=True)
+        # A TypedDict's non-required keys are absent, not null, when the tool omits
+        # them -- and the published outputSchema declares them non-nullable, so
+        # emitting nulls would violate the server's own schema.
+        exclude_unset = issubclass(self.output_model, _TypedDictOutputModel)
+        structured_content = validated.model_dump(mode="json", by_alias=True, exclude_unset=exclude_unset)
 
         return CallToolResult(content=unstructured_content, structured_content=structured_content)
 
@@ -494,6 +498,17 @@ def _create_model_from_class(cls: type[Any], type_hints: dict[str, Any]) -> type
     return create_model(cls.__name__, __config__=ConfigDict(from_attributes=True), **model_fields)
 
 
+class _TypedDictOutputModel(BaseModel):
+    """Base for output models generated from a TypedDict return annotation.
+
+    Non-required TypedDict keys are given a `None` default so they are optional on
+    the generated model, but `None` is not a valid value for their declared type and
+    the published `outputSchema` does not accept it. Dumping such a model has to
+    honour TypedDict semantics -- a key the tool did not return stays absent rather
+    than becoming an explicit null -- so `convert_result` keys off this base class.
+    """
+
+
 def _create_model_from_typeddict(td_type: type[Any]) -> type[BaseModel]:
     """Create a Pydantic model from a TypedDict.
 
@@ -507,12 +522,13 @@ def _create_model_from_typeddict(td_type: type[Any]) -> type[BaseModel]:
         if field_name not in required_keys:
             # For optional TypedDict fields, set default=None
             # This makes them not required in the Pydantic model
-            # The model should use exclude_unset=True when dumping to get TypedDict semantics
+            # Dumped with exclude_unset=True (see `_TypedDictOutputModel`) so an
+            # omitted key stays omitted instead of serializing as null
             model_fields[field_name] = (field_type, None)
         else:
             model_fields[field_name] = field_type
 
-    return create_model(td_type.__name__, **model_fields)
+    return create_model(td_type.__name__, __base__=_TypedDictOutputModel, **model_fields)
 
 
 def _create_wrapped_model(func_name: str, annotation: Any) -> type[BaseModel]:

tests/server/mcpserver/test_func_metadata.py

@@ -5,9 +5,10 @@
 # pyright: reportUnknownLambdaType=false
 from collections.abc import Callable
 from dataclasses import dataclass
-from typing import Annotated, Any, Final, NamedTuple, TypedDict
+from typing import Annotated, Any, Final, NamedTuple, NotRequired, TypedDict
 
 import annotated_types
+import jsonschema
 import pytest
 from dirty_equals import IsPartialDict
 from mcp_types import CallToolResult, InputRequiredResult
@@ -811,6 +812,66 @@ def func_returning_typeddict_required() -> PersonTypedDictRequired:  # pragma: n
     }
 
 
+def test_typeddict_output_omits_keys_the_tool_did_not_return():
+    """A non-required TypedDict key the tool omits stays absent from structuredContent.
+
+    SDK-defined: those keys carry a `None` default so they are optional on the generated
+    model, but the published outputSchema declares them non-nullable, so serializing them
+    as explicit nulls would make every such tool emit content violating the server's own
+    schema (and a conforming client reject the call).
+    """
+
+    class Person(TypedDict):
+        name: str
+        age: NotRequired[int]
+        nickname: NotRequired[str]
+
+    def get_person() -> Person:
+        return {"name": "Dave"}
+
+    meta = func_metadata(get_person)
+    # Call the real function rather than restating its return value: the existing
+    # tests in this file never invoke the tool body, which is why this went unnoticed.
+    result = meta.convert_result(get_person())
+
+    assert isinstance(result, CallToolResult)
+    assert result.structured_content == {"name": "Dave"}
+
+    # The load-bearing assertion: the payload has to satisfy the schema this same
+    # metadata published, which is the contract a client validates against.
+    assert meta.output_schema is not None
+    jsonschema.validate(instance=result.structured_content, schema=meta.output_schema)
+
+    # A key the tool DOES return still travels, including a falsy one.
+    both = meta.convert_result({"name": "Dave", "age": 0})
+    assert isinstance(both, CallToolResult)
+    assert both.structured_content == {"name": "Dave", "age": 0}
+    jsonschema.validate(instance=both.structured_content, schema=meta.output_schema)
+
+
+def test_total_false_typeddict_output_omits_every_unreturned_key():
+    """`total=False` makes every key non-required, so an empty return stays empty.
+
+    SDK-defined: pins the degenerate case, where the old behaviour turned `{}` into a
+    payload of nothing but nulls.
+    """
+
+    class Partial(TypedDict, total=False):
+        name: str
+        age: int
+
+    def get_partial() -> Partial:
+        return {}
+
+    meta = func_metadata(get_partial)
+    result = meta.convert_result(get_partial())
+
+    assert isinstance(result, CallToolResult)
+    assert result.structured_content == {}
+    assert meta.output_schema is not None
+    jsonschema.validate(instance=result.structured_content, schema=meta.output_schema)
+
+
 def test_structured_output_ordinary_class():
     """Test structured output with ordinary annotated classes"""