fastmcp 2.8.1__py3-none-any.whl → 2.9.0__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,
@@ -231,7 +232,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 +278,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 +292,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}: {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
+
+        # 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/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

fastmcp/utilities/inspect.py

@@ -0,0 +1,326 @@
+"""Utilities for inspecting FastMCP instances."""
+
+from __future__ import annotations
+
+import importlib.metadata
+from dataclasses import dataclass
+from typing import Any
+
+from mcp.server.fastmcp import FastMCP as FastMCP1x
+
+import fastmcp
+from fastmcp.server.server import FastMCP
+
+
+@dataclass
+class ToolInfo:
+    """Information about a tool."""
+
+    key: str
+    name: str
+    description: str | None
+    input_schema: dict[str, Any]
+    annotations: dict[str, Any] | None = None
+    tags: list[str] | None = None
+    enabled: bool | None = None
+
+
+@dataclass
+class PromptInfo:
+    """Information about a prompt."""
+
+    key: str
+    name: str
+    description: str | None
+    arguments: list[dict[str, Any]] | None = None
+    tags: list[str] | None = None
+    enabled: bool | None = None
+
+
+@dataclass
+class ResourceInfo:
+    """Information about a resource."""
+
+    key: str
+    uri: str
+    name: str | None
+    description: str | None
+    mime_type: str | None = None
+    tags: list[str] | None = None
+    enabled: bool | None = None
+
+
+@dataclass
+class TemplateInfo:
+    """Information about a resource template."""
+
+    key: str
+    uri_template: str
+    name: str | None
+    description: str | None
+    mime_type: str | None = None
+    tags: list[str] | None = None
+    enabled: bool | None = None
+
+
+@dataclass
+class FastMCPInfo:
+    """Information extracted from a FastMCP instance."""
+
+    name: str
+    instructions: str | None
+    fastmcp_version: str
+    mcp_version: str
+    server_version: str
+    tools: list[ToolInfo]
+    prompts: list[PromptInfo]
+    resources: list[ResourceInfo]
+    templates: list[TemplateInfo]
+    capabilities: dict[str, Any]
+
+
+async def inspect_fastmcp_v2(mcp: FastMCP[Any]) -> FastMCPInfo:
+    """Extract information from a FastMCP v2.x instance.
+
+    Args:
+        mcp: The FastMCP v2.x instance to inspect
+
+    Returns:
+        FastMCPInfo dataclass containing the extracted information
+    """
+    # Get all the components using FastMCP2's direct methods
+    tools_dict = await mcp.get_tools()
+    prompts_dict = await mcp.get_prompts()
+    resources_dict = await mcp.get_resources()
+    templates_dict = await mcp.get_resource_templates()
+
+    # Extract detailed tool information
+    tool_infos = []
+    for key, tool in tools_dict.items():
+        # Convert to MCP tool to get input schema
+        mcp_tool = tool.to_mcp_tool(name=key)
+        tool_infos.append(
+            ToolInfo(
+                key=key,
+                name=tool.name or key,
+                description=tool.description,
+                input_schema=mcp_tool.inputSchema if mcp_tool.inputSchema else {},
+                annotations=tool.annotations.model_dump() if tool.annotations else None,
+                tags=list(tool.tags) if tool.tags else None,
+                enabled=tool.enabled,
+            )
+        )
+
+    # Extract detailed prompt information
+    prompt_infos = []
+    for key, prompt in prompts_dict.items():
+        prompt_infos.append(
+            PromptInfo(
+                key=key,
+                name=prompt.name or key,
+                description=prompt.description,
+                arguments=[arg.model_dump() for arg in prompt.arguments]
+                if prompt.arguments
+                else None,
+                tags=list(prompt.tags) if prompt.tags else None,
+                enabled=prompt.enabled,
+            )
+        )
+
+    # Extract detailed resource information
+    resource_infos = []
+    for key, resource in resources_dict.items():
+        resource_infos.append(
+            ResourceInfo(
+                key=key,
+                uri=key,  # For v2, key is the URI
+                name=resource.name,
+                description=resource.description,
+                mime_type=resource.mime_type,
+                tags=list(resource.tags) if resource.tags else None,
+                enabled=resource.enabled,
+            )
+        )
+
+    # Extract detailed template information
+    template_infos = []
+    for key, template in templates_dict.items():
+        template_infos.append(
+            TemplateInfo(
+                key=key,
+                uri_template=key,  # For v2, key is the URI template
+                name=template.name,
+                description=template.description,
+                mime_type=template.mime_type,
+                tags=list(template.tags) if template.tags else None,
+                enabled=template.enabled,
+            )
+        )
+
+    # Basic MCP capabilities that FastMCP supports
+    capabilities = {
+        "tools": {"listChanged": True},
+        "resources": {"subscribe": False, "listChanged": False},
+        "prompts": {"listChanged": False},
+        "logging": {},
+    }
+
+    return FastMCPInfo(
+        name=mcp.name,
+        instructions=mcp.instructions,
+        fastmcp_version=fastmcp.__version__,
+        mcp_version=importlib.metadata.version("mcp"),
+        server_version=fastmcp.__version__,  # v2.x uses FastMCP version
+        tools=tool_infos,
+        prompts=prompt_infos,
+        resources=resource_infos,
+        templates=template_infos,
+        capabilities=capabilities,
+    )
+
+
+async def inspect_fastmcp_v1(mcp: Any) -> FastMCPInfo:
+    """Extract information from a FastMCP v1.x instance using a Client.
+
+    Args:
+        mcp: The FastMCP v1.x instance to inspect
+
+    Returns:
+        FastMCPInfo dataclass containing the extracted information
+    """
+    from fastmcp import Client
+
+    # Use a client to interact with the FastMCP1x server
+    async with Client(mcp) as client:
+        # Get components via client calls (these return MCP objects)
+        mcp_tools = await client.list_tools()
+        mcp_prompts = await client.list_prompts()
+        mcp_resources = await client.list_resources()
+
+        # Try to get resource templates (FastMCP 1.x does have templates)
+        try:
+            mcp_templates = await client.list_resource_templates()
+        except Exception:
+            mcp_templates = []
+
+        # Extract detailed tool information from MCP Tool objects
+        tool_infos = []
+        for mcp_tool in mcp_tools:
+            # Extract annotations if they exist
+            annotations = None
+            if hasattr(mcp_tool, "annotations") and mcp_tool.annotations:
+                if hasattr(mcp_tool.annotations, "model_dump"):
+                    annotations = mcp_tool.annotations.model_dump()
+                elif isinstance(mcp_tool.annotations, dict):
+                    annotations = mcp_tool.annotations
+                else:
+                    annotations = None
+
+            tool_infos.append(
+                ToolInfo(
+                    key=mcp_tool.name,  # For 1.x, key and name are the same
+                    name=mcp_tool.name,
+                    description=mcp_tool.description,
+                    input_schema=mcp_tool.inputSchema if mcp_tool.inputSchema else {},
+                    annotations=annotations,
+                    tags=None,  # 1.x doesn't have tags
+                    enabled=None,  # 1.x doesn't have enabled field
+                )
+            )
+
+        # Extract detailed prompt information from MCP Prompt objects
+        prompt_infos = []
+        for mcp_prompt in mcp_prompts:
+            # Convert arguments if they exist
+            arguments = None
+            if hasattr(mcp_prompt, "arguments") and mcp_prompt.arguments:
+                arguments = [arg.model_dump() for arg in mcp_prompt.arguments]
+
+            prompt_infos.append(
+                PromptInfo(
+                    key=mcp_prompt.name,  # For 1.x, key and name are the same
+                    name=mcp_prompt.name,
+                    description=mcp_prompt.description,
+                    arguments=arguments,
+                    tags=None,  # 1.x doesn't have tags
+                    enabled=None,  # 1.x doesn't have enabled field
+                )
+            )
+
+        # Extract detailed resource information from MCP Resource objects
+        resource_infos = []
+        for mcp_resource in mcp_resources:
+            resource_infos.append(
+                ResourceInfo(
+                    key=str(mcp_resource.uri),  # For 1.x, key and uri are the same
+                    uri=str(mcp_resource.uri),
+                    name=mcp_resource.name,
+                    description=mcp_resource.description,
+                    mime_type=mcp_resource.mimeType,
+                    tags=None,  # 1.x doesn't have tags
+                    enabled=None,  # 1.x doesn't have enabled field
+                )
+            )
+
+        # Extract detailed template information from MCP ResourceTemplate objects
+        template_infos = []
+        for mcp_template in mcp_templates:
+            template_infos.append(
+                TemplateInfo(
+                    key=str(
+                        mcp_template.uriTemplate
+                    ),  # For 1.x, key and uriTemplate are the same
+                    uri_template=str(mcp_template.uriTemplate),
+                    name=mcp_template.name,
+                    description=mcp_template.description,
+                    mime_type=mcp_template.mimeType,
+                    tags=None,  # 1.x doesn't have tags
+                    enabled=None,  # 1.x doesn't have enabled field
+                )
+            )
+
+        # Basic MCP capabilities
+        capabilities = {
+            "tools": {"listChanged": True},
+            "resources": {"subscribe": False, "listChanged": False},
+            "prompts": {"listChanged": False},
+            "logging": {},
+        }
+
+        return FastMCPInfo(
+            name=mcp.name,
+            instructions=getattr(mcp, "instructions", None),
+            fastmcp_version=fastmcp.__version__,  # Report current fastmcp version
+            mcp_version=importlib.metadata.version("mcp"),
+            server_version="1.0",  # FastMCP 1.x version
+            tools=tool_infos,
+            prompts=prompt_infos,
+            resources=resource_infos,
+            templates=template_infos,  # FastMCP1x does have templates
+            capabilities=capabilities,
+        )
+
+
+def _is_fastmcp_v1(mcp: Any) -> bool:
+    """Check if the given instance is a FastMCP v1.x instance."""
+
+    # Check if it's an instance of FastMCP1x and not FastMCP2
+    return isinstance(mcp, FastMCP1x) and not isinstance(mcp, FastMCP)
+
+
+async def inspect_fastmcp(mcp: FastMCP[Any] | Any) -> FastMCPInfo:
+    """Extract information from a FastMCP instance into a dataclass.
+
+    This function automatically detects whether the instance is FastMCP v1.x or v2.x
+    and uses the appropriate extraction method.
+
+    Args:
+        mcp: The FastMCP instance to inspect (v1.x or v2.x)
+
+    Returns:
+        FastMCPInfo dataclass containing the extracted information
+    """
+    if _is_fastmcp_v1(mcp):
+        return await inspect_fastmcp_v1(mcp)
+    else:
+        return await inspect_fastmcp_v2(mcp)