Skip to content

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

Fix experimental parser missing top-level response schemas (#2087) (#2092)

Jeremiah Lowin59aabe274172
diff --git a/src/fastmcp/experimental/utilities/openapi/parser.py b/src/fastmcp/experimental/utilities/openapi/parser.py
index 799601a7e..bc81fc050 100644
--- a/src/fastmcp/experimental/utilities/openapi/parser.py
+++ b/src/fastmcp/experimental/utilities/openapi/parser.py
@@ -474,9 +474,22 @@ class OpenAPIParser(
and media_type_obj.media_type_schema
):
try:
- schema_dict = self._extract_schema_as_dict(
- media_type_obj.media_type_schema
- )
+ # Track if this is a top-level $ref before resolution
+ top_level_schema_name = None
+ media_schema = media_type_obj.media_type_schema
+ if isinstance(media_schema, self.reference_cls):
+ ref_str = media_schema.ref
+ if isinstance(ref_str, str) and ref_str.startswith(
+ "#/components/schemas/"
+ ):
+ top_level_schema_name = ref_str.split("/")[-1]
+
+ schema_dict = self._extract_schema_as_dict(media_schema)
+ # Add marker for top-level schema if it was a ref
+ if top_level_schema_name:
+ schema_dict["x-fastmcp-top-level-schema"] = (
+ top_level_schema_name
+ )
resp_info.content_schema[media_type_str] = schema_dict
except ValueError as e:
# Re-raise ValueError for external reference errors
@@ -625,6 +638,13 @@ class OpenAPIParser(
for response in responses.values():
if response.content_schema:
for content_schema in response.content_schema.values():
+ # Check if this schema was originally a top-level $ref
+ if "x-fastmcp-top-level-schema" in content_schema:
+ schema_name = content_schema["x-fastmcp-top-level-schema"]
+ if schema_name in all_schemas:
+ needed_schemas.add(schema_name)
+
+ # Extract all dependencies (transitive refs within the schema)
deps = self._extract_schema_dependencies(
content_schema, all_schemas
)
diff --git a/tests/experimental/openapi_parser/utilities/openapi/test_transitive_references.py b/tests/experimental/openapi_parser/utilities/openapi/test_transitive_references.py
index da1000da8..e3cae4ae1 100644
--- a/tests/experimental/openapi_parser/utilities/openapi/test_transitive_references.py
+++ b/tests/experimental/openapi_parser/utilities/openapi/test_transitive_references.py
@@ -786,3 +786,57 @@ class TestTransitiveAndNestedReferences:
assert len(overlap) == 0, (
f"Found overlapping schemas between input and output: {overlap}"
)
+
+ def test_issue_2087_top_level_response_ref_includes_all_nested_schemas(self):
+ """Issue #2087: Top-level response $ref must include itself in response_schemas."""
+ spec = {
+ "openapi": "3.0.1",
+ "info": {"title": "Test", "version": "1.0"},
+ "paths": {
+ "/persons": {
+ "get": {
+ "responses": {
+ "200": {
+ "description": "OK",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/PersonList"
+ }
+ }
+ },
+ }
+ }
+ }
+ }
+ },
+ "components": {
+ "schemas": {
+ "PersonList": {
+ "properties": {
+ "Items": {
+ "type": "array",
+ "items": {"$ref": "#/components/schemas/Person"},
+ }
+ }
+ },
+ "Person": {
+ "properties": {
+ "Name": {"$ref": "#/components/schemas/Name"},
+ "Job": {"$ref": "#/components/schemas/Job"},
+ }
+ },
+ "Name": {"properties": {"First": {"type": "string"}}},
+ "Job": {"properties": {"Company": {"type": "string"}}},
+ }
+ },
+ }
+
+ routes = parse_openapi_to_http_routes(spec)
+ route = routes[0]
+
+ # Bug was: PersonList missing from response_schemas despite being top-level ref
+ assert "PersonList" in route.response_schemas
+ assert "Person" in route.response_schemas
+ assert "Name" in route.response_schemas
+ assert "Job" in route.response_schemas