Repository navigation
Description
What happened?
FastMCP.from_openapi(..., validate_output=False) silently loses the typed result for endpoints whose 2xx JSON response is a non-object (e.g. an array). The call succeeds and structured_content is correct, but CallToolResult.data is None on every call, and the only visible symptom is a client-side log line:
ERROR [client] Error parsing structured content: 1 validation error for dict[str,any]
Input should be a valid dictionary [type=dict_type, input_value=[1, 2, 3], input_type=list]
With the default validate_output=True the same endpoint hydrates data correctly, so this is specific to the permissive-schema path. The validate_output docstring says False means "a permissive schema is used instead, allowing any response structure while still returning structured JSON", and the replacement code keeps the wrap-result flag "so non-object responses still get wrapped" — the wrapping works, but the client-side unwrapping it implies never completes, which looks like an unintended violation of that intent.
Example Code
Single-file script, no network (httpx2.MockTransport stands in for the backend):
import asyncio
import httpx2
from fastmcp import FastMCP
from fastmcp.client import Client
SPEC = {
"openapi": "3.0.0",
"info": {"title": "Test API", "version": "1.0.0"},
"servers": [{"url": "https://api.example.com"}],
"paths": {
"/items": {
"get": {
"operationId": "list_items",
"summary": "List items",
"responses": {
"200": {
"description": "An array of integers",
"content": {
"application/json": {
"schema": {
"type": "array",
"items": {"type": "integer"},
}
}
},
}
},
}
}
},
}
def handler(request: httpx2.Request) -> httpx2.Response:
return httpx2.Response(200, json=[1, 2, 3]) # conforms to the spec
async def main() -> None:
for validate_output in (True, False):
client = httpx2.AsyncClient(
base_url="https://api.example.com",
transport=httpx2.MockTransport(handler),
)
server = FastMCP.from_openapi(
openapi_spec=SPEC, client=client, validate_output=validate_output
)
async with Client(server) as c:
result = await c.call_tool("list_items", {})
print(
f"validate_output={validate_output}: "
f"structured={result.structured_content} data={result.data!r}"
)
await client.aclose()
asyncio.run(main())Output on current main (fb52bd3):
validate_output=True: structured={'result': [1, 2, 3]} data=[1, 2, 3]
validate_output=False: structured={'result': [1, 2, 3]} data=None
Expected: data == [1, 2, 3] in both modes, with no error logged.
Root cause (verified, non-obvious)
For a non-object 2xx schema, extract_output_schema_from_responses (fastmcp/utilities/openapi/schemas.py) builds {"type": "object", "properties": {"result": <schema>}, "required": ["result"], "x-fastmcp-wrap-result": True}. With validate_output=False, _create_openapi_tool (fastmcp/server/providers/openapi/provider.py) replaces that with {"type": "object", "additionalProperties": True} plus the flag — dropping the properties.result anchor while keeping the flag. The server still wraps (OpenAPITool.run only checks the flag), so structured_content is right, but the client hydrates data via output_schema.get("properties", {}).get("result", output_schema) (fastmcp/client/mixins/tools.py): with no properties key it falls back to the whole permissive object schema, so the unwrapped array is validated against dict[str, Any], validate_python raises, and the exception is swallowed and logged, leaving data as None. Every other producer of x-fastmcp-wrap-result (ParsedFunction.from_function via _WrappedResult, and the OpenAPI extractor itself) always emits properties.result alongside the flag; the permissive replacement is the only place that breaks that invariant, which is why only this path is affected.
I have a minimal fix ready with regression tests (keep a properties.result anchor in the permissive schema, using an always-pass subschema so responses that drift from the spec stay accepted — MCP clients validate structuredContent against the advertised outputSchema at the SDK layer, so restoring the declared constraints there would make drifting responses raise instead). With it, the script above prints data=[1, 2, 3] in both modes, and the OpenAPI provider/utilities and client result-hydration suites pass. Happy to open a PR.
Version Information
- fastmcp: current
main(fb52bd3), installed from source (fastmcp-slim 4.1.1.dev5+fb52bd36) - mcp: 2.0.0
- httpx2: 2.12.0
- Python 3.12.2, Windows 11
- Repro is in-memory (MockTransport), no network involved
Activity
fix(openapi): hydrate data for wrapped non-object responses with vali…
[4.1] Backport fixes for 4.1.8 (#6415)