fastmcp 2.12.5__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 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,14 @@ 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
 
@@ -82,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,
@@ -145,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
 
@@ -189,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
@@ -205,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)
@@ -235,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)
@@ -248,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",
@@ -293,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
@@ -306,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
@@ -320,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.
@@ -335,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)
@@ -349,7 +364,6 @@ class Settings(BaseSettings):
     show_cli_banner: Annotated[
         bool,
         Field(
-            default=True,
             description=inspect.cleandoc(
                 """
                 If True, the server banner will be displayed when running the server via CLI.

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

@@ -16,7 +16,7 @@ from typing import (
 
 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
@@ -32,6 +32,7 @@ from fastmcp.utilities.types import (
     Image,
     NotSet,
     NotSetT,
+    create_function_without_params,
     find_kwarg_by_type,
     get_cached_typeadapter,
     replace_type,
@@ -68,6 +69,7 @@ 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")
@@ -75,6 +77,7 @@ class ToolResult:
             content = structured_content
 
         self.content: list[ContentBlock] = _convert_to_content(result=content)
+        self.meta: dict[str, Any] | None = meta
 
         if structured_content is not None:
             try:
@@ -96,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
@@ -156,6 +167,7 @@ class Tool(FastMCPComponent):
             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)
@@ -168,10 +180,11 @@ 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,
+        output_schema: dict[str, Any] | Literal[False] | NotSetT | None = NotSet,
         serializer: ToolResultSerializerType | None = None,
         meta: dict[str, Any] | None = None,
         enabled: bool | None = None,
@@ -182,6 +195,7 @@ class Tool(FastMCPComponent):
             name=name,
             title=title,
             description=description,
+            icons=icons,
             tags=tags,
             annotations=annotations,
             exclude_args=exclude_args,
@@ -209,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,
+        annotations: ToolAnnotations | NotSetT | None = NotSet,
+        output_schema: dict[str, Any] | Literal[False] | NotSetT | None = NotSet,
         serializer: ToolResultSerializerType | None = None,
-        meta: dict[str, Any] | None | NotSetT = NotSet,
+        meta: dict[str, Any] | NotSetT | None = NotSet,
         transform_args: dict[str, ArgTransform] | None = None,
         enabled: bool | None = None,
         transform_fn: Callable[..., Any] | None = None,
@@ -248,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,
+        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)
 
@@ -280,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(
@@ -291,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,
@@ -351,6 +378,21 @@ class FunctionTool(Tool):
         )
 
 
+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]
@@ -411,7 +453,14 @@ 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, prune_titles=True
@@ -441,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,
@@ -453,8 +501,9 @@ class ParsedFunction:
                         mcp.types.AudioContent,
                         mcp.types.ResourceLink,
                         mcp.types.EmbeddedResource,
-                    )
-                },
+                    ),
+                    _UnserializableType,
+                ),
             )
 
             try:
@@ -463,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)
@@ -546,13 +594,12 @@ def _convert_to_content(
 
     # If any item is a ContentBlock, convert non-ContentBlock items to TextContent
     # without aggregating them
-    if any(isinstance(item, ContentBlock) for item in result):
+    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))]

fastmcp/tools/tool_manager.py

@@ -1,10 +1,11 @@
 from __future__ import annotations
 
 import warnings
-from collections.abc import Callable
-from typing import TYPE_CHECKING, Any
+from collections.abc import Callable, Mapping
+from typing import Any
 
 from mcp.types import ToolAnnotations
+from pydantic import ValidationError
 
 from fastmcp import settings
 from fastmcp.exceptions import NotFoundError, ToolError
@@ -16,9 +17,6 @@ from fastmcp.tools.tool_transform import (
 )
 from fastmcp.utilities.logging import get_logger
 
-if TYPE_CHECKING:
-    from fastmcp.server.server import MountedServer
-
 logger = get_logger(__name__)
 
 
@@ -29,12 +27,15 @@ class ToolManager:
         self,
         duplicate_behavior: DuplicateBehavior | None = None,
         mask_error_details: bool | None = None,
-        transformations: dict[str, ToolTransformConfig] | None = None,
+        transformations: Mapping[str, ToolTransformConfig] | None = None,
     ):
         self._tools: dict[str, Tool] = {}
-        self._mounted_servers: list[MountedServer] = []
-        self.mask_error_details = mask_error_details or settings.mask_error_details
-        self.transformations = transformations or {}
+        self.mask_error_details: bool = (
+            mask_error_details or settings.mask_error_details
+        )
+        self.transformations: dict[str, ToolTransformConfig] = dict(
+            transformations or {}
+        )
 
         # Default to "warn" if None is provided
         if duplicate_behavior is None:
@@ -48,56 +49,12 @@ class ToolManager:
 
         self.duplicate_behavior = duplicate_behavior
 
-    def mount(self, server: MountedServer) -> None:
-        """Adds a mounted server as a source for tools."""
-        self._mounted_servers.append(server)
-
-    async def _load_tools(self, *, via_server: bool = False) -> dict[str, Tool]:
-        """
-        The single, consolidated recursive method for fetching tools. The 'via_server'
-        parameter determines the communication path.
-
-        - via_server=False: Manager-to-manager path for complete, unfiltered inventory
-        - via_server=True: Server-to-server path for filtered MCP requests
-        """
-        all_tools: dict[str, Tool] = {}
-
-        for mounted in self._mounted_servers:
-            try:
-                if via_server:
-                    # Use the server-to-server filtered path
-                    child_results = await mounted.server._list_tools()
-                else:
-                    # Use the manager-to-manager unfiltered path
-                    child_results = await mounted.server._tool_manager.list_tools()
-
-                # The combination logic is the same for both paths
-                child_dict = {t.key: t for t in child_results}
-                if mounted.prefix:
-                    for tool in child_dict.values():
-                        prefixed_tool = tool.model_copy(
-                            key=f"{mounted.prefix}_{tool.key}"
-                        )
-                        all_tools[prefixed_tool.key] = prefixed_tool
-                else:
-                    all_tools.update(child_dict)
-            except Exception as e:
-                # Skip failed mounts silently, matches existing behavior
-                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
-        all_tools.update(self._tools)
-
+    async def _load_tools(self) -> dict[str, Tool]:
+        """Return this manager's local tools with transformations applied."""
         transformed_tools = apply_transformations_to_tools(
-            tools=all_tools,
+            tools=self._tools,
             transformations=self.transformations,
         )
-
         return transformed_tools
 
     async def has_tool(self, key: str) -> bool:
@@ -114,25 +71,9 @@ class ToolManager:
 
     async def get_tools(self) -> dict[str, Tool]:
         """
-        Gets the complete, unfiltered inventory of all tools.
-        """
-        return await self._load_tools(via_server=False)
-
-    async def list_tools(self) -> list[Tool]:
+        Gets the complete, unfiltered inventory of local tools.
         """
-        Lists all tools, applying protocol filtering.
-        """
-        tools_dict = await self._load_tools(via_server=True)
-        return list(tools_dict.values())
-
-    @property
-    def _tools_transformed(self) -> list[str]:
-        """Get the local tools."""
-
-        return [
-            transformation.name or tool_name
-            for tool_name, transformation in self.transformations.items()
-        ]
+        return await self._load_tools()
 
     def add_tool_from_fn(
         self,
@@ -214,41 +155,18 @@ class ToolManager:
         Internal API for servers: Finds and calls a tool, respecting the
         filtered protocol path.
         """
-        # 1. Check local tools first. The server will have already applied its filter.
-        if key in self._tools or key in self._tools_transformed:
-            tool = await self.get_tool(key)
-            if not tool:
-                raise NotFoundError(f"Tool {key!r} not found")
-
-            try:
-                return await tool.run(arguments)
-
-            # raise ToolErrors as-is
-            except ToolError as e:
-                logger.exception(f"Error calling tool {key!r}")
-                raise e
-
-            # Handle other exceptions
-            except Exception as e:
-                logger.exception(f"Error calling tool {key!r}")
-                if self.mask_error_details:
-                    # Mask internal details
-                    raise ToolError(f"Error calling tool {key!r}") from e
-                else:
-                    # Include original error details
-                    raise ToolError(f"Error calling tool {key!r}: {e}") from e
-
-        # 2. Check mounted servers using the filtered protocol path.
-        for mounted in reversed(self._mounted_servers):
-            tool_key = key
-            if mounted.prefix:
-                if key.startswith(f"{mounted.prefix}_"):
-                    tool_key = key.removeprefix(f"{mounted.prefix}_")
-                else:
-                    continue
-            try:
-                return await mounted.server._call_tool(tool_key, arguments)
-            except NotFoundError:
-                continue
-
-        raise NotFoundError(f"Tool {key!r} not found.")
+        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 Exception as e:
+            logger.exception(f"Error calling tool {key!r}")
+            if self.mask_error_details:
+                raise ToolError(f"Error calling tool {key!r}") from e
+            else:
+                raise ToolError(f"Error calling tool {key!r}: {e}") from e

fastmcp/tools/tool_transform.py

@@ -4,6 +4,7 @@ import inspect
 import warnings
 from collections.abc import Callable
 from contextvars import ContextVar
+from copy import deepcopy
 from dataclasses import dataclass
 from typing import Annotated, Any, Literal, cast
 
@@ -34,7 +35,7 @@ _current_tool: ContextVar[TransformedTool | None] = ContextVar(  # type: ignore[
 )
 
 
-async def forward(**kwargs) -> ToolResult:
+async def forward(**kwargs: Any) -> ToolResult:
     """Forward to parent tool with argument transformation applied.
 
     This function can only be called from within a transformed tool's custom
@@ -64,7 +65,7 @@ async def forward(**kwargs) -> ToolResult:
     return await tool.forwarding_fn(**kwargs)
 
 
-async def forward_raw(**kwargs) -> ToolResult:
+async def forward_raw(**kwargs: Any) -> ToolResult:
     """Forward directly to parent tool without transformation.
 
     This function bypasses all argument transformation and validation, calling the parent
@@ -365,15 +366,15 @@ class TransformedTool(Tool):
         cls,
         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,
         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 | Literal[False] = NotSet,
-        serializer: Callable[[Any], str] | None | NotSetT = NotSet,
-        meta: dict[str, Any] | None | NotSetT = NotSet,
+        annotations: ToolAnnotations | NotSetT | None = NotSet,
+        output_schema: dict[str, Any] | Literal[False] | NotSetT | None = NotSet,
+        serializer: Callable[[Any], str] | NotSetT | None = NotSet,
+        meta: dict[str, Any] | NotSetT | None = NotSet,
         enabled: bool | None = None,
     ) -> TransformedTool:
         """Create a transformed tool from a parent tool.
@@ -620,7 +621,8 @@ class TransformedTool(Tool):
         """
 
         # Build transformed schema and mapping
-        parent_defs = parent_tool.parameters.get("$defs", {})
+        # Deep copy to prevent compress_schema from mutating parent tool's $defs
+        parent_defs = deepcopy(parent_tool.parameters.get("$defs", {}))
         parent_props = parent_tool.parameters.get("properties", {}).copy()
         parent_required = set(parent_tool.parameters.get("required", []))
 
@@ -681,7 +683,7 @@ class TransformedTool(Tool):
             schema = compress_schema(schema, prune_defs=True)
 
         # Create forwarding function that closes over everything it needs
-        async def _forward(**kwargs):
+        async def _forward(**kwargs: Any):
             # Validate arguments
             valid_args = set(new_props.keys())
             provided_args = set(kwargs.keys())