Skip to content

πŸš€ 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.py
index 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 OrderedDict
from collections.abc import Callable, Hashable, Mapping
from contextvars import ContextVar
from copy import deepcopy
-from dataclasses import MISSING, dataclass, field, make_dataclass
+from dataclasses import MISSING, dataclass, field, fields, is_dataclass, make_dataclass
from datetime import date, datetime, time, timedelta
from functools import lru_cache
from 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: str
resolved_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 = 0
steps: 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 references
if 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 built
if 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] = cls
return 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 model
def _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 built
if 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] = cls
return cls
diff --git a/tests/utilities/json_schema_type/test_recursive_hydration.py b/tests/utilities/json_schema_type/test_recursive_hydration.py
new file mode 100644
index 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)