Skip to content

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

fix(openapi): rewrite model references in prefixItems (#5131)

astsfab3bfd09eec
diff --git a/fastmcp_slim/fastmcp/utilities/openapi/schemas.py b/fastmcp_slim/fastmcp/utilities/openapi/schemas.py
index 488d6b9bd..7f08d6a94 100644
--- a/fastmcp_slim/fastmcp/utilities/openapi/schemas.py
+++ b/fastmcp_slim/fastmcp/utilities/openapi/schemas.py
@@ -118,6 +118,11 @@ def _replace_ref_with_defs(
}
elif item_schema := schema.get("items"):
schema["items"] = _replace_ref_with_defs(item_schema)
+ if "prefixItems" in schema:
+ schema["prefixItems"] = [
+ _replace_ref_with_defs(item) if isinstance(item, dict) else item
+ for item in schema["prefixItems"]
+ ]
for section in ["anyOf", "allOf", "oneOf"]:
if section in schema:
schema[section] = [_replace_ref_with_defs(item) for item in schema[section]]
diff --git a/tests/server/providers/openapi/test_tuple_schemas.py b/tests/server/providers/openapi/test_tuple_schemas.py
new file mode 100644
index 000000000..c1cd21f08
--- /dev/null
+++ b/tests/server/providers/openapi/test_tuple_schemas.py
@@ -0,0 +1,84 @@
+"""FastAPI tuple schemas retain resolvable model references."""
+
+import httpx2
+import pytest
+from fastapi import FastAPI
+from jsonschema import Draft202012Validator, ValidationError
+from pydantic import BaseModel
+
+from fastmcp import Client, FastMCP
+
+
+class Item(BaseModel):
+ name: str
+
+
+async def test_fastapi_tuple_input_schema() -> None:
+ app = FastAPI()
+
+ @app.post("/items", operation_id="save_item")
+ def save_item(value: tuple[Item, int]) -> dict[str, str]:
+ return {"name": value[0].name}
+
+ arguments = {"value": [{"name": "example"}, 2]}
+ async with httpx2.AsyncClient(
+ base_url="https://example.com", transport=httpx2.ASGITransport(app)
+ ) as http_client:
+ server = FastMCP.from_openapi(openapi_spec=app.openapi(), client=http_client)
+ async with Client(server) as client:
+ tool = (await client.list_tools())[0]
+ validator = Draft202012Validator(tool.input_schema)
+ validator.validate(arguments)
+ with pytest.raises(ValidationError):
+ validator.validate({"value": [{"name": 42}, 2]})
+ with pytest.raises(ValidationError):
+ validator.validate({"value": [{"name": "example"}, "invalid"]})
+
+ result = await client.call_tool("save_item", arguments)
+
+ assert result.structured_content == {"name": "example"}
+
+
+async def test_fastapi_tuple_output_schema() -> None:
+ app = FastAPI()
+
+ @app.post("/items", operation_id="get_item")
+ def get_item() -> tuple[Item, int]:
+ return Item(name="example"), 2
+
+ async with httpx2.AsyncClient(
+ base_url="https://example.com", transport=httpx2.ASGITransport(app)
+ ) as http_client:
+ server = FastMCP.from_openapi(openapi_spec=app.openapi(), client=http_client)
+ async with Client(server) as client:
+ tool = (await client.list_tools())[0]
+ result = await client.call_tool("get_item")
+
+ assert result.structured_content == {"result": [{"name": "example"}, 2]}
+ assert tool.output_schema is not None
+ Draft202012Validator(tool.output_schema).validate(result.structured_content)
+
+
+async def test_fastapi_nested_tuple_schemas() -> None:
+ class Batch(BaseModel):
+ entries: list[tuple[Item, int]]
+
+ app = FastAPI()
+
+ @app.post("/batches", operation_id="save_batch")
+ def save_batch(batch: Batch) -> Batch:
+ return batch
+
+ arguments = {"entries": [[{"name": "example"}, 2]]}
+ async with httpx2.AsyncClient(
+ base_url="https://example.com", transport=httpx2.ASGITransport(app)
+ ) as http_client:
+ server = FastMCP.from_openapi(openapi_spec=app.openapi(), client=http_client)
+ async with Client(server) as client:
+ tool = (await client.list_tools())[0]
+ Draft202012Validator(tool.input_schema).validate(arguments)
+ result = await client.call_tool("save_batch", arguments)
+
+ assert result.structured_content == arguments
+ assert tool.output_schema is not None
+ Draft202012Validator(tool.output_schema).validate(result.structured_content)
diff --git a/tests/utilities/openapi/test_prefixitems_ref_rewrite.py b/tests/utilities/openapi/test_prefixitems_ref_rewrite.py
new file mode 100644
index 000000000..a81b8c4ba
--- /dev/null
+++ b/tests/utilities/openapi/test_prefixitems_ref_rewrite.py
@@ -0,0 +1,39 @@
+from copy import deepcopy
+
+from fastmcp.utilities.openapi.schemas import _replace_ref_with_defs
+
+
+def test_replace_ref_with_defs_rewrites_nested_prefix_items() -> None:
+ schema = {
+ "type": "array",
+ "prefixItems": [
+ {"$ref": "#/components/schemas/Item"},
+ {
+ "type": "array",
+ "prefixItems": [{"$ref": "#/components/schemas/Nested"}],
+ },
+ ],
+ "items": {"$ref": "#/components/schemas/Tail"},
+ "examples": [[{"$ref": "#/components/schemas/Example"}]],
+ }
+ original = deepcopy(schema)
+
+ result = _replace_ref_with_defs(schema)
+
+ assert result["prefixItems"][0] == {"$ref": "#/$defs/Item"}
+ assert result["prefixItems"][1]["prefixItems"] == [{"$ref": "#/$defs/Nested"}]
+ assert result["items"] == {"$ref": "#/$defs/Tail"}
+ assert result["examples"] == original["examples"]
+ assert schema == original
+
+
+def test_replace_ref_with_defs_preserves_boolean_prefix_items() -> None:
+ schema = {
+ "type": "array",
+ "prefixItems": [True, {"$ref": "#/components/schemas/Item"}, False],
+ }
+
+ assert _replace_ref_with_defs(schema) == {
+ "type": "array",
+ "prefixItems": [True, {"$ref": "#/$defs/Item"}, False],
+ }