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

fastmcp/server/server.py

@@ -25,10 +25,7 @@ from mcp.server.lowlevel.server import Server as MCPServer
 from mcp.server.stdio import stdio_server
 from mcp.types import (
     AnyFunction,
-    EmbeddedResource,
     GetPromptResult,
-    ImageContent,
-    TextContent,
     ToolAnnotations,
 )
 from mcp.types import Prompt as MCPPrompt
@@ -62,6 +59,7 @@ from fastmcp.utilities.cache import TimedCache
 from fastmcp.utilities.components import FastMCPComponent
 from fastmcp.utilities.logging import get_logger
 from fastmcp.utilities.mcp_config import MCPConfig
+from fastmcp.utilities.types import MCPContent
 
 if TYPE_CHECKING:
     from fastmcp.client import Client
@@ -242,16 +240,28 @@ class FastMCP(Generic[LifespanResultT]):
         ]:
             if arg is not None:
                 # Deprecated in 2.8.0
-                warnings.warn(
-                    f"Providing `{name}` when creating a server is deprecated. Provide it when calling `run` or as a global setting instead.",
-                    DeprecationWarning,
-                    stacklevel=2,
-                )
+                if fastmcp.settings.deprecation_warnings:
+                    warnings.warn(
+                        f"Providing `{name}` when creating a server is deprecated. Provide it when calling `run` or as a global setting instead.",
+                        DeprecationWarning,
+                        stacklevel=2,
+                    )
                 deprecated_settings[name] = arg
 
         combined_settings = fastmcp.settings.model_dump() | deprecated_settings
         self._deprecated_settings = Settings(**combined_settings)
 
+    @property
+    def settings(self) -> Settings:
+        # Deprecated in 2.8.0
+        if fastmcp.settings.deprecation_warnings:
+            warnings.warn(
+                "Accessing `.settings` on a FastMCP instance is deprecated. Use the global `fastmcp.settings` instead.",
+                DeprecationWarning,
+                stacklevel=2,
+            )
+        return self._deprecated_settings
+
     @property
     def name(self) -> str:
         return self._mcp_server.name
@@ -502,7 +512,7 @@ class FastMCP(Generic[LifespanResultT]):
 
     async def _mcp_call_tool(
         self, key: str, arguments: dict[str, Any]
-    ) -> list[TextContent | ImageContent | EmbeddedResource]:
+    ) -> list[MCPContent]:
         """
         Handle MCP 'callTool' requests.
 
@@ -528,9 +538,7 @@ class FastMCP(Generic[LifespanResultT]):
                 # standardize NotFound message
                 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 with raw MCP arguments. FastMCP subclasses should override
         this method, not _mcp_call_tool.
@@ -856,11 +864,12 @@ class FastMCP(Generic[LifespanResultT]):
             tags: Optional set of tags for categorizing the resource
         """
         # deprecated since 2.7.0
-        warnings.warn(
-            "The add_resource_fn method is deprecated. Use the resource decorator instead.",
-            DeprecationWarning,
-            stacklevel=2,
-        )
+        if fastmcp.settings.deprecation_warnings:
+            warnings.warn(
+                "The add_resource_fn method is deprecated. Use the resource decorator instead.",
+                DeprecationWarning,
+                stacklevel=2,
+            )
         self._resource_manager.add_resource_or_template_from_fn(
             fn=fn,
             uri=uri,
@@ -1218,19 +1227,19 @@ class FastMCP(Generic[LifespanResultT]):
         port: int | None = None,
         log_level: str | None = None,
         path: str | None = None,
-        message_path: str | None = None,
         uvicorn_config: dict[str, Any] | None = None,
     ) -> None:
         """Run the server using SSE transport."""
 
         # Deprecated since 2.3.2
-        warnings.warn(
-            "The run_sse_async method is deprecated (as of 2.3.2). Use run_http_async for a "
-            "modern (non-SSE) alternative, or create an SSE app with "
-            "`fastmcp.server.http.create_sse_app` and run it directly.",
-            DeprecationWarning,
-            stacklevel=2,
-        )
+        if fastmcp.settings.deprecation_warnings:
+            warnings.warn(
+                "The run_sse_async method is deprecated (as of 2.3.2). Use run_http_async for a "
+                "modern (non-SSE) alternative, or create an SSE app with "
+                "`fastmcp.server.http.create_sse_app` and run it directly.",
+                DeprecationWarning,
+                stacklevel=2,
+            )
         await self.run_http_async(
             transport="sse",
             host=host,
@@ -1255,12 +1264,13 @@ class FastMCP(Generic[LifespanResultT]):
             middleware: A list of middleware to apply to the app
         """
         # Deprecated since 2.3.2
-        warnings.warn(
-            "The sse_app method is deprecated (as of 2.3.2). Use http_app as a modern (non-SSE) "
-            "alternative, or call `fastmcp.server.http.create_sse_app` directly.",
-            DeprecationWarning,
-            stacklevel=2,
-        )
+        if fastmcp.settings.deprecation_warnings:
+            warnings.warn(
+                "The sse_app method is deprecated (as of 2.3.2). Use http_app as a modern (non-SSE) "
+                "alternative, or call `fastmcp.server.http.create_sse_app` directly.",
+                DeprecationWarning,
+                stacklevel=2,
+            )
         return create_sse_app(
             server=self,
             message_path=message_path or self._deprecated_settings.message_path,
@@ -1283,11 +1293,12 @@ class FastMCP(Generic[LifespanResultT]):
             middleware: A list of middleware to apply to the app
         """
         # Deprecated since 2.3.2
-        warnings.warn(
-            "The streamable_http_app method is deprecated (as of 2.3.2). Use http_app() instead.",
-            DeprecationWarning,
-            stacklevel=2,
-        )
+        if fastmcp.settings.deprecation_warnings:
+            warnings.warn(
+                "The streamable_http_app method is deprecated (as of 2.3.2). Use http_app() instead.",
+                DeprecationWarning,
+                stacklevel=2,
+            )
         return self.http_app(path=path, middleware=middleware)
 
     def http_app(
@@ -1316,8 +1327,16 @@ class FastMCP(Generic[LifespanResultT]):
                 or self._deprecated_settings.streamable_http_path,
                 event_store=None,
                 auth=self.auth,
-                json_response=self._deprecated_settings.json_response,
-                stateless_http=self._deprecated_settings.stateless_http,
+                json_response=(
+                    json_response
+                    if json_response is not None
+                    else self._deprecated_settings.json_response
+                ),
+                stateless_http=(
+                    stateless_http
+                    if stateless_http is not None
+                    else self._deprecated_settings.stateless_http
+                ),
                 debug=self._deprecated_settings.debug,
                 middleware=middleware,
             )
@@ -1340,12 +1359,13 @@ class FastMCP(Generic[LifespanResultT]):
         uvicorn_config: dict[str, Any] | None = None,
     ) -> None:
         # Deprecated since 2.3.2
-        warnings.warn(
-            "The run_streamable_http_async method is deprecated (as of 2.3.2). "
-            "Use run_http_async instead.",
-            DeprecationWarning,
-            stacklevel=2,
-        )
+        if fastmcp.settings.deprecation_warnings:
+            warnings.warn(
+                "The run_streamable_http_async method is deprecated (as of 2.3.2). "
+                "Use run_http_async instead.",
+                DeprecationWarning,
+                stacklevel=2,
+            )
         await self.run_http_async(
             transport="streamable-http",
             host=host,
@@ -1413,30 +1433,33 @@ class FastMCP(Generic[LifespanResultT]):
 
         if tool_separator is not None:
             # Deprecated since 2.4.0
-            warnings.warn(
-                "The tool_separator parameter is deprecated and will be removed in a future version. "
-                "Tools are now prefixed using 'prefix_toolname' format.",
-                DeprecationWarning,
-                stacklevel=2,
-            )
+            if fastmcp.settings.deprecation_warnings:
+                warnings.warn(
+                    "The tool_separator parameter is deprecated and will be removed in a future version. "
+                    "Tools are now prefixed using 'prefix_toolname' format.",
+                    DeprecationWarning,
+                    stacklevel=2,
+                )
 
         if resource_separator is not None:
             # Deprecated since 2.4.0
-            warnings.warn(
-                "The resource_separator parameter is deprecated and ignored. "
-                "Resource prefixes are now added using the protocol://prefix/path format.",
-                DeprecationWarning,
-                stacklevel=2,
-            )
+            if fastmcp.settings.deprecation_warnings:
+                warnings.warn(
+                    "The resource_separator parameter is deprecated and ignored. "
+                    "Resource prefixes are now added using the protocol://prefix/path format.",
+                    DeprecationWarning,
+                    stacklevel=2,
+                )
 
         if prompt_separator is not None:
             # Deprecated since 2.4.0
-            warnings.warn(
-                "The prompt_separator parameter is deprecated and will be removed in a future version. "
-                "Prompts are now prefixed using 'prefix_promptname' format.",
-                DeprecationWarning,
-                stacklevel=2,
-            )
+            if fastmcp.settings.deprecation_warnings:
+                warnings.warn(
+                    "The prompt_separator parameter is deprecated and will be removed in a future version. "
+                    "Prompts are now prefixed using 'prefix_promptname' format.",
+                    DeprecationWarning,
+                    stacklevel=2,
+                )
 
         # if as_proxy is not specified and the server has a custom lifespan,
         # we should treat it as a proxy
@@ -1498,30 +1521,33 @@ class FastMCP(Generic[LifespanResultT]):
         """
         if tool_separator is not None:
             # Deprecated since 2.4.0
-            warnings.warn(
-                "The tool_separator parameter is deprecated and will be removed in a future version. "
-                "Tools are now prefixed using 'prefix_toolname' format.",
-                DeprecationWarning,
-                stacklevel=2,
-            )
+            if fastmcp.settings.deprecation_warnings:
+                warnings.warn(
+                    "The tool_separator parameter is deprecated and will be removed in a future version. "
+                    "Tools are now prefixed using 'prefix_toolname' format.",
+                    DeprecationWarning,
+                    stacklevel=2,
+                )
 
         if resource_separator is not None:
             # Deprecated since 2.4.0
-            warnings.warn(
-                "The resource_separator parameter is deprecated and ignored. "
-                "Resource prefixes are now added using the protocol://prefix/path format.",
-                DeprecationWarning,
-                stacklevel=2,
-            )
+            if fastmcp.settings.deprecation_warnings:
+                warnings.warn(
+                    "The resource_separator parameter is deprecated and ignored. "
+                    "Resource prefixes are now added using the protocol://prefix/path format.",
+                    DeprecationWarning,
+                    stacklevel=2,
+                )
 
         if prompt_separator is not None:
             # Deprecated since 2.4.0
-            warnings.warn(
-                "The prompt_separator parameter is deprecated and will be removed in a future version. "
-                "Prompts are now prefixed using 'prefix_promptname' format.",
-                DeprecationWarning,
-                stacklevel=2,
-            )
+            if fastmcp.settings.deprecation_warnings:
+                warnings.warn(
+                    "The prompt_separator parameter is deprecated and will be removed in a future version. "
+                    "Prompts are now prefixed using 'prefix_promptname' format.",
+                    DeprecationWarning,
+                    stacklevel=2,
+                )
 
         # Import tools from the mounted server
         tool_prefix = f"{prefix}_"
@@ -1657,11 +1683,12 @@ class FastMCP(Generic[LifespanResultT]):
         Create a FastMCP proxy server from a FastMCP client.
         """
         # Deprecated since 2.3.5
-        warnings.warn(
-            "FastMCP.from_client() is deprecated; use FastMCP.as_proxy() instead.",
-            DeprecationWarning,
-            stacklevel=2,
-        )
+        if fastmcp.settings.deprecation_warnings:
+            warnings.warn(
+                "FastMCP.from_client() is deprecated; use FastMCP.as_proxy() instead.",
+                DeprecationWarning,
+                stacklevel=2,
+            )
 
         return cls.as_proxy(client, **settings)
 

fastmcp/settings.py

@@ -1,7 +1,6 @@
 from __future__ import annotations as _annotations
 
 import inspect
-import warnings
 from pathlib import Path
 from typing import Annotated, Any, Literal
 
@@ -15,6 +14,10 @@ from pydantic_settings import (
 )
 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"]
@@ -39,10 +42,8 @@ class ExtendedEnvSettingsSource(EnvSettingsSource):
                 if env_val is not None:
                     if prefix == "FASTMCP_SERVER_":
                         # Deprecated in 2.8.0
-                        warnings.warn(
+                        logger.warning(
                             "Using `FASTMCP_SERVER_` environment variables is deprecated. Use `FASTMCP_` instead.",
-                            DeprecationWarning,
-                            stacklevel=2,
                         )
                     return env_val, field_key, value_is_complex
 
@@ -89,10 +90,8 @@ class Settings(BaseSettings):
         which accessed fastmcp.settings.settings
         """
         # Deprecated in 2.8.0
-        warnings.warn(
+        logger.warning(
             "Using fastmcp.settings.settings is deprecated. Use fastmcp.settings instead.",
-            DeprecationWarning,
-            stacklevel=2,
         )
         return self
 
@@ -111,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(

fastmcp/tools/tool.py

@@ -7,7 +7,7 @@ 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 Field
 
@@ -17,7 +17,9 @@ 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 (
+    Audio,
     Image,
+    MCPContent,
     find_kwarg_by_type,
     get_cached_typeadapter,
 )
@@ -75,9 +77,7 @@ class Tool(FastMCPComponent):
             enabled=enabled,
         )
 
-    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()")
 
@@ -142,9 +142,7 @@ class FunctionTool(Tool):
             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
 
@@ -265,17 +263,20 @@ 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.
@@ -287,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,13 +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
@@ -71,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,
@@ -119,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:

fastmcp/tools/tool_transform.py

@@ -7,12 +7,12 @@ from dataclasses import dataclass
 from types import EllipsisType
 from typing import Any, Literal
 
-from mcp.types import EmbeddedResource, ImageContent, TextContent, ToolAnnotations
+from mcp.types import ToolAnnotations
 from pydantic import ConfigDict
 
 from fastmcp.tools.tool import ParsedFunction, Tool
 from fastmcp.utilities.logging import get_logger
-from fastmcp.utilities.types import get_cached_typeadapter
+from fastmcp.utilities.types import MCPContent, get_cached_typeadapter
 
 logger = get_logger(__name__)
 
@@ -97,6 +97,7 @@ class ArgTransform:
         type: New type for the argument. Use ... for no change.
         hide: If True, hide this argument from clients but pass a constant value to parent.
         required: If True, make argument required (remove default). Use ... for no change.
+        examples: Examples for the argument. Use ... for no change.
 
     Examples:
         # Rename argument 'old_name' to 'new_name'
@@ -137,6 +138,7 @@ class ArgTransform:
     type: Any | EllipsisType = NotSet
     hide: bool = False
     required: Literal[True] | EllipsisType = NotSet
+    examples: Any | EllipsisType = NotSet
 
     def __post_init__(self):
         """Validate that only one of default or default_factory is provided."""
@@ -200,9 +202,7 @@ class TransformedTool(Tool):
     forwarding_fn: Callable[..., Any]  # Always present, handles arg transformation
     transform_args: dict[str, ArgTransform]
 
-    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 context set for forward() functions.
 
         This method executes the tool's function while setting up the context
@@ -584,6 +584,10 @@ class TransformedTool(Tool):
             # Update the schema with the type information from TypeAdapter
             new_schema.update(type_schema)
 
+        # Handle examples transformation
+        if transform.examples is not NotSet:
+            new_schema["examples"] = transform.examples
+
         return new_name, new_schema, is_required
 
     @staticmethod

fastmcp/utilities/types.py

@@ -6,13 +6,21 @@ from collections.abc import Callable
 from functools import lru_cache
 from pathlib import Path
 from types import UnionType
-from typing import Annotated, TypeVar, Union, get_args, get_origin
-
-from mcp.types import ImageContent
+from typing import Annotated, TypeAlias, TypeVar, Union, get_args, get_origin
+
+from mcp.types import (
+    Annotations,
+    AudioContent,
+    EmbeddedResource,
+    ImageContent,
+    TextContent,
+)
 from pydantic import BaseModel, ConfigDict, TypeAdapter
 
 T = TypeVar("T")
 
+MCPContent: TypeAlias = TextContent | ImageContent | AudioContent | EmbeddedResource
+
 
 class FastMCPBaseModel(BaseModel):
     """Base model for FastMCP models."""
@@ -88,6 +96,7 @@ class Image:
         path: str | Path | None = None,
         data: bytes | None = None,
         format: str | None = None,
+        annotations: Annotations | None = None,
     ):
         if path is None and data is None:
             raise ValueError("Either path or data must be provided")
@@ -98,6 +107,7 @@ class Image:
         self.data = data
         self._format = format
         self._mime_type = self._get_mime_type()
+        self.annotations = annotations
 
     def _get_mime_type(self) -> str:
         """Get MIME type from format or guess from file extension."""
@@ -115,7 +125,11 @@ class Image:
             }.get(suffix, "application/octet-stream")
         return "image/png"  # default for raw binary data
 
-    def to_image_content(self) -> ImageContent:
+    def to_image_content(
+        self,
+        mime_type: str | None = None,
+        annotations: Annotations | None = None,
+    ) -> ImageContent:
         """Convert to MCP ImageContent."""
         if self.path:
             with open(self.path, "rb") as f:
@@ -125,4 +139,67 @@ class Image:
         else:
             raise ValueError("No image data available")
 
-        return ImageContent(type="image", data=data, mimeType=self._mime_type)
+        return ImageContent(
+            type="image",
+            data=data,
+            mimeType=mime_type or self._mime_type,
+            annotations=annotations or self.annotations,
+        )
+
+
+class Audio:
+    """Helper class for returning audio from tools."""
+
+    def __init__(
+        self,
+        path: str | Path | None = None,
+        data: bytes | None = None,
+        format: str | None = None,
+        annotations: Annotations | None = None,
+    ):
+        if path is None and data is None:
+            raise ValueError("Either path or data must be provided")
+        if path is not None and data is not None:
+            raise ValueError("Only one of path or data can be provided")
+
+        self.path = Path(path) if path else None
+        self.data = data
+        self._format = format
+        self._mime_type = self._get_mime_type()
+        self.annotations = annotations
+
+    def _get_mime_type(self) -> str:
+        """Get MIME type from format or guess from file extension."""
+        if self._format:
+            return f"audio/{self._format.lower()}"
+
+        if self.path:
+            suffix = self.path.suffix.lower()
+            return {
+                ".wav": "audio/wav",
+                ".mp3": "audio/mpeg",
+                ".ogg": "audio/ogg",
+                ".m4a": "audio/mp4",
+                ".flac": "audio/flac",
+            }.get(suffix, "application/octet-stream")
+        return "audio/wav"  # default for raw binary data
+
+    def to_audio_content(
+        self,
+        mime_type: str | None = None,
+        annotations: Annotations | None = None,
+    ) -> AudioContent:
+        if self.path:
+            with open(self.path, "rb") as f:
+                data = base64.b64encode(f.read()).decode()
+        elif self.data is not None:
+            data = base64.b64encode(self.data).decode()
+        else:
+            raise ValueError("No audio data available")
+
+        return AudioContent(
+            type="audio",
+            data=data,
+            mimeType=mime_type or self._mime_type,
+            annotations=annotations or self.annotations,
+        )