Skip to content

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

Keep schema definitions when hydrating a wrapped tool result (#5927)

Asem ahmedcf163b8e5e19
diff --git a/fastmcp_slim/fastmcp/client/mixins/tools.py b/fastmcp_slim/fastmcp/client/mixins/tools.py
index 07c20a033..d0548ed01 100644
--- a/fastmcp_slim/fastmcp/client/mixins/tools.py
+++ b/fastmcp_slim/fastmcp/client/mixins/tools.py
@@ -339,6 +339,31 @@ class ClientToolsMixin:
)
+def _wrapped_result_schema(output_schema: dict[str, Any]) -> dict[str, Any] | bool:
+ """Narrow a wrapped output schema to `properties.result` and keep its defs.
+
+ The server leaves `$defs` and draft-07 `definitions` on the root schema,
+ beside `properties.result`. Validating the inner schema without them makes
+ every local `$ref` resolve to an empty object.
+ """
+ properties = output_schema.get("properties")
+ if not isinstance(properties, dict):
+ return output_schema
+ narrowed = properties.get("result")
+ if isinstance(narrowed, bool):
+ return narrowed
+ if not isinstance(narrowed, dict):
+ return output_schema
+ carried = {
+ key: output_schema[key]
+ for key in ("$defs", "definitions")
+ if key in output_schema and key not in narrowed
+ }
+ if not carried:
+ return narrowed
+ return {**narrowed, **carried}
+
+
async def _parse_call_tool_result(
name: str,
result: mcp_types.CallToolResult,
@@ -403,9 +428,7 @@ async def _parse_call_tool_result(
output_schema = tool_output_schemas.get(name)
if output_schema:
if wrap_from_meta or output_schema.get("x-fastmcp-wrap-result"):
- output_schema = output_schema.get("properties", {}).get(
- "result", output_schema
- )
+ output_schema = _wrapped_result_schema(output_schema)
type_adapter = json_schema_to_type_adapter(output_schema)
data = type_adapter.validate_python(structured_content)
else:
diff --git a/tests/client/test_result_hydration.py b/tests/client/test_result_hydration.py
index 1406aaf5a..acb24ceb9 100644
--- a/tests/client/test_result_hydration.py
+++ b/tests/client/test_result_hydration.py
@@ -12,6 +12,7 @@ import pytest
from pydantic import BaseModel
from fastmcp import Client, FastMCP
+from fastmcp.tools import Tool
class Reading(BaseModel):
@@ -22,6 +23,16 @@ class Reading(BaseModel):
ident: UUID
+class Item(BaseModel):
+ name: str
+ when: date
+
+
+class TreeNode(BaseModel):
+ value: int
+ children: list["TreeNode"] = []
+
+
class TestStructuredResultHydration:
@pytest.mark.parametrize(
("field_schema", "value", "expected"),
@@ -110,3 +121,79 @@ class TestStructuredResultHydration:
data = (await client.call_tool("recent")).data
assert data["days"] == [date(2026, 8, 27), date(2026, 8, 28)]
+
+
+class TestWrappedResultKeepsDefs:
+ """A non-object return is wrapped as `{"result": ...}` and its `$defs`
+ stay at the root of the output schema, beside `properties.result`."""
+
+ @pytest.mark.parametrize("dereference_schemas", [True, False])
+ async def test_list_of_models_hydrates(self, dereference_schemas: bool):
+ mcp = FastMCP(dereference_schemas=dereference_schemas)
+
+ @mcp.tool
+ def items() -> list[Item]:
+ return [Item(name="a", when=date(2024, 1, 2))]
+
+ async with Client(mcp) as client:
+ data = (await client.call_tool("items")).data
+
+ assert isinstance(data, list)
+ assert not isinstance(data[0], dict)
+ assert data[0].name == "a"
+ assert data[0].when == date(2024, 1, 2)
+
+ @pytest.mark.parametrize("dereference_schemas", [True, False])
+ async def test_optional_model_hydrates(self, dereference_schemas: bool):
+ mcp = FastMCP(dereference_schemas=dereference_schemas)
+
+ @mcp.tool
+ def maybe_item() -> Item | None:
+ return Item(name="a", when=date(2024, 1, 2))
+
+ async with Client(mcp) as client:
+ data = (await client.call_tool("maybe_item")).data
+
+ assert not isinstance(data, dict)
+ assert data.name == "a"
+ assert data.when == date(2024, 1, 2)
+
+ @pytest.mark.parametrize("dereference_schemas", [True, False])
+ async def test_list_of_recursive_models_hydrates(self, dereference_schemas: bool):
+ mcp = FastMCP(dereference_schemas=dereference_schemas)
+
+ @mcp.tool
+ def trees() -> list[TreeNode]:
+ return [TreeNode(value=1, children=[TreeNode(value=2)])]
+
+ async with Client(mcp) as client:
+ data = (await client.call_tool("trees")).data
+
+ assert isinstance(data, list)
+ assert not isinstance(data[0], dict)
+ assert data[0].value == 1
+ assert not isinstance(data[0].children[0], dict)
+ assert data[0].children[0].value == 2
+
+ async def test_boolean_result_schema_accepts_any_value(self):
+ mcp = FastMCP()
+
+ def example() -> str:
+ return "example"
+
+ mcp.add_tool(
+ Tool.from_function(
+ example,
+ output_schema={
+ "type": "object",
+ "properties": {"result": True},
+ "required": ["result"],
+ "x-fastmcp-wrap-result": True,
+ },
+ )
+ )
+
+ async with Client(mcp) as client:
+ data = (await client.call_tool("example")).data
+
+ assert data == "example"