π The fast, Pythonic way to build MCP servers and clients.
Fix schema wrapping for non-object union types in output schemas
Jeremiah Lowin7e0a237945ca
diff --git a/src/fastmcp/tools/tool.py b/src/fastmcp/tools/tool.pyindex 03cab7d3c..6cca87919 100644--- a/src/fastmcp/tools/tool.py+++ b/src/fastmcp/tools/tool.py@@ -3,7 +3,7 @@ from __future__ import annotationsimport inspectfrom collections.abc import Callablefrom dataclasses import dataclass-from typing import TYPE_CHECKING, Annotated, Any, Literal+from typing import TYPE_CHECKING, Annotated, Any, Generic, Literal, TypeVarimport mcp.typesimport pydantic_core@@ -31,34 +31,22 @@ if TYPE_CHECKING:logger = get_logger(__name__)--class _UnserializableType:- pass+T = TypeVar("T")-def default_serializer(data: Any) -> str:- return pydantic_core.to_json(data, fallback=str, indent=2).decode()+@dataclass+class _WrappedResult(Generic[T]):+ """Generic wrapper for non-object return types."""+ result: T-def _wrap_schema_if_needed(schema: dict[str, Any] | None) -> dict[str, Any] | None:- """Wrap non-object schemas with result property for structured output.- This wrapping allows primitive types (int, str, etc.) to be returned as- structured content by placing them under a "result" key.+class _UnserializableType:+ pass- Args:- schema: The JSON schema to potentially wrap- Returns:- Wrapped schema if needed, or original schema if already an object type- """- if schema and schema.get("type") != "object":- return {- "type": "object",- "properties": {"result": schema},- "x-fastmcp-wrap-result": True,- }- return schema+def default_serializer(data: Any) -> str:+ return pydantic_core.to_json(data, fallback=str, indent=2).decode()class ToolResult:@@ -246,7 +234,7 @@ class FunctionTool(Tool):raise ValueError("You must provide a name for lambda functions")if isinstance(output_schema, NotSetT):- output_schema = _wrap_schema_if_needed(parsed_fn.output_schema)+ output_schema = parsed_fn.output_schemaelif output_schema is False:output_schema = None# Note: explicit schemas (dict) are used as-is without auto-wrapping@@ -329,8 +317,8 @@ class ParsedFunction:cls,fn: Callable[..., Any],exclude_args: list[str] | None = None,- ignore_response_types: list[type] | None = None,validate: bool = True,+ wrap_non_object_output_schema: bool = True,) -> ParsedFunction:from fastmcp.server.context import Context@@ -389,7 +377,7 @@ class ParsedFunction:# or are MCP content types that explicitly don't form structured# content. By replacing them with an explicitly unserializable type,# we ensure that no output schema is automatically generated.- output_type = replace_type(+ clean_output_type = replace_type(output_type,{t: _UnserializableType@@ -408,8 +396,25 @@ class ParsedFunction:)try:- output_type_adapter = get_cached_typeadapter(output_type)- output_schema = output_type_adapter.json_schema()+ type_adapter = get_cached_typeadapter(clean_output_type)+ base_schema = type_adapter.json_schema()++ # Generate schema for wrapped type if it's non-object+ # because MCP requires that output schemas are objects+ if (+ wrap_non_object_output_schema+ and base_schema.get("type") != "object"+ ):+ # Use the wrapped result schema directly+ wrapped_type = _WrappedResult[clean_output_type]+ wrapped_adapter = get_cached_typeadapter(wrapped_type)+ output_schema = wrapped_adapter.json_schema()+ output_schema["x-fastmcp-wrap-result"] = True+ else:+ output_schema = base_schema++ output_schema = compress_schema(output_schema)+except PydanticSchemaGenerationError as e:if "_UnserializableType" not in str(e):logger.debug(f"Unable to generate schema for type {output_type!r}")@@ -422,21 +427,6 @@ class ParsedFunction:output_schema=output_schema or None,)- try:- output_type_adapter = get_cached_typeadapter(output_type)- output_schema = output_type_adapter.json_schema()- except PydanticSchemaGenerationError as e:- if "_UnserializableType" not in str(e):- logger.debug(f"Unable to generate schema for type {output_type!r}")-- return cls(- fn=fn,- name=fn_name,- description=fn_doc,- input_schema=input_schema,- output_schema=output_schema or None,- )-def _convert_to_content(result: Any,diff --git a/src/fastmcp/tools/tool_transform.py b/src/fastmcp/tools/tool_transform.pyindex 61d9ecc9e..95c4a877e 100644--- a/src/fastmcp/tools/tool_transform.py+++ b/src/fastmcp/tools/tool_transform.py@@ -9,7 +9,7 @@ from typing import Any, Literalfrom mcp.types import ToolAnnotationsfrom pydantic import ConfigDict-from fastmcp.tools.tool import ParsedFunction, Tool, ToolResult, _wrap_schema_if_needed+from fastmcp.tools.tool import ParsedFunction, Tool, ToolResultfrom fastmcp.utilities.logging import get_loggerfrom fastmcp.utilities.types import NotSet, NotSetT, get_cached_typeadapter@@ -430,7 +430,7 @@ class TransformedTool(Tool):# Smart fallback: try custom function, then parent, then Noneif transform_fn is not None:parsed_fn = ParsedFunction.from_function(transform_fn, validate=False)- final_output_schema = _wrap_schema_if_needed(parsed_fn.output_schema)+ final_output_schema = parsed_fn.output_schemaif final_output_schema is None:# Check if function returns ToolResult - if so, don't fall back to parentimport inspectdiff --git a/tests/server/test_server_interactions.py b/tests/server/test_server_interactions.pyindex f37434194..8d905919e 100644--- a/tests/server/test_server_interactions.py+++ b/tests/server/test_server_interactions.py@@ -27,6 +27,7 @@ from fastmcp.prompts.prompt import Prompt, PromptMessagefrom fastmcp.resources import FileResource, ResourceTemplatefrom fastmcp.resources.resource import FunctionResourcefrom fastmcp.tools.tool import Tool, ToolResult+from fastmcp.utilities.json_schema import compress_schemafrom fastmcp.utilities.types import Audio, File, Image@@ -894,7 +895,9 @@ class TestToolOutputSchema:# this line will fail until MCP adds output schemas!!assert tools[0].outputSchema == {"type": "object",- "properties": {"result": type_schema},+ "properties": {"result": {**type_schema, "title": "Result"}},+ "required": ["result"],+ "title": "_WrappedResult","x-fastmcp-wrap-result": True,}@@ -912,7 +915,7 @@ class TestToolOutputSchema:async with Client(mcp) as client:tools = await client.list_tools()- type_schema = TypeAdapter(annotation).json_schema()+ type_schema = compress_schema(TypeAdapter(annotation).json_schema())assert len(tools) == 1assert tools[0].outputSchema == type_schema@@ -1020,7 +1023,9 @@ class TestToolOutputSchema:tool = next(t for t in tools if t.name == "primitive_tool")expected_schema = {"type": "object",- "properties": {"result": {"type": "string"}},+ "properties": {"result": {"type": "string", "title": "Result"}},+ "required": ["result"],+ "title": "_WrappedResult","x-fastmcp-wrap-result": True,}assert tool.outputSchema == expected_schema@@ -1045,7 +1050,9 @@ class TestToolOutputSchema:expected_inner_schema = TypeAdapter(list[dict[str, int]]).json_schema()expected_schema = {"type": "object",- "properties": {"result": expected_inner_schema},+ "properties": {"result": {**expected_inner_schema, "title": "Result"}},+ "required": ["result"],+ "title": "_WrappedResult","x-fastmcp-wrap-result": True,}assert tool.outputSchema == expected_schema@@ -1074,7 +1081,7 @@ class TestToolOutputSchema:# List tools and verify schema is object type (not wrapped)tools = await client.list_tools()tool = next(t for t in tools if t.name == "dataclass_tool")- expected_schema = TypeAdapter(User).json_schema()+ expected_schema = compress_schema(TypeAdapter(User).json_schema())assert tool.outputSchema == expected_schemaassert (tool.outputSchema and "x-fastmcp-wrap-result" not in tool.outputSchemadiff --git a/tests/tools/test_tool.py b/tests/tools/test_tool.pyindex a2278d6d1..119d52f38 100644--- a/tests/tools/test_tool.py+++ b/tests/tools/test_tool.py@@ -14,6 +14,7 @@ from pydantic import AnyUrl, BaseModel, Field, TypeAdapterfrom typing_extensions import TypedDictfrom fastmcp.tools.tool import Tool, _convert_to_content+from fastmcp.utilities.json_schema import compress_schemafrom fastmcp.utilities.types import Audio, File, Image@@ -35,7 +36,9 @@ class TestToolFromFunction:# With primitive wrapping, int return type becomes object with result propertyexpected_schema = {"type": "object",- "properties": {"result": {"type": "integer"}},+ "properties": {"result": {"type": "integer", "title": "Result"}},+ "required": ["result"],+ "title": "_WrappedResult","x-fastmcp-wrap-result": True,}assert tool.output_schema == expected_schema@@ -296,7 +299,9 @@ class TestToolFromFunctionOutputSchema:# Non-object types get wrappedexpected_schema = {"type": "object",- "properties": {"result": base_schema},+ "properties": {"result": {**base_schema, "title": "Result"}},+ "required": ["result"],+ "title": "_WrappedResult","x-fastmcp-wrap-result": True,}assert tool.output_schema == expected_schema@@ -321,7 +326,9 @@ class TestToolFromFunctionOutputSchema:expected_schema = {"type": "object",- "properties": {"result": base_schema},+ "properties": {"result": {**base_schema, "title": "Result"}},+ "required": ["result"],+ "title": "_WrappedResult","x-fastmcp-wrap-result": True,}assert tool.output_schema == expected_schema@@ -369,7 +376,8 @@ class TestToolFromFunctionOutputSchema:return Person(name="John", age=30)tool = Tool.from_function(func)- assert tool.output_schema == TypeAdapter(Person).json_schema()+ expected_schema = compress_schema(TypeAdapter(Person).json_schema())+ assert tool.output_schema == expected_schemaasync def test_base_model_return_annotation(self):class Person(BaseModel):@@ -380,7 +388,8 @@ class TestToolFromFunctionOutputSchema:return Person(name="John", age=30)tool = Tool.from_function(func)- assert tool.output_schema == TypeAdapter(Person).json_schema()+ expected_schema = compress_schema(TypeAdapter(Person).json_schema())+ assert tool.output_schema == expected_schemaasync def test_typeddict_return_annotation(self):class Person(TypedDict):@@ -391,7 +400,8 @@ class TestToolFromFunctionOutputSchema:return Person(name="John", age=30)tool = Tool.from_function(func)- assert tool.output_schema == TypeAdapter(Person).json_schema()+ expected_schema = compress_schema(TypeAdapter(Person).json_schema())+ assert tool.output_schema == expected_schemaasync def test_unserializable_return_annotation(self):class Unserializable:@@ -568,7 +578,9 @@ class TestToolFromFunctionOutputSchema:tool = Tool.from_function(func)expected_schema = {"type": "object",- "properties": {"result": {"type": "integer"}},+ "properties": {"result": {"type": "integer", "title": "Result"}},+ "required": ["result"],+ "title": "_WrappedResult","x-fastmcp-wrap-result": True,}assert tool.output_schema == expected_schema@@ -638,7 +650,9 @@ class TestToolFromFunctionOutputSchema:tool = Tool.from_function(func)expected_schema = {"type": "object",- "properties": {"result": {"type": "string"}},+ "properties": {"result": {"type": "string", "title": "Result"}},+ "required": ["result"],+ "title": "_WrappedResult","x-fastmcp-wrap-result": True,}assert tool.output_schema == expected_schema@@ -1220,13 +1234,39 @@ class TestAutomaticStructuredContent:async with Client(mcp) as client:result = await client.call_tool("get_profile", {"user_id": "456"})- # Client should deserialize back to a dataclass (type name will match)+ # Client should deserialize back to a dataclass (type name preserved with new compression)assert result.data.__class__.__name__ == "UserProfile"assert result.data.name == "Bob"assert result.data.age == 25assert result.data.verified is True+class TestUnionReturnTypes:+ """Tests for tools with union return types."""++ async def test_dataclass_union_string_works(self):+ """Test that union of dataclass and string works correctly."""++ @dataclass+ class Data:+ value: int++ def get_data(return_error: bool) -> Data | str:+ if return_error:+ return "error occurred"+ return Data(value=42)++ tool = Tool.from_function(get_data)++ # Test returning dataclass+ result1 = await tool.run({"return_error": False})+ assert result1.structured_content == {"result": {"value": 42}}++ # Test returning string+ result2 = await tool.run({"return_error": True})+ assert result2.structured_content == {"result": "error occurred"}++class TestToolTitle:"""Tests for tool title functionality."""diff --git a/tests/tools/test_tool_transform.py b/tests/tools/test_tool_transform.pyindex 5e976b381..f0dedf4e0 100644--- a/tests/tools/test_tool_transform.py+++ b/tests/tools/test_tool_transform.py@@ -1063,7 +1063,9 @@ class TestTransformToolOutputSchema:# Should inherit parent's wrapped string schemaexpected_schema = {"type": "object",- "properties": {"result": {"type": "string"}},+ "properties": {"result": {"type": "string", "title": "Result"}},+ "required": ["result"],+ "title": "_WrappedResult","x-fastmcp-wrap-result": True,}assert new_tool.output_schema == expected_schema@@ -1121,7 +1123,9 @@ class TestTransformToolOutputSchema:# Should infer string schema from custom function and wrap itexpected_schema = {"type": "object",- "properties": {"result": {"type": "string"}},+ "properties": {"result": {"type": "string", "title": "Result"}},+ "required": ["result"],+ "title": "_WrappedResult","x-fastmcp-wrap-result": True,}assert new_tool.output_schema == expected_schema