fastmcp 2.13.3__py3-none-any.whl → 2.14.1__py3-none-any.whl

fastmcp/settings.py

@@ -3,19 +3,16 @@ from __future__ import annotations as _annotations
 import inspect
 import os
 import warnings
+from datetime import timedelta
 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 (
     BaseSettings,
-    EnvSettingsSource,
-    PydanticBaseSettingsSource,
     SettingsConfigDict,
 )
-from typing_extensions import Self
 
 from fastmcp.utilities.logging import get_logger
 
@@ -33,61 +30,123 @@ if TYPE_CHECKING:
     from fastmcp.server.auth.auth import AuthProvider
 
 
-class ExtendedEnvSettingsSource(EnvSettingsSource):
-    """
-    A special EnvSettingsSource that allows for multiple env var prefixes to be used.
+class DocketSettings(BaseSettings):
+    """Docket worker configuration."""
 
-    Raises a deprecation warning if the old `FASTMCP_SERVER_` prefix is used.
-    """
+    model_config = SettingsConfigDict(
+        env_prefix="FASTMCP_DOCKET_",
+        extra="ignore",
+    )
 
-    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
+    name: Annotated[
+        str,
+        Field(
+            description=inspect.cleandoc(
+                """
+                Name for the Docket queue. All servers/workers sharing the same name
+                and backend URL will share a task queue.
+                """
+            ),
+        ),
+    ] = "fastmcp"
 
-        return super().get_field_value(field, field_name)
+    url: Annotated[
+        str,
+        Field(
+            description=inspect.cleandoc(
+                """
+                URL for the Docket backend. Supports:
+                - memory:// - In-memory backend (single process only)
+                - redis://host:port/db - Redis/Valkey backend (distributed, multi-process)
 
+                Example: redis://localhost:6379/0
 
-class ExtendedSettingsConfigDict(SettingsConfigDict, total=False):
-    env_prefixes: list[str] | None
+                Default is memory:// for single-process scenarios. Use Redis or Valkey
+                when coordinating tasks across multiple processes (e.g., additional
+                workers via the fastmcp tasks CLI).
+                """
+            ),
+        ),
+    ] = "memory://"
 
+    worker_name: Annotated[
+        str | None,
+        Field(
+            description=inspect.cleandoc(
+                """
+                Name for the Docket worker. If None, Docket will auto-generate
+                a unique worker name.
+                """
+            ),
+        ),
+    ] = None
 
-class ExperimentalSettings(BaseSettings):
-    model_config = SettingsConfigDict(
-        env_prefix="FASTMCP_EXPERIMENTAL_",
-        extra="ignore",
-    )
+    concurrency: Annotated[
+        int,
+        Field(
+            description=inspect.cleandoc(
+                """
+                Maximum number of tasks the worker can process concurrently.
+                """
+            ),
+        ),
+    ] = 10
 
-    enable_new_openapi_parser: Annotated[
-        bool,
+    redelivery_timeout: Annotated[
+        timedelta,
         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.
+                Task redelivery timeout. If a worker doesn't complete
+                a task within this time, the task will be redelivered to another
+                worker.
                 """
             ),
         ),
-    ] = False
+    ] = timedelta(seconds=300)
+
+    reconnection_delay: Annotated[
+        timedelta,
+        Field(
+            description=inspect.cleandoc(
+                """
+                Delay between reconnection attempts when the worker
+                loses connection to the Docket backend.
+                """
+            ),
+        ),
+    ] = timedelta(seconds=5)
+
+
+class ExperimentalSettings(BaseSettings):
+    model_config = SettingsConfigDict(
+        env_prefix="FASTMCP_EXPERIMENTAL_",
+        extra="ignore",
+        validate_assignment=True,
+    )
+
+    # Deprecated in 2.14 - the new OpenAPI parser is now the default and only parser
+    enable_new_openapi_parser: bool = False
+
+    @field_validator("enable_new_openapi_parser", mode="after")
+    @classmethod
+    def _warn_openapi_parser_deprecated(cls, v: bool) -> bool:
+        if v:
+            warnings.warn(
+                "enable_new_openapi_parser is deprecated. "
+                "The new OpenAPI parser is now the default (and only) parser. "
+                "You can remove this setting.",
+                DeprecationWarning,
+                stacklevel=2,
+            )
+        return v
 
 
 class Settings(BaseSettings):
     """FastMCP settings."""
 
-    model_config = ExtendedSettingsConfigDict(
-        env_prefixes=["FASTMCP_", "FASTMCP_SERVER_"],
+    model_config = SettingsConfigDict(
+        env_prefix="FASTMCP_",
         env_file=ENV_FILE,
         extra="ignore",
         env_nested_delimiter="__",
@@ -121,36 +180,6 @@ class Settings(BaseSettings):
             settings = getattr(settings, parent_attr)
         setattr(settings, attr, value)
 
-    @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(user_data_dir("fastmcp", appauthor=False))
 
     test_mode: bool = False
@@ -167,6 +196,8 @@ class Settings(BaseSettings):
 
     experimental: ExperimentalSettings = ExperimentalSettings()
 
+    docket: DocketSettings = DocketSettings()
+
     enable_rich_tracebacks: Annotated[
         bool,
         Field(
@@ -207,19 +238,6 @@ class Settings(BaseSettings):
         ),
     ] = True
 
-    resource_prefix_format: Annotated[
-        Literal["protocol", "path"],
-        Field(
-            description=inspect.cleandoc(
-                """
-                When perfixing a resource URI, either use path formatting (resource://prefix/path)
-                or protocol formatting (prefix+resource://path). Protocol formatting was the default in FastMCP < 2.4;
-                path formatting is current default.
-                """
-            ),
-        ),
-    ] = "path"
-
     client_init_timeout: Annotated[
         float | None,
         Field(
@@ -392,23 +410,3 @@ class Settings(BaseSettings):
         auth_class = type_adapter.validate_python(self.server_auth)
 
         return auth_class
-
-
-def __getattr__(name: str):
-    """
-    Used to deprecate the module-level Image class; can be removed once it is no longer imported to root.
-    """
-    if name == "settings":
-        import fastmcp
-
-        settings = fastmcp.settings
-        # Deprecated in 2.10.2
-        if settings.deprecation_warnings:
-            warnings.warn(
-                "`from fastmcp.settings import settings` is deprecated. use `fastmcp.settings` instead.",
-                DeprecationWarning,
-                stacklevel=2,
-            )
-        return settings
-
-    raise AttributeError(f"module '{__name__}' has no attribute '{name}'")

fastmcp/tools/tool.py

@@ -9,20 +9,28 @@ from typing import (
     Annotated,
     Any,
     Generic,
-    Literal,
     TypeAlias,
     get_type_hints,
 )
 
 import mcp.types
 import pydantic_core
-from mcp.types import CallToolResult, ContentBlock, Icon, TextContent, ToolAnnotations
+from mcp.shared.tool_name_validation import validate_and_warn_tool_name
+from mcp.types import (
+    CallToolResult,
+    ContentBlock,
+    Icon,
+    TextContent,
+    ToolAnnotations,
+    ToolExecution,
+)
 from mcp.types import Tool as MCPTool
-from pydantic import Field, PydanticSchemaGenerationError
+from pydantic import Field, PydanticSchemaGenerationError, model_validator
 from typing_extensions import TypeVar
 
 import fastmcp
-from fastmcp.server.dependencies import get_context
+from fastmcp.server.dependencies import get_context, without_injected_parameters
+from fastmcp.server.tasks.config import TaskConfig
 from fastmcp.utilities.components import FastMCPComponent
 from fastmcp.utilities.json_schema import compress_schema
 from fastmcp.utilities.logging import get_logger
@@ -33,7 +41,6 @@ from fastmcp.utilities.types import (
     NotSet,
     NotSetT,
     create_function_without_params,
-    find_kwarg_by_type,
     get_cached_typeadapter,
     replace_type,
 )
@@ -126,11 +133,21 @@ class Tool(FastMCPComponent):
         ToolAnnotations | None,
         Field(description="Additional annotations about the tool"),
     ] = None
+    execution: Annotated[
+        ToolExecution | None,
+        Field(description="Task execution configuration (SEP-1686)"),
+    ] = None
     serializer: Annotated[
         ToolResultSerializerType | None,
         Field(description="Optional custom serializer for tool results"),
     ] = None
 
+    @model_validator(mode="after")
+    def _validate_tool_name(self) -> Tool:
+        """Validate tool name according to MCP specification (SEP-986)."""
+        validate_and_warn_tool_name(self.name)
+        return self
+
     def enable(self) -> None:
         super().enable()
         try:
@@ -169,6 +186,7 @@ class Tool(FastMCPComponent):
             outputSchema=overrides.get("outputSchema", self.output_schema),
             icons=overrides.get("icons", self.icons),
             annotations=overrides.get("annotations", self.annotations),
+            execution=overrides.get("execution", self.execution),
             _meta=overrides.get(
                 "_meta", self.get_meta(include_fastmcp_meta=include_fastmcp_meta)
             ),
@@ -184,10 +202,11 @@ class Tool(FastMCPComponent):
         tags: set[str] | None = None,
         annotations: ToolAnnotations | None = None,
         exclude_args: list[str] | None = None,
-        output_schema: dict[str, Any] | Literal[False] | NotSetT | None = NotSet,
+        output_schema: dict[str, Any] | NotSetT | None = NotSet,
         serializer: ToolResultSerializerType | None = None,
         meta: dict[str, Any] | None = None,
         enabled: bool | None = None,
+        task: bool | TaskConfig | None = None,
     ) -> FunctionTool:
         """Create a Tool from a function."""
         return FunctionTool.from_function(
@@ -203,6 +222,7 @@ class Tool(FastMCPComponent):
             serializer=serializer,
             meta=meta,
             enabled=enabled,
+            task=task,
         )
 
     async def run(self, arguments: dict[str, Any]) -> ToolResult:
@@ -227,7 +247,7 @@ class Tool(FastMCPComponent):
         description: str | NotSetT | None = NotSet,
         tags: set[str] | None = None,
         annotations: ToolAnnotations | NotSetT | None = NotSet,
-        output_schema: dict[str, Any] | Literal[False] | NotSetT | None = NotSet,
+        output_schema: dict[str, Any] | NotSetT | None = NotSet,
         serializer: ToolResultSerializerType | None = None,
         meta: dict[str, Any] | NotSetT | None = NotSet,
         transform_args: dict[str, ArgTransform] | None = None,
@@ -254,6 +274,32 @@ class Tool(FastMCPComponent):
 
 class FunctionTool(Tool):
     fn: Callable[..., Any]
+    task_config: Annotated[
+        TaskConfig,
+        Field(description="Background task execution configuration (SEP-1686)."),
+    ] = Field(default_factory=lambda: TaskConfig(mode="forbidden"))
+
+    def to_mcp_tool(
+        self,
+        *,
+        include_fastmcp_meta: bool | None = None,
+        **overrides: Any,
+    ) -> MCPTool:
+        """Convert the FastMCP tool to an MCP tool.
+
+        Extends the base implementation to add task execution mode if enabled.
+        """
+        # Get base MCP tool from parent
+        mcp_tool = super().to_mcp_tool(
+            include_fastmcp_meta=include_fastmcp_meta, **overrides
+        )
+
+        # Add task execution mode per SEP-1686
+        # Only set execution if not overridden and mode is not "forbidden"
+        if self.task_config.mode != "forbidden" and "execution" not in overrides:
+            mcp_tool.execution = ToolExecution(taskSupport=self.task_config.mode)
+
+        return mcp_tool
 
     @classmethod
     def from_function(
@@ -266,41 +312,41 @@ class FunctionTool(Tool):
         tags: set[str] | None = None,
         annotations: ToolAnnotations | None = None,
         exclude_args: list[str] | None = None,
-        output_schema: dict[str, Any] | Literal[False] | NotSetT | None = NotSet,
+        output_schema: dict[str, Any] | NotSetT | None = NotSet,
         serializer: ToolResultSerializerType | None = None,
         meta: dict[str, Any] | None = None,
         enabled: bool | None = None,
+        task: bool | TaskConfig | 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.",
+                "The `exclude_args` parameter is deprecated as of FastMCP 2.14. "
+                "Use dependency injection with `Depends()` instead for better lifecycle management. "
+                "See https://gofastmcp.com/servers/dependencies for examples.",
                 DeprecationWarning,
                 stacklevel=2,
             )
 
         parsed_fn = ParsedFunction.from_function(fn, exclude_args=exclude_args)
+        func_name = name or parsed_fn.name
 
-        if name is None and parsed_fn.name == "<lambda>":
+        if func_name == "<lambda>":
             raise ValueError("You must provide a name for lambda functions")
 
+        # Normalize task to TaskConfig and validate
+        if task is None:
+            task_config = TaskConfig(mode="forbidden")
+        elif isinstance(task, bool):
+            task_config = TaskConfig.from_bool(task)
+        else:
+            task_config = task
+        task_config.validate_function(fn, func_name)
+
         if isinstance(output_schema, NotSetT):
             final_output_schema = parsed_fn.output_schema
-        elif output_schema is False:
-            # Handle False as deprecated synonym for None (deprecated in 2.11.4)
-            if fastmcp.settings.deprecation_warnings:
-                warnings.warn(
-                    "Passing output_schema=False is deprecated. Use output_schema=None instead.",
-                    DeprecationWarning,
-                    stacklevel=2,
-                )
-            final_output_schema = None
         else:
-            # At this point output_schema is not NotSetT and not False, so it must be dict | None
+            # At this point output_schema is not NotSetT, so it must be dict | None
             final_output_schema = output_schema
         # Note: explicit schemas (dict) are used as-is without auto-wrapping
 
@@ -325,21 +371,14 @@ class FunctionTool(Tool):
             serializer=serializer,
             meta=meta,
             enabled=enabled if enabled is not None else True,
+            task_config=task_config,
         )
 
     async def run(self, arguments: dict[str, Any]) -> ToolResult:
         """Run the tool with arguments."""
-        from fastmcp.server.context import Context
-
-        arguments = arguments.copy()
-
-        context_kwarg = find_kwarg_by_type(self.fn, kwarg_type=Context)
-        if context_kwarg and context_kwarg not in arguments:
-            arguments[context_kwarg] = get_context()
-
-        type_adapter = get_cached_typeadapter(self.fn)
+        wrapper_fn = without_injected_parameters(self.fn)
+        type_adapter = get_cached_typeadapter(wrapper_fn)
         result = type_adapter.validate_python(arguments)
-
         if inspect.isawaitable(result):
             result = await result
 
@@ -409,8 +448,6 @@ class ParsedFunction:
         validate: bool = True,
         wrap_non_object_output_schema: bool = True,
     ) -> ParsedFunction:
-        from fastmcp.server.context import Context
-
         if validate:
             sig = inspect.signature(fn)
             # Reject functions with *args or **kwargs
@@ -446,22 +483,19 @@ class ParsedFunction:
         if isinstance(fn, staticmethod):
             fn = fn.__func__
 
-        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)
+        # Handle injected parameters (Context, Docket dependencies)
+        wrapper_fn = without_injected_parameters(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)
+        # Also handle exclude_args with non-serializable types (issue #2431)
+        # This must happen before Pydantic tries to serialize the parameters
+        if exclude_args:
+            wrapper_fn = create_function_without_params(wrapper_fn, list(exclude_args))
 
-        input_type_adapter = get_cached_typeadapter(fn_for_typeadapter)
+        input_type_adapter = get_cached_typeadapter(wrapper_fn)
         input_schema = input_type_adapter.json_schema()
+
+        # Compress and handle exclude_args
+        prune_params = list(exclude_args) if exclude_args else None
         input_schema = compress_schema(
             input_schema, prune_params=prune_params, prune_titles=True
         )

fastmcp/tools/tool_transform.py

@@ -1,7 +1,6 @@
 from __future__ import annotations
 
 import inspect
-import warnings
 from collections.abc import Callable
 from contextvars import ContextVar
 from copy import deepcopy
@@ -14,7 +13,6 @@ from pydantic import ConfigDict
 from pydantic.fields import Field
 from pydantic.functional_validators import BeforeValidator
 
-import fastmcp
 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
@@ -372,7 +370,7 @@ class TransformedTool(Tool):
         transform_fn: Callable[..., Any] | None = None,
         transform_args: dict[str, ArgTransform] | None = None,
         annotations: ToolAnnotations | NotSetT | None = NotSet,
-        output_schema: dict[str, Any] | Literal[False] | NotSetT | None = NotSet,
+        output_schema: dict[str, Any] | NotSetT | None = NotSet,
         serializer: Callable[[Any], str] | NotSetT | None = NotSet,
         meta: dict[str, Any] | NotSetT | None = NotSet,
         enabled: bool | None = None,
@@ -487,15 +485,6 @@ class TransformedTool(Tool):
                         final_output_schema = tool.output_schema
             else:
                 final_output_schema = tool.output_schema
-        elif output_schema is False:
-            # Handle False as deprecated synonym for None (deprecated in 2.11.4)
-            if fastmcp.settings.deprecation_warnings:
-                warnings.warn(
-                    "Passing output_schema=False is deprecated. Use output_schema=None instead.",
-                    DeprecationWarning,
-                    stacklevel=2,
-                )
-            final_output_schema = None
         else:
             final_output_schema = cast(dict | None, output_schema)
 

fastmcp/utilities/components.py

@@ -96,7 +96,7 @@ class FastMCPComponent(FastMCPBaseModel):
 
         return meta or None
 
-    def model_copy(
+    def model_copy(  # type: ignore[override]
         self,
         *,
         update: dict[str, Any] | None = None,
@@ -137,7 +137,7 @@ class FastMCPComponent(FastMCPBaseModel):
         """Disable the component."""
         self.enabled = False
 
-    def copy(self) -> Self:
+    def copy(self) -> Self:  # type: ignore[override]
         """Create a copy of the component."""
         return self.model_copy()
 
@@ -173,7 +173,7 @@ class MirroredComponent(FastMCPComponent):
             )
         super().disable()
 
-    def copy(self) -> Self:
+    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()

fastmcp/utilities/json_schema_type.py

@@ -248,7 +248,7 @@ def _create_numeric_type(
         if v is not None
     }
 
-    return Annotated[base, Field(**constraints)] if constraints else base
+    return Annotated[base, Field(**constraints)] if constraints else base  # type: ignore[return-value]
 
 
 def _create_enum(name: str, values: list[Any]) -> type:
@@ -265,8 +265,8 @@ def _create_array_type(
     if isinstance(items, list):
         # Handle positional item schemas
         item_types = [_schema_to_type(s, schemas) for s in items]
-        combined = Union[tuple(item_types)]  # type: ignore # noqa: UP007
-        base = list[combined]
+        combined = Union[tuple(item_types)]  # type: ignore[arg-type] # noqa: UP007
+        base = list[combined]  # type: ignore[valid-type]
     else:
         # Handle single item schema
         item_type = _schema_to_type(items, schemas)
@@ -282,7 +282,7 @@ def _create_array_type(
         if v is not None
     }
 
-    return Annotated[base, Field(**constraints)] if constraints else base
+    return Annotated[base, Field(**constraints)] if constraints else base  # type: ignore[return-value]
 
 
 def _return_Any() -> Any:

fastmcp/utilities/mcp_config.py

@@ -43,8 +43,7 @@ def mcp_server_type_to_servers_and_transports(
 
     if isinstance(mcp_server, TransformingRemoteMCPServer | TransformingStdioMCPServer):
         server, transport = mcp_server._to_server_and_underlying_transport(
-            server_name=server_name,
-            client_name=client_name,
+            server_name=server_name, client_name=client_name
         )
     else:
         transport = mcp_server.to_transport()

fastmcp/utilities/mcp_server_config/v1/mcp_server_config.py

@@ -192,7 +192,7 @@ class MCPServerConfig(BaseModel):
         """
         if isinstance(v, dict):
             return FileSystemSource(**v)
-        return v
+        return v  # type: ignore[return-value]
 
     @field_validator("environment", mode="before")
     @classmethod