fastmcp 2.10.5__py3-none-any.whl → 2.11.0__py3-none-any.whl

fastmcp/settings.py

@@ -5,7 +5,7 @@ import warnings
 from pathlib import Path
 from typing import Annotated, Any, Literal
 
-from pydantic import Field, model_validator
+from pydantic import Field, field_validator
 from pydantic.fields import FieldInfo
 from pydantic_settings import (
     BaseSettings,
@@ -55,6 +55,25 @@ class ExtendedSettingsConfigDict(SettingsConfigDict, total=False):
     env_prefixes: list[str] | None
 
 
+class ExperimentalSettings(BaseSettings):
+    model_config = SettingsConfigDict(
+        env_prefix="FASTMCP_EXPERIMENTAL_",
+        extra="ignore",
+    )
+
+    enable_new_openapi_parser: Annotated[
+        bool,
+        Field(
+            description=inspect.cleandoc(
+                """
+                Whether to use the new OpenAPI parser. This parser was introduced
+                for testing in 2.11 and will become the default soon.
+                """
+            ),
+        ),
+    ] = False
+
+
 class Settings(BaseSettings):
     """FastMCP settings."""
 
@@ -64,8 +83,35 @@ class Settings(BaseSettings):
         extra="ignore",
         env_nested_delimiter="__",
         nested_model_default_partial_update=True,
+        validate_assignment=True,
     )
 
+    def get_setting(self, attr: str) -> Any:
+        """
+        Get a setting. If the setting contains one or more `__`, it will be
+        treated as a nested setting.
+        """
+        settings = self
+        while "__" in attr:
+            parent_attr, attr = attr.split("__", 1)
+            if not hasattr(settings, parent_attr):
+                raise AttributeError(f"Setting {parent_attr} does not exist.")
+            settings = getattr(settings, parent_attr)
+        return getattr(settings, attr)
+
+    def set_setting(self, attr: str, value: Any) -> None:
+        """
+        Set a setting. If the setting contains one or more `__`, it will be
+        treated as a nested setting.
+        """
+        settings = self
+        while "__" in attr:
+            parent_attr, attr = attr.split("__", 1)
+            if not hasattr(settings, parent_attr):
+                raise AttributeError(f"Setting {parent_attr} does not exist.")
+            settings = getattr(settings, parent_attr)
+        setattr(settings, attr, value)
+
     @classmethod
     def settings_customise_sources(
         cls,
@@ -99,7 +145,18 @@ class Settings(BaseSettings):
     home: Path = Path.home() / ".fastmcp"
 
     test_mode: bool = False
+
     log_level: LOG_LEVEL = "INFO"
+
+    @field_validator("log_level", mode="before")
+    @classmethod
+    def normalize_log_level(cls, v):
+        if isinstance(v, str):
+            return v.upper()
+        return v
+
+    experimental: ExperimentalSettings = ExperimentalSettings()
+
     enable_rich_tracebacks: Annotated[
         bool,
         Field(
@@ -162,17 +219,6 @@ class Settings(BaseSettings):
         ),
     ] = None
 
-    @model_validator(mode="after")
-    def setup_logging(self) -> Self:
-        """Finalize the settings."""
-        from fastmcp.utilities.logging import configure_logging
-
-        configure_logging(
-            self.log_level, enable_rich_tracebacks=self.enable_rich_tracebacks
-        )
-
-        return self
-
     # HTTP settings
     host: str = "127.0.0.1"
     port: int = 8000
@@ -213,19 +259,23 @@ class Settings(BaseSettings):
     )
 
     # Auth settings
-    default_auth_provider: Annotated[
-        Literal["bearer_env"] | None,
+    server_auth: Annotated[
+        str | None,
         Field(
             description=inspect.cleandoc(
                 """
-                Configure the authentication provider. This setting is intended only to
-                be used for remote confirugation of providers that fully support
-                environment variable configuration.
+                Configure the authentication provider for the server. Auth
+                providers are registered with a specific key, and providing that
+                key here will cause the server to automatically configure the
+                provider from the environment.
 
                 If None, no automatic configuration will take place.
 
                 This setting is *always* overriden by any auth provider passed to the
                 FastMCP constructor.
+
+                Note that most auth providers require additional configuration
+                that must be provided via env vars.
                 """
             ),
         ),
@@ -258,6 +308,21 @@ class Settings(BaseSettings):
         ),
     ] = None
 
+    include_fastmcp_meta: Annotated[
+        bool,
+        Field(
+            default=True,
+            description=inspect.cleandoc(
+                """
+                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. 
+                """
+            ),
+        ),
+    ] = True
+
 
 def __getattr__(name: str):
     """
@@ -270,7 +335,7 @@ def __getattr__(name: str):
         # Deprecated in 2.10.2
         if settings.deprecation_warnings:
             warnings.warn(
-                "`from fastmcp.settings import settings` is deprecated. use `fasmtpc.settings` instead.",
+                "`from fastmcp.settings import settings` is deprecated. use `fastmcp.settings` instead.",
                 DeprecationWarning,
                 stacklevel=2,
             )

fastmcp/tools/tool.py

@@ -3,7 +3,15 @@ from __future__ import annotations
 import inspect
 from collections.abc import Callable
 from dataclasses import dataclass
-from typing import TYPE_CHECKING, Annotated, Any, Generic, Literal, TypeVar
+from typing import (
+    TYPE_CHECKING,
+    Annotated,
+    Any,
+    Generic,
+    Literal,
+    TypeVar,
+    get_type_hints,
+)
 
 import mcp.types
 import pydantic_core
@@ -122,7 +130,12 @@ class Tool(FastMCPComponent):
         except RuntimeError:
             pass  # No context available
 
-    def to_mcp_tool(self, **overrides: Any) -> MCPTool:
+    def to_mcp_tool(
+        self,
+        *,
+        include_fastmcp_meta: bool | None = None,
+        **overrides: Any,
+    ) -> MCPTool:
         if self.title:
             title = self.title
         elif self.annotations and self.annotations.title:
@@ -137,6 +150,7 @@ class Tool(FastMCPComponent):
             "outputSchema": self.output_schema,
             "annotations": self.annotations,
             "title": title,
+            "_meta": self.get_meta(include_fastmcp_meta=include_fastmcp_meta),
         }
         return MCPTool(**kwargs | overrides)
 
@@ -151,6 +165,7 @@ class Tool(FastMCPComponent):
         exclude_args: list[str] | None = None,
         output_schema: dict[str, Any] | None | NotSetT | Literal[False] = NotSet,
         serializer: Callable[[Any], str] | None = None,
+        meta: dict[str, Any] | None = None,
         enabled: bool | None = None,
     ) -> FunctionTool:
         """Create a Tool from a function."""
@@ -164,6 +179,7 @@ class Tool(FastMCPComponent):
             exclude_args=exclude_args,
             output_schema=output_schema,
             serializer=serializer,
+            meta=meta,
             enabled=enabled,
         )
 
@@ -185,12 +201,14 @@ class Tool(FastMCPComponent):
         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 = None,
+        description: str | None | NotSetT = NotSet,
         tags: set[str] | None = None,
         annotations: ToolAnnotations | None = None,
         output_schema: dict[str, Any] | None | Literal[False] = None,
         serializer: Callable[[Any], str] | None = None,
+        meta: dict[str, Any] | None | NotSetT = NotSet,
         enabled: bool | None = None,
     ) -> TransformedTool:
         from fastmcp.tools.tool_transform import TransformedTool
@@ -199,12 +217,14 @@ class Tool(FastMCPComponent):
             tool=tool,
             transform_fn=transform_fn,
             name=name,
+            title=title,
             transform_args=transform_args,
             description=description,
             tags=tags,
             annotations=annotations,
             output_schema=output_schema,
             serializer=serializer,
+            meta=meta,
             enabled=enabled,
         )
 
@@ -224,6 +244,7 @@ class FunctionTool(Tool):
         exclude_args: list[str] | None = None,
         output_schema: dict[str, Any] | None | NotSetT | Literal[False] = NotSet,
         serializer: Callable[[Any], str] | None = None,
+        meta: dict[str, Any] | None = None,
         enabled: bool | None = None,
     ) -> FunctionTool:
         """Create a Tool from a function."""
@@ -256,6 +277,7 @@ class FunctionTool(Tool):
             annotations=annotations,
             tags=tags or set(),
             serializer=serializer,
+            meta=meta,
             enabled=enabled if enabled is not None else True,
         )
 
@@ -369,7 +391,20 @@ class ParsedFunction:
         input_schema = compress_schema(input_schema, prune_params=prune_params)
 
         output_schema = None
-        output_type = inspect.signature(fn).return_annotation
+        # Get the return annotation from the signature
+        sig = inspect.signature(fn)
+        output_type = sig.return_annotation
+
+        # If the annotation is a string (from __future__ annotations), resolve it
+        if isinstance(output_type, str):
+            try:
+                # Use get_type_hints to resolve the return type
+                # include_extras=True preserves Annotated metadata
+                type_hints = get_type_hints(fn, include_extras=True)
+                output_type = type_hints.get("return", output_type)
+            except Exception:
+                # If resolution fails, keep the string annotation
+                pass
 
         if output_type not in (inspect._empty, None, Any, ...):
             # there are a variety of types that we don't want to attempt to
@@ -397,7 +432,7 @@ class ParsedFunction:
 
             try:
                 type_adapter = get_cached_typeadapter(clean_output_type)
-                base_schema = type_adapter.json_schema()
+                base_schema = type_adapter.json_schema(mode="serialization")
 
                 # Generate schema for wrapped type if it's non-object
                 # because MCP requires that output schemas are objects
@@ -408,7 +443,7 @@ class ParsedFunction:
                     # Use the wrapped result schema directly
                     wrapped_type = _WrappedResult[clean_output_type]
                     wrapped_adapter = get_cached_typeadapter(wrapped_type)
-                    output_schema = wrapped_adapter.json_schema()
+                    output_schema = wrapped_adapter.json_schema(mode="serialization")
                     output_schema["x-fastmcp-wrap-result"] = True
                 else:
                     output_schema = base_schema

fastmcp/tools/tool_manager.py

@@ -10,6 +10,10 @@ from fastmcp import settings
 from fastmcp.exceptions import NotFoundError, ToolError
 from fastmcp.settings import DuplicateBehavior
 from fastmcp.tools.tool import Tool, ToolResult
+from fastmcp.tools.tool_transform import (
+    ToolTransformConfig,
+    apply_transformations_to_tools,
+)
 from fastmcp.utilities.logging import get_logger
 
 if TYPE_CHECKING:
@@ -25,10 +29,12 @@ class ToolManager:
         self,
         duplicate_behavior: DuplicateBehavior | None = None,
         mask_error_details: bool | None = None,
+        transformations: dict[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 {}
 
         # Default to "warn" if None is provided
         if duplicate_behavior is None:
@@ -76,13 +82,19 @@ class ToolManager:
             except Exception as e:
                 # Skip failed mounts silently, matches existing behavior
                 logger.warning(
-                    f"Failed to get tools from mounted server '{mounted.prefix}': {e}"
+                    f"Failed to get tools from server: {mounted.server.name!r}, mounted at: {mounted.prefix!r}: {e}"
                 )
                 continue
 
         # Finally, add local tools, which always take precedence
         all_tools.update(self._tools)
-        return all_tools
+
+        transformed_tools = apply_transformations_to_tools(
+            tools=all_tools,
+            transformations=self.transformations,
+        )
+
+        return transformed_tools
 
     async def has_tool(self, key: str) -> bool:
         """Check if a tool exists."""
@@ -109,6 +121,15 @@ class ToolManager:
         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()
+        ]
+
     def add_tool_from_fn(
         self,
         fn: Callable[..., Any],
@@ -155,6 +176,21 @@ class ToolManager:
             self._tools[tool.key] = tool
         return tool
 
+    def add_tool_transformation(
+        self, tool_name: str, transformation: ToolTransformConfig
+    ) -> None:
+        """Add a tool transformation."""
+        self.transformations[tool_name] = transformation
+
+    def get_tool_transformation(self, tool_name: str) -> ToolTransformConfig | None:
+        """Get a tool transformation."""
+        return self.transformations.get(tool_name)
+
+    def remove_tool_transformation(self, tool_name: str) -> None:
+        """Remove a tool transformation."""
+        if tool_name in self.transformations:
+            del self.transformations[tool_name]
+
     def remove_tool(self, key: str) -> None:
         """Remove a tool from the server.
 
@@ -175,7 +211,7 @@ class ToolManager:
         filtered protocol path.
         """
         # 1. Check local tools first. The server will have already applied its filter.
-        if key in self._tools:
+        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")

fastmcp/tools/tool_transform.py

@@ -4,14 +4,23 @@ import inspect
 from collections.abc import Callable
 from contextvars import ContextVar
 from dataclasses import dataclass
-from typing import Any, Literal
+from typing import Annotated, Any, Literal
 
 from mcp.types import ToolAnnotations
 from pydantic import ConfigDict
+from pydantic.fields import Field
+from pydantic.functional_validators import BeforeValidator
 
 from fastmcp.tools.tool import ParsedFunction, Tool, ToolResult, _convert_to_content
+from fastmcp.utilities.components import _convert_set_default_none
+from fastmcp.utilities.json_schema import compress_schema
 from fastmcp.utilities.logging import get_logger
-from fastmcp.utilities.types import NotSet, NotSetT, get_cached_typeadapter
+from fastmcp.utilities.types import (
+    FastMCPBaseModel,
+    NotSet,
+    NotSetT,
+    get_cached_typeadapter,
+)
 
 logger = get_logger(__name__)
 
@@ -193,6 +202,30 @@ class ArgTransform:
             )
 
 
+class ArgTransformConfig(FastMCPBaseModel):
+    """A model for requesting a single argument transform."""
+
+    name: str | None = Field(default=None, description="The new name for the argument.")
+    description: str | None = Field(
+        default=None, description="The new description for the argument."
+    )
+    default: str | int | float | bool | None = Field(
+        default=None, description="The new default value for the argument."
+    )
+    hide: bool = Field(
+        default=False, description="Whether to hide the argument from the tool."
+    )
+    required: Literal[True] | None = Field(
+        default=None, description="Whether the argument is required."
+    )
+    examples: Any | None = Field(default=None, description="Examples of the argument.")
+
+    def to_arg_transform(self) -> ArgTransform:
+        """Convert the argument transform to a FastMCP argument transform."""
+
+        return ArgTransform(**self.model_dump(exclude_unset=True))  # pyright: ignore[reportAny]
+
+
 class TransformedTool(Tool):
     """A tool that is transformed from another tool.
 
@@ -325,13 +358,15 @@ class TransformedTool(Tool):
         cls,
         tool: Tool,
         name: str | None = None,
-        description: str | None = None,
+        title: str | None | NotSetT = NotSet,
+        description: str | None | NotSetT = NotSet,
         tags: set[str] | None = None,
         transform_fn: Callable[..., Any] | None = None,
         transform_args: dict[str, ArgTransform] | None = None,
         annotations: ToolAnnotations | None = None,
         output_schema: dict[str, Any] | None | Literal[False] = None,
         serializer: Callable[[Any], str] | None = None,
+        meta: dict[str, Any] | None | NotSetT = NotSet,
         enabled: bool | None = None,
     ) -> TransformedTool:
         """Create a transformed tool from a parent tool.
@@ -342,6 +377,7 @@ class TransformedTool(Tool):
                 to call the parent tool. Functions with **kwargs receive transformed
                 argument names.
             name: New name for the tool. Defaults to parent tool's name.
+            title: New title for the tool. Defaults to parent tool's title.
             transform_args: Optional transformations for parent tool arguments.
                 Only specified arguments are transformed, others pass through unchanged:
                 - Simple rename (str)
@@ -355,6 +391,10 @@ class TransformedTool(Tool):
                 - dict: Use custom output schema
                 - False: Disable output schema and structured outputs
             serializer: New serializer. Defaults to parent's serializer.
+            meta: Control meta information:
+                - NotSet (default): Inherit from parent tool
+                - dict: Use custom meta information
+                - None: Remove meta information
 
         Returns:
             TransformedTool with the specified transformations.
@@ -411,7 +451,7 @@ class TransformedTool(Tool):
         if unknown_args:
             raise ValueError(
                 f"Unknown arguments in transform_args: {', '.join(sorted(unknown_args))}. "
-                f"Parent tool has: {', '.join(sorted(parent_params))}"
+                f"Parent tool `{tool.name}` has: {', '.join(sorted(parent_params))}"
             )
 
         # Always create the forwarding transform
@@ -506,19 +546,26 @@ class TransformedTool(Tool):
                     f"{', '.join(sorted(duplicates))}"
                 )
 
-        final_description = description if description is not None else tool.description
+        final_name = name or tool.name
+        final_description = (
+            description if not isinstance(description, NotSetT) else tool.description
+        )
+        final_title = title if not isinstance(title, NotSetT) else tool.title
+        final_meta = meta if not isinstance(meta, NotSetT) else tool.meta
 
         transformed_tool = cls(
             fn=final_fn,
             forwarding_fn=forwarding_fn,
             parent_tool=tool,
-            name=name or tool.name,
+            name=final_name,
+            title=final_title,
             description=final_description,
             parameters=final_schema,
             output_schema=final_output_schema,
             tags=tags or tool.tags,
             annotations=annotations or tool.annotations,
             serializer=serializer or tool.serializer,
+            meta=final_meta,
             transform_args=transform_args,
             enabled=enabled if enabled is not None else True,
         )
@@ -606,6 +653,7 @@ class TransformedTool(Tool):
 
         if parent_defs:
             schema["$defs"] = parent_defs
+            schema = compress_schema(schema, prune_defs=True)
 
         # Create forwarding function that closes over everything it needs
         async def _forward(**kwargs):
@@ -791,3 +839,71 @@ class TransformedTool(Tool):
         return any(
             p.kind == inspect.Parameter.VAR_KEYWORD for p in sig.parameters.values()
         )
+
+
+class ToolTransformConfig(FastMCPBaseModel):
+    """Provides a way to transform a tool."""
+
+    name: str | None = Field(default=None, description="The new name for the tool.")
+
+    title: str | None = Field(
+        default=None,
+        description="The new title of the tool.",
+    )
+    description: str | None = Field(
+        default=None,
+        description="The new description of the tool.",
+    )
+    tags: Annotated[set[str], BeforeValidator(_convert_set_default_none)] = Field(
+        default_factory=set,
+        description="The new tags for the tool.",
+    )
+    meta: dict[str, Any] | None = Field(
+        default=None,
+        description="The new meta information for the tool.",
+    )
+
+    enabled: bool = Field(
+        default=True,
+        description="Whether the tool is enabled.",
+    )
+
+    arguments: dict[str, ArgTransformConfig] = Field(
+        default_factory=dict,
+        description="A dictionary of argument transforms to apply to the tool.",
+    )
+
+    def apply(self, tool: Tool) -> TransformedTool:
+        """Create a TransformedTool from a provided tool and this transformation configuration."""
+
+        tool_changes: dict[str, Any] = self.model_dump(
+            exclude_unset=True, exclude={"arguments"}
+        )
+
+        return TransformedTool.from_tool(
+            tool=tool,
+            **tool_changes,
+            transform_args={k: v.to_arg_transform() for k, v in self.arguments.items()},
+        )
+
+
+def apply_transformations_to_tools(
+    tools: dict[str, Tool],
+    transformations: dict[str, ToolTransformConfig],
+) -> dict[str, Tool]:
+    """Apply a list of transformations to a list of tools. Tools that do not have any transforamtions
+    are left unchanged.
+    """
+
+    transformed_tools: dict[str, Tool] = {}
+
+    for tool_name, tool in tools.items():
+        if transformation := transformations.get(tool_name):
+            transformed_tools[transformation.name or tool_name] = transformation.apply(
+                tool
+            )
+            continue
+
+        transformed_tools[tool_name] = tool
+
+    return transformed_tools

fastmcp/utilities/components.py

@@ -1,14 +1,21 @@
+from __future__ import annotations
+
 from collections.abc import Sequence
-from typing import Annotated, Any, TypeVar
+from typing import Annotated, Any, TypedDict, TypeVar
 
 from pydantic import BeforeValidator, Field, PrivateAttr
 from typing_extensions import Self
 
+import fastmcp
 from fastmcp.utilities.types import FastMCPBaseModel
 
 T = TypeVar("T")
 
 
+class FastMCPMeta(TypedDict, total=False):
+    tags: list[str]
+
+
 def _convert_set_default_none(maybe_set: set[T] | Sequence[T] | None) -> set[T]:
     """Convert a sequence to a set, defaulting to an empty set if None."""
     if maybe_set is None:
@@ -36,7 +43,9 @@ class FastMCPComponent(FastMCPBaseModel):
         default_factory=set,
         description="Tags for the component.",
     )
-
+    meta: dict[str, Any] | None = Field(
+        default=None, description="Meta information about the component"
+    )
     enabled: bool = Field(
         default=True,
         description="Whether the component is enabled.",
@@ -58,6 +67,30 @@ class FastMCPComponent(FastMCPBaseModel):
         """
         return self._key or self.name
 
+    def get_meta(
+        self, include_fastmcp_meta: bool | None = None
+    ) -> dict[str, Any] | None:
+        """
+        Get the meta information about the component.
+
+        If include_fastmcp_meta is True, a `_fastmcp` key will be added to the
+        meta, containing a `tags` field with the tags of the component.
+        """
+
+        if include_fastmcp_meta is None:
+            include_fastmcp_meta = fastmcp.settings.include_fastmcp_meta
+
+        meta = self.meta or {}
+
+        if include_fastmcp_meta:
+            fastmcp_meta = FastMCPMeta(tags=sorted(self.tags))
+            # overwrite any existing _fastmcp meta with keys from the new one
+            if upstream_meta := meta.get("_fastmcp"):
+                fastmcp_meta = upstream_meta | fastmcp_meta
+            meta["_fastmcp"] = fastmcp_meta
+
+        return meta or None
+
     def with_key(self, key: str) -> Self:
         return self.model_copy(update={"_key": key})