π The fast, Pythonic way to build MCP servers and clients.
"""Tests for DereferenceRefsMiddleware."""
from enum import Enum
import pydantic
from fastmcp import Client, FastMCP
class Color(Enum):
RED = "red"
GREEN = "green"
BLUE = "blue"
class PaintRequest(pydantic.BaseModel):
color: Color
opacity: float = 1.0
class TestDereferenceRefsMiddleware:
"""End-to-end tests for the dereference_schemas server kwarg."""
async def test_dereference_schemas_true_inlines_refs(self):
"""With dereference_schemas=True (default), tool schemas have $ref inlined."""
mcp = FastMCP("test", dereference_schemas=True)
@mcp.tool
def paint(request: PaintRequest) -> str:
return "ok"
async with Client(mcp) as client:
tools = await client.list_tools()
schema = tools[0].input_schema
# $defs should be removed β everything inlined
assert "$defs" not in schema
# The Color enum should be inlined into the request property
assert "$ref" not in str(schema)
async def test_dereference_schemas_false_preserves_refs(self):
"""With dereference_schemas=False, $ref and $defs are preserved."""
mcp = FastMCP("test", dereference_schemas=False)
@mcp.tool
def paint(request: PaintRequest) -> str:
return "ok"
async with Client(mcp) as client:
tools = await client.list_tools()
schema = tools[0].input_schema
# $defs should still be present
assert "$defs" in schema
async def test_default_is_true(self):
"""Default behavior dereferences $ref."""
mcp = FastMCP("test")
@mcp.tool
def paint(request: PaintRequest) -> str:
return "ok"
async with Client(mcp) as client:
tools = await client.list_tools()
schema = tools[0].input_schema
assert "$defs" not in schema
async def test_does_not_mutate_original_tool(self):
"""Middleware should not mutate the shared Tool object."""
mcp = FastMCP("test", dereference_schemas=True)
@mcp.tool
def paint(request: PaintRequest) -> str:
return "ok"
# Get the original tool's parameters before middleware runs
original_tools = await mcp._local_provider._list_tools()
assert "$defs" in original_tools[0].parameters
# List tools through the client (triggers middleware)
async with Client(mcp) as client:
await client.list_tools()
# The original tool stored in the server should still have $defs
tools_after = await mcp._local_provider._list_tools()
assert "$defs" in tools_after[0].parameters
async def test_output_schema_dereferenced(self):
"""Middleware also dereferences output_schema when present."""
mcp = FastMCP("test", dereference_schemas=True)
@mcp.tool
def paint(request: PaintRequest) -> PaintRequest:
return request
async with Client(mcp) as client:
tools = await client.list_tools()
tool = tools[0]
# Both input and output schemas should be dereferenced
assert "$defs" not in tool.input_schema
if tool.output_schema is not None:
assert "$defs" not in tool.output_schema
async def test_resource_templates_dereferenced(self):
"""Middleware dereferences resource template schemas."""
mcp = FastMCP("test", dereference_schemas=True)
@mcp.resource("paint://{color}")
def get_paint(color: Color) -> str:
return f"paint: {color}"
async with Client(mcp) as client:
templates = await client.list_resource_templates()
# Resource templates also get their schemas dereferenced
# (only if the template parameters have $ref)
assert len(templates) == 1
async def test_no_ref_schemas_unchanged(self):
"""Tools without $ref should pass through unmodified."""
mcp = FastMCP("test", dereference_schemas=True)
@mcp.tool
def add(a: int, b: int) -> int:
return a + b
async with Client(mcp) as client:
tools = await client.list_tools()
schema = tools[0].input_schema
# 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"