fastmcp 2.7.1__py3-none-any.whl → 2.8.1__py3-none-any.whl

fastmcp/settings.py

@@ -2,31 +2,99 @@ from __future__ import annotations as _annotations
 
 import inspect
 from pathlib import Path
-from typing import Annotated, Literal
+from typing import Annotated, Any, Literal
 
 from pydantic import Field, model_validator
+from pydantic.fields import FieldInfo
 from pydantic_settings import (
     BaseSettings,
+    EnvSettingsSource,
+    PydanticBaseSettingsSource,
     SettingsConfigDict,
 )
 from typing_extensions import Self
 
+from fastmcp.utilities.logging import get_logger
+
+logger = get_logger(__name__)
+
 LOG_LEVEL = Literal["DEBUG", "INFO", "WARNING", "ERROR", "CRITICAL"]
 
 DuplicateBehavior = Literal["warn", "error", "replace", "ignore"]
 
 
+class ExtendedEnvSettingsSource(EnvSettingsSource):
+    """
+    A special EnvSettingsSource that allows for multiple env var prefixes to be used.
+
+    Raises a deprecation warning if the old `FASTMCP_SERVER_` prefix is used.
+    """
+
+    def get_field_value(
+        self, field: FieldInfo, field_name: str
+    ) -> tuple[Any, str, bool]:
+        if prefixes := self.config.get("env_prefixes"):
+            for prefix in prefixes:
+                self.env_prefix = prefix
+                env_val, field_key, value_is_complex = super().get_field_value(
+                    field, field_name
+                )
+                if env_val is not None:
+                    if prefix == "FASTMCP_SERVER_":
+                        # Deprecated in 2.8.0
+                        logger.warning(
+                            "Using `FASTMCP_SERVER_` environment variables is deprecated. Use `FASTMCP_` instead.",
+                        )
+                    return env_val, field_key, value_is_complex
+
+        return super().get_field_value(field, field_name)
+
+
+class ExtendedSettingsConfigDict(SettingsConfigDict, total=False):
+    env_prefixes: list[str] | None
+
+
 class Settings(BaseSettings):
     """FastMCP settings."""
 
-    model_config = SettingsConfigDict(
-        env_prefix="FASTMCP_",
+    model_config = ExtendedSettingsConfigDict(
+        env_prefixes=["FASTMCP_", "FASTMCP_SERVER_"],
         env_file=".env",
         extra="ignore",
         env_nested_delimiter="__",
         nested_model_default_partial_update=True,
     )
 
+    @classmethod
+    def settings_customise_sources(
+        cls,
+        settings_cls: type[BaseSettings],
+        init_settings: PydanticBaseSettingsSource,
+        env_settings: PydanticBaseSettingsSource,
+        dotenv_settings: PydanticBaseSettingsSource,
+        file_secret_settings: PydanticBaseSettingsSource,
+    ) -> tuple[PydanticBaseSettingsSource, ...]:
+        # can remove this classmethod after deprecated FASTMCP_SERVER_ prefix is
+        # removed
+        return (
+            init_settings,
+            ExtendedEnvSettingsSource(settings_cls),
+            dotenv_settings,
+            file_secret_settings,
+        )
+
+    @property
+    def settings(self) -> Self:
+        """
+        This property is for backwards compatibility with FastMCP < 2.8.0,
+        which accessed fastmcp.settings.settings
+        """
+        # Deprecated in 2.8.0
+        logger.warning(
+            "Using fastmcp.settings.settings is deprecated. Use fastmcp.settings instead.",
+        )
+        return self
+
     home: Path = Path.home() / ".fastmcp"
 
     test_mode: bool = False
@@ -42,6 +110,20 @@ class Settings(BaseSettings):
         ),
     ] = True
 
+    deprecation_warnings: Annotated[
+        bool,
+        Field(
+            description=inspect.cleandoc(
+                """
+                Whether to show deprecation warnings. You can completely reset
+                Python's warning behavior by running `warnings.resetwarnings()`.
+                Note this will NOT apply to deprecation warnings from the
+                settings class itself.
+                """,
+            )
+        ),
+    ] = True
+
     client_raise_first_exceptiongroup_error: Annotated[
         bool,
         Field(
@@ -107,27 +189,6 @@ class Settings(BaseSettings):
 
         return self
 
-
-class ServerSettings(BaseSettings):
-    """FastMCP server settings.
-
-    All settings can be configured via environment variables with the prefix FASTMCP_.
-    For example, FASTMCP_DEBUG=true will set debug=True.
-    """
-
-    model_config = SettingsConfigDict(
-        env_prefix="FASTMCP_SERVER_",
-        env_file=".env",
-        extra="ignore",
-        env_nested_delimiter="__",
-        nested_model_default_partial_update=True,
-    )
-
-    log_level: Annotated[
-        LOG_LEVEL,
-        Field(default_factory=lambda: Settings().log_level),
-    ]
-
     # HTTP settings
     host: str = "127.0.0.1"
     port: int = 8000
@@ -136,15 +197,6 @@ class ServerSettings(BaseSettings):
     streamable_http_path: str = "/mcp"
     debug: bool = False
 
-    # resource settings
-    on_duplicate_resources: DuplicateBehavior = "warn"
-
-    # tool settings
-    on_duplicate_tools: DuplicateBehavior = "warn"
-
-    # prompt settings
-    on_duplicate_prompts: DuplicateBehavior = "warn"
-
     # error handling
     mask_error_details: Annotated[
         bool,
@@ -162,7 +214,7 @@ class ServerSettings(BaseSettings):
         ),
     ] = False
 
-    dependencies: Annotated[
+    server_dependencies: Annotated[
         list[str],
         Field(
             default_factory=list,
@@ -170,9 +222,6 @@ class ServerSettings(BaseSettings):
         ),
     ] = []
 
-    # cache settings (for getting attributes from servers, used to avoid repeated calls)
-    cache_expiration_seconds: float = 0
-
     # StreamableHTTP settings
     json_response: bool = False
     stateless_http: bool = (
@@ -198,5 +247,32 @@ class ServerSettings(BaseSettings):
         ),
     ] = None
 
+    include_tags: Annotated[
+        set[str] | None,
+        Field(
+            default=None,
+            description=inspect.cleandoc(
+                """
+                If provided, only components that match these tags will be
+                exposed to clients. A component is considered to match if ANY of
+                its tags match ANY of the tags in the set.
+                """
+            ),
+        ),
+    ] = None
+    exclude_tags: Annotated[
+        set[str] | None,
+        Field(
+            default=None,
+            description=inspect.cleandoc(
+                """
+                If provided, components that match these tags will be excluded
+                from the server. A component is considered to match if ANY of
+                its tags match ANY of the tags in the set.
+                """
+            ),
+        ),
+    ] = None
+
 
 settings = Settings()

fastmcp/tools/__init__.py

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

fastmcp/tools/tool.py

@@ -2,29 +2,30 @@ from __future__ import annotations
 
 import inspect
 import json
-from abc import ABC, abstractmethod
 from collections.abc import Callable
-from typing import TYPE_CHECKING, Annotated, Any
+from dataclasses import dataclass
+from typing import TYPE_CHECKING, Any
 
 import pydantic_core
-from mcp.types import EmbeddedResource, ImageContent, TextContent, ToolAnnotations
+from mcp.types import TextContent, ToolAnnotations
 from mcp.types import Tool as MCPTool
-from pydantic import BeforeValidator, Field
+from pydantic import Field
 
 import fastmcp
 from fastmcp.server.dependencies import get_context
+from fastmcp.utilities.components import FastMCPComponent
 from fastmcp.utilities.json_schema import compress_schema
 from fastmcp.utilities.logging import get_logger
 from fastmcp.utilities.types import (
-    FastMCPBaseModel,
+    Audio,
     Image,
-    _convert_set_defaults,
+    MCPContent,
     find_kwarg_by_type,
     get_cached_typeadapter,
 )
 
 if TYPE_CHECKING:
-    pass
+    from fastmcp.tools.tool_transform import ArgTransform, TransformedTool
 
 logger = get_logger(__name__)
 
@@ -33,24 +34,13 @@ def default_serializer(data: Any) -> str:
     return pydantic_core.to_json(data, fallback=str, indent=2).decode()
 
 
-class Tool(FastMCPBaseModel, ABC):
+class Tool(FastMCPComponent):
     """Internal tool registration info."""
 
-    name: str = Field(description="Name of the tool")
-    description: str | None = Field(
-        default=None, description="Description of what the tool does"
-    )
     parameters: dict[str, Any] = Field(description="JSON schema for tool parameters")
-    tags: Annotated[set[str], BeforeValidator(_convert_set_defaults)] = Field(
-        default_factory=set, description="Tags for the tool"
-    )
     annotations: ToolAnnotations | None = Field(
         default=None, description="Additional annotations about the tool"
     )
-    exclude_args: list[str] | None = Field(
-        default=None,
-        description="Arguments to exclude from the tool schema, such as State, Memory, or Credential",
-    )
     serializer: Callable[[Any], str] | None = Field(
         default=None, description="Optional custom serializer for tool results"
     )
@@ -73,6 +63,7 @@ class Tool(FastMCPBaseModel, ABC):
         annotations: ToolAnnotations | None = None,
         exclude_args: list[str] | None = None,
         serializer: Callable[[Any], str] | None = None,
+        enabled: bool | None = None,
     ) -> FunctionTool:
         """Create a Tool from a function."""
         return FunctionTool.from_function(
@@ -83,21 +74,40 @@ class Tool(FastMCPBaseModel, ABC):
             annotations=annotations,
             exclude_args=exclude_args,
             serializer=serializer,
+            enabled=enabled,
         )
 
-    def __eq__(self, other: object) -> bool:
-        if type(self) is not type(other):
-            return False
-        assert isinstance(other, type(self))
-        return self.model_dump() == other.model_dump()
-
-    @abstractmethod
-    async def run(
-        self, arguments: dict[str, Any]
-    ) -> list[TextContent | ImageContent | EmbeddedResource]:
+    async def run(self, arguments: dict[str, Any]) -> list[MCPContent]:
         """Run the tool with arguments."""
         raise NotImplementedError("Subclasses must implement run()")
 
+    @classmethod
+    def from_tool(
+        cls,
+        tool: Tool,
+        transform_fn: Callable[..., Any] | None = None,
+        name: str | None = None,
+        transform_args: dict[str, ArgTransform] | None = None,
+        description: str | None = None,
+        tags: set[str] | None = None,
+        annotations: ToolAnnotations | None = None,
+        serializer: Callable[[Any], str] | None = None,
+        enabled: bool | None = None,
+    ) -> TransformedTool:
+        from fastmcp.tools.tool_transform import TransformedTool
+
+        return TransformedTool.from_tool(
+            tool=tool,
+            transform_fn=transform_fn,
+            name=name,
+            transform_args=transform_args,
+            description=description,
+            tags=tags,
+            annotations=annotations,
+            serializer=serializer,
+            enabled=enabled,
+        )
+
 
 class FunctionTool(Tool):
     fn: Callable[..., Any]
@@ -112,70 +122,27 @@ class FunctionTool(Tool):
         annotations: ToolAnnotations | None = None,
         exclude_args: list[str] | None = None,
         serializer: Callable[[Any], str] | None = None,
+        enabled: bool | None = None,
     ) -> FunctionTool:
         """Create a Tool from a function."""
-        from fastmcp.server.context import Context
-
-        # Reject functions with *args or **kwargs
-        sig = inspect.signature(fn)
-        for param in sig.parameters.values():
-            if param.kind == inspect.Parameter.VAR_POSITIONAL:
-                raise ValueError("Functions with *args are not supported as tools")
-            if param.kind == inspect.Parameter.VAR_KEYWORD:
-                raise ValueError("Functions with **kwargs are not supported as tools")
-
-        if exclude_args:
-            for arg_name in exclude_args:
-                if arg_name not in sig.parameters:
-                    raise ValueError(
-                        f"Parameter '{arg_name}' in exclude_args does not exist in function."
-                    )
-                param = sig.parameters[arg_name]
-                if param.default == inspect.Parameter.empty:
-                    raise ValueError(
-                        f"Parameter '{arg_name}' in exclude_args must have a default value."
-                    )
 
-        func_name = name or getattr(fn, "__name__", None) or fn.__class__.__name__
+        parsed_fn = ParsedFunction.from_function(fn, exclude_args=exclude_args)
 
-        if func_name == "<lambda>":
+        if name is None and parsed_fn.name == "<lambda>":
             raise ValueError("You must provide a name for lambda functions")
 
-        func_doc = description or fn.__doc__
-
-        # if the fn is a callable class, we need to get the __call__ method from here out
-        if not inspect.isroutine(fn):
-            fn = fn.__call__
-        # if the fn is a staticmethod, we need to work with the underlying function
-        if isinstance(fn, staticmethod):
-            fn = fn.__func__
-
-        type_adapter = get_cached_typeadapter(fn)
-        schema = type_adapter.json_schema()
-
-        prune_params: list[str] = []
-        context_kwarg = find_kwarg_by_type(fn, kwarg_type=Context)
-        if context_kwarg:
-            prune_params.append(context_kwarg)
-        if exclude_args:
-            prune_params.extend(exclude_args)
-
-        schema = compress_schema(schema, prune_params=prune_params)
-
         return cls(
-            fn=fn,
-            name=func_name,
-            description=func_doc,
-            parameters=schema,
+            fn=parsed_fn.fn,
+            name=name or parsed_fn.name,
+            description=description or parsed_fn.description,
+            parameters=parsed_fn.parameters,
             tags=tags or set(),
             annotations=annotations,
-            exclude_args=exclude_args,
             serializer=serializer,
+            enabled=enabled if enabled is not None else True,
         )
 
-    async def run(
-        self, arguments: dict[str, Any]
-    ) -> list[TextContent | ImageContent | EmbeddedResource]:
+    async def run(self, arguments: dict[str, Any]) -> list[MCPContent]:
         """Run the tool with arguments."""
         from fastmcp.server.context import Context
 
@@ -185,7 +152,7 @@ class FunctionTool(Tool):
         if context_kwarg and context_kwarg not in arguments:
             arguments[context_kwarg] = get_context()
 
-        if fastmcp.settings.settings.tool_attempt_parse_json_args:
+        if fastmcp.settings.tool_attempt_parse_json_args:
             # Pre-parse data from JSON in order to handle cases like `["a", "b", "c"]`
             # being passed in as JSON inside a string rather than an actual list.
             #
@@ -222,21 +189,94 @@ class FunctionTool(Tool):
         return _convert_to_content(result, serializer=self.serializer)
 
 
+@dataclass
+class ParsedFunction:
+    fn: Callable[..., Any]
+    name: str
+    description: str | None
+    parameters: dict[str, Any]
+
+    @classmethod
+    def from_function(
+        cls,
+        fn: Callable[..., Any],
+        exclude_args: list[str] | None = None,
+        validate: bool = True,
+    ) -> ParsedFunction:
+        from fastmcp.server.context import Context
+
+        if validate:
+            sig = inspect.signature(fn)
+            # Reject functions with *args or **kwargs
+            for param in sig.parameters.values():
+                if param.kind == inspect.Parameter.VAR_POSITIONAL:
+                    raise ValueError("Functions with *args are not supported as tools")
+                if param.kind == inspect.Parameter.VAR_KEYWORD:
+                    raise ValueError(
+                        "Functions with **kwargs are not supported as tools"
+                    )
+
+            # Reject exclude_args that don't exist in the function or don't have a default value
+            if exclude_args:
+                for arg_name in exclude_args:
+                    if arg_name not in sig.parameters:
+                        raise ValueError(
+                            f"Parameter '{arg_name}' in exclude_args does not exist in function."
+                        )
+                    param = sig.parameters[arg_name]
+                    if param.default == inspect.Parameter.empty:
+                        raise ValueError(
+                            f"Parameter '{arg_name}' in exclude_args must have a default value."
+                        )
+
+        # collect name and doc before we potentially modify the function
+        fn_name = getattr(fn, "__name__", None) or fn.__class__.__name__
+        fn_doc = fn.__doc__
+
+        # if the fn is a callable class, we need to get the __call__ method from here out
+        if not inspect.isroutine(fn):
+            fn = fn.__call__
+        # if the fn is a staticmethod, we need to work with the underlying function
+        if isinstance(fn, staticmethod):
+            fn = fn.__func__
+
+        type_adapter = get_cached_typeadapter(fn)
+        schema = type_adapter.json_schema()
+
+        prune_params: list[str] = []
+        context_kwarg = find_kwarg_by_type(fn, kwarg_type=Context)
+        if context_kwarg:
+            prune_params.append(context_kwarg)
+        if exclude_args:
+            prune_params.extend(exclude_args)
+
+        schema = compress_schema(schema, prune_params=prune_params)
+        return cls(
+            fn=fn,
+            name=fn_name,
+            description=fn_doc,
+            parameters=schema,
+        )
+
+
 def _convert_to_content(
     result: Any,
     serializer: Callable[[Any], str] | None = None,
     _process_as_single_item: bool = False,
-) -> list[TextContent | ImageContent | EmbeddedResource]:
+) -> list[MCPContent]:
     """Convert a result to a sequence of content objects."""
     if result is None:
         return []
 
-    if isinstance(result, TextContent | ImageContent | EmbeddedResource):
+    if isinstance(result, MCPContent):
         return [result]
 
     if isinstance(result, Image):
         return [result.to_image_content()]
 
+    elif isinstance(result, Audio):
+        return [result.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.
@@ -248,7 +288,7 @@ def _convert_to_content(
         other_content = []
 
         for item in result:
-            if isinstance(item, TextContent | ImageContent | EmbeddedResource | Image):
+            if isinstance(item, MCPContent | Image | Audio):
                 mcp_types.append(_convert_to_content(item)[0])
             else:
                 other_content.append(item)

fastmcp/tools/tool_manager.py

@@ -4,12 +4,14 @@ import warnings
 from collections.abc import Callable
 from typing import TYPE_CHECKING, Any
 
-from mcp.types import EmbeddedResource, ImageContent, TextContent, ToolAnnotations
+from mcp.types import ToolAnnotations
 
+from fastmcp import settings
 from fastmcp.exceptions import NotFoundError, ToolError
 from fastmcp.settings import DuplicateBehavior
 from fastmcp.tools.tool import Tool
 from fastmcp.utilities.logging import get_logger
+from fastmcp.utilities.types import MCPContent
 
 if TYPE_CHECKING:
     pass
@@ -23,10 +25,10 @@ class ToolManager:
     def __init__(
         self,
         duplicate_behavior: DuplicateBehavior | None = None,
-        mask_error_details: bool = False,
+        mask_error_details: bool | None = None,
     ):
         self._tools: dict[str, Tool] = {}
-        self.mask_error_details = mask_error_details
+        self.mask_error_details = mask_error_details or settings.mask_error_details
 
         # Default to "warn" if None is provided
         if duplicate_behavior is None:
@@ -70,11 +72,12 @@ class ToolManager:
     ) -> Tool:
         """Add a tool to the server."""
         # deprecated in 2.7.0
-        warnings.warn(
-            "ToolManager.add_tool_from_fn() is deprecated. Use Tool.from_function() and call add_tool() instead.",
-            DeprecationWarning,
-            stacklevel=2,
-        )
+        if settings.deprecation_warnings:
+            warnings.warn(
+                "ToolManager.add_tool_from_fn() is deprecated. Use Tool.from_function() and call add_tool() instead.",
+                DeprecationWarning,
+                stacklevel=2,
+            )
         tool = Tool.from_function(
             fn,
             name=name,
@@ -118,9 +121,7 @@ class ToolManager:
         else:
             raise NotFoundError(f"Unknown tool: {key}")
 
-    async def call_tool(
-        self, key: str, arguments: dict[str, Any]
-    ) -> list[TextContent | ImageContent | EmbeddedResource]:
+    async def call_tool(self, key: str, arguments: dict[str, Any]) -> list[MCPContent]:
         """Call a tool by name with arguments."""
         tool = self.get_tool(key)
         if not tool: