fastmcp 2.12.1__py3-none-any.whl → 2.13.2__py3-none-any.whl

fastmcp/settings.py

@@ -1,10 +1,12 @@
 from __future__ import annotations as _annotations
 
 import inspect
+import os
 import warnings
 from pathlib import Path
-from typing import Annotated, Any, Literal
+from typing import TYPE_CHECKING, Annotated, Any, Literal
 
+from platformdirs import user_data_dir
 from pydantic import Field, ImportString, field_validator
 from pydantic.fields import FieldInfo
 from pydantic_settings import (
@@ -19,10 +21,17 @@ from fastmcp.utilities.logging import get_logger
 
 logger = get_logger(__name__)
 
+ENV_FILE = os.getenv("FASTMCP_ENV_FILE", ".env")
+
 LOG_LEVEL = Literal["DEBUG", "INFO", "WARNING", "ERROR", "CRITICAL"]
 
 DuplicateBehavior = Literal["warn", "error", "replace", "ignore"]
 
+TEN_MB_IN_BYTES = 1024 * 1024 * 10
+
+if TYPE_CHECKING:
+    from fastmcp.server.auth.auth import AuthProvider
+
 
 class ExtendedEnvSettingsSource(EnvSettingsSource):
     """
@@ -79,7 +88,7 @@ class Settings(BaseSettings):
 
     model_config = ExtendedSettingsConfigDict(
         env_prefixes=["FASTMCP_", "FASTMCP_SERVER_"],
-        env_file=".env",
+        env_file=ENV_FILE,
         extra="ignore",
         env_nested_delimiter="__",
         nested_model_default_partial_update=True,
@@ -142,7 +151,7 @@ class Settings(BaseSettings):
         )
         return self
 
-    home: Path = Path.home() / ".fastmcp"
+    home: Path = Path(user_data_dir("fastmcp", appauthor=False))
 
     test_mode: bool = False
 
@@ -186,7 +195,6 @@ class Settings(BaseSettings):
     client_raise_first_exceptiongroup_error: Annotated[
         bool,
         Field(
-            default=True,
             description=inspect.cleandoc(
                 """
                 Many MCP components operate in anyio taskgroups, and raise
@@ -202,7 +210,6 @@ class Settings(BaseSettings):
     resource_prefix_format: Annotated[
         Literal["protocol", "path"],
         Field(
-            default="path",
             description=inspect.cleandoc(
                 """
                 When perfixing a resource URI, either use path formatting (resource://prefix/path)
@@ -232,7 +239,6 @@ class Settings(BaseSettings):
     mask_error_details: Annotated[
         bool,
         Field(
-            default=False,
             description=inspect.cleandoc(
                 """
                 If True, error details from user-supplied functions (tool, resource, prompt)
@@ -245,6 +251,22 @@ class Settings(BaseSettings):
         ),
     ] = False
 
+    strict_input_validation: Annotated[
+        bool,
+        Field(
+            description=inspect.cleandoc(
+                """
+                If True, tool inputs are strictly validated against the input
+                JSON schema. For example, providing the string \"10\" to an
+                integer field will raise an error. If False, compatible inputs
+                will be coerced to match the schema, which can increase
+                compatibility. For example, providing the string \"10\" to an
+                integer field will be coerced to 10. Defaults to False.
+                """
+            ),
+        ),
+    ] = False
+
     server_dependencies: list[str] = Field(
         default_factory=list,
         description="List of dependencies to install in the server environment",
@@ -258,7 +280,7 @@ class Settings(BaseSettings):
 
     # Auth settings
     server_auth: Annotated[
-        ImportString | None,
+        str | None,
         Field(
             description=inspect.cleandoc(
                 """
@@ -266,13 +288,13 @@ class Settings(BaseSettings):
                 the full module path to an AuthProvider class (e.g., 
                 'fastmcp.server.auth.providers.google.GoogleProvider').
 
-                The specified class will be imported and instantiated automatically.
-                Any class that inherits from AuthProvider can be used, including
-                custom implementations.
+                The specified class will be imported and instantiated automatically
+                during FastMCP server creation. Any class that inherits from AuthProvider
+                can be used, including custom implementations.
 
                 If None, no automatic configuration will take place.
 
-                This setting is *always* overriden by any auth provider passed to the
+                This setting is *always* overridden by any auth provider passed to the
                 FastMCP constructor.
 
                 Note that most auth providers require additional configuration
@@ -290,7 +312,6 @@ class Settings(BaseSettings):
     include_tags: Annotated[
         set[str] | None,
         Field(
-            default=None,
             description=inspect.cleandoc(
                 """
                 If provided, only components that match these tags will be
@@ -303,7 +324,6 @@ class Settings(BaseSettings):
     exclude_tags: Annotated[
         set[str] | None,
         Field(
-            default=None,
             description=inspect.cleandoc(
                 """
                 If provided, components that match these tags will be excluded
@@ -317,7 +337,6 @@ class Settings(BaseSettings):
     include_fastmcp_meta: Annotated[
         bool,
         Field(
-            default=True,
             description=inspect.cleandoc(
                 """
                 Whether to include FastMCP meta in the server's MCP responses.
@@ -332,7 +351,6 @@ class Settings(BaseSettings):
     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)
@@ -343,6 +361,38 @@ class Settings(BaseSettings):
         ),
     ] = False
 
+    show_cli_banner: Annotated[
+        bool,
+        Field(
+            description=inspect.cleandoc(
+                """
+                If True, the server banner will be displayed when running the server via CLI.
+                This setting can be overridden by the --no-banner CLI flag.
+                Set to False via FASTMCP_SHOW_CLI_BANNER=false to suppress the banner.
+                """
+            ),
+        ),
+    ] = True
+
+    @property
+    def server_auth_class(self) -> AuthProvider | None:
+        from fastmcp.utilities.types import get_cached_typeadapter
+
+        if not self.server_auth:
+            return None
+
+        # https://github.com/jlowin/fastmcp/issues/1749
+        # Pydantic imports the module in an ImportString during model validation, but we don't want the server
+        # auth module imported during settings creation as it imports dependencies we aren't ready for yet.
+        # To fix this while limiting breaking changes, we delay the import by only creating the ImportString
+        # when the class is actually needed
+
+        type_adapter = get_cached_typeadapter(ImportString)
+
+        auth_class = type_adapter.validate_python(self.server_auth)
+
+        return auth_class
+
 
 def __getattr__(name: str):
     """

fastmcp/tools/__init__.py

@@ -2,4 +2,4 @@ from .tool import Tool, FunctionTool
 from .tool_manager import ToolManager
 from .tool_transform import forward, forward_raw
 
-__all__ = ["Tool", "ToolManager", "FunctionTool", "forward", "forward_raw"]
+__all__ = ["FunctionTool", "Tool", "ToolManager", "forward", "forward_raw"]

fastmcp/tools/tool.py

@@ -10,12 +10,13 @@ from typing import (
     Any,
     Generic,
     Literal,
+    TypeAlias,
     get_type_hints,
 )
 
 import mcp.types
 import pydantic_core
-from mcp.types import ContentBlock, TextContent, ToolAnnotations
+from mcp.types import CallToolResult, ContentBlock, Icon, TextContent, ToolAnnotations
 from mcp.types import Tool as MCPTool
 from pydantic import Field, PydanticSchemaGenerationError
 from typing_extensions import TypeVar
@@ -31,6 +32,7 @@ from fastmcp.utilities.types import (
     Image,
     NotSet,
     NotSetT,
+    create_function_without_params,
     find_kwarg_by_type,
     get_cached_typeadapter,
     replace_type,
@@ -55,6 +57,9 @@ class _UnserializableType:
     pass
 
 
+ToolResultSerializerType: TypeAlias = Callable[[Any], str]
+
+
 def default_serializer(data: Any) -> str:
     return pydantic_core.to_json(data, fallback=str).decode()
 
@@ -64,18 +69,20 @@ class ToolResult:
         self,
         content: list[ContentBlock] | Any | None = None,
         structured_content: dict[str, Any] | Any | None = None,
+        meta: dict[str, Any] | None = None,
     ):
         if content is None and structured_content is None:
             raise ValueError("Either content or structured_content must be provided")
         elif content is None:
             content = structured_content
 
-        self.content = _convert_to_content(content)
+        self.content: list[ContentBlock] = _convert_to_content(result=content)
+        self.meta: dict[str, Any] | None = meta
 
         if structured_content is not None:
             try:
                 structured_content = pydantic_core.to_jsonable_python(
-                    structured_content
+                    value=structured_content
                 )
             except pydantic_core.PydanticSerializationError as e:
                 logger.error(
@@ -92,7 +99,15 @@ class ToolResult:
 
     def to_mcp_result(
         self,
-    ) -> list[ContentBlock] | tuple[list[ContentBlock], dict[str, Any]]:
+    ) -> (
+        list[ContentBlock] | tuple[list[ContentBlock], dict[str, Any]] | CallToolResult
+    ):
+        if self.meta is not None:
+            return CallToolResult(
+                structuredContent=self.structured_content,
+                content=self.content,
+                _meta=self.meta,
+            )
         if self.structured_content is None:
             return self.content
         return self.content, self.structured_content
@@ -112,7 +127,7 @@ class Tool(FastMCPComponent):
         Field(description="Additional annotations about the tool"),
     ] = None
     serializer: Annotated[
-        Callable[[Any], str] | None,
+        ToolResultSerializerType | None,
         Field(description="Optional custom serializer for tool results"),
     ] = None
 
@@ -138,23 +153,26 @@ class Tool(FastMCPComponent):
         include_fastmcp_meta: bool | None = None,
         **overrides: Any,
     ) -> MCPTool:
+        """Convert the FastMCP tool to an MCP tool."""
+        title = None
+
         if self.title:
             title = self.title
         elif self.annotations and self.annotations.title:
             title = self.annotations.title
-        else:
-            title = None
-
-        kwargs = {
-            "name": self.name,
-            "description": self.description,
-            "inputSchema": self.parameters,
-            "outputSchema": self.output_schema,
-            "annotations": self.annotations,
-            "title": title,
-            "_meta": self.get_meta(include_fastmcp_meta=include_fastmcp_meta),
-        }
-        return MCPTool(**kwargs | overrides)
+
+        return MCPTool(
+            name=overrides.get("name", self.name),
+            title=overrides.get("title", title),
+            description=overrides.get("description", self.description),
+            inputSchema=overrides.get("inputSchema", self.parameters),
+            outputSchema=overrides.get("outputSchema", self.output_schema),
+            icons=overrides.get("icons", self.icons),
+            annotations=overrides.get("annotations", self.annotations),
+            _meta=overrides.get(
+                "_meta", self.get_meta(include_fastmcp_meta=include_fastmcp_meta)
+            ),
+        )
 
     @staticmethod
     def from_function(
@@ -162,11 +180,12 @@ class Tool(FastMCPComponent):
         name: str | None = None,
         title: str | None = None,
         description: str | None = None,
+        icons: list[Icon] | None = None,
         tags: set[str] | None = None,
         annotations: ToolAnnotations | None = None,
         exclude_args: list[str] | None = None,
-        output_schema: dict[str, Any] | None | NotSetT | Literal[False] = NotSet,
-        serializer: Callable[[Any], str] | None = None,
+        output_schema: dict[str, Any] | Literal[False] | NotSetT | None = NotSet,
+        serializer: ToolResultSerializerType | None = None,
         meta: dict[str, Any] | None = None,
         enabled: bool | None = None,
     ) -> FunctionTool:
@@ -176,6 +195,7 @@ class Tool(FastMCPComponent):
             name=name,
             title=title,
             description=description,
+            icons=icons,
             tags=tags,
             annotations=annotations,
             exclude_args=exclude_args,
@@ -203,13 +223,13 @@ class Tool(FastMCPComponent):
         tool: Tool,
         *,
         name: str | None = None,
-        title: str | None | NotSetT = NotSet,
-        description: str | None | NotSetT = NotSet,
+        title: str | NotSetT | None = NotSet,
+        description: str | NotSetT | None = NotSet,
         tags: set[str] | None = 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,
+        annotations: ToolAnnotations | NotSetT | None = NotSet,
+        output_schema: dict[str, Any] | Literal[False] | NotSetT | None = NotSet,
+        serializer: ToolResultSerializerType | None = None,
+        meta: dict[str, Any] | NotSetT | None = NotSet,
         transform_args: dict[str, ArgTransform] | None = None,
         enabled: bool | None = None,
         transform_fn: Callable[..., Any] | None = None,
@@ -242,15 +262,26 @@ class FunctionTool(Tool):
         name: str | None = None,
         title: str | None = None,
         description: str | None = None,
+        icons: list[Icon] | None = None,
         tags: set[str] | None = None,
         annotations: ToolAnnotations | None = None,
         exclude_args: list[str] | None = None,
-        output_schema: dict[str, Any] | None | NotSetT | Literal[False] = NotSet,
-        serializer: Callable[[Any], str] | None = None,
+        output_schema: dict[str, Any] | Literal[False] | NotSetT | None = NotSet,
+        serializer: ToolResultSerializerType | None = None,
         meta: dict[str, Any] | None = None,
         enabled: bool | None = None,
     ) -> FunctionTool:
         """Create a Tool from a function."""
+        if exclude_args and fastmcp.settings.deprecation_warnings:
+            warnings.warn(
+                "The `exclude_args` parameter will be deprecated in FastMCP 2.14. "
+                "We recommend using dependency injection with `Depends()` instead, which provides "
+                "better lifecycle management and is more explicit. "
+                "`exclude_args` will continue to work until then. "
+                "See https://gofastmcp.com/docs/servers/tools for examples.",
+                DeprecationWarning,
+                stacklevel=2,
+            )
 
         parsed_fn = ParsedFunction.from_function(fn, exclude_args=exclude_args)
 
@@ -274,10 +305,11 @@ class FunctionTool(Tool):
         # Note: explicit schemas (dict) are used as-is without auto-wrapping
 
         # Validate that explicit schemas are object type for structured content
+        # (resolving $ref references for self-referencing types)
         if final_output_schema is not None and isinstance(final_output_schema, dict):
-            if final_output_schema.get("type") != "object":
+            if not _is_object_schema(final_output_schema):
                 raise ValueError(
-                    f'Output schemas must have "type" set to "object" due to MCP spec limitations. Received: {final_output_schema!r}'
+                    f"Output schemas must represent object types due to MCP spec limitations. Received: {final_output_schema!r}"
                 )
 
         return cls(
@@ -285,6 +317,7 @@ class FunctionTool(Tool):
             name=name or parsed_fn.name,
             title=title,
             description=description or parsed_fn.description,
+            icons=icons,
             parameters=parsed_fn.input_schema,
             output_schema=final_output_schema,
             annotations=annotations,
@@ -315,30 +348,51 @@ class FunctionTool(Tool):
 
         unstructured_result = _convert_to_content(result, serializer=self.serializer)
 
-        structured_output = None
-        # First handle structured content based on output schema, if any
-        if self.output_schema is not None:
-            if self.output_schema.get("x-fastmcp-wrap-result"):
-                # Schema says wrap - always wrap in result key
-                structured_output = {"result": result}
-            else:
-                structured_output = result
-        # If no output schema, try to serialize the result. If it is a dict, use
-        # it as structured content. If it is not a dict, ignore it.
-        if structured_output is None:
+        if self.output_schema is None:
+            # Do not produce a structured output for MCP Content Types
+            if isinstance(result, ContentBlock | Audio | Image | File) or (
+                isinstance(result, list | tuple)
+                and any(isinstance(item, ContentBlock) for item in result)
+            ):
+                return ToolResult(content=unstructured_result)
+
+            # Otherwise, try to serialize the result as a dict
             try:
-                structured_output = pydantic_core.to_jsonable_python(result)
-                if not isinstance(structured_output, dict):
-                    structured_output = None
-            except Exception:
+                structured_content = pydantic_core.to_jsonable_python(result)
+                if isinstance(structured_content, dict):
+                    return ToolResult(
+                        content=unstructured_result,
+                        structured_content=structured_content,
+                    )
+
+            except pydantic_core.PydanticSerializationError:
                 pass
 
+            return ToolResult(content=unstructured_result)
+
+        wrap_result = self.output_schema.get("x-fastmcp-wrap-result")
+
         return ToolResult(
             content=unstructured_result,
-            structured_content=structured_output,
+            structured_content={"result": result} if wrap_result else result,
         )
 
 
+def _is_object_schema(schema: dict[str, Any]) -> bool:
+    """Check if a JSON schema represents an object type."""
+    # Direct object type
+    if schema.get("type") == "object":
+        return True
+
+    # Schema with properties but no explicit type is treated as object
+    if "properties" in schema:
+        return True
+
+    # Self-referencing types use $ref pointing to $defs
+    # The referenced type is always an object in our use case
+    return "$ref" in schema and "$defs" in schema
+
+
 @dataclass
 class ParsedFunction:
     fn: Callable[..., Any]
@@ -399,9 +453,18 @@ class ParsedFunction:
         if exclude_args:
             prune_params.extend(exclude_args)
 
-        input_type_adapter = get_cached_typeadapter(fn)
+        # Create a function without excluded parameters in annotations
+        # This prevents Pydantic from trying to serialize non-serializable types
+        # before we can exclude them in compress_schema
+        fn_for_typeadapter = fn
+        if prune_params:
+            fn_for_typeadapter = create_function_without_params(fn, prune_params)
+
+        input_type_adapter = get_cached_typeadapter(fn_for_typeadapter)
         input_schema = input_type_adapter.json_schema()
-        input_schema = compress_schema(input_schema, prune_params=prune_params)
+        input_schema = compress_schema(
+            input_schema, prune_params=prune_params, prune_titles=True
+        )
 
         output_schema = None
         # Get the return annotation from the signature
@@ -427,9 +490,8 @@ class ParsedFunction:
             # we ensure that no output schema is automatically generated.
             clean_output_type = replace_type(
                 output_type,
-                {
-                    t: _UnserializableType
-                    for t in (
+                dict.fromkeys(  # type: ignore[arg-type]
+                    (
                         Image,
                         Audio,
                         File,
@@ -439,8 +501,9 @@ class ParsedFunction:
                         mcp.types.AudioContent,
                         mcp.types.ResourceLink,
                         mcp.types.EmbeddedResource,
-                    )
-                },
+                    ),
+                    _UnserializableType,
+                ),
             )
 
             try:
@@ -449,10 +512,9 @@ class ParsedFunction:
 
                 # Generate schema for wrapped type if it's non-object
                 # because MCP requires that output schemas are objects
-                if (
-                    wrap_non_object_output_schema
-                    and base_schema.get("type") != "object"
-                ):
+                # Check if schema is an object type, resolving $ref references
+                # (self-referencing types use $ref at root level)
+                if wrap_non_object_output_schema and not _is_object_schema(base_schema):
                     # Use the wrapped result schema directly
                     wrapped_type = _WrappedResult[clean_output_type]
                     wrapped_adapter = get_cached_typeadapter(wrapped_type)
@@ -461,7 +523,7 @@ class ParsedFunction:
                 else:
                     output_schema = base_schema
 
-                output_schema = compress_schema(output_schema)
+                output_schema = compress_schema(output_schema, prune_titles=True)
 
             except PydanticSchemaGenerationError as e:
                 if "_UnserializableType" not in str(e):
@@ -476,65 +538,68 @@ class ParsedFunction:
         )
 
 
-def _convert_to_content(
-    result: Any,
-    serializer: Callable[[Any], str] | None = None,
-    _process_as_single_item: bool = False,
-) -> list[ContentBlock]:
-    """Convert a result to a sequence of content objects."""
+def _serialize_with_fallback(
+    result: Any, serializer: ToolResultSerializerType | None = None
+) -> str:
+    if serializer is not None:
+        try:
+            return serializer(result)
+        except Exception as e:
+            logger.warning(
+                "Error serializing tool result: %s",
+                e,
+                exc_info=True,
+            )
 
-    if result is None:
-        return []
+    return default_serializer(result)
 
-    if isinstance(result, ContentBlock):
-        return [result]
 
-    if isinstance(result, Image):
-        return [result.to_image_content()]
+def _convert_to_single_content_block(
+    item: Any,
+    serializer: ToolResultSerializerType | None = None,
+) -> ContentBlock:
+    if isinstance(item, ContentBlock):
+        return item
 
-    elif isinstance(result, Audio):
-        return [result.to_audio_content()]
+    if isinstance(item, Image):
+        return item.to_image_content()
 
-    elif isinstance(result, File):
-        return [result.to_resource_content()]
+    if isinstance(item, Audio):
+        return item.to_audio_content()
 
-    if isinstance(result, list | tuple) and not _process_as_single_item:
-        # if the result is a list, then it could either be a list of MCP types,
-        # or a "regular" list that the tool is returning, or a mix of both.
-        #
-        # so we extract all the MCP types / images and convert them as individual content elements,
-        # and aggregate the rest as a single content element
+    if isinstance(item, File):
+        return item.to_resource_content()
 
-        mcp_types = []
-        other_content = []
+    if isinstance(item, str):
+        return TextContent(type="text", text=item)
 
-        for item in result:
-            if isinstance(item, ContentBlock | Image | Audio | File):
-                mcp_types.append(_convert_to_content(item)[0])
-            else:
-                other_content.append(item)
+    return TextContent(type="text", text=_serialize_with_fallback(item, serializer))
 
-        if other_content:
-            other_content = _convert_to_content(
-                other_content,
-                serializer=serializer,
-                _process_as_single_item=True,
-            )
 
-        return other_content + mcp_types
+def _convert_to_content(
+    result: Any,
+    serializer: ToolResultSerializerType | None = None,
+) -> list[ContentBlock]:
+    """Convert a result to a sequence of content objects."""
 
-    if not isinstance(result, str):
-        if serializer is None:
-            result = default_serializer(result)
-        else:
-            try:
-                result = serializer(result)
-            except Exception as e:
-                logger.warning(
-                    "Error serializing tool result: %s",
-                    e,
-                    exc_info=True,
-                )
-                result = default_serializer(result)
+    if result is None:
+        return []
 
-    return [TextContent(type="text", text=result)]
+    if not isinstance(result, (list | tuple)):
+        return [_convert_to_single_content_block(result, serializer)]
+
+    # If all items are ContentBlocks, return them as is
+    if all(isinstance(item, ContentBlock) for item in result):
+        return result
+
+    # If any item is a ContentBlock, convert non-ContentBlock items to TextContent
+    # without aggregating them
+    if any(isinstance(item, ContentBlock | Image | Audio | File) for item in result):
+        return [
+            _convert_to_single_content_block(item, serializer)
+            if not isinstance(item, ContentBlock)
+            else item
+            for item in result
+        ]
+    # If none of the items are ContentBlocks, aggregate all items into a single TextContent
+    return [TextContent(type="text", text=_serialize_with_fallback(result, serializer))]