Skip to content

πŸš€ The fast, Pythonic way to build MCP servers and clients.

Avoid repeated traversal of shared tool schema definitions (#5412)

Jeremiah Lowinadfb6a6ed538
diff --git a/fastmcp_slim/fastmcp/server/transforms/search/base.py b/fastmcp_slim/fastmcp/server/transforms/search/base.py
index f2cfbd69d..f9295f048 100644
--- a/fastmcp_slim/fastmcp/server/transforms/search/base.py
+++ b/fastmcp_slim/fastmcp/server/transforms/search/base.py
@@ -127,9 +127,7 @@ def _resolve_ref(schema: Any, defs: dict[str, Any]) -> Any:
return schema
-def _object_fields(
- schema: Any, defs: dict[str, Any], seen: frozenset[str] = frozenset()
-) -> list[str] | None:
+def _object_fields(schema: Any, defs: dict[str, Any]) -> list[str] | None:
"""Field names of the object a schema describes, one level deep, or None.
Looks through a local `$ref`, an array's `items`, every object branch
@@ -140,28 +138,35 @@ def _object_fields(
without this step a typed return renders as `object[]` and the caller
has to fetch once just to learn the field names.
"""
- if isinstance(schema, dict) and isinstance(schema.get("$ref"), str):
- # A recursive alias (`Json = list[Json] | int`) refers back to itself
- # through anyOf/items; stop at the second visit instead of looping.
- if schema["$ref"] in seen:
- return None
- seen = seen | {schema["$ref"]}
- schema = _resolve_ref(schema, defs)
- if not isinstance(schema, dict):
- return None
- if schema.get("type") == "array":
- return _object_fields(schema.get("items"), defs, seen)
- fields: list[str] = []
- for key in ("anyOf", "oneOf", "allOf"):
- branches = schema.get(key)
- if isinstance(branches, list):
- for branch in branches:
- fields.extend(_object_fields(branch, defs, seen) or [])
- props = schema.get("properties")
- if isinstance(props, dict):
- fields.extend(props)
- unique = list(dict.fromkeys(fields))
- return unique or None
+ # Visit each resolved node once across the whole walk, so shared union
+ # branches and recursive aliases cannot repeatedly expand the same graph.
+ seen: set[int] = set()
+ fields: dict[str, None] = {}
+ pending: list[tuple[Any, bool]] = [(schema, False)]
+ while pending:
+ node, expanded = pending.pop()
+ if expanded:
+ props = node.get("properties")
+ if isinstance(props, dict):
+ fields.update(dict.fromkeys(props))
+ continue
+
+ node = _resolve_ref(node, defs)
+ if not isinstance(node, dict) or id(node) in seen:
+ continue
+ seen.add(id(node))
+ if node.get("type") == "array":
+ pending.append((node.get("items"), False))
+ continue
+
+ # Properties follow union branches, preserving the existing field order.
+ pending.append((node, True))
+ for key in ("allOf", "oneOf", "anyOf"):
+ branches = node.get(key)
+ if isinstance(branches, list):
+ pending.extend((branch, False) for branch in reversed(branches))
+
+ return list(fields) or None
def _nested_fields(field: Any, defs: dict[str, Any]) -> str:
diff --git a/tests/experimental/transforms/test_code_mode_serialization.py b/tests/experimental/transforms/test_code_mode_serialization.py
index 7f847644c..003893d6b 100644
--- a/tests/experimental/transforms/test_code_mode_serialization.py
+++ b/tests/experimental/transforms/test_code_mode_serialization.py
@@ -179,6 +179,86 @@ def test_schema_section_stops_on_recursive_refs() -> None:
assert "- `tree` (object): `value`, `children`" in lines
[email protected]("union", ["anyOf", "oneOf", "allOf"])
+def test_schema_section_visits_shared_definitions_once(union: str) -> None:
+ class TrackedSchema(dict[str, Any]):
+ visits = 0
+
+ def get(self, key: object, default: Any = None, /) -> Any:
+ if key == "properties":
+ self.visits += 1
+ return super().get(key, default)
+
+ defs = {"N0": TrackedSchema(properties={"value": {}, "shared": {}})}
+ for i in range(1, 13):
+ defs[f"N{i}"] = TrackedSchema(
+ {
+ union: [
+ {"$ref": f"#/$defs/N{i - 1}"},
+ {"$ref": f"#/$defs/N{i - 1}"},
+ ],
+ "properties": {"shared": {}, f"level{i}": {}},
+ }
+ )
+ schema = {
+ "$defs": defs,
+ "properties": {"payload": {"$ref": "#/$defs/N12"}},
+ }
+
+ lines = _schema_section(schema, "Parameters")
+
+ names = ["value", "shared", *(f"level{i}" for i in range(1, 13))]
+ assert lines == [
+ "**Parameters**",
+ "- `payload` (object): " + ", ".join(f"`{name}`" for name in names),
+ ]
+ assert all(definition.visits == 1 for definition in defs.values())
+
+
+def test_schema_section_preserves_order_through_mutually_recursive_refs() -> None:
+ schema = {
+ "$defs": {
+ "A": {
+ "anyOf": [{"$ref": "#/$defs/B"}],
+ "properties": {"shared": {}, "a": {}},
+ },
+ "B": {
+ "type": "array",
+ "items": {
+ "allOf": [{"$ref": "#/$defs/A"}],
+ "properties": {"shared": {}, "b": {}},
+ },
+ },
+ },
+ "properties": {
+ "first": {"$ref": "#/$defs/A"},
+ "second": {"$ref": "#/$defs/B"},
+ },
+ }
+
+ assert _schema_section(schema, "Parameters") == [
+ "**Parameters**",
+ "- `first` (object): `shared`, `b`, `a`",
+ "- `second` (object): `shared`, `a`, `b`",
+ ]
+
+
+def test_schema_section_handles_deep_shared_definitions() -> None:
+ defs = {"N0": {"properties": {"value": {}}}}
+ for i in range(1, 1501):
+ defs[f"N{i}"] = {
+ "anyOf": [
+ {"$ref": f"#/$defs/N{i - 1}"},
+ {"$ref": f"#/$defs/N{i - 1}"},
+ ]
+ }
+
+ assert _schema_section(
+ {"$defs": defs, "properties": {"payload": {"$ref": "#/$defs/N1500"}}},
+ "Parameters",
+ ) == ["**Parameters**", "- `payload` (object): `value`"]
+
+
def test_schema_section_truncates_long_nested_objects() -> None:
fields = {f"f{i}": {} for i in range(20)}
schema = {