Skip to content

πŸš€ 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.py
index 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 resolved
if "$defs" in dereferenced:
diff --git a/tests/server/middleware/test_dereference.py b/tests/server/middleware/test_dereference.py
index 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 regardless
assert "$defs" not in schema
assert 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.py
index 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 result
assert "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."""