π The fast, Pythonic way to build MCP servers and clients.
Fix $ref output schema object detection regression (#3420)
Jeremiah Lowinceb8ff18c6d8
diff --git a/src/fastmcp/tools/function_parsing.py b/src/fastmcp/tools/function_parsing.pyindex a056c37c9..c5ac20fff 100644--- a/src/fastmcp/tools/function_parsing.py+++ b/src/fastmcp/tools/function_parsing.py@@ -63,8 +63,16 @@ class _UnserializableType:pass-def _is_object_schema(schema: dict[str, Any]) -> bool:+def _is_object_schema(+ schema: dict[str, Any],+ *,+ _root_schema: dict[str, Any] | None = None,+ _seen_refs: set[str] | None = None,+) -> bool:"""Check if a JSON schema represents an object type."""+ root_schema = _root_schema or schema+ seen_refs = _seen_refs or set()+# Direct object typeif schema.get("type") == "object":return True@@ -73,9 +81,34 @@ def _is_object_schema(schema: dict[str, Any]) -> bool:if "properties" in schema:return True- # Self-referencing types use $ref pointing to $defs- # The referenced type is always an object in our use case- return "$ref" in schema and "$defs" in schema+ # Resolve local $ref definitions and recurse into the target schema.+ ref = schema.get("$ref")+ if not isinstance(ref, str) or not ref.startswith("#/"):+ return False++ if ref in seen_refs:+ return False++ # Walk the JSON Pointer path from the root schema, unescaping each+ # token per RFC 6901 (~1 β /, ~0 β ~).+ pointer = ref.removeprefix("#/")+ segments = pointer.split("/")+ target: Any = root_schema+ for segment in segments:+ unescaped = segment.replace("~1", "/").replace("~0", "~")+ if not isinstance(target, dict) or unescaped not in target:+ return False+ target = target[unescaped]++ target_schema = target+ if not isinstance(target_schema, dict):+ return False++ return _is_object_schema(+ target_schema,+ _root_schema=root_schema,+ _seen_refs=seen_refs | {ref},+ )@dataclassdiff --git a/tests/server/providers/local_provider_tools/test_output_schema.py b/tests/server/providers/local_provider_tools/test_output_schema.pyindex 6f1f38d44..f9136492e 100644--- a/tests/server/providers/local_provider_tools/test_output_schema.py+++ b/tests/server/providers/local_provider_tools/test_output_schema.py@@ -1,16 +1,17 @@"""Tests for tool output schemas."""from dataclasses import dataclass-from typing import Any+from typing import Any, Literalimport pytestfrom mcp.types import (TextContent,)from pydantic import AnyUrl, BaseModel, TypeAdapter-from typing_extensions import TypedDict+from typing_extensions import TypeAliasType, TypedDictfrom fastmcp import FastMCP+from fastmcp.tools.function_parsing import _is_object_schemafrom fastmcp.tools.tool import ToolResultfrom fastmcp.utilities.json_schema import compress_schema@@ -282,3 +283,99 @@ class TestToolOutputSchema:result = await mcp.call_tool("edge_case_tool", {})assert result.structured_content == {"result": [42, "hello"]}++ async def test_output_schema_wraps_non_object_ref_schema(self):+ """Root $ref schemas should only skip wrapping when they resolve to objects."""+ mcp = FastMCP()+ AliasType = TypeAliasType("AliasType", Literal["foo", "bar"])++ @mcp.tool+ def alias_tool() -> AliasType:+ return "foo"++ tools = await mcp.list_tools()+ tool = next(t for t in tools if t.name == "alias_tool")++ expected_inner_schema = compress_schema(+ TypeAdapter(AliasType).json_schema(mode="serialization"),+ prune_titles=True,+ )+ assert tool.output_schema == {+ "type": "object",+ "properties": {"result": expected_inner_schema},+ "required": ["result"],+ "x-fastmcp-wrap-result": True,+ }++ result = await mcp.call_tool("alias_tool", {})+ assert result.structured_content == {"result": "foo"}+++class TestIsObjectSchemaRefResolution:+ """Tests for $ref resolution in _is_object_schema, including JSON Pointer+ escaping and nested $defs paths."""++ def test_simple_ref_to_object(self):+ schema = {+ "$ref": "#/$defs/MyModel",+ "$defs": {+ "MyModel": {"type": "object", "properties": {"x": {"type": "int"}}}+ },+ }+ assert _is_object_schema(schema) is True++ def test_simple_ref_to_non_object(self):+ schema = {+ "$ref": "#/$defs/MyEnum",+ "$defs": {"MyEnum": {"enum": ["a", "b"]}},+ }+ assert _is_object_schema(schema) is False++ def test_nested_defs_path(self):+ """Refs like #/$defs/Outer/$defs/Inner should walk into nested dicts."""+ schema = {+ "$ref": "#/$defs/Outer/$defs/Inner",+ "$defs": {+ "Outer": {+ "$defs": {+ "Inner": {+ "type": "object",+ "properties": {"y": {"type": "string"}},+ },+ },+ },+ },+ }+ assert _is_object_schema(schema) is True++ def test_nested_defs_non_object(self):+ schema = {+ "$ref": "#/$defs/Outer/$defs/Inner",+ "$defs": {+ "Outer": {+ "$defs": {+ "Inner": {"type": "string"},+ },+ },+ },+ }+ assert _is_object_schema(schema) is False++ def test_json_pointer_tilde_escape(self):+ """~0 should unescape to ~ and ~1 should unescape to /."""+ schema = {+ "$ref": "#/$defs/has~1slash~0tilde",+ "$defs": {"has/slash~tilde": {"type": "object", "properties": {}}},+ }+ assert _is_object_schema(schema) is True++ def test_missing_nested_segment_returns_false(self):+ schema = {+ "$ref": "#/$defs/Outer/$defs/Missing",+ "$defs": {+ "Outer": {+ "$defs": {},+ },+ },+ }+ assert _is_object_schema(schema) is False