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

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,
         )
 
@@ -192,6 +208,7 @@ class Tool(FastMCPComponent):
         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
@@ -207,6 +224,7 @@ class Tool(FastMCPComponent):
             annotations=annotations,
             output_schema=output_schema,
             serializer=serializer,
+            meta=meta,
             enabled=enabled,
         )
 
@@ -226,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."""
@@ -258,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,
         )
 
@@ -371,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

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:
@@ -82,7 +88,13 @@ class ToolManager:
 
         # 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.
 
@@ -333,6 +366,7 @@ class TransformedTool(Tool):
         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.
@@ -357,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.
@@ -413,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
@@ -513,6 +551,7 @@ class TransformedTool(Tool):
             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,
@@ -526,6 +565,7 @@ class TransformedTool(Tool):
             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,
         )
@@ -613,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):
@@ -798,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})