fastmcp 2.11.3__py3-none-any.whl → 2.12.0rc1__py3-none-any.whl

fastmcp/server/server.py

@@ -3,7 +3,9 @@
 from __future__ import annotations
 
 import inspect
+import json
 import re
+import secrets
 import warnings
 from collections.abc import AsyncIterator, Awaitable, Callable
 from contextlib import (
@@ -69,6 +71,7 @@ from fastmcp.utilities.types import NotSet, NotSetT
 
 if TYPE_CHECKING:
     from fastmcp.client import Client
+    from fastmcp.client.sampling import ServerSamplingHandler
     from fastmcp.client.transports import ClientTransport, ClientTransportT
     from fastmcp.experimental.server.openapi import FastMCPOpenAPI as FastMCPOpenAPINew
     from fastmcp.experimental.server.openapi.routing import (
@@ -166,12 +169,15 @@ class FastMCP(Generic[LifespanResultT]):
         streamable_http_path: str | None = None,
         json_response: bool | None = None,
         stateless_http: bool | None = None,
+        sampling_handler: ServerSamplingHandler[LifespanResultT] | None = None,
+        sampling_handler_behavior: Literal["always", "fallback"] | None = None,
     ):
         self.resource_prefix_format: Literal["protocol", "path"] = (
             resource_prefix_format or fastmcp.settings.resource_prefix_format
         )
 
         self._additional_http_routes: list[BaseRoute] = []
+        self._mounted_servers: list[MountedServer] = []
         self._tool_manager = ToolManager(
             duplicate_behavior=on_duplicate_tools,
             mask_error_details=mask_error_details,
@@ -192,8 +198,9 @@ class FastMCP(Generic[LifespanResultT]):
             lifespan = default_lifespan
         else:
             self._has_lifespan = True
+        # Generate random ID if no name provided
         self._mcp_server = LowLevelServer[LifespanResultT](
-            name=name or "FastMCP",
+            name=name or self.generate_name(),
             version=version,
             instructions=instructions,
             lifespan=_lifespan_wrapper(self, lifespan),
@@ -221,7 +228,27 @@ class FastMCP(Generic[LifespanResultT]):
 
         # Set up MCP protocol handlers
         self._setup_handlers()
-        self.dependencies = dependencies or fastmcp.settings.server_dependencies
+
+        # Handle dependencies with deprecation warning
+        # TODO: Remove dependencies parameter (deprecated in v2.11.4)
+        if dependencies is not None:
+            import warnings
+
+            warnings.warn(
+                "The 'dependencies' parameter is deprecated as of FastMCP 2.11.4 and will be removed in a future version. "
+                "Please specify dependencies in a fastmcp.json configuration file instead:\n"
+                '{\n  "entrypoint": "your_server.py",\n  "environment": {\n    "dependencies": '
+                f"{json.dumps(dependencies)}\n  }}\n}}\n"
+                "See https://gofastmcp.com/docs/deployment/server-configuration for more information.",
+                DeprecationWarning,
+                stacklevel=2,
+            )
+        self.dependencies = (
+            dependencies or fastmcp.settings.server_dependencies
+        )  # TODO: Remove (deprecated in v2.11.4)
+
+        self.sampling_handler = sampling_handler
+        self.sampling_handler_behavior = sampling_handler_behavior or "fallback"
 
         self.include_fastmcp_meta = (
             include_fastmcp_meta
@@ -444,7 +471,7 @@ class FastMCP(Generic[LifespanResultT]):
         Request and returns a Response.
 
         Args:
-            path: URL path for the route (e.g., "/oauth/callback")
+            path: URL path for the route (e.g., "/auth/callback")
             methods: List of HTTP methods to support (e.g., ["GET", "POST"])
             name: Optional name for the route (to reference this route with
                 Starlette's reverse URL lookup feature)
@@ -475,8 +502,26 @@ class FastMCP(Generic[LifespanResultT]):
 
         return decorator
 
+    def _get_additional_http_routes(self) -> list[BaseRoute]:
+        """Get all additional HTTP routes including from mounted servers.
+
+        Returns a list of all custom HTTP routes from this server and
+        recursively from all mounted servers.
+
+        Returns:
+            List of Starlette BaseRoute objects
+        """
+        routes = list(self._additional_http_routes)
+
+        # Recursively get routes from mounted servers
+        for mounted_server in self._mounted_servers:
+            mounted_routes = mounted_server.server._get_additional_http_routes()
+            routes.extend(mounted_routes)
+
+        return routes
+
     async def _mcp_list_tools(self) -> list[MCPTool]:
-        logger.debug("Handler called: list_tools")
+        logger.debug(f"[{self.name}] Handler called: list_tools")
 
         async with fastmcp.server.context.Context(fastmcp=self):
             tools = await self._list_tools()
@@ -520,7 +565,7 @@ class FastMCP(Generic[LifespanResultT]):
             return await self._apply_middleware(mw_context, _handler)
 
     async def _mcp_list_resources(self) -> list[MCPResource]:
-        logger.debug("Handler called: list_resources")
+        logger.debug(f"[{self.name}] Handler called: list_resources")
 
         async with fastmcp.server.context.Context(fastmcp=self):
             resources = await self._list_resources()
@@ -565,7 +610,7 @@ class FastMCP(Generic[LifespanResultT]):
             return await self._apply_middleware(mw_context, _handler)
 
     async def _mcp_list_resource_templates(self) -> list[MCPResourceTemplate]:
-        logger.debug("Handler called: list_resource_templates")
+        logger.debug(f"[{self.name}] Handler called: list_resource_templates")
 
         async with fastmcp.server.context.Context(fastmcp=self):
             templates = await self._list_resource_templates()
@@ -610,7 +655,7 @@ class FastMCP(Generic[LifespanResultT]):
             return await self._apply_middleware(mw_context, _handler)
 
     async def _mcp_list_prompts(self) -> list[MCPPrompt]:
-        logger.debug("Handler called: list_prompts")
+        logger.debug(f"[{self.name}] Handler called: list_prompts")
 
         async with fastmcp.server.context.Context(fastmcp=self):
             prompts = await self._list_prompts()
@@ -669,7 +714,9 @@ class FastMCP(Generic[LifespanResultT]):
         Returns:
             List of MCP Content objects containing the tool results
         """
-        logger.debug("Handler called: call_tool %s with %s", key, arguments)
+        logger.debug(
+            f"[{self.name}] Handler called: call_tool %s with %s", key, arguments
+        )
 
         async with fastmcp.server.context.Context(fastmcp=self):
             try:
@@ -711,7 +758,7 @@ class FastMCP(Generic[LifespanResultT]):
 
         Delegates to _read_resource, which should be overridden by FastMCP subclasses.
         """
-        logger.debug("Handler called: read_resource %s", uri)
+        logger.debug(f"[{self.name}] Handler called: read_resource %s", uri)
 
         async with fastmcp.server.context.Context(fastmcp=self):
             try:
@@ -766,7 +813,9 @@ class FastMCP(Generic[LifespanResultT]):
 
         Delegates to _get_prompt, which should be overridden by FastMCP subclasses.
         """
-        logger.debug("Handler called: get_prompt %s with %s", name, arguments)
+        logger.debug(
+            f"[{self.name}] Handler called: get_prompt %s with %s", name, arguments
+        )
 
         async with fastmcp.server.context.Context(fastmcp=self):
             try:
@@ -984,7 +1033,7 @@ class FastMCP(Generic[LifespanResultT]):
                 description=description,
                 tags=tags,
                 output_schema=output_schema,
-                annotations=annotations,
+                annotations=cast(ToolAnnotations | None, annotations),
                 exclude_args=exclude_args,
                 meta=meta,
                 serializer=self._tool_serializer,
@@ -1214,7 +1263,7 @@ class FastMCP(Generic[LifespanResultT]):
                     mime_type=mime_type,
                     tags=tags,
                     enabled=enabled,
-                    annotations=annotations,
+                    annotations=cast(Annotations | None, annotations),
                     meta=meta,
                 )
                 self.add_template(template)
@@ -1229,7 +1278,7 @@ class FastMCP(Generic[LifespanResultT]):
                     mime_type=mime_type,
                     tags=tags,
                     enabled=enabled,
-                    annotations=annotations,
+                    annotations=cast(Annotations | None, annotations),
                     meta=meta,
                 )
                 self.add_resource(resource)
@@ -1796,6 +1845,7 @@ class FastMCP(Generic[LifespanResultT]):
             server=server,
             resource_prefix_format=self.resource_prefix_format,
         )
+        self._mounted_servers.append(mounted_server)
         self._tool_manager.mount(mounted_server)
         self._resource_manager.mount(mounted_server)
         self._prompt_manager.mount(mounted_server)
@@ -1922,9 +1972,11 @@ class FastMCP(Generic[LifespanResultT]):
             self._prompt_manager.add_prompt(prompt)
 
         if prefix:
-            logger.debug(f"Imported server {server.name} with prefix '{prefix}'")
+            logger.debug(
+                f"[{self.name}] Imported server {server.name} with prefix '{prefix}'"
+            )
         else:
-            logger.debug(f"Imported server {server.name}")
+            logger.debug(f"[{self.name}] Imported server {server.name}")
 
     @classmethod
     def from_openapi(
@@ -2151,6 +2203,15 @@ class FastMCP(Generic[LifespanResultT]):
 
         return True
 
+    @classmethod
+    def generate_name(cls, name: str | None = None) -> str:
+        class_name = cls.__name__
+
+        if name is None:
+            return f"{class_name}-{secrets.token_hex(2)}"
+        else:
+            return f"{class_name}-{name}-{secrets.token_hex(2)}"
+
 
 @dataclass
 class MountedServer:

fastmcp/settings.py

@@ -146,6 +146,7 @@ class Settings(BaseSettings):
 
     test_mode: bool = False
 
+    log_enabled: bool = True
     log_level: LOG_LEVEL = "INFO"
 
     @field_validator("log_level", mode="before")
@@ -314,12 +315,26 @@ class Settings(BaseSettings):
                 Whether to include FastMCP meta in the server's MCP responses.
                 If True, a `_fastmcp` key will be added to the `meta` field of
                 all MCP component responses. This key will contain a dict of
-                various FastMCP-specific metadata, such as tags. 
+                various FastMCP-specific metadata, such as tags.
                 """
             ),
         ),
     ] = True
 
+    mounted_components_raise_on_load_error: Annotated[
+        bool,
+        Field(
+            default=False,
+            description=inspect.cleandoc(
+                """
+                If True, errors encountered when loading mounted components (tools, resources, prompts)
+                will be raised instead of logged as warnings. This is useful for debugging
+                but will interrupt normal operation.
+                """
+            ),
+        ),
+    ] = False
+
 
 def __getattr__(name: str):
     """

fastmcp/tools/tool.py

@@ -1,6 +1,7 @@
 from __future__ import annotations
 
 import inspect
+import warnings
 from collections.abc import Callable
 from dataclasses import dataclass
 from typing import (
@@ -8,6 +9,7 @@ from typing import (
     Annotated,
     Any,
     Generic,
+    Literal,
     TypeVar,
     get_type_hints,
 )
@@ -18,6 +20,7 @@ from mcp.types import ContentBlock, TextContent, ToolAnnotations
 from mcp.types import Tool as MCPTool
 from pydantic import Field, PydanticSchemaGenerationError
 
+import fastmcp
 from fastmcp.server.dependencies import get_context
 from fastmcp.utilities.components import FastMCPComponent
 from fastmcp.utilities.json_schema import compress_schema
@@ -162,7 +165,7 @@ class Tool(FastMCPComponent):
         tags: set[str] | None = None,
         annotations: ToolAnnotations | None = None,
         exclude_args: list[str] | None = None,
-        output_schema: dict[str, Any] | None | NotSetT = NotSet,
+        output_schema: dict[str, Any] | None | NotSetT | Literal[False] = NotSet,
         serializer: Callable[[Any], str] | None = None,
         meta: dict[str, Any] | None = None,
         enabled: bool | None = None,
@@ -204,7 +207,7 @@ class Tool(FastMCPComponent):
         description: str | None | NotSetT = NotSet,
         tags: set[str] | None = None,
         annotations: ToolAnnotations | None | NotSetT = NotSet,
-        output_schema: dict[str, Any] | None | NotSetT = NotSet,
+        output_schema: dict[str, Any] | None | NotSetT | Literal[False] = NotSet,
         serializer: Callable[[Any], str] | None = None,
         meta: dict[str, Any] | None | NotSetT = NotSet,
         transform_args: dict[str, ArgTransform] | None = None,
@@ -242,7 +245,7 @@ class FunctionTool(Tool):
         tags: set[str] | None = None,
         annotations: ToolAnnotations | None = None,
         exclude_args: list[str] | None = None,
-        output_schema: dict[str, Any] | None | NotSetT = NotSet,
+        output_schema: dict[str, Any] | None | NotSetT | Literal[False] = NotSet,
         serializer: Callable[[Any], str] | None = None,
         meta: dict[str, Any] | None = None,
         enabled: bool | None = None,
@@ -255,16 +258,26 @@ class FunctionTool(Tool):
             raise ValueError("You must provide a name for lambda functions")
 
         if isinstance(output_schema, NotSetT):
-            output_schema = parsed_fn.output_schema
+            final_output_schema = parsed_fn.output_schema
         elif output_schema is False:
-            output_schema = None
+            # Handle False as deprecated synonym for None (deprecated in 2.11.4)
+            if fastmcp.settings.deprecation_warnings:
+                warnings.warn(
+                    "Passing output_schema=False is deprecated. Use output_schema=None instead.",
+                    DeprecationWarning,
+                    stacklevel=2,
+                )
+            final_output_schema = None
+        else:
+            # At this point output_schema is not NotSetT and not False, so it must be dict | None
+            final_output_schema = output_schema
         # Note: explicit schemas (dict) are used as-is without auto-wrapping
 
         # Validate that explicit schemas are object type for structured content
-        if output_schema is not None and isinstance(output_schema, dict):
-            if output_schema.get("type") != "object":
+        if final_output_schema is not None and isinstance(final_output_schema, dict):
+            if final_output_schema.get("type") != "object":
                 raise ValueError(
-                    f'Output schemas must have "type" set to "object" due to MCP spec limitations. Received: {output_schema!r}'
+                    f'Output schemas must have "type" set to "object" due to MCP spec limitations. Received: {final_output_schema!r}'
                 )
 
         return cls(
@@ -273,7 +286,7 @@ class FunctionTool(Tool):
             title=title,
             description=description or parsed_fn.description,
             parameters=parsed_fn.input_schema,
-            output_schema=output_schema,
+            output_schema=final_output_schema,
             annotations=annotations,
             tags=tags or set(),
             serializer=serializer,

fastmcp/tools/tool_manager.py

@@ -86,6 +86,8 @@ class ToolManager:
                 logger.warning(
                     f"Failed to get tools from server: {mounted.server.name!r}, mounted at: {mounted.prefix!r}: {e}"
                 )
+                if settings.mounted_components_raise_on_load_error:
+                    raise
                 continue
 
         # Finally, add local tools, which always take precedence

fastmcp/tools/tool_transform.py

@@ -1,10 +1,11 @@
 from __future__ import annotations
 
 import inspect
+import warnings
 from collections.abc import Callable
 from contextvars import ContextVar
 from dataclasses import dataclass
-from typing import Annotated, Any, Literal
+from typing import Annotated, Any, Literal, cast
 
 import pydantic_core
 from mcp.types import ToolAnnotations
@@ -12,6 +13,7 @@ from pydantic import ConfigDict
 from pydantic.fields import Field
 from pydantic.functional_validators import BeforeValidator
 
+import fastmcp
 from fastmcp.tools.tool import ParsedFunction, Tool, ToolResult, _convert_to_content
 from fastmcp.utilities.components import _convert_set_default_none
 from fastmcp.utilities.json_schema import compress_schema
@@ -27,7 +29,7 @@ logger = get_logger(__name__)
 
 
 # Context variable to store current transformed tool
-_current_tool: ContextVar[TransformedTool | None] = ContextVar(
+_current_tool: ContextVar[TransformedTool | None] = ContextVar(  # type: ignore[assignment]
     "_current_tool", default=None
 )
 
@@ -369,7 +371,7 @@ class TransformedTool(Tool):
         transform_fn: Callable[..., Any] | None = None,
         transform_args: dict[str, ArgTransform] | None = None,
         annotations: ToolAnnotations | None | NotSetT = NotSet,
-        output_schema: dict[str, Any] | None | NotSetT = NotSet,
+        output_schema: dict[str, Any] | None | NotSetT | Literal[False] = NotSet,
         serializer: Callable[[Any], str] | None | NotSetT = NotSet,
         meta: dict[str, Any] | None | NotSetT = NotSet,
         enabled: bool | None = None,
@@ -437,7 +439,7 @@ class TransformedTool(Tool):
             })
 
             # Disable structured outputs
-            Tool.from_tool(parent, output_schema=False)
+            Tool.from_tool(parent, output_schema=None)
 
             # Return ToolResult for full control
             async def custom_output(**kwargs) -> ToolResult:
@@ -471,8 +473,8 @@ class TransformedTool(Tool):
         if output_schema is NotSet:
             # Use smart fallback: try custom function, then parent
             if transform_fn is not None:
-                assert parsed_fn is not None
-                final_output_schema = parsed_fn.output_schema
+                # parsed fn is not none here
+                final_output_schema = cast(ParsedFunction, parsed_fn).output_schema
                 if final_output_schema is None:
                     # Check if function returns ToolResult - if so, don't fall back to parent
                     return_annotation = inspect.signature(
@@ -484,16 +486,25 @@ class TransformedTool(Tool):
                         final_output_schema = tool.output_schema
             else:
                 final_output_schema = tool.output_schema
+        elif output_schema is False:
+            # Handle False as deprecated synonym for None (deprecated in 2.11.4)
+            if fastmcp.settings.deprecation_warnings:
+                warnings.warn(
+                    "Passing output_schema=False is deprecated. Use output_schema=None instead.",
+                    DeprecationWarning,
+                    stacklevel=2,
+                )
+            final_output_schema = None
         else:
-            assert isinstance(output_schema, dict | None)
-            final_output_schema = output_schema
+            final_output_schema = cast(dict | None, output_schema)
 
         if transform_fn is None:
             # User wants pure transformation - use forwarding_fn as the main function
             final_fn = forwarding_fn
             final_schema = schema
         else:
-            assert parsed_fn is not None
+            # parsed fn is not none here
+            parsed_fn = cast(ParsedFunction, parsed_fn)
             # User provided custom function - merge schemas
             final_fn = transform_fn
 
@@ -830,12 +841,30 @@ class TransformedTool(Tool):
             if "default" in param_schema:
                 final_required.discard(param_name)
 
-        return {
+        # Merge $defs from both schemas, with override taking precedence
+        merged_defs = base_schema.get("$defs", {}).copy()
+        override_defs = override_schema.get("$defs", {})
+
+        for def_name, def_schema in override_defs.items():
+            if def_name in merged_defs:
+                base_def = merged_defs[def_name].copy()
+                base_def.update(def_schema)
+                merged_defs[def_name] = base_def
+            else:
+                merged_defs[def_name] = def_schema.copy()
+
+        result = {
             "type": "object",
             "properties": merged_props,
             "required": list(final_required),
         }
 
+        if merged_defs:
+            result["$defs"] = merged_defs
+            result = compress_schema(result, prune_defs=True)
+
+        return result
+
     @staticmethod
     def _function_has_kwargs(fn: Callable[..., Any]) -> bool:
         """Check if function accepts **kwargs.

fastmcp/utilities/auth.py

@@ -0,0 +1,34 @@
+"""Authentication utility helpers."""
+
+from __future__ import annotations
+
+import json
+from typing import Any
+
+
+def parse_scopes(value: Any) -> list[str] | None:
+    """Parse scopes from environment variables or settings values.
+
+    Accepts either a JSON array string, a comma- or space-separated string,
+    a list of strings, or ``None``. Returns a list of scopes or ``None`` if
+    no value is provided.
+    """
+    if value is None or value == "":
+        return None if value is None else []
+    if isinstance(value, list):
+        return [str(v).strip() for v in value if str(v).strip()]
+    if isinstance(value, str):
+        value = value.strip()
+        if not value:
+            return []
+        # Try JSON array first
+        if value.startswith("["):
+            try:
+                data = json.loads(value)
+                if isinstance(data, list):
+                    return [str(v).strip() for v in data if str(v).strip()]
+            except Exception:
+                pass
+        # Fallback to comma/space separated list
+        return [s.strip() for s in value.replace(",", " ").split() if s.strip()]
+    return value