π The fast, Pythonic way to build MCP servers and clients.
fix(json-schema): keep tools/list working when a root $ref resolves to a boolean schema (#6185)
ayush6c6b34e402fe
diff --git a/fastmcp_slim/fastmcp/utilities/json_schema.py b/fastmcp_slim/fastmcp/utilities/json_schema.pyindex ba9efa645..449532064 100644--- a/fastmcp_slim/fastmcp/utilities/json_schema.py+++ b/fastmcp_slim/fastmcp/utilities/json_schema.py@@ -373,8 +373,14 @@ def dereference_refs(schema: dict[str, Any]) -> dict[str, Any]:needs_merge = _needs_ref_merge(schema)if needs_merge:dereferenced = _merge_ref_siblings(schema, dereferenced, schema)- # Type assertion: top-level schema is always a dict- assert isinstance(dereferenced, dict)+ # A boolean schema is valid JSON Schema (`true` accepts every+ # instance, `false` rejects every instance), so a root $ref can+ # resolve to a non-dict value. jsonref then replaces the whole+ # schema with that value, and there is nothing to inline into.+ # Fall back to the same partial resolution used for circular and+ # oversized schemas rather than failing the entire listing.+ if not isinstance(dereferenced, dict):+ return resolve_root_ref(schema)# Remove $defs since all references have been resolvedif "$defs" in dereferenced:diff --git a/tests/server/middleware/test_dereference.py b/tests/server/middleware/test_dereference.pyindex ce4b369c9..80596016f 100644--- a/tests/server/middleware/test_dereference.py+++ b/tests/server/middleware/test_dereference.py@@ -134,3 +134,42 @@ class TestDereferenceRefsMiddleware:# Simple schema should not have $defs regardlessassert "$defs" not in schemaassert schema["properties"]["a"]["type"] == "integer"++ async def test_root_ref_to_boolean_schema_does_not_fail_listing(self):+ """A tool whose schema has a root $ref to a boolean schema is listed.++ `true` is a valid JSON Schema, but dereferencing it replaces the+ whole schema with a non-dict, which previously raised and failed+ tools/list for the entire server (#6125). The tool now keeps its+ schema and every other tool stays visible.+ """+ from fastmcp.tools import Tool++ class AnyArgs(Tool):+ async def run(self, arguments):+ return "ok"++ mcp = FastMCP("test", dereference_schemas=True)+ mcp.add_tool(+ AnyArgs(+ name="anything",+ parameters={+ "type": "object",+ "$ref": "#/$defs/Any",+ "$defs": {"Any": True},+ },+ )+ )++ @mcp.tool+ def ping() -> str:+ return "pong"++ async with Client(mcp) as client:+ tools = await client.list_tools()++ assert [t.name for t in tools] == ["anything", "ping"]+ # The boolean schema can't be inlined, so the tool keeps its+ # original $ref and $defs rather than crashing the listing.+ anything = tools[0].input_schema+ assert anything["type"] == "object"diff --git a/tests/utilities/test_json_schema.py b/tests/utilities/test_json_schema.pyindex e36173df1..c0195dc3d 100644--- a/tests/utilities/test_json_schema.py+++ b/tests/utilities/test_json_schema.py@@ -382,6 +382,62 @@ class TestDereferenceRefs:assert "$defs" not in resultassert "discriminator" in result["properties"]["item"]["properties"]+ def test_falls_back_for_root_ref_to_boolean_schema(self):+ """A root $ref resolving to a boolean schema must not crash.++ `true` is a valid JSON Schema, so ``$defs: {"Any": true}`` with a+ root $ref is legal. jsonref replaces the whole schema with the+ boolean, which previously hit the dict assertion and failed+ tools/list for the entire server (#6125). The schema now falls+ back to partial resolution and keeps its own keywords.+ """+ schema = {+ "type": "object",+ "$ref": "#/$defs/Any",+ "$defs": {"Any": True},+ }+ result = dereference_refs(schema)++ assert result == schema++ def test_falls_back_for_root_ref_to_false_schema_without_siblings(self):+ """A root $ref resolving to `false` (no siblings) stays intact."""+ schema = {"$ref": "#/$defs/Any", "$defs": {"Any": False}}+ result = dereference_refs(schema)++ assert result == schema++ def test_falls_back_for_root_ref_to_non_schema_json_value(self):+ """A root $ref resolving to any non-dict value must not crash.++ $defs entries are arbitrary JSON, so a pointer can also reach a+ list or scalar; the same fallback applies.+ """+ schema = {+ "type": "object",+ "$ref": "#/$defs/List",+ "$defs": {"List": [1, 2, 3]},+ }+ result = dereference_refs(schema)++ assert result == schema++ def test_nested_ref_to_boolean_schema_is_inlined_as_is(self):+ """A nested $ref resolving to a boolean schema is kept in place.++ jsonref replaces the property node with the boolean itself, which+ is a valid sub-schema; this has always worked and must keep working.+ """+ schema = {+ "type": "object",+ "properties": {"x": {"$ref": "#/$defs/B"}},+ "$defs": {"B": True},+ }+ result = dereference_refs(schema)++ assert "$defs" not in result+ assert result["properties"]["x"] is True+@pytest.mark.parametrize("name", ["default", "const", "enum", "examples"])def test_strips_discriminator_under_property_named_like_a_keyword(self, name: str):"""A property named like a data keyword still holds a sub-schema."""