fastmcp 2.14.4__py3-none-any.whl → 3.0.0b1__py3-none-any.whl

fastmcp/tools/tool_transform.py

@@ -1,6 +1,7 @@
 from __future__ import annotations
 
 import inspect
+import warnings
 from collections.abc import Callable
 from contextvars import ContextVar
 from copy import deepcopy
@@ -13,7 +14,9 @@ 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
+import fastmcp
+from fastmcp.tools.function_parsing import ParsedFunction
+from fastmcp.tools.tool import 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
@@ -28,7 +31,7 @@ logger = get_logger(__name__)
 
 
 # Context variable to store current transformed tool
-_current_tool: ContextVar[TransformedTool | None] = ContextVar(  # type: ignore[assignment]
+_current_tool: ContextVar[TransformedTool | None] = ContextVar(
     "_current_tool", default=None
 )
 
@@ -364,6 +367,7 @@ class TransformedTool(Tool):
         cls,
         tool: Tool,
         name: str | None = None,
+        version: str | NotSetT | None = NotSet,
         title: str | NotSetT | None = NotSet,
         description: str | NotSetT | None = NotSet,
         tags: set[str] | None = None,
@@ -371,9 +375,8 @@ class TransformedTool(Tool):
         transform_args: dict[str, ArgTransform] | None = None,
         annotations: ToolAnnotations | NotSetT | None = NotSet,
         output_schema: dict[str, Any] | NotSetT | None = NotSet,
-        serializer: Callable[[Any], str] | NotSetT | None = NotSet,
+        serializer: Callable[[Any], str] | NotSetT | None = NotSet,  # Deprecated
         meta: dict[str, Any] | NotSetT | None = NotSet,
-        enabled: bool | None = None,
     ) -> TransformedTool:
         """Create a transformed tool from a parent tool.
 
@@ -383,6 +386,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.
+            version: New version for the tool. Defaults to parent tool's version.
             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:
@@ -396,7 +400,7 @@ class TransformedTool(Tool):
                 - None (default): Inherit from transform_fn if available, then parent tool
                 - dict: Use custom output schema
                 - False: Disable output schema and structured outputs
-            serializer: New serializer. Defaults to parent's serializer.
+            serializer: Deprecated. Return ToolResult from your tools for full control over serialization.
             meta: Control meta information:
                 - NotSet (default): Inherit from parent tool
                 - dict: Use custom meta information
@@ -449,6 +453,18 @@ class TransformedTool(Tool):
                 )
             ```
         """
+        if (
+            serializer is not NotSet
+            and serializer is not None
+            and fastmcp.settings.deprecation_warnings
+        ):
+            warnings.warn(
+                "The `serializer` parameter is deprecated. "
+                "Return ToolResult from your tools for full control over serialization. "
+                "See https://gofastmcp.com/servers/tools#custom-serialization for migration examples.",
+                DeprecationWarning,
+                stacklevel=2,
+            )
         transform_args = transform_args or {}
 
         if transform_fn is not None:
@@ -555,6 +571,7 @@ class TransformedTool(Tool):
                 )
 
         final_name = name or tool.name
+        final_version = version if not isinstance(version, NotSetT) else tool.version
         final_description = (
             description if not isinstance(description, NotSetT) else tool.description
         )
@@ -566,13 +583,13 @@ class TransformedTool(Tool):
         final_serializer = (
             serializer if not isinstance(serializer, NotSetT) else tool.serializer
         )
-        final_enabled = enabled if enabled is not None else tool.enabled
 
         transformed_tool = cls(
             fn=final_fn,
             forwarding_fn=forwarding_fn,
             parent_tool=tool,
             name=final_name,
+            version=final_version,
             title=final_title,
             description=final_description,
             parameters=final_schema,
@@ -582,7 +599,7 @@ class TransformedTool(Tool):
             serializer=final_serializer,
             meta=final_meta,
             transform_args=transform_args,
-            enabled=final_enabled,
+            auth=tool.auth,
         )
 
         return transformed_tool
@@ -669,7 +686,7 @@ class TransformedTool(Tool):
 
         if parent_defs:
             schema["$defs"] = parent_defs
-            schema = compress_schema(schema, prune_defs=True)
+            schema = compress_schema(schema)
 
         # Create forwarding function that closes over everything it needs
         async def _forward(**kwargs: Any):
@@ -852,7 +869,7 @@ class TransformedTool(Tool):
 
         if merged_defs:
             result["$defs"] = merged_defs
-            result = compress_schema(result, prune_defs=True)
+            result = compress_schema(result)
 
         return result
 
@@ -879,7 +896,9 @@ class ToolTransformConfig(FastMCPBaseModel):
     """Provides a way to transform a tool."""
 
     name: str | None = Field(default=None, description="The new name for the tool.")
-
+    version: str | None = Field(
+        default=None, description="The new version for the tool."
+    )
     title: str | None = Field(
         default=None,
         description="The new title of the tool.",
@@ -897,11 +916,6 @@ class ToolTransformConfig(FastMCPBaseModel):
         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.",
@@ -927,17 +941,20 @@ def apply_transformations_to_tools(
 ) -> dict[str, Tool]:
     """Apply a list of transformations to a list of tools. Tools that do not have any transformations
     are left unchanged.
+
+    Note: tools dict is keyed by prefixed key (e.g., "tool:my_tool"),
+    but transformations are keyed by tool name (e.g., "my_tool").
     """
 
     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
-            )
+    for tool_key, tool in tools.items():
+        # Look up transformation by tool name, not prefixed key
+        if transformation := transformations.get(tool.name):
+            transformed = transformation.apply(tool)
+            transformed_tools[transformed.key] = transformed
             continue
 
-        transformed_tools[tool_name] = tool
+        transformed_tools[tool_key] = tool
 
     return transformed_tools

fastmcp/utilities/async_utils.py

@@ -0,0 +1,69 @@
+"""Async utilities for FastMCP."""
+
+import functools
+from collections.abc import Awaitable, Callable
+from typing import Any, Literal, TypeVar, overload
+
+import anyio
+from anyio.to_thread import run_sync as run_sync_in_threadpool
+
+T = TypeVar("T")
+
+
+async def call_sync_fn_in_threadpool(
+    fn: Callable[..., Any], *args: Any, **kwargs: Any
+) -> Any:
+    """Call a sync function in a threadpool to avoid blocking the event loop.
+
+    Uses anyio.to_thread.run_sync which properly propagates contextvars,
+    making this safe for functions that depend on context (like dependency injection).
+    """
+    return await run_sync_in_threadpool(functools.partial(fn, *args, **kwargs))
+
+
+@overload
+async def gather(
+    *awaitables: Awaitable[T],
+    return_exceptions: Literal[True],
+) -> list[T | BaseException]: ...
+
+
+@overload
+async def gather(
+    *awaitables: Awaitable[T],
+    return_exceptions: Literal[False] = ...,
+) -> list[T]: ...
+
+
+async def gather(
+    *awaitables: Awaitable[T],
+    return_exceptions: bool = False,
+) -> list[T] | list[T | BaseException]:
+    """Run awaitables concurrently and return results in order.
+
+    Uses anyio TaskGroup for structured concurrency.
+
+    Args:
+        *awaitables: Awaitables to run concurrently
+        return_exceptions: If True, exceptions are returned in results.
+                          If False, first exception cancels all and raises.
+
+    Returns:
+        List of results in the same order as input awaitables.
+    """
+    results: list[T | BaseException] = [None] * len(awaitables)  # type: ignore[assignment]
+
+    async def run_at(i: int, aw: Awaitable[T]) -> None:
+        try:
+            results[i] = await aw
+        except BaseException as e:
+            if return_exceptions:
+                results[i] = e
+            else:
+                raise
+
+    async with anyio.create_task_group() as tg:
+        for i, aw in enumerate(awaitables):
+            tg.start_soon(run_at, i, aw)
+
+    return results

fastmcp/utilities/components.py

@@ -1,20 +1,37 @@
 from __future__ import annotations
 
 from collections.abc import Sequence
-from typing import Annotated, Any, TypedDict, cast
+from typing import TYPE_CHECKING, Annotated, Any, ClassVar, TypedDict, cast
 
 from mcp.types import Icon
-from pydantic import BeforeValidator, Field, PrivateAttr
+from pydantic import BeforeValidator, Field
 from typing_extensions import Self, TypeVar
 
-import fastmcp
+from fastmcp.server.tasks.config import TaskConfig
 from fastmcp.utilities.types import FastMCPBaseModel
 
+if TYPE_CHECKING:
+    from docket import Docket
+    from docket.execution import Execution
+
 T = TypeVar("T", default=Any)
 
 
 class FastMCPMeta(TypedDict, total=False):
     tags: list[str]
+    version: str
+    versions: list[str]
+
+
+def get_fastmcp_metadata(meta: dict[str, Any] | None) -> FastMCPMeta:
+    """Extract FastMCP metadata from a component's meta dict.
+
+    Handles both the current `fastmcp` namespace and the legacy `_fastmcp`
+    namespace for compatibility with older FastMCP servers.
+    """
+    if not meta:
+        return {}
+    return cast(FastMCPMeta, meta.get("fastmcp") or meta.get("_fastmcp") or {})
 
 
 def _convert_set_default_none(maybe_set: set[T] | Sequence[T] | None) -> set[T]:
@@ -26,12 +43,47 @@ def _convert_set_default_none(maybe_set: set[T] | Sequence[T] | None) -> set[T]:
     return set(maybe_set)
 
 
+def _coerce_version(v: str | int | None) -> str | None:
+    """Coerce version to string, accepting int or str.
+
+    Raises ValueError if version contains '@' (used as key delimiter).
+    """
+    if v is None:
+        return None
+    version = str(v)
+    if "@" in version:
+        raise ValueError(
+            f"Version string cannot contain '@' (used as key delimiter): {version!r}"
+        )
+    return version
+
+
 class FastMCPComponent(FastMCPBaseModel):
     """Base class for FastMCP tools, prompts, resources, and resource templates."""
 
+    KEY_PREFIX: ClassVar[str] = ""
+
+    def __init_subclass__(cls, **kwargs: Any) -> None:
+        super().__init_subclass__(**kwargs)
+        # Warn if a subclass doesn't define KEY_PREFIX (inherited or its own)
+        if not cls.KEY_PREFIX:
+            import warnings
+
+            warnings.warn(
+                f"{cls.__name__} does not define KEY_PREFIX. "
+                f"Component keys will not be type-prefixed, which may cause collisions.",
+                UserWarning,
+                stacklevel=2,
+            )
+
     name: str = Field(
         description="The name of the component.",
     )
+    version: Annotated[str | None, BeforeValidator(_coerce_version)] = Field(
+        default=None,
+        description="Optional version identifier for this component. "
+        "Multiple versions of the same component (same name) can coexist.",
+    )
     title: str | None = Field(
         default=None,
         description="The title of the component for display purposes.",
@@ -51,73 +103,68 @@ class FastMCPComponent(FastMCPBaseModel):
     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.",
-    )
+    task_config: Annotated[
+        TaskConfig,
+        Field(description="Background task execution configuration (SEP-1686)."),
+    ] = Field(default_factory=lambda: TaskConfig(mode="forbidden"))
+
+    @classmethod
+    def make_key(cls, identifier: str) -> str:
+        """Construct the lookup key for this component type.
 
-    _key: str | None = PrivateAttr()
+        Args:
+            identifier: The raw identifier (name for tools/prompts, uri for resources)
 
-    def __init__(self, *, key: str | None = None, **kwargs: Any) -> None:
-        super().__init__(**kwargs)
-        self._key = key
+        Returns:
+            A prefixed key like "tool:name" or "resource:uri"
+        """
+        if cls.KEY_PREFIX:
+            return f"{cls.KEY_PREFIX}:{identifier}"
+        return identifier
 
     @property
     def key(self) -> str:
-        """
-        The key of the component. This is used for internal bookkeeping
-        and may reflect e.g. prefixes or other identifiers. You should not depend on
-        keys having a certain value, as the same tool loaded from different
-        hierarchies of servers may have different keys.
-        """
-        return self._key or self.name
+        """The globally unique lookup key for this component.
 
-    def get_meta(
-        self, include_fastmcp_meta: bool | None = None
-    ) -> dict[str, Any] | None:
-        """
-        Get the meta information about the component.
+        Format: "{key_prefix}:{identifier}@{version}" or "{key_prefix}:{identifier}@"
+        e.g. "tool:my_tool@v2", "tool:my_tool@", "resource:file://x.txt@"
 
-        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.
+        The @ suffix is ALWAYS present to enable unambiguous parsing of keys
+        (URIs may contain @ characters, so we always include the delimiter).
+
+        Subclasses should override this to use their specific identifier.
+        Base implementation uses name.
         """
+        base_key = self.make_key(self.name)
+        return f"{base_key}@{self.version or ''}"
 
-        if include_fastmcp_meta is None:
-            include_fastmcp_meta = fastmcp.settings.include_fastmcp_meta
+    def get_meta(self) -> dict[str, Any]:
+        """Get the meta information about the component.
 
-        meta = self.meta or {}
+        Returns a dict that always includes a `fastmcp` key containing:
+        - `tags`: sorted list of component tags
+        - `version`: component version (only if set)
 
-        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
+        Internal keys (prefixed with `_`) are stripped from the fastmcp namespace.
+        """
+        meta = dict(self.meta) if self.meta else {}
 
-        return meta or None
+        fastmcp_meta: FastMCPMeta = {"tags": sorted(self.tags)}
+        if self.version is not None:
+            fastmcp_meta["version"] = self.version
 
-    def model_copy(  # type: ignore[override]
-        self,
-        *,
-        update: dict[str, Any] | None = None,
-        deep: bool = False,
-        key: str | None = None,
-    ) -> Self:
-        """
-        Create a copy of the component.
+        # Merge with upstream fastmcp meta, stripping internal keys
+        if (upstream_meta := meta.get("fastmcp")) is not None:
+            if not isinstance(upstream_meta, dict):
+                raise TypeError("meta['fastmcp'] must be a dict")
+            # Filter out internal keys (e.g., _internal used for enabled state)
+            public_upstream = {
+                k: v for k, v in upstream_meta.items() if not k.startswith("_")
+            }
+            fastmcp_meta = cast(FastMCPMeta, public_upstream | fastmcp_meta)
+        meta["fastmcp"] = fastmcp_meta
 
-        Args:
-            update: A dictionary of fields to update.
-            deep: Whether to deep copy the component.
-            key: The key to use for the copy.
-        """
-        # `model_copy` has an `update` parameter but it doesn't work for certain private attributes
-        # https://github.com/pydantic/pydantic/issues/12116
-        # So we manually set the private attribute here instead, such as _key
-        copy = super().model_copy(update=update, deep=deep)
-        if key is not None:
-            copy._key = key
-        return cast(Self, copy)
+        return meta
 
     def __eq__(self, other: object) -> bool:
         if type(self) is not type(other):
@@ -127,55 +174,69 @@ class FastMCPComponent(FastMCPBaseModel):
         return self.model_dump() == other.model_dump()
 
     def __repr__(self) -> str:
-        return f"{self.__class__.__name__}(name={self.name!r}, title={self.title!r}, description={self.description!r}, tags={self.tags}, enabled={self.enabled})"
+        parts = [f"name={self.name!r}"]
+        if self.version:
+            parts.append(f"version={self.version!r}")
+        parts.extend(
+            [
+                f"title={self.title!r}",
+                f"description={self.description!r}",
+                f"tags={self.tags}",
+            ]
+        )
+        return f"{self.__class__.__name__}({', '.join(parts)})"
 
     def enable(self) -> None:
-        """Enable the component."""
-        self.enabled = True
+        """Removed in 3.0. Use server.enable(keys=[...]) instead."""
+        raise NotImplementedError(
+            f"Component.enable() was removed in FastMCP 3.0. "
+            f"Use server.enable(keys=['{self.key}']) instead."
+        )
 
     def disable(self) -> None:
-        """Disable the component."""
-        self.enabled = False
+        """Removed in 3.0. Use server.disable(keys=[...]) instead."""
+        raise NotImplementedError(
+            f"Component.disable() was removed in FastMCP 3.0. "
+            f"Use server.disable(keys=['{self.key}']) instead."
+        )
 
     def copy(self) -> Self:  # type: ignore[override]
         """Create a copy of the component."""
         return self.model_copy()
 
+    def register_with_docket(self, docket: Docket) -> None:
+        """Register this component with docket for background execution.
 
-class MirroredComponent(FastMCPComponent):
-    """Base class for components that are mirrored from a remote server.
-
-    Mirrored components cannot be enabled or disabled directly. Call copy() first
-    to create a local version you can modify.
-    """
+        No-ops if task_config.mode is "forbidden". Subclasses override to
+        register their callable (self.run, self.read, self.render, or self.fn).
+        """
+        # Base implementation: no-op (subclasses override)
 
-    _mirrored: bool = PrivateAttr(default=False)
+    async def add_to_docket(
+        self, docket: Docket, *args: Any, **kwargs: Any
+    ) -> Execution:
+        """Schedule this component for background execution via docket.
 
-    def __init__(self, *, _mirrored: bool = False, **kwargs: Any) -> None:
-        super().__init__(**kwargs)
-        self._mirrored = _mirrored
+        Subclasses override this to handle their specific calling conventions:
+        - Tool: add_to_docket(docket, arguments: dict, **kwargs)
+        - Resource: add_to_docket(docket, **kwargs)
+        - ResourceTemplate: add_to_docket(docket, params: dict, **kwargs)
+        - Prompt: add_to_docket(docket, arguments: dict | None, **kwargs)
 
-    def enable(self) -> None:
-        """Enable the component."""
-        if self._mirrored:
+        The **kwargs are passed through to docket.add() (e.g., key=task_key).
+        """
+        if not self.task_config.supports_tasks():
             raise RuntimeError(
-                f"Cannot enable mirrored component '{self.name}'. "
-                f"Create a local copy first with {self.name}.copy() and add it to your server."
+                f"Cannot add {self.__class__.__name__} '{self.name}' to docket: "
+                f"task execution not supported"
             )
-        super().enable()
+        raise NotImplementedError(
+            f"{self.__class__.__name__} does not implement add_to_docket()"
+        )
 
-    def disable(self) -> None:
-        """Disable the component."""
-        if self._mirrored:
-            raise RuntimeError(
-                f"Cannot disable mirrored component '{self.name}'. "
-                f"Create a local copy first with {self.name}.copy() and add it to your server."
-            )
-        super().disable()
+    def get_span_attributes(self) -> dict[str, Any]:
+        """Return span attributes for telemetry.
 
-    def copy(self) -> Self:  # type: ignore[override]
-        """Create a copy of the component that can be modified."""
-        # Create a copy and mark it as not mirrored
-        copied = self.model_copy()
-        copied._mirrored = False
-        return copied
+        Subclasses should call super() and merge their specific attributes.
+        """
+        return {"fastmcp.component.key": self.key}