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

fastmcp/settings.py

@@ -192,9 +192,9 @@ class Settings(BaseSettings):
     # HTTP settings
     host: str = "127.0.0.1"
     port: int = 8000
-    sse_path: str = "/sse"
+    sse_path: str = "/sse/"
     message_path: str = "/messages/"
-    streamable_http_path: str = "/mcp"
+    streamable_http_path: str = "/mcp/"
     debug: bool = False
 
     # error handling

fastmcp/tools/tool.py

@@ -18,6 +18,7 @@ from fastmcp.utilities.json_schema import compress_schema
 from fastmcp.utilities.logging import get_logger
 from fastmcp.utilities.types import (
     Audio,
+    File,
     Image,
     MCPContent,
     find_kwarg_by_type,
@@ -45,6 +46,22 @@ class Tool(FastMCPComponent):
         default=None, description="Optional custom serializer for tool results"
     )
 
+    def enable(self) -> None:
+        super().enable()
+        try:
+            context = get_context()
+            context._queue_tool_list_changed()  # type: ignore[private-use]
+        except RuntimeError:
+            pass  # No context available
+
+    def disable(self) -> None:
+        super().disable()
+        try:
+            context = get_context()
+            context._queue_tool_list_changed()  # type: ignore[private-use]
+        except RuntimeError:
+            pass  # No context available
+
     def to_mcp_tool(self, **overrides: Any) -> MCPTool:
         kwargs = {
             "name": self.name,
@@ -231,7 +248,7 @@ class ParsedFunction:
 
         # collect name and doc before we potentially modify the function
         fn_name = getattr(fn, "__name__", None) or fn.__class__.__name__
-        fn_doc = fn.__doc__
+        fn_doc = inspect.getdoc(fn)
 
         # if the fn is a callable class, we need to get the __call__ method from here out
         if not inspect.isroutine(fn):
@@ -277,6 +294,9 @@ def _convert_to_content(
     elif isinstance(result, Audio):
         return [result.to_audio_content()]
 
+    elif isinstance(result, File):
+        return [result.to_resource_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.
@@ -288,7 +308,7 @@ def _convert_to_content(
         other_content = []
 
         for item in result:
-            if isinstance(item, MCPContent | Image | Audio):
+            if isinstance(item, MCPContent | Image | Audio | File):
                 mcp_types.append(_convert_to_content(item)[0])
             else:
                 other_content.append(item)

fastmcp/tools/tool_manager.py

@@ -1,4 +1,4 @@
-from __future__ import annotations as _annotations
+from __future__ import annotations
 
 import warnings
 from collections.abc import Callable
@@ -14,7 +14,7 @@ from fastmcp.utilities.logging import get_logger
 from fastmcp.utilities.types import MCPContent
 
 if TYPE_CHECKING:
-    pass
+    from fastmcp.server.server import MountedServer
 
 logger = get_logger(__name__)
 
@@ -28,6 +28,7 @@ class ToolManager:
         mask_error_details: bool | None = None,
     ):
         self._tools: dict[str, Tool] = {}
+        self._mounted_servers: list[MountedServer] = []
         self.mask_error_details = mask_error_details or settings.mask_error_details
 
         # Default to "warn" if None is provided
@@ -42,23 +43,72 @@ class ToolManager:
 
         self.duplicate_behavior = duplicate_behavior
 
-    def has_tool(self, key: str) -> bool:
+    def mount(self, server: MountedServer) -> None:
+        """Adds a mounted server as a source for tools."""
+        self._mounted_servers.append(server)
+
+    async def _load_tools(self, *, via_server: bool = False) -> dict[str, Tool]:
+        """
+        The single, consolidated recursive method for fetching tools. The 'via_server'
+        parameter determines the communication path.
+
+        - via_server=False: Manager-to-manager path for complete, unfiltered inventory
+        - via_server=True: Server-to-server path for filtered MCP requests
+        """
+        all_tools: dict[str, Tool] = {}
+
+        for mounted in self._mounted_servers:
+            try:
+                if via_server:
+                    # Use the server-to-server filtered path
+                    child_results = await mounted.server._list_tools()
+                else:
+                    # Use the manager-to-manager unfiltered path
+                    child_results = await mounted.server._tool_manager.list_tools()
+
+                # The combination logic is the same for both paths
+                child_dict = {t.key: t for t in child_results}
+                if mounted.prefix:
+                    for tool in child_dict.values():
+                        prefixed_tool = tool.with_key(f"{mounted.prefix}_{tool.key}")
+                        all_tools[prefixed_tool.key] = prefixed_tool
+                else:
+                    all_tools.update(child_dict)
+            except Exception as e:
+                # Skip failed mounts silently, matches existing behavior
+                logger.warning(
+                    f"Failed to get tools from mounted server '{mounted.prefix}': {e}"
+                )
+                continue
+
+        # Finally, add local tools, which always take precedence
+        all_tools.update(self._tools)
+        return all_tools
+
+    async def has_tool(self, key: str) -> bool:
         """Check if a tool exists."""
-        return key in self._tools
+        tools = await self.get_tools()
+        return key in tools
 
-    def get_tool(self, key: str) -> Tool:
+    async def get_tool(self, key: str) -> Tool:
         """Get tool by key."""
-        if key in self._tools:
-            return self._tools[key]
-        raise NotFoundError(f"Unknown tool: {key}")
+        tools = await self.get_tools()
+        if key in tools:
+            return tools[key]
+        raise NotFoundError(f"Tool {key!r} not found")
 
-    def get_tools(self) -> dict[str, Tool]:
-        """Get all registered tools, indexed by registered key."""
-        return self._tools
+    async def get_tools(self) -> dict[str, Tool]:
+        """
+        Gets the complete, unfiltered inventory of all tools.
+        """
+        return await self._load_tools(via_server=False)
 
-    def list_tools(self) -> list[Tool]:
-        """List all registered tools."""
-        return list(self.get_tools().values())
+    async def list_tools(self) -> list[Tool]:
+        """
+        Lists all tools, applying protocol filtering.
+        """
+        tools_dict = await self._load_tools(via_server=True)
+        return list(tools_dict.values())
 
     def add_tool_from_fn(
         self,
@@ -89,22 +139,21 @@ class ToolManager:
         )
         return self.add_tool(tool)
 
-    def add_tool(self, tool: Tool, key: str | None = None) -> Tool:
+    def add_tool(self, tool: Tool) -> Tool:
         """Register a tool with the server."""
-        key = key or tool.name
-        existing = self._tools.get(key)
+        existing = self._tools.get(tool.key)
         if existing:
             if self.duplicate_behavior == "warn":
-                logger.warning(f"Tool already exists: {key}")
-                self._tools[key] = tool
+                logger.warning(f"Tool already exists: {tool.key}")
+                self._tools[tool.key] = tool
             elif self.duplicate_behavior == "replace":
-                self._tools[key] = tool
+                self._tools[tool.key] = tool
             elif self.duplicate_behavior == "error":
-                raise ValueError(f"Tool already exists: {key}")
+                raise ValueError(f"Tool already exists: {tool.key}")
             elif self.duplicate_behavior == "ignore":
                 return existing
         else:
-            self._tools[key] = tool
+            self._tools[tool.key] = tool
         return tool
 
     def remove_tool(self, key: str) -> None:
@@ -119,28 +168,48 @@ class ToolManager:
         if key in self._tools:
             del self._tools[key]
         else:
-            raise NotFoundError(f"Unknown tool: {key}")
+            raise NotFoundError(f"Tool {key!r} not found")
 
     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:
-            raise NotFoundError(f"Unknown tool: {key}")
-
-        try:
-            return await tool.run(arguments)
-
-        # raise ToolErrors as-is
-        except ToolError as e:
-            logger.exception(f"Error calling tool {key!r}: {e}")
-            raise e
-
-        # Handle other exceptions
-        except Exception as e:
-            logger.exception(f"Error calling tool {key!r}: {e}")
-            if self.mask_error_details:
-                # Mask internal details
-                raise ToolError(f"Error calling tool {key!r}") from e
-            else:
-                # Include original error details
-                raise ToolError(f"Error calling tool {key!r}: {e}") from e
+        """
+        Internal API for servers: Finds and calls a tool, respecting the
+        filtered protocol path.
+        """
+        # 1. Check local tools first. The server will have already applied its filter.
+        if key in self._tools:
+            tool = await self.get_tool(key)
+            if not tool:
+                raise NotFoundError(f"Tool {key!r} not found")
+
+            try:
+                return await tool.run(arguments)
+
+            # raise ToolErrors as-is
+            except ToolError as e:
+                logger.exception(f"Error calling tool {key!r}")
+                raise e
+
+            # Handle other exceptions
+            except Exception as e:
+                logger.exception(f"Error calling tool {key!r}")
+                if self.mask_error_details:
+                    # Mask internal details
+                    raise ToolError(f"Error calling tool {key!r}") from e
+                else:
+                    # Include original error details
+                    raise ToolError(f"Error calling tool {key!r}: {e}") from e
+
+        # 2. Check mounted servers using the filtered protocol path.
+        for mounted in reversed(self._mounted_servers):
+            tool_key = key
+            if mounted.prefix:
+                if key.startswith(f"{mounted.prefix}_"):
+                    tool_key = key.removeprefix(f"{mounted.prefix}_")
+                else:
+                    continue
+            try:
+                return await mounted.server._call_tool(tool_key, arguments)
+            except NotFoundError:
+                continue
+
+        raise NotFoundError(f"Tool {key!r} not found.")

fastmcp/tools/tool_transform.py

@@ -100,35 +100,55 @@ class ArgTransform:
         examples: Examples for the argument. Use ... for no change.
 
     Examples:
-        # Rename argument 'old_name' to 'new_name'
+        Rename argument 'old_name' to 'new_name'
+        ```python
         ArgTransform(name="new_name")
+        ```
 
-        # Change description only
+        Change description only
+        ```python
         ArgTransform(description="Updated description")
+        ```
 
-        # Add a default value (makes argument optional)
+        Add a default value (makes argument optional)
+        ```python
         ArgTransform(default=42)
+        ```
 
-        # Add a default factory (makes argument optional)
+        Add a default factory (makes argument optional)
+        ```python
         ArgTransform(default_factory=lambda: time.time())
+        ```
 
-        # Change the type
+        Change the type
+        ```python
         ArgTransform(type=str)
+        ```
 
-        # Hide the argument entirely from clients
+        Hide the argument entirely from clients
+        ```python
         ArgTransform(hide=True)
+        ```
 
-        # Hide argument but pass a constant value to parent
+        Hide argument but pass a constant value to parent
+        ```python
         ArgTransform(hide=True, default="constant_value")
+        ```
 
-        # Hide argument but pass a factory-generated value to parent
+        Hide argument but pass a factory-generated value to parent
+        ```python
         ArgTransform(hide=True, default_factory=lambda: uuid.uuid4().hex)
+        ```
 
-        # Make an optional parameter required (removes any default)
+        Make an optional parameter required (removes any default)
+        ```python
         ArgTransform(required=True)
+        ```
 
-        # Combine multiple transformations
+        Combine multiple transformations
+        ```python
         ArgTransform(name="new_name", description="New desc", default=None, type=int)
+        ```
     """
 
     name: str | EllipsisType = NotSet
@@ -279,9 +299,9 @@ class TransformedTool(Tool):
             name: New name for the tool. Defaults to parent tool's name.
             transform_args: Optional transformations for parent tool arguments.
                 Only specified arguments are transformed, others pass through unchanged:
-                - str: Simple rename
-                - ArgTransform: Complex transformation (rename/description/default/drop)
-                - None: Drop the argument
+                - Simple rename (str)
+                - Complex transformation (rename/description/default/drop) (ArgTransform)
+                - Drop the argument (None)
             description: New description. Defaults to parent's description.
             tags: New tags. Defaults to parent's tags.
             annotations: New annotations. Defaults to parent's annotations.
@@ -290,23 +310,29 @@ class TransformedTool(Tool):
         Returns:
             TransformedTool with the specified transformations.
 
-                Examples:
+        Examples:
             # Transform specific arguments only
+            ```python
             Tool.from_tool(parent, transform_args={"old": "new"})  # Others unchanged
+            ```
 
             # Custom function with partial transforms
+            ```python
             async def custom(x: int, y: int) -> str:
                 result = await forward(x=x, y=y)
                 return f"Custom: {result}"
 
             Tool.from_tool(parent, transform_fn=custom, transform_args={"a": "x", "b": "y"})
+            ```
 
             # Using **kwargs (gets all args, transformed and untransformed)
+            ```python
             async def flexible(**kwargs) -> str:
                 result = await forward(**kwargs)
                 return f"Got: {kwargs}"
 
             Tool.from_tool(parent, transform_fn=flexible, transform_args={"a": "x"})
+            ```
         """
         transform_args = transform_args or {}
 
@@ -423,8 +449,8 @@ class TransformedTool(Tool):
 
         Returns:
             A tuple containing:
-            - dict: The new JSON schema for the transformed tool
-            - Callable: Async function that validates and forwards calls to the parent tool
+            - The new JSON schema for the transformed tool as a dictionary
+            - Async function that validates and forwards calls to the parent tool
         """
 
         # Build transformed schema and mapping

fastmcp/utilities/components.py

@@ -1,7 +1,8 @@
 from collections.abc import Sequence
-from typing import Annotated, TypeVar
+from typing import Annotated, Any, TypeVar
 
-from pydantic import BeforeValidator, Field
+from pydantic import BeforeValidator, Field, PrivateAttr
+from typing_extensions import Self
 
 from fastmcp.utilities.types import FastMCPBaseModel
 
@@ -37,6 +38,25 @@ class FastMCPComponent(FastMCPBaseModel):
         description="Whether the component is enabled.",
     )
 
+    _key: str | None = PrivateAttr()
+
+    def __init__(self, *, key: str | None = None, **kwargs: Any) -> None:
+        super().__init__(**kwargs)
+        self._key = key
+
+    @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
+
+    def with_key(self, key: str) -> Self:
+        return self.model_copy(update={"_key": key})
+
     def __eq__(self, other: object) -> bool:
         if type(self) is not type(other):
             return False