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

fastmcp/server/middleware/logging.py

@@ -2,11 +2,20 @@
 
 import json
 import logging
+from collections.abc import Callable
+from logging import Logger
 from typing import Any
 
+import pydantic_core
+
 from .middleware import CallNext, Middleware, MiddlewareContext
 
 
+def default_serializer(data: Any) -> str:
+    """The default serializer for Payloads in the logging middleware."""
+    return pydantic_core.to_json(data, fallback=str).decode()
+
+
 class LoggingMiddleware(Middleware):
     """Middleware that provides comprehensive request and response logging.
 
@@ -33,6 +42,7 @@ class LoggingMiddleware(Middleware):
         include_payloads: bool = False,
         max_payload_length: int = 1000,
         methods: list[str] | None = None,
+        payload_serializer: Callable[[Any], str] | None = None,
     ):
         """Initialize logging middleware.
 
@@ -43,13 +53,14 @@ class LoggingMiddleware(Middleware):
             max_payload_length: Maximum length of payload to log (prevents huge logs)
             methods: List of methods to log. If None, logs all methods.
         """
-        self.logger = logger or logging.getLogger("fastmcp.requests")
-        self.log_level = log_level
-        self.include_payloads = include_payloads
-        self.max_payload_length = max_payload_length
-        self.methods = methods
-
-    def _format_message(self, context: MiddlewareContext) -> str:
+        self.logger: Logger = logger or logging.getLogger("fastmcp.requests")
+        self.log_level: int = log_level
+        self.include_payloads: bool = include_payloads
+        self.max_payload_length: int = max_payload_length
+        self.methods: list[str] | None = methods
+        self.payload_serializer: Callable[[Any], str] | None = payload_serializer
+
+    def _format_message(self, context: MiddlewareContext[Any]) -> str:
         """Format a message for logging."""
         parts = [
             f"source={context.source}",
@@ -57,18 +68,29 @@ class LoggingMiddleware(Middleware):
             f"method={context.method or 'unknown'}",
         ]
 
-        if self.include_payloads and hasattr(context.message, "__dict__"):
-            try:
-                payload = json.dumps(context.message.__dict__, default=str)
-                if len(payload) > self.max_payload_length:
-                    payload = payload[: self.max_payload_length] + "..."
-                parts.append(f"payload={payload}")
-            except (TypeError, ValueError):
-                parts.append("payload=<non-serializable>")
+        if self.include_payloads:
+            payload: str
 
+            if not self.payload_serializer:
+                payload = default_serializer(context.message)
+            else:
+                try:
+                    payload = self.payload_serializer(context.message)
+                except Exception as e:
+                    self.logger.warning(
+                        f"Failed {e} to serialize payload: {context.type} {context.method} {context.source}."
+                    )
+                    payload = default_serializer(context.message)
+
+            if len(payload) > self.max_payload_length:
+                payload = payload[: self.max_payload_length] + "..."
+
+            parts.append(f"payload={payload}")
         return " ".join(parts)
 
-    async def on_message(self, context: MiddlewareContext, call_next: CallNext) -> Any:
+    async def on_message(
+        self, context: MiddlewareContext[Any], call_next: CallNext[Any, Any]
+    ) -> Any:
         """Log all messages."""
         message_info = self._format_message(context)
         if self.methods and context.method not in self.methods:
@@ -111,6 +133,7 @@ class StructuredLoggingMiddleware(Middleware):
         log_level: int = logging.INFO,
         include_payloads: bool = False,
         methods: list[str] | None = None,
+        payload_serializer: Callable[[Any], str] | None = None,
     ):
         """Initialize structured logging middleware.
 
@@ -119,15 +142,18 @@ class StructuredLoggingMiddleware(Middleware):
             log_level: Log level for messages (default: INFO)
             include_payloads: Whether to include message payloads in logs
             methods: List of methods to log. If None, logs all methods.
+            serializer: Callable that converts objects to a JSON string for the
+                payload. If not provided, uses FastMCP's default tool serializer.
         """
-        self.logger = logger or logging.getLogger("fastmcp.structured")
-        self.log_level = log_level
-        self.include_payloads = include_payloads
-        self.methods = methods
+        self.logger: Logger = logger or logging.getLogger("fastmcp.structured")
+        self.log_level: int = log_level
+        self.include_payloads: bool = include_payloads
+        self.methods: list[str] | None = methods
+        self.payload_serializer: Callable[[Any], str] | None = payload_serializer
 
     def _create_log_entry(
-        self, context: MiddlewareContext, event: str, **extra_fields
-    ) -> dict:
+        self, context: MiddlewareContext[Any], event: str, **extra_fields: Any
+    ) -> dict[str, Any]:
         """Create a structured log entry."""
         entry = {
             "event": event,
@@ -138,15 +164,27 @@ class StructuredLoggingMiddleware(Middleware):
             **extra_fields,
         }
 
-        if self.include_payloads and hasattr(context.message, "__dict__"):
-            try:
-                entry["payload"] = context.message.__dict__
-            except (TypeError, ValueError):
-                entry["payload"] = "<non-serializable>"
+        if self.include_payloads:
+            payload: str
+
+            if not self.payload_serializer:
+                payload = default_serializer(context.message)
+            else:
+                try:
+                    payload = self.payload_serializer(context.message)
+                except Exception as e:
+                    self.logger.warning(
+                        f"Failed {str(e)} to serialize payload: {context.type} {context.method} {context.source}."
+                    )
+                    payload = default_serializer(context.message)
+
+            entry["payload"] = payload
 
         return entry
 
-    async def on_message(self, context: MiddlewareContext, call_next: CallNext) -> Any:
+    async def on_message(
+        self, context: MiddlewareContext[Any], call_next: CallNext[Any, Any]
+    ) -> Any:
         """Log structured message information."""
         start_entry = self._create_log_entry(context, "request_start")
         if self.methods and context.method not in self.methods:

fastmcp/server/proxy.py

@@ -546,6 +546,8 @@ class ProxyClient(Client[ClientTransportT]):
         | str,
         **kwargs,
     ):
+        if "name" not in kwargs:
+            kwargs["name"] = self.generate_name()
         if "roots" not in kwargs:
             kwargs["roots"] = default_proxy_roots_handler
         if "sampling_handler" not in kwargs:

fastmcp/server/sampling/handler.py

@@ -0,0 +1,19 @@
+from collections.abc import Awaitable, Callable
+from typing import TypeAlias
+
+from mcp import CreateMessageResult
+from mcp.server.session import ServerSession
+from mcp.shared.context import LifespanContextT, RequestContext
+from mcp.types import CreateMessageRequestParams as SamplingParams
+from mcp.types import (
+    SamplingMessage,
+)
+
+ServerSamplingHandler: TypeAlias = Callable[
+    [
+        list[SamplingMessage],
+        SamplingParams,
+        RequestContext[ServerSession, LifespanContextT],
+    ],
+    str | CreateMessageResult | Awaitable[str | CreateMessageResult],
+]

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 (
@@ -49,7 +51,7 @@ from fastmcp.prompts import Prompt, PromptManager
 from fastmcp.prompts.prompt import FunctionPrompt
 from fastmcp.resources import Resource, ResourceManager
 from fastmcp.resources.template import ResourceTemplate
-from fastmcp.server.auth.auth import AuthProvider
+from fastmcp.server.auth import AuthProvider
 from fastmcp.server.auth.registry import get_registered_provider
 from fastmcp.server.http import (
     StarletteWithLifespan,
@@ -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)
@@ -1891,7 +1941,7 @@ class FastMCP(Generic[LifespanResultT]):
         # Import tools from the server
         for key, tool in (await server.get_tools()).items():
             if prefix:
-                tool = tool.with_key(f"{prefix}_{key}")
+                tool = tool.model_copy(key=f"{prefix}_{key}")
             self._tool_manager.add_tool(tool)
 
         # Import resources and templates from the server
@@ -1900,7 +1950,9 @@ class FastMCP(Generic[LifespanResultT]):
                 resource_key = add_resource_prefix(
                     key, prefix, self.resource_prefix_format
                 )
-                resource = resource.with_key(resource_key)
+                resource = resource.model_copy(
+                    update={"name": f"{prefix}_{resource.name}"}, key=resource_key
+                )
             self._resource_manager.add_resource(resource)
 
         for key, template in (await server.get_resource_templates()).items():
@@ -1908,19 +1960,23 @@ class FastMCP(Generic[LifespanResultT]):
                 template_key = add_resource_prefix(
                     key, prefix, self.resource_prefix_format
                 )
-                template = template.with_key(template_key)
+                template = template.model_copy(
+                    update={"name": f"{prefix}_{template.name}"}, key=template_key
+                )
             self._resource_manager.add_template(template)
 
         # Import prompts from the server
         for key, prompt in (await server.get_prompts()).items():
             if prefix:
-                prompt = prompt.with_key(f"{prefix}_{key}")
+                prompt = prompt.model_copy(key=f"{prefix}_{key}")
             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(
@@ -2147,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")
@@ -222,9 +223,9 @@ class Settings(BaseSettings):
     # HTTP settings
     host: str = "127.0.0.1"
     port: int = 8000
-    sse_path: str = "/sse/"
+    sse_path: str = "/sse"
     message_path: str = "/messages/"
-    streamable_http_path: str = "/mcp/"
+    streamable_http_path: str = "/mcp"
     debug: bool = False
 
     # error handling
@@ -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 (
@@ -19,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
@@ -199,17 +201,18 @@ class Tool(FastMCPComponent):
     def from_tool(
         cls,
         tool: Tool,
-        transform_fn: Callable[..., Any] | None = None,
+        *,
         name: str | None = None,
         title: str | None | NotSetT = NotSet,
-        transform_args: dict[str, ArgTransform] | None = None,
         description: str | None | NotSetT = NotSet,
         tags: set[str] | None = None,
-        annotations: ToolAnnotations | None = None,
-        output_schema: dict[str, Any] | None | Literal[False] = None,
+        annotations: ToolAnnotations | 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,
         enabled: bool | None = None,
+        transform_fn: Callable[..., Any] | None = None,
     ) -> TransformedTool:
         from fastmcp.tools.tool_transform import TransformedTool
 
@@ -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

@@ -75,7 +75,9 @@ class ToolManager:
                 child_dict = {t.key: t for t in child_results}
                 if mounted.prefix:
                     for tool in child_dict.values():
-                        prefixed_tool = tool.with_key(f"{mounted.prefix}_{tool.key}")
+                        prefixed_tool = tool.model_copy(
+                            key=f"{mounted.prefix}_{tool.key}"
+                        )
                         all_tools[prefixed_tool.key] = prefixed_tool
                 else:
                     all_tools.update(child_dict)
@@ -84,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