Skip to content

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

fix: Reuse shared OpenAPI composition members (#5460)

Jeremiah Lowin86c59525fce5
diff --git a/fastmcp_slim/fastmcp/utilities/openapi/schemas.py b/fastmcp_slim/fastmcp/utilities/openapi/schemas.py
index 4527347b1..04fe85819 100644
--- a/fastmcp_slim/fastmcp/utilities/openapi/schemas.py
+++ b/fastmcp_slim/fastmcp/utilities/openapi/schemas.py
@@ -227,43 +227,99 @@ def _make_optional_parameter_nullable(schema: dict[str, Any]) -> dict[str, Any]:
return schema
+_MAX_COMPOSITION_MEMBERS = 100_000
+
+
def _allof_members(
schema: dict[str, Any],
schema_defs: dict[str, Any],
resolving: set[str] | None = None,
) -> list[dict[str, Any]]:
- """Expand local schema references while collecting ``allOf`` members."""
- resolving = resolving or set()
-
- ref = schema.get("$ref")
- if isinstance(ref, str):
- for prefix in ("#/$defs/", "#/components/schemas/"):
- if ref.startswith(prefix):
- name = ref.removeprefix(prefix)
- referenced_schema = schema_defs.get(name)
- if isinstance(referenced_schema, dict) and name not in resolving:
- siblings = {
- key: value for key, value in schema.items() if key != "$ref"
- }
- members = _allof_members(
- referenced_schema, schema_defs, resolving | {name}
- )
- if siblings:
- members.extend(_allof_members(siblings, schema_defs, resolving))
- return members
- break
-
- all_of = schema.get("allOf")
- if isinstance(all_of, list):
- members = []
- for member in all_of:
- if isinstance(member, dict):
- members.extend(_allof_members(member, schema_defs, resolving))
-
- siblings = {key: value for key, value in schema.items() if key != "allOf"}
- return members + ([siblings] if siblings else [])
-
- return [schema]
+ """Collect local composition members, reusing shared definition results."""
+ cached: dict[int, tuple[dict[str, Any], list[dict[str, Any]], frozenset[str]]] = {}
+ active: set[tuple[int, frozenset[str]]] = set()
+ retained = 0
+ visits = 0
+ merged = 0
+
+ def collect(
+ node: dict[str, Any], refs: set[str]
+ ) -> tuple[list[dict[str, Any]], frozenset[str], bool]:
+ nonlocal retained, visits, merged
+ visits += 1
+ if visits > _MAX_COMPOSITION_MEMBERS:
+ raise ValueError("Schema composition has too many visited members")
+ identity = id(node)
+ context = (identity, frozenset(refs))
+ if context in active:
+ return [node], frozenset(), True
+ cached_entry = cached.get(identity)
+ if cached_entry is not None and not refs.intersection(cached_entry[2]):
+ return cached_entry[1], cached_entry[2], False
+ active.add(context)
+ members: dict[int, dict[str, Any]] = {}
+ dependencies: set[str] = set()
+ contextual = False
+
+ def append(items: list[dict[str, Any]]) -> None:
+ nonlocal merged
+ merged += len(items)
+ if merged > _MAX_COMPOSITION_MEMBERS:
+ raise ValueError("Schema composition has too many merged members")
+ # Preserve the last occurrence's position, which determines the
+ # existing property merge order when definitions share a field.
+ for item in items:
+ key = id(item)
+ members.pop(key, None)
+ members[key] = item
+
+ ref = node.get("$ref")
+ referenced = None
+ name = ""
+ if isinstance(ref, str):
+ for prefix in ("#/$defs/", "#/components/schemas/"):
+ if ref.startswith(prefix):
+ name = ref.removeprefix(prefix)
+ dependencies.add(name)
+ referenced = schema_defs.get(name) if name not in refs else None
+ contextual |= name in refs
+ break
+ children: list[tuple[dict[str, Any], set[str]]] = []
+ trailing: list[dict[str, Any]] = []
+ if isinstance(referenced, dict):
+ children.append((referenced, refs | {name}))
+ siblings = {key: value for key, value in node.items() if key != "$ref"}
+ if siblings:
+ children.append((siblings, refs))
+ elif isinstance(node.get("allOf"), list):
+ children.extend(
+ (member, refs) for member in node["allOf"] if isinstance(member, dict)
+ )
+ siblings = {key: value for key, value in node.items() if key != "allOf"}
+ if siblings:
+ trailing.append(siblings)
+ else:
+ trailing.append(node)
+ for child, child_refs in children:
+ items, child_dependencies, child_contextual = collect(child, child_refs)
+ merged += len(child_dependencies)
+ append(items)
+ dependencies.update(child_dependencies)
+ contextual |= child_contextual
+ append(trailing)
+ active.remove(context)
+ result = list(members.values())
+ dependency_names = frozenset(dependencies)
+ retained += len(result) + len(dependency_names)
+ if retained > _MAX_COMPOSITION_MEMBERS:
+ raise ValueError("Schema composition has too many collected members")
+ # A cycle cut depends on this traversal's ancestors. Only reuse complete
+ # results, and only when none of their references is currently active.
+ if not contextual:
+ cached[identity] = (node, result, dependency_names)
+ return result, dependency_names, contextual
+
+ return collect(schema, resolving or set())[0]
# Keywords the properties/required merge represents, or that only annotate.
diff --git a/tests/utilities/openapi/test_composition_graphs.py b/tests/utilities/openapi/test_composition_graphs.py
new file mode 100644
index 000000000..46f634c30
--- /dev/null
+++ b/tests/utilities/openapi/test_composition_graphs.py
@@ -0,0 +1,184 @@
+"""Shared composition members are collected once in their effective order."""
+
+from typing import Any
+
+import httpx2
+import pytest
+import yaml
+
+import fastmcp.utilities.openapi.schemas as schemas
+from fastmcp import Client, FastMCP
+from fastmcp.utilities.openapi.schemas import _allof_members
+
+
+def test_deep_composition_chain_retains_leaf_members():
+ leaf = {"type": "object", "properties": {"name": {"type": "string"}}}
+ definitions: dict[str, Any] = {"L0": leaf}
+ for level in range(1, 251):
+ definitions[f"L{level}"] = {
+ "allOf": [{"$ref": f"#/components/schemas/L{level - 1}"}]
+ }
+ assert _allof_members({"$ref": "#/components/schemas/L250"}, definitions) == [leaf]
+
+
+def test_shared_members_are_collected_once():
+ leaf = {"type": "object", "properties": {"name": {"type": "string"}}}
+ defs: dict[str, Any] = {"L0": leaf}
+ for level in range(1, 9):
+ defs[f"L{level}"] = {
+ "allOf": [{"$ref": f"#/$defs/L{level - 1}"} for _ in range(3)]
+ }
+ members = _allof_members({"$ref": "#/$defs/L8"}, defs)
+ assert sum(member is leaf for member in members) == 1
+
+
+def test_repeated_members_keep_last_occurrence_order():
+ first = {"properties": {"name": {"type": "string"}}}
+ second = {"properties": {"name": {"type": "integer"}}}
+ members = _allof_members(
+ {
+ "allOf": [
+ {"$ref": "#/$defs/A"},
+ {"$ref": "#/$defs/B"},
+ {"$ref": "#/$defs/A"},
+ ]
+ },
+ {"A": first, "B": second},
+ )
+ assert [m for m in members if "properties" in m] == [second, first]
+
+
+async def test_shared_body_members_advertise_and_send_declared_fields():
+ definitions: dict[str, Any] = {
+ "L0": {"type": "object", "properties": {"name": {"type": "string"}}}
+ }
+ for level in range(1, 19):
+ definitions[f"L{level}"] = {
+ "allOf": [{"$ref": f"#/components/schemas/L{level - 1}"} for _ in range(3)]
+ }
+ spec = {
+ "openapi": "3.1.0",
+ "info": {"title": "API", "version": "1"},
+ "components": {"schemas": definitions},
+ "paths": {
+ "/items": {
+ "post": {
+ "operationId": "create_item",
+ "requestBody": {
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/L18",
+ "properties": {"local": {"type": "string"}},
+ }
+ }
+ }
+ },
+ "responses": {"200": {"description": "OK"}},
+ }
+ }
+ },
+ }
+ seen: list[httpx2.Request] = []
+
+ def capture(request: httpx2.Request) -> httpx2.Response:
+ seen.append(request)
+ return httpx2.Response(200, json={"ok": True})
+
+ async with httpx2.AsyncClient(
+ base_url="https://api.example.com", transport=httpx2.MockTransport(capture)
+ ) as http:
+ server = FastMCP.from_openapi(spec, client=http)
+ async with Client(server) as client:
+ tool = (await client.list_tools())[0]
+ assert set(tool.input_schema["properties"]) == {"name", "local"}
+ await client.call_tool("create_item", {"name": "item", "local": "value"})
+ assert seen[0].content == b'{"name":"item","local":"value"}'
+
+
+def test_cyclic_members_keep_contextual_merge_order():
+ first = {"properties": {"name": {"default": "A"}}}
+ last = {"properties": {"name": {"default": "C"}}}
+ definitions = {
+ "A": {"allOf": [first, {"$ref": "#/$defs/C"}]},
+ "C": {
+ "allOf": [
+ {"$ref": "#/$defs/A"},
+ {"$ref": "#/$defs/C"},
+ {"$ref": "#/$defs/A"},
+ last,
+ ]
+ },
+ }
+ members = _allof_members(
+ {"allOf": [{"$ref": "#/$defs/C"}, {"$ref": "#/$defs/A"}]},
+ definitions,
+ )
+ properties = {}
+ for member in members:
+ properties.update(member.get("properties", {}))
+ assert properties["name"]["default"] == "C"
+
+
+def test_cached_members_respect_initial_resolving_context():
+ leaf = {"properties": {"name": {"default": "value"}}}
+ reference = {"$ref": "#/$defs/A"}
+ assert _allof_members(reference, {"A": leaf}, {"A"}) == [reference]
+
+
+def test_composition_dependency_budget(monkeypatch):
+ monkeypatch.setattr(schemas, "_MAX_COMPOSITION_MEMBERS", 15)
+ definitions: dict[str, Any] = {"L0": {"properties": {"name": {"type": "string"}}}}
+ for i in range(1, 6):
+ definitions[f"L{i}"] = {"$ref": f"#/$defs/L{i - 1}"}
+ with pytest.raises(ValueError, match="Schema composition has too many"):
+ _allof_members({"$ref": "#/$defs/L5"}, definitions)
+
+
+def test_composition_visit_budget(monkeypatch):
+ monkeypatch.setattr(schemas, "_MAX_COMPOSITION_MEMBERS", 15)
+ leaf = {"properties": {"name": {"type": "string"}}}
+ with pytest.raises(ValueError, match="too many visited members"):
+ _allof_members({"allOf": [leaf] * 20}, {})
+
+
+def test_cyclic_composition_budget(monkeypatch):
+ monkeypatch.setattr(schemas, "_MAX_COMPOSITION_MEMBERS", 50)
+ definitions = {
+ "A": {"allOf": [{"$ref": "#/$defs/B"}] * 10},
+ "B": {"allOf": [{"$ref": "#/$defs/A"}] * 10},
+ }
+ with pytest.raises(ValueError, match="Schema composition has too many"):
+ _allof_members({"$ref": "#/$defs/A"}, definitions)
+
+
+def test_repeated_collections_share_the_merge_budget(monkeypatch):
+ monkeypatch.setattr(schemas, "_MAX_COMPOSITION_MEMBERS", 300)
+ group = {"allOf": [{"properties": {str(i): {"type": "string"}}} for i in range(40)]}
+ with pytest.raises(ValueError, match="too many merged members"):
+ _allof_members({"allOf": [group] * 10}, {})
+
+
+def test_aliased_cyclic_members_keep_reference_order():
+ definitions = yaml.safe_load(
+ """
+A: &shared
+ allOf:
+ - properties:
+ name:
+ default: A
+ - $ref: '#/$defs/B'
+B:
+ allOf:
+ - properties:
+ name:
+ default: B
+ - $ref: '#/$defs/C'
+C: *shared
+"""
+ )
+ assert definitions["A"] is definitions["C"]
+ properties = {}
+ for member in _allof_members({"$ref": "#/$defs/A"}, definitions):
+ properties.update(member.get("properties", {}))
+ assert properties["name"]["default"] == "A"