fastmcp 2.14.1__py3-none-any.whl → 2.14.3__py3-none-any.whl

fastmcp/server/elicitation.py

@@ -304,15 +304,19 @@ def _dict_to_enum_schema(
         multi_select: If True, use anyOf pattern; if False, use oneOf pattern
 
     Returns:
-        {"oneOf": [{"const": "low", "title": "Low Priority"}, ...]} for single-select
-        {"anyOf": [{"const": "low", "title": "Low Priority"}, ...]} for multi-select
+        {"type": "string", "oneOf": [...]} for single-select
+        {"anyOf": [...]} for multi-select (used as array items)
     """
     pattern_key = "anyOf" if multi_select else "oneOf"
     pattern = []
     for value, metadata in enum_dict.items():
         title = metadata.get("title", value)
         pattern.append({"const": value, "title": title})
-    return {pattern_key: pattern}
+
+    result: dict[str, Any] = {pattern_key: pattern}
+    if not multi_select:
+        result["type"] = "string"
+    return result
 
 
 def get_elicitation_schema(response_type: type[T]) -> dict[str, Any]:

fastmcp/server/middleware/error_handling.py

@@ -87,7 +87,7 @@ class ErrorHandlingMiddleware(Middleware):
             return error
 
         # Map common exceptions to appropriate MCP error codes
-        error_type = type(error)
+        error_type = type(error.__cause__) if error.__cause__ else type(error)
 
         if error_type in (ValueError, TypeError):
             return McpError(

fastmcp/server/openapi/components.py

@@ -64,10 +64,8 @@ class OpenAPITool(Tool):
         try:
             # Get base URL from client
             base_url = (
-                str(self._client.base_url)
-                if hasattr(self._client, "base_url") and self._client.base_url
-                else "http://localhost"
-            )
+                str(self._client.base_url) if hasattr(self._client, "base_url") else ""
+            ) or "http://localhost"
 
             # Get Headers from client
             cli_headers = (

fastmcp/server/server.py

@@ -105,23 +105,6 @@ if TYPE_CHECKING:
 logger = get_logger(__name__)
 
 
-def _create_named_fn_wrapper(fn: Callable[..., Any], name: str) -> Callable[..., Any]:
-    """Create a wrapper function with a custom __name__ for Docket registration.
-
-    Docket uses fn.__name__ as the key for function registration and lookup.
-    When mounting servers, we need unique names to avoid collisions between
-    mounted servers that have identically-named functions.
-    """
-    import functools
-
-    @functools.wraps(fn)
-    async def wrapper(*args: Any, **kwargs: Any) -> Any:
-        return await fn(*args, **kwargs)
-
-    wrapper.__name__ = name
-    return wrapper
-
-
 DuplicateBehavior = Literal["warn", "error", "replace", "ignore"]
 Transport = Literal["stdio", "http", "sse", "streamable-http"]
 
@@ -214,8 +197,9 @@ class FastMCP(Generic[LifespanResultT]):
         # Resolve server default for background task support
         self._support_tasks_by_default: bool = tasks if tasks is not None else False
 
-        # Docket instance (set during lifespan for cross-task access)
+        # Docket and Worker instances (set during lifespan for cross-task access)
         self._docket = None
+        self._worker = None
 
         self._additional_http_routes: list[BaseRoute] = []
         self._mounted_servers: list[MountedServer] = []
@@ -437,7 +421,7 @@ class FastMCP(Generic[LifespanResultT]):
                         isinstance(tool, FunctionTool)
                         and tool.task_config.mode != "forbidden"
                     ):
-                        docket.register(tool.fn)
+                        docket.register(tool.fn, names=[tool.key])
 
                 for prompt in self._prompt_manager._prompts.values():
                     if (
@@ -445,21 +429,24 @@ class FastMCP(Generic[LifespanResultT]):
                         and prompt.task_config.mode != "forbidden"
                     ):
                         # task execution requires async fn (validated at creation time)
-                        docket.register(cast(Callable[..., Awaitable[Any]], prompt.fn))
+                        docket.register(
+                            cast(Callable[..., Awaitable[Any]], prompt.fn),
+                            names=[prompt.key],
+                        )
 
                 for resource in self._resource_manager._resources.values():
                     if (
                         isinstance(resource, FunctionResource)
                         and resource.task_config.mode != "forbidden"
                     ):
-                        docket.register(resource.fn)
+                        docket.register(resource.fn, names=[resource.name])
 
                 for template in self._resource_manager._templates.values():
                     if (
                         isinstance(template, FunctionResourceTemplate)
                         and template.task_config.mode != "forbidden"
                     ):
-                        docket.register(template.fn)
+                        docket.register(template.fn, names=[template.name])
 
                 # Also register functions from mounted servers so tasks can
                 # execute in the parent's Docket context
@@ -482,6 +469,8 @@ class FastMCP(Generic[LifespanResultT]):
 
                     # Create and start Worker
                     async with Worker(docket, **worker_kwargs) as worker:  # type: ignore[arg-type]
+                        # Store on server instance for cross-context access
+                        self._worker = worker
                         # Set Worker in ContextVar so CurrentWorker can access it
                         worker_token = _current_worker.set(worker)
                         try:
@@ -489,21 +478,16 @@ class FastMCP(Generic[LifespanResultT]):
                             try:
                                 yield
                             finally:
-                                # Cancel worker task on exit with timeout to prevent hanging
                                 worker_task.cancel()
-                                with suppress(
-                                    asyncio.CancelledError, asyncio.TimeoutError
-                                ):
-                                    await asyncio.wait_for(worker_task, timeout=2.0)
+                                with suppress(asyncio.CancelledError):
+                                    await worker_task
                         finally:
                             _current_worker.reset(worker_token)
+                            self._worker = None
                 finally:
-                    # Reset ContextVar
                     _current_docket.reset(docket_token)
-                    # Clear instance attribute
                     self._docket = None
         finally:
-            # Reset server ContextVar
             _current_server.reset(server_token)
 
     async def _register_mounted_server_functions(
@@ -535,8 +519,7 @@ class FastMCP(Generic[LifespanResultT]):
                     fn_name = f"{prefix}_{tool.key}"
                 else:
                     fn_name = tool.key
-                named_fn = _create_named_fn_wrapper(tool.fn, fn_name)
-                docket.register(named_fn)
+                docket.register(tool.fn, names=[fn_name])
 
         # Register prompts with prefixed names
         for prompt in server._prompt_manager._prompts.values():
@@ -545,10 +528,10 @@ class FastMCP(Generic[LifespanResultT]):
                 and prompt.task_config.mode != "forbidden"
             ):
                 fn_name = f"{prefix}_{prompt.key}" if prefix else prompt.key
-                named_fn = _create_named_fn_wrapper(
-                    cast(Callable[..., Awaitable[Any]], prompt.fn), fn_name
+                docket.register(
+                    cast(Callable[..., Awaitable[Any]], prompt.fn),
+                    names=[fn_name],
                 )
-                docket.register(named_fn)
 
         # Register resources with prefixed names (use name, not key/URI)
         for resource in server._resource_manager._resources.values():
@@ -557,8 +540,7 @@ class FastMCP(Generic[LifespanResultT]):
                 and resource.task_config.mode != "forbidden"
             ):
                 fn_name = f"{prefix}_{resource.name}" if prefix else resource.name
-                named_fn = _create_named_fn_wrapper(resource.fn, fn_name)
-                docket.register(named_fn)
+                docket.register(resource.fn, names=[fn_name])
 
         # Register resource templates with prefixed names (use name, not key/URI)
         for template in server._resource_manager._templates.values():
@@ -567,8 +549,7 @@ class FastMCP(Generic[LifespanResultT]):
                 and template.task_config.mode != "forbidden"
             ):
                 fn_name = f"{prefix}_{template.name}" if prefix else template.name
-                named_fn = _create_named_fn_wrapper(template.fn, fn_name)
-                docket.register(named_fn)
+                docket.register(template.fn, names=[fn_name])
 
         # Recursively register from nested mounted servers with accumulated prefix
         for nested in server._mounted_servers:
@@ -584,6 +565,8 @@ class FastMCP(Generic[LifespanResultT]):
     @asynccontextmanager
     async def _lifespan_manager(self) -> AsyncIterator[None]:
         if self._lifespan_result_set:
+            # Lifespan already ran - ContextVars will be set by Context.__aenter__
+            # at request time, so we just yield here.
             yield
             return
 
@@ -2516,10 +2499,7 @@ class FastMCP(Generic[LifespanResultT]):
         """
         # Display server banner
         if show_banner:
-            log_server_banner(
-                server=self,
-                transport="stdio",
-            )
+            log_server_banner(server=self)
 
         with temporary_log_level(log_level):
             async with self._lifespan_manager():
@@ -2582,22 +2562,9 @@ class FastMCP(Generic[LifespanResultT]):
             stateless_http=stateless_http,
         )
 
-        # Get the path for the server URL
-        server_path = (
-            app.state.path.lstrip("/")
-            if hasattr(app, "state") and hasattr(app.state, "path")
-            else path or ""
-        )
-
         # Display server banner
         if show_banner:
-            log_server_banner(
-                server=self,
-                transport=transport,
-                host=host,
-                port=port,
-                path=server_path,
-            )
+            log_server_banner(server=self)
         uvicorn_config_from_user = uvicorn_config or {}
 
         config_kwargs: dict[str, Any] = {

fastmcp/server/tasks/handlers.py

@@ -56,6 +56,7 @@ async def handle_tool_as_task(
     ctx = get_context()
     session_id = ctx.session_id
 
+    # Get Docket from ContextVar (set by Context.__aenter__ at request time)
     docket = _current_docket.get()
     if docket is None:
         raise McpError(
@@ -72,13 +73,15 @@ async def handle_tool_as_task(
     tool = await server.get_tool(tool_name)
 
     # Store task key mapping and creation timestamp in Redis for protocol handlers
-    redis_key = f"fastmcp:task:{session_id}:{server_task_id}"
-    created_at_key = f"fastmcp:task:{session_id}:{server_task_id}:created_at"
+    task_meta_key = docket.key(f"fastmcp:task:{session_id}:{server_task_id}")
+    created_at_key = docket.key(
+        f"fastmcp:task:{session_id}:{server_task_id}:created_at"
+    )
     ttl_seconds = int(
         docket.execution_ttl.total_seconds() + TASK_MAPPING_TTL_BUFFER_SECONDS
     )
     async with docket.redis() as redis:
-        await redis.set(redis_key, task_key, ex=ttl_seconds)
+        await redis.set(task_meta_key, task_key, ex=ttl_seconds)
         await redis.set(created_at_key, created_at, ex=ttl_seconds)
 
     # Send notifications/tasks/created per SEP-1686 (mandatory)
@@ -165,6 +168,7 @@ async def handle_prompt_as_task(
     ctx = get_context()
     session_id = ctx.session_id
 
+    # Get Docket from ContextVar (set by Context.__aenter__ at request time)
     docket = _current_docket.get()
     if docket is None:
         raise McpError(
@@ -181,13 +185,15 @@ async def handle_prompt_as_task(
     prompt = await server.get_prompt(prompt_name)
 
     # Store task key mapping and creation timestamp in Redis for protocol handlers
-    redis_key = f"fastmcp:task:{session_id}:{server_task_id}"
-    created_at_key = f"fastmcp:task:{session_id}:{server_task_id}:created_at"
+    task_meta_key = docket.key(f"fastmcp:task:{session_id}:{server_task_id}")
+    created_at_key = docket.key(
+        f"fastmcp:task:{session_id}:{server_task_id}:created_at"
+    )
     ttl_seconds = int(
         docket.execution_ttl.total_seconds() + TASK_MAPPING_TTL_BUFFER_SECONDS
     )
     async with docket.redis() as redis:
-        await redis.set(redis_key, task_key, ex=ttl_seconds)
+        await redis.set(task_meta_key, task_key, ex=ttl_seconds)
         await redis.set(created_at_key, created_at, ex=ttl_seconds)
 
     # Send notifications/tasks/created per SEP-1686 (mandatory)
@@ -272,12 +278,13 @@ async def handle_resource_as_task(
     ctx = get_context()
     session_id = ctx.session_id
 
+    # Get Docket from ContextVar (set by Context.__aenter__ at request time)
     docket = _current_docket.get()
     if docket is None:
         raise McpError(
             ErrorData(
                 code=INTERNAL_ERROR,
-                message="Background tasks require Docket",
+                message="Background tasks require a running FastMCP server context",
             )
         )
 
@@ -285,13 +292,15 @@ async def handle_resource_as_task(
     task_key = build_task_key(session_id, server_task_id, "resource", str(uri))
 
     # Store task key mapping and creation timestamp in Redis for protocol handlers
-    redis_key = f"fastmcp:task:{session_id}:{server_task_id}"
-    created_at_key = f"fastmcp:task:{session_id}:{server_task_id}:created_at"
+    task_meta_key = docket.key(f"fastmcp:task:{session_id}:{server_task_id}")
+    created_at_key = docket.key(
+        f"fastmcp:task:{session_id}:{server_task_id}:created_at"
+    )
     ttl_seconds = int(
         docket.execution_ttl.total_seconds() + TASK_MAPPING_TTL_BUFFER_SECONDS
     )
     async with docket.redis() as redis:
-        await redis.set(redis_key, task_key, ex=ttl_seconds)
+        await redis.set(task_meta_key, task_key, ex=ttl_seconds)
         await redis.set(created_at_key, created_at, ex=ttl_seconds)
 
     # Send notifications/tasks/created per SEP-1686 (mandatory)

fastmcp/server/tasks/protocol.py

@@ -77,10 +77,12 @@ async def tasks_get_handler(server: FastMCP, params: dict[str, Any]) -> GetTaskR
             )
 
         # Look up full task key and creation timestamp from Redis
-        redis_key = f"fastmcp:task:{session_id}:{client_task_id}"
-        created_at_key = f"fastmcp:task:{session_id}:{client_task_id}:created_at"
+        task_meta_key = docket.key(f"fastmcp:task:{session_id}:{client_task_id}")
+        created_at_key = docket.key(
+            f"fastmcp:task:{session_id}:{client_task_id}:created_at"
+        )
         async with docket.redis() as redis:
-            task_key_bytes = await redis.get(redis_key)
+            task_key_bytes = await redis.get(task_meta_key)
             created_at_bytes = await redis.get(created_at_key)
 
         task_key = None if task_key_bytes is None else task_key_bytes.decode("utf-8")
@@ -176,9 +178,9 @@ async def tasks_result_handler(server: FastMCP, params: dict[str, Any]) -> Any:
             )
 
         # Look up full task key from Redis
-        redis_key = f"fastmcp:task:{session_id}:{client_task_id}"
+        task_meta_key = docket.key(f"fastmcp:task:{session_id}:{client_task_id}")
         async with docket.redis() as redis:
-            task_key_bytes = await redis.get(redis_key)
+            task_key_bytes = await redis.get(task_meta_key)
 
         task_key = None if task_key_bytes is None else task_key_bytes.decode("utf-8")
 
@@ -309,10 +311,12 @@ async def tasks_cancel_handler(
             )
 
         # Look up full task key and creation timestamp from Redis
-        redis_key = f"fastmcp:task:{session_id}:{client_task_id}"
-        created_at_key = f"fastmcp:task:{session_id}:{client_task_id}:created_at"
+        task_meta_key = docket.key(f"fastmcp:task:{session_id}:{client_task_id}")
+        created_at_key = docket.key(
+            f"fastmcp:task:{session_id}:{client_task_id}:created_at"
+        )
         async with docket.redis() as redis:
-            task_key_bytes = await redis.get(redis_key)
+            task_key_bytes = await redis.get(task_meta_key)
             created_at_bytes = await redis.get(created_at_key)
 
         task_key = None if task_key_bytes is None else task_key_bytes.decode("utf-8")

fastmcp/server/tasks/subscriptions.py

@@ -70,7 +70,7 @@ async def subscribe_to_task_updates(
                 )
 
     except Exception as e:
-        logger.warning(f"Subscription task failed for {task_id}: {e}", exc_info=True)
+        logger.error(f"subscribe_to_task_updates failed for {task_id}: {e}")
 
 
 async def _send_status_notification(
@@ -101,8 +101,7 @@ async def _send_status_notification(
     key_parts = parse_task_key(task_key)
     session_id = key_parts["session_id"]
 
-    # Retrieve createdAt timestamp from Redis
-    created_at_key = f"fastmcp:task:{session_id}:{task_id}:created_at"
+    created_at_key = docket.key(f"fastmcp:task:{session_id}:{task_id}:created_at")
     async with docket.redis() as redis:
         created_at_bytes = await redis.get(created_at_key)
 
@@ -175,8 +174,7 @@ async def _send_progress_notification(
     key_parts = parse_task_key(task_key)
     session_id = key_parts["session_id"]
 
-    # Retrieve createdAt timestamp from Redis
-    created_at_key = f"fastmcp:task:{session_id}:{task_id}:created_at"
+    created_at_key = docket.key(f"fastmcp:task:{session_id}:{task_id}:created_at")
     async with docket.redis() as redis:
         created_at_bytes = await redis.get(created_at_key)
 

fastmcp/settings.py

@@ -392,6 +392,21 @@ class Settings(BaseSettings):
         ),
     ] = True
 
+    check_for_updates: Annotated[
+        Literal["stable", "prerelease", "off"],
+        Field(
+            description=inspect.cleandoc(
+                """
+                Controls update checking when displaying the CLI banner.
+                - "stable": Check for stable releases only (default)
+                - "prerelease": Also check for pre-release versions (alpha, beta, rc)
+                - "off": Disable update checking entirely
+                Set via FASTMCP_CHECK_FOR_UPDATES environment variable.
+                """
+            ),
+        ),
+    ] = "stable"
+
     @property
     def server_auth_class(self) -> AuthProvider | None:
         from fastmcp.utilities.types import get_cached_typeadapter

fastmcp/tools/tool.py

@@ -32,7 +32,7 @@ import fastmcp
 from fastmcp.server.dependencies import get_context, without_injected_parameters
 from fastmcp.server.tasks.config import TaskConfig
 from fastmcp.utilities.components import FastMCPComponent
-from fastmcp.utilities.json_schema import compress_schema
+from fastmcp.utilities.json_schema import compress_schema, resolve_root_ref
 from fastmcp.utilities.logging import get_logger
 from fastmcp.utilities.types import (
     Audio,
@@ -559,6 +559,10 @@ class ParsedFunction:
 
                 output_schema = compress_schema(output_schema, prune_titles=True)
 
+                # Resolve root-level $ref to meet MCP spec requirement for type: object
+                # Self-referential Pydantic models generate schemas with $ref at root
+                output_schema = resolve_root_ref(output_schema)
+
             except PydanticSchemaGenerationError as e:
                 if "_UnserializableType" not in str(e):
                     logger.debug(f"Unable to generate schema for type {output_type!r}")

fastmcp/tools/tool_manager.py

@@ -8,7 +8,7 @@ from mcp.types import ToolAnnotations
 from pydantic import ValidationError
 
 from fastmcp import settings
-from fastmcp.exceptions import NotFoundError, ToolError
+from fastmcp.exceptions import FastMCPError, NotFoundError, ToolError
 from fastmcp.settings import DuplicateBehavior
 from fastmcp.tools.tool import Tool, ToolResult
 from fastmcp.tools.tool_transform import (
@@ -158,12 +158,10 @@ class ToolManager:
         tool = await self.get_tool(key)
         try:
             return await tool.run(arguments)
-        except ValidationError as e:
-            logger.exception(f"Error validating tool {key!r}: {e}")
-            raise e
-        except ToolError as e:
-            logger.exception(f"Error calling tool {key!r}")
-            raise e
+        except FastMCPError:
+            raise
+        except ValidationError:
+            raise
         except Exception as e:
             logger.exception(f"Error calling tool {key!r}")
             if self.mask_error_details:

fastmcp/utilities/cli.py

@@ -3,7 +3,7 @@ from __future__ import annotations
 import json
 import os
 from pathlib import Path
-from typing import TYPE_CHECKING, Any, Literal
+from typing import TYPE_CHECKING, Any
 
 from pydantic import ValidationError
 from rich.align import Align
@@ -17,6 +17,7 @@ from fastmcp.utilities.logging import get_logger
 from fastmcp.utilities.mcp_server_config import MCPServerConfig
 from fastmcp.utilities.mcp_server_config.v1.sources.filesystem import FileSystemSource
 from fastmcp.utilities.types import get_cached_typeadapter
+from fastmcp.utilities.version_check import check_for_newer_version
 
 if TYPE_CHECKING:
     from fastmcp import FastMCP
@@ -197,23 +198,11 @@ LOGO_ASCII_4 = (
 )
 
 
-def log_server_banner(
-    server: FastMCP[Any],
-    transport: Literal["stdio", "http", "sse", "streamable-http"],
-    *,
-    host: str | None = None,
-    port: int | None = None,
-    path: str | None = None,
-) -> None:
-    """Creates and logs a formatted banner with server information and logo.
+def log_server_banner(server: FastMCP[Any]) -> None:
+    """Creates and logs a formatted banner with server information and logo."""
 
-    Args:
-        transport: The transport protocol being used
-        server_name: Optional server name to display
-        host: Host address (for HTTP transports)
-        port: Port number (for HTTP transports)
-        path: Server path (for HTTP transports)
-    """
+    # Check for updates (non-blocking, fails silently)
+    newer_version = check_for_newer_version()
 
     # Create the logo text
     # Use Text with no_wrap and markup disabled to preserve ANSI escape codes
@@ -228,39 +217,36 @@ def log_server_banner(
     info_table.add_column(style="cyan", justify="left")  # Label column
     info_table.add_column(style="dim", justify="left")  # Value column
 
-    match transport:
-        case "http" | "streamable-http":
-            display_transport = "HTTP"
-        case "sse":
-            display_transport = "SSE"
-        case "stdio":
-            display_transport = "STDIO"
-
-    info_table.add_row("🖥", "Server name:", Text(server.name + "\n", style="bold blue"))
-    info_table.add_row("📦", "Transport:", display_transport)
-
-    # Show connection info based on transport
-    if transport in ("http", "streamable-http", "sse") and host and port:
-        server_url = f"http://{host}:{port}"
-        if path:
-            server_url += f"/{path.lstrip('/')}"
-        info_table.add_row("🔗", "Server URL:", server_url)
-
-    # Add documentation link
-    info_table.add_row("", "", "")
-    info_table.add_row("📚", "Docs:", "https://gofastmcp.com")
-    info_table.add_row("🚀", "Hosting:", "https://fastmcp.cloud")
+    info_table.add_row("🖥", "Server:", Text(server.name, style="dim"))
+    info_table.add_row("🚀", "Deploy free:", "https://fastmcp.cloud")
 
     # Create panel with logo, title, and information using Group
+    docs_url = Text("https://gofastmcp.com", style="dim")
     panel_content = Group(
+        "",
         Align.center(logo_text),
         "",
-        Align.center(title_text),
         "",
+        Align.center(title_text),
+        Align.center(docs_url),
         "",
         Align.center(info_table),
     )
 
+    # v3 notice banner (shown below main panel)
+    v3_line1 = Text("✨ FastMCP 3.0 is coming!", style="bold")
+    v3_line2 = Text.assemble(
+        ("Pin ", "dim"),
+        ("`fastmcp < 3`", "dim bold"),
+        (" in production, then upgrade when you're ready.", "dim"),
+    )
+    v3_notice = Panel(
+        Group(Align.center(v3_line1), Align.center(v3_line2)),
+        border_style="blue",
+        padding=(0, 2),
+        width=80,
+    )
+
     panel = Panel(
         panel_content,
         border_style="dim",
@@ -270,5 +256,26 @@ def log_server_banner(
     )
 
     console = Console(stderr=True)
-    # Center the panel itself
-    console.print(Group("\n", Align.center(panel), "\n"))
+
+    # Build output elements
+    output_elements: list[Align | Panel | str] = ["\n", Align.center(panel)]
+    output_elements.append(Align.center(v3_notice))
+
+    # Add update notice if a newer version is available (shown last for visibility)
+    if newer_version:
+        update_line1 = Text.assemble(
+            ("🎉 Update available: ", "bold"),
+            (newer_version, "bold green"),
+        )
+        update_line2 = Text("Run: pip install --upgrade fastmcp", style="dim")
+        update_notice = Panel(
+            Group(Align.center(update_line1), Align.center(update_line2)),
+            border_style="blue",
+            padding=(0, 2),
+            width=80,
+        )
+        output_elements.append(Align.center(update_notice))
+
+    output_elements.append("\n")
+
+    console.print(Group(*output_elements))

fastmcp/utilities/json_schema.py

@@ -1,6 +1,46 @@
 from __future__ import annotations
 
 from collections import defaultdict
+from typing import Any
+
+
+def resolve_root_ref(schema: dict[str, Any]) -> dict[str, Any]:
+    """Resolve $ref at root level to meet MCP spec requirements.
+
+    MCP specification requires outputSchema to have "type": "object" at the root level.
+    When Pydantic generates schemas for self-referential models, it uses $ref at the
+    root level pointing to $defs. This function resolves such references by inlining
+    the referenced definition while preserving $defs for nested references.
+
+    Args:
+        schema: JSON schema dict that may have $ref at root level
+
+    Returns:
+        A new schema dict with root-level $ref resolved, or the original schema
+        if no resolution is needed
+
+    Example:
+        >>> schema = {
+        ...     "$defs": {"Node": {"type": "object", "properties": {...}}},
+        ...     "$ref": "#/$defs/Node"
+        ... }
+        >>> resolved = resolve_root_ref(schema)
+        >>> # Result: {"type": "object", "properties": {...}, "$defs": {...}}
+    """
+    # Only resolve if we have $ref at root level with $defs but no explicit type
+    if "$ref" in schema and "$defs" in schema and "type" not in schema:
+        ref = schema["$ref"]
+        # Only handle local $defs references
+        if isinstance(ref, str) and ref.startswith("#/$defs/"):
+            def_name = ref.split("/")[-1]
+            defs = schema["$defs"]
+            if def_name in defs:
+                # Create a new schema by copying the referenced definition
+                resolved = dict(defs[def_name])
+                # Preserve $defs for nested references (other fields may still use them)
+                resolved["$defs"] = defs
+                return resolved
+    return schema
 
 
 def _prune_param(schema: dict, param: str) -> dict: