π The fast, Pythonic way to build MCP servers and clients.
Fix hydration of mutually recursive schema types (#6394)
nate nowack0d7bb12844e9
diff --git a/fastmcp_slim/fastmcp/utilities/json_schema_type.py b/fastmcp_slim/fastmcp/utilities/json_schema_type.pyindex 967391afa..3a203a680 100644--- a/fastmcp_slim/fastmcp/utilities/json_schema_type.py+++ b/fastmcp_slim/fastmcp/utilities/json_schema_type.py@@ -64,7 +64,7 @@ from collections import OrderedDictfrom collections.abc import Callable, Hashable, Mappingfrom contextvars import ContextVarfrom copy import deepcopy-from dataclasses import MISSING, dataclass, field, make_dataclass+from dataclasses import MISSING, dataclass, field, fields, is_dataclass, make_dataclassfrom datetime import date, datetime, time, timedeltafrom functools import lru_cachefrom typing import (@@ -77,6 +77,7 @@ from typing import (TypeVar,Union,cast,+ get_type_hints,)from uuid import UUID@@ -241,9 +242,21 @@ class _Conversion:root_class_name: strresolved_refs: dict[str, Any] = field(default_factory=dict)building: set[tuple[str, str]] = field(default_factory=set)+ classes: dict[tuple[str, str], type] = field(default_factory=dict)+ recursive_refs: dict[str, tuple[str, str]] = field(default_factory=dict)+ # Model fields whose default failed its probe, possibly only because a+ # recursive reference was still unresolved; rechecked after resolution.+ unchecked_defaults: list[tuple[type[BaseModel], str]] = field(default_factory=list)depth: int = 0steps: int = 0+ def reference(self, key: tuple[str, str]) -> ForwardRef:+ """Refer to a class's identity rather than its possibly shared display name."""+ digest = hashlib.sha256(repr(key).encode()).hexdigest()+ name = f"_FastMCPRef_{digest}"+ self.recursive_refs[name] = key+ return ForwardRef(name)+_conversion: ContextVar[_Conversion] = ContextVar("json_schema_conversion")@@ -360,25 +373,78 @@ def _convert_normalized(schema: dict[str, Any], name: str | None) -> type:# (including the empty string) is a valid class-name source.title = schema.get("title")root_title = title if isinstance(title, str) else "Root"- token = _conversion.set(- _Conversion(- root_hash=root_hash,- root_size=root_size,- root_class_name=_sanitize_name(name or root_title),- )+ conversion = _Conversion(+ root_hash=root_hash,+ root_size=root_size,+ root_class_name=_sanitize_name(name or root_title),)+ token = _conversion.set(conversion)try:# Always use the top-level schema for referencesif schema.get("type") == "object":- return _object_schema_to_type(schema, schemas=schema, name=name)+ result = _object_schema_to_type(schema, schemas=schema, name=name)elif name:raise ValueError(f"Can not apply name to non-object schema: {name}")- result = _schema_to_type(schema, schemas=schema)+ else:+ result = _schema_to_type(schema, schemas=schema)+ _resolve_recursive_types(conversion)+ # Publish only complete graphs: another conversion must not reuse a+ # class whose recursive fields still depend on this conversion's namespace.+ for key, cls in conversion.classes.items():+ _classes.put(key, cls, conversion.root_size)return result # type: ignore[return-value] # ty:ignore[invalid-return-type]finally:_conversion.reset(token)+def _resolve_recursive_types(conversion: _Conversion) -> None:+ """Bind recursive fields after every class in the conversion has been built."""+ if not conversion.recursive_refs:+ return+ namespace = {+ name: conversion.classes[key] for name, key in conversion.recursive_refs.items()+ }+ # Root references use the root's public name, including when a nested+ # mutually recursive class also points back to the conversion root.+ for cls in conversion.classes.values():+ if cls.__name__ == conversion.root_class_name:+ namespace[conversion.root_class_name] = cls+ for cls in conversion.classes.values():+ if is_dataclass(cls):+ hints = get_type_hints(+ cls,+ localns={cls.__name__: cls, **namespace},+ include_extras=True,+ )+ cls.__annotations__.update(hints)+ for dataclass_field in fields(cls):+ dataclass_field.type = hints[dataclass_field.name]+ for cls in conversion.classes.values():+ if issubclass(cls, BaseModel):+ cls.model_rebuild(+ force=True, _types_namespace={cls.__name__: cls, **namespace}+ )+ rechecked: set[type[BaseModel]] = set()+ for model, field_name in conversion.unchecked_defaults:+ field_info = model.model_fields[field_name]+ if _default_is_valid(field_info.annotation, field_info.default):+ field_info.validate_default = True+ rechecked.add(model)+ for model in rechecked:+ model.model_rebuild(+ force=True, _types_namespace={model.__name__: model, **namespace}+ )+++def _default_is_valid(field_type: Any, default: Any) -> bool:+ try:+ TypeAdapter(field_type).validate_python(default)+ except Exception:+ # Invalid, or not checkable yet because a recursive reference is unresolved+ return False+ return True++def json_schema_to_type_adapter(schema: Mapping[str, Any] | bool) -> TypeAdapter[Any]:"""Return a cached `TypeAdapter` for `json_schema_to_type(schema)`.@@ -1079,12 +1145,12 @@ def _create_pydantic_model()# Return existing class if already built- existing = _classes.get(cache_key)+ existing = conversion.classes.get(cache_key) or _classes.get(cache_key)if existing is not None:return existing# A recursive reference to a class that is still being builtif cache_key in conversion.building:- return ForwardRef(sanitized_name) # type: ignore[return-value] # ty:ignore[invalid-return-type]+ return conversion.reference(cache_key) # type: ignore[return-value] # ty:ignore[invalid-return-type]conversion.building.add(cache_key)try:@@ -1093,7 +1159,7 @@ def _create_pydantic_model()finally:conversion.building.discard(cache_key)- _classes.put(cache_key, cls, conversion.root_size)+ conversion.classes[cache_key] = clsreturn cls@@ -1107,6 +1173,7 @@ def _build_pydantic_model(required = schema.get("required", [])field_definitions: dict[str, tuple[Any, Any]] = {}+ unchecked: list[str] = []for prop_name, prop_schema in properties.items():# Boolean schemas (JSON Schema draft-06+): resolve type directly,# then use an empty dict for .get() calls below.@@ -1124,13 +1191,9 @@ def _build_pydantic_model(# 1. Valid defaults get hydrated (e.g., date strings β date objects)# 2. Invalid defaults are preserved as-is rather than causing# validation errors that would be caught and logged during parsing- validate_default = False- try:- TypeAdapter(field_type).validate_python(default_value) # ty:ignore[invalid-argument-type]- validate_default = True- except Exception: # noqa: S110- # Default doesn't satisfy its own type; keep it as-is- pass+ validate_default = _default_is_valid(field_type, default_value)+ if not validate_default:+ unchecked.append(prop_name)field_definitions[prop_name] = (field_type,Field(default=default_value, validate_default=validate_default),@@ -1140,7 +1203,10 @@ def _build_pydantic_model(else:field_definitions[prop_name] = (Union[field_type, type(None)], None) # type: ignore[misc] # noqa: UP007 # ty:ignore[invalid-type-form]- return safe_create_model(name, field_definitions, config=ConfigDict(extra="allow"))+ model = safe_create_model(name, field_definitions, config=ConfigDict(extra="allow"))+ conversion = _conversion.get()+ conversion.unchecked_defaults.extend((model, prop) for prop in unchecked)+ return modeldef _create_dataclass(@@ -1167,12 +1233,12 @@ def _create_dataclass()# Return existing class if already built- existing = _classes.get(cache_key)+ existing = conversion.classes.get(cache_key) or _classes.get(cache_key)if existing is not None:return existing# A recursive reference to a class that is still being builtif cache_key in conversion.building:- return ForwardRef(sanitized_name) # type: ignore[return-value] # ty:ignore[invalid-return-type]+ return conversion.reference(cache_key) # type: ignore[return-value] # ty:ignore[invalid-return-type]conversion.building.add(cache_key)try:@@ -1180,7 +1246,7 @@ def _create_dataclass(finally:conversion.building.discard(cache_key)if isinstance(cls, type):- _classes.put(cache_key, cls, conversion.root_size)+ conversion.classes[cache_key] = clsreturn clsdiff --git a/tests/utilities/json_schema_type/test_recursive_hydration.py b/tests/utilities/json_schema_type/test_recursive_hydration.pynew file mode 100644index 000000000..e5609ff71--- /dev/null+++ b/tests/utilities/json_schema_type/test_recursive_hydration.py@@ -0,0 +1,180 @@+"""Recursive objects with the same display name must retain their own fields."""++from __future__ import annotations++from copy import deepcopy+from typing import Any++import pytest+from pydantic import BaseModel, TypeAdapter++from fastmcp import Client, FastMCP+from fastmcp.utilities import json_schema_type++[email protected](autouse=True)+def isolated_class_cache(monkeypatch: pytest.MonkeyPatch) -> None:+ monkeypatch.setattr(+ json_schema_type,+ "_classes",+ json_schema_type._LRUCache(max_entries=5000, max_weight=4_000_000),+ )+ monkeypatch.setattr(+ json_schema_type,+ "_adapters",+ json_schema_type._LRUCache(max_entries=1000, max_weight=4_000_000),+ )++[email protected]("model", [False, True], ids=["dataclass", "pydantic"])[email protected]("titles", [False, True], ids=["untitled", "same-title"])+def test_mutual_recursion_keeps_distinct_types(model: bool, titles: bool) -> None:+ person: dict[str, Any] = {+ "type": "object",+ "properties": {+ "name": {"type": "string"},+ "pet": {"anyOf": [{"$ref": "#/$defs/Pet"}, {"type": "null"}]},+ },+ "required": ["name"],+ }+ pet: dict[str, Any] = {+ "type": "object",+ "properties": {+ "name": {"type": "string"},+ "owner": {"anyOf": [{"$ref": "#/$defs/Person"}, {"type": "null"}]},+ },+ "required": ["name"],+ }+ for definition in (person, pet):+ if model:+ definition["additionalProperties"] = True+ if titles:+ definition["title"] = "Record"+ schema = {+ "type": "object",+ "properties": {"person": {"$ref": "#/$defs/Person"}},+ "$defs": {"Person": person, "Pet": pet},+ }+ original = deepcopy(schema)+ generated = json_schema_type.json_schema_to_type(schema)+ result = TypeAdapter[Any](generated).validate_python(+ {+ "person": {+ "name": "Ann",+ "pet": {+ "name": "Rex",+ "owner": {"name": "Bob", "pet": {"name": "Max"}},+ },+ }+ }+ )++ assert result.person.pet.owner.pet.name == "Max"+ assert result.person.pet.owner.pet.owner is None+ assert type(result.person.pet.owner) is type(result.person)+ assert type(result.person.pet.owner.pet) is type(result.person.pet)+ assert type(result.person).__name__ == ("Record" if titles else "Root_2")+ assert schema == original+ assert json_schema_type.json_schema_to_type(schema) is generated++[email protected]("model", [False, True], ids=["dataclass", "pydantic"])+def test_mutual_recursion_with_root_reference(model: bool) -> None:+ definitions: dict[str, Any] = {+ "A": {+ "type": "object",+ "properties": {+ "b": {"$ref": "#/$defs/B"},+ "doc": {"$ref": "#"},+ },+ },+ "B": {+ "type": "object",+ "properties": {"a": {"$ref": "#/$defs/A"}},+ },+ }+ if model:+ for definition in definitions.values():+ definition["additionalProperties"] = True+ generated = json_schema_type.json_schema_to_type(+ {+ "type": "object",+ "title": "Doc",+ "properties": {"first": {"$ref": "#/$defs/A"}},+ "$defs": definitions,+ }+ )+ result = TypeAdapter[Any](generated).validate_python(+ {"first": {"b": {"a": {"doc": {}}}}}+ )+ assert type(result.first.b.a) is type(result.first)+ assert type(result.first.b.a.doc) is generated+ assert result.first.b.a.doc.first is None+++def test_recursive_default_hydrates_after_resolution() -> None:+ generated = json_schema_type.json_schema_to_type(+ {+ "type": "object",+ "additionalProperties": True,+ "properties": {"node": {"$ref": "#/$defs/Node", "default": {"name": "x"}}},+ "$defs": {+ "Node": {+ "type": "object",+ "properties": {+ "name": {"type": "string"},+ "child": {"$ref": "#/$defs/Node"},+ },+ }+ },+ }+ )+ result = TypeAdapter[Any](generated).validate_python({})+ assert not isinstance(result.node, dict)+ assert result.node.name == "x"+ assert result.node.child is None+++class HydrationPerson(BaseModel):+ name: str+ pet: HydrationPet | None = None+++class HydrationPet(BaseModel):+ name: str+ owner: HydrationPerson | None = None+++HydrationPerson.model_rebuild()+HydrationPet.model_rebuild()+++async def test_client_hydrates_mutually_recursive_models() -> None:+ server = FastMCP()++ @server.tool+ def get_person() -> HydrationPerson:+ return HydrationPerson(+ name="Ann",+ pet=HydrationPet(+ name="Rex",+ owner=HydrationPerson(name="Bob", pet=HydrationPet(name="Max")),+ ),+ )++ async with Client(server) as client:+ first = await client.call_tool("get_person", {})+ second = await client.call_tool("get_person", {})++ for result in (first, second):+ assert result.structured_content == {+ "name": "Ann",+ "pet": {+ "name": "Rex",+ "owner": {"name": "Bob", "pet": {"name": "Max", "owner": None}},+ },+ }+ assert result.data.pet.owner.pet.name == "Max"+ assert result.data.pet.owner.pet.owner is None+ assert type(result.data.pet.owner.pet) is type(result.data.pet)+ assert type(first.data) is type(second.data)