fastmcp 2.0.0__py3-none-any.whl → 2.1.0__py3-none-any.whl

fastmcp/server/openapi.py

@@ -12,7 +12,7 @@ from pydantic.networks import AnyUrl
 
 from fastmcp.resources import Resource, ResourceTemplate
 from fastmcp.server.server import FastMCP
-from fastmcp.tools.base import Tool
+from fastmcp.tools.tool import Tool
 from fastmcp.utilities import openapi
 from fastmcp.utilities.func_metadata import func_metadata
 from fastmcp.utilities.logging import get_logger
@@ -115,6 +115,7 @@ class OpenAPITool(Tool):
         parameters: dict[str, Any],
         fn_metadata: Any,
         is_async: bool = True,
+        tags: set[str] = set(),
     ):
         super().__init__(
             name=name,
@@ -124,6 +125,7 @@ class OpenAPITool(Tool):
             fn_metadata=fn_metadata,
             is_async=is_async,
             context_kwarg="context",  # Default context keyword argument
+            tags=tags,
         )
         self._client = client
         self._route = route
@@ -242,12 +244,14 @@ class OpenAPIResource(Resource):
         name: str,
         description: str,
         mime_type: str = "application/json",
+        tags: set[str] = set(),
     ):
         super().__init__(
             uri=AnyUrl(uri),  # Convert string to AnyUrl
             name=name,
             description=description,
             mime_type=mime_type,
+            tags=tags,
         )
         self._client = client
         self._route = route
@@ -332,6 +336,7 @@ class OpenAPIResourceTemplate(ResourceTemplate):
         name: str,
         description: str,
         parameters: dict[str, Any],
+        tags: set[str] = set(),
     ):
         super().__init__(
             uri_template=uri_template,
@@ -339,6 +344,7 @@ class OpenAPIResourceTemplate(ResourceTemplate):
             description=description,
             fn=self._create_resource_fn,
             parameters=parameters,
+            tags=tags,
         )
         self._client = client
         self._route = route
@@ -405,6 +411,7 @@ class OpenAPIResourceTemplate(ResourceTemplate):
             description=self.description
             or f"Resource for {self._route.path}",  # Provide default if None
             mime_type="application/json",  # Default, will be updated when read
+            tags=set(self._route.tags or []),
         )
 
 
@@ -525,10 +532,13 @@ class FastMCPOpenAPI(FastMCP):
             parameters=combined_schema,
             fn_metadata=func_metadata(_openapi_passthrough),
             is_async=True,
+            tags=set(route.tags or []),
         )
         # Register the tool by directly assigning to the tools dictionary
         self._tool_manager._tools[tool_name] = tool
-        logger.debug(f"Registered TOOL: {tool_name} ({route.method} {route.path})")
+        logger.debug(
+            f"Registered TOOL: {tool_name} ({route.method} {route.path}) with tags: {route.tags}"
+        )
 
     def _create_openapi_resource(self, route: openapi.HTTPRoute, operation_id: str):
         """Creates and registers an OpenAPIResource with enhanced description."""
@@ -550,11 +560,12 @@ class FastMCPOpenAPI(FastMCP):
             uri=resource_uri,
             name=resource_name,
             description=enhanced_description,
+            tags=set(route.tags or []),
         )
         # Register the resource by directly assigning to the resources dictionary
         self._resource_manager._resources[str(resource.uri)] = resource
         logger.debug(
-            f"Registered RESOURCE: {resource_uri} ({route.method} {route.path})"
+            f"Registered RESOURCE: {resource_uri} ({route.method} {route.path}) with tags: {route.tags}"
         )
 
     def _create_openapi_template(self, route: openapi.HTTPRoute, operation_id: str):
@@ -594,11 +605,12 @@ class FastMCPOpenAPI(FastMCP):
             name=template_name,
             description=enhanced_description,
             parameters=template_params_schema,
+            tags=set(route.tags or []),
         )
         # Register the template by directly assigning to the templates dictionary
         self._resource_manager._templates[uri_template_str] = template
         logger.debug(
-            f"Registered TEMPLATE: {uri_template_str} ({route.method} {route.path})"
+            f"Registered TEMPLATE: {uri_template_str} ({route.method} {route.path}) with tags: {route.tags}"
         )
 
     async def call_tool(self, name: str, arguments: dict[str, Any]) -> Any:

fastmcp/server/proxy.py

@@ -9,7 +9,7 @@ from fastmcp.prompts import Prompt
 from fastmcp.resources import Resource, ResourceTemplate
 from fastmcp.server.context import Context
 from fastmcp.server.server import FastMCP
-from fastmcp.tools.base import Tool
+from fastmcp.tools.tool import Tool
 from fastmcp.utilities.func_metadata import func_metadata
 from fastmcp.utilities.logging import get_logger
 
@@ -40,11 +40,15 @@ class ProxyTool(Tool):
     async def run(
         self, arguments: dict[str, Any], context: Context | None = None
     ) -> Any:
+        # the client context manager will swallow any exceptions inside a TaskGroup
+        # so we return the raw result and raise an exception ourselves
         async with self._client:
-            result = await self._client.call_tool(self.name, arguments)
+            result = await self._client.call_tool(
+                self.name, arguments, _return_raw_result=True
+            )
         if result.isError:
             raise ValueError(cast(mcp.types.TextContent, result.content[0]).text)
-        return result.content[0]
+        return result.content
 
 
 class ProxyResource(Resource):
@@ -73,12 +77,12 @@ class ProxyResource(Resource):
 
         async with self._client:
             result = await self._client.read_resource(self.uri)
-        if isinstance(result.contents[0], TextResourceContents):
-            return result.contents[0].text
-        elif isinstance(result.contents[0], BlobResourceContents):
-            return result.contents[0].blob
+        if isinstance(result[0], TextResourceContents):
+            return result[0].text
+        elif isinstance(result[0], BlobResourceContents):
+            return result[0].blob
         else:
-            raise ValueError(f"Unsupported content type: {type(result.contents[0])}")
+            raise ValueError(f"Unsupported content type: {type(result[0])}")
 
 
 class ProxyTemplate(ResourceTemplate):
@@ -103,20 +107,20 @@ class ProxyTemplate(ResourceTemplate):
         async with self._client:
             result = await self._client.read_resource(uri)
 
-        if isinstance(result.contents[0], TextResourceContents):
-            value = result.contents[0].text
-        elif isinstance(result.contents[0], BlobResourceContents):
-            value = result.contents[0].blob
+        if isinstance(result[0], TextResourceContents):
+            value = result[0].text
+        elif isinstance(result[0], BlobResourceContents):
+            value = result[0].blob
         else:
-            raise ValueError(f"Unsupported content type: {type(result.contents[0])}")
+            raise ValueError(f"Unsupported content type: {type(result[0])}")
 
         return ProxyResource(
             client=self._client,
             uri=uri,
             name=self.name,
             description=self.description,
-            mime_type=result.contents[0].mimeType,
-            contents=result.contents,
+            mime_type=result[0].mimeType,
+            contents=result,
             _value=value,
         )
 
@@ -177,15 +181,15 @@ class FastMCPProxy(FastMCP):
 
         async with client:
             # Register proxies for client tools
-            tools_result = await client.list_tools()
-            for tool in tools_result.tools:
+            tools = await client.list_tools()
+            for tool in tools:
                 tool_proxy = await ProxyTool.from_client(client, tool)
                 server._tool_manager._tools[tool_proxy.name] = tool_proxy
                 logger.debug(f"Created proxy for tool: {tool_proxy.name}")
 
             # Register proxies for client resources
-            resources_result = await client.list_resources()
-            for resource in resources_result.resources:
+            resources = await client.list_resources()
+            for resource in resources:
                 resource_proxy = await ProxyResource.from_client(client, resource)
                 server._resource_manager._resources[str(resource_proxy.uri)] = (
                     resource_proxy
@@ -193,8 +197,8 @@ class FastMCPProxy(FastMCP):
                 logger.debug(f"Created proxy for resource: {resource_proxy.uri}")
 
             # Register proxies for client resource templates
-            templates_result = await client.list_resource_templates()
-            for template in templates_result.resourceTemplates:
+            templates = await client.list_resource_templates()
+            for template in templates:
                 template_proxy = await ProxyTemplate.from_client(client, template)
                 server._resource_manager._templates[template_proxy.uri_template] = (
                     template_proxy
@@ -204,8 +208,8 @@ class FastMCPProxy(FastMCP):
                 )
 
             # Register proxies for client prompts
-            prompts_result = await client.list_prompts()
-            for prompt in prompts_result.prompts:
+            prompts = await client.list_prompts()
+            for prompt in prompts:
                 prompt_proxy = await ProxyPrompt.from_client(client, prompt)
                 server._prompt_manager._prompts[prompt_proxy.name] = prompt_proxy
                 logger.debug(f"Created proxy for prompt: {prompt_proxy.name}")

fastmcp/server/server.py

@@ -3,9 +3,10 @@
 import inspect
 import json
 import re
-from collections.abc import AsyncIterator, Callable, Sequence
+from collections.abc import AsyncIterator, Callable
 from contextlib import (
     AbstractAsyncContextManager,
+    AsyncExitStack,
     asynccontextmanager,
 )
 from typing import TYPE_CHECKING, Any, Generic, Literal
@@ -18,7 +19,6 @@ from fastapi import FastAPI
 from mcp.server.lowlevel.helper_types import ReadResourceContents
 from mcp.server.lowlevel.server import LifespanResultT
 from mcp.server.lowlevel.server import Server as MCPServer
-from mcp.server.lowlevel.server import lifespan as default_lifespan
 from mcp.server.session import ServerSession
 from mcp.server.sse import SseServerTransport
 from mcp.server.stdio import stdio_server
@@ -56,6 +56,19 @@ if TYPE_CHECKING:
 logger = get_logger(__name__)
 
 
+@asynccontextmanager
+async def default_lifespan(server: "FastMCP") -> AsyncIterator[Any]:
+    """Default lifespan context manager that does nothing.
+
+    Args:
+        server: The server instance this lifespan is managing
+
+    Returns:
+        An empty context object
+    """
+    yield {}
+
+
 def lifespan_wrapper(
     app: "FastMCP",
     lifespan: Callable[["FastMCP"], AbstractAsyncContextManager[LifespanResultT]],
@@ -64,7 +77,18 @@ def lifespan_wrapper(
 ]:
     @asynccontextmanager
     async def wrap(s: MCPServer[LifespanResultT]) -> AsyncIterator[LifespanResultT]:
-        async with lifespan(app) as context:
+        async with AsyncExitStack() as stack:
+            # enter main app's lifespan
+            context = await stack.enter_async_context(lifespan(app))
+
+            # Enter all mounted app lifespans
+            for prefix, mounted_app in app._mounted_apps.items():
+                mounted_context = mounted_app._mcp_server.lifespan(
+                    mounted_app._mcp_server
+                )
+                await stack.enter_async_context(mounted_context)
+                logger.debug(f"Prepared lifespan for mounted app '{prefix}'")
+
             yield context
 
     return wrap
@@ -78,29 +102,34 @@ class FastMCP(Generic[LifespanResultT]):
         lifespan: (
             Callable[["FastMCP"], AbstractAsyncContextManager[LifespanResultT]] | None
         ) = None,
+        tags: set[str] | None = None,
         **settings: Any,
     ):
+        self.tags: set[str] = tags or set()
         self.settings = fastmcp.settings.ServerSettings(**settings)
 
+        # Setup for mounted apps - must be initialized before _mcp_server
+        self._mounted_apps: dict[str, FastMCP] = {}
+
+        if lifespan is None:
+            lifespan = default_lifespan
+
         self._mcp_server = MCPServer[LifespanResultT](
             name=name or "FastMCP",
             instructions=instructions,
-            lifespan=lifespan_wrapper(self, lifespan) if lifespan else default_lifespan,  # type: ignore
+            lifespan=lifespan_wrapper(self, lifespan),
         )
         self._tool_manager = ToolManager(
-            warn_on_duplicate_tools=self.settings.warn_on_duplicate_tools
+            duplicate_behavior=self.settings.on_duplicate_tools
         )
         self._resource_manager = ResourceManager(
-            warn_on_duplicate_resources=self.settings.warn_on_duplicate_resources
+            duplicate_behavior=self.settings.on_duplicate_resources
         )
         self._prompt_manager = PromptManager(
-            warn_on_duplicate_prompts=self.settings.warn_on_duplicate_prompts
+            duplicate_behavior=self.settings.on_duplicate_prompts
         )
         self.dependencies = self.settings.dependencies
 
-        # Setup for mounted apps
-        self._mounted_apps: dict[str, FastMCP] = {}
-
         # Set up MCP protocol handlers
         self._setup_handlers()
 
@@ -151,6 +180,7 @@ class FastMCP(Generic[LifespanResultT]):
 
     async def list_tools(self) -> list[MCPTool]:
         """List all available tools."""
+
         tools = self._tool_manager.list_tools()
         return [
             MCPTool(
@@ -177,7 +207,7 @@ class FastMCP(Generic[LifespanResultT]):
 
     async def call_tool(
         self, name: str, arguments: dict[str, Any]
-    ) -> Sequence[TextContent | ImageContent | EmbeddedResource]:
+    ) -> list[TextContent | ImageContent | EmbeddedResource]:
         """Call a tool by name with arguments."""
         context = self.get_context()
         result = await self._tool_manager.call_tool(name, arguments, context=context)
@@ -228,6 +258,7 @@ class FastMCP(Generic[LifespanResultT]):
         fn: AnyFunction,
         name: str | None = None,
         description: str | None = None,
+        tags: set[str] | None = None,
     ) -> None:
         """Add a tool to the server.
 
@@ -238,11 +269,17 @@ class FastMCP(Generic[LifespanResultT]):
             fn: The function to register as a tool
             name: Optional name for the tool (defaults to function name)
             description: Optional description of what the tool does
+            tags: Optional set of tags for categorizing the tool
         """
-        self._tool_manager.add_tool(fn, name=name, description=description)
+        self._tool_manager.add_tool_from_fn(
+            fn, name=name, description=description, tags=tags
+        )
 
     def tool(
-        self, name: str | None = None, description: str | None = None
+        self,
+        name: str | None = None,
+        description: str | None = None,
+        tags: set[str] | None = None,
     ) -> Callable[[AnyFunction], AnyFunction]:
         """Decorator to register a tool.
 
@@ -253,6 +290,7 @@ class FastMCP(Generic[LifespanResultT]):
         Args:
             name: Optional name for the tool (defaults to function name)
             description: Optional description of what the tool does
+            tags: Optional set of tags for categorizing the tool
 
         Example:
             @server.tool()
@@ -277,7 +315,7 @@ class FastMCP(Generic[LifespanResultT]):
             )
 
         def decorator(fn: AnyFunction) -> AnyFunction:
-            self.add_tool(fn, name=name, description=description)
+            self.add_tool(fn, name=name, description=description, tags=tags)
             return fn
 
         return decorator
@@ -297,6 +335,7 @@ class FastMCP(Generic[LifespanResultT]):
         name: str | None = None,
         description: str | None = None,
         mime_type: str | None = None,
+        tags: set[str] | None = None,
     ) -> Callable[[AnyFunction], AnyFunction]:
         """Decorator to register a function as a resource.
 
@@ -314,6 +353,7 @@ class FastMCP(Generic[LifespanResultT]):
             name: Optional name for the resource
             description: Optional description of the resource
             mime_type: Optional MIME type for the resource
+            tags: Optional set of tags for categorizing the resource
 
         Example:
             @server.resource("resource://my-resource")
@@ -358,12 +398,13 @@ class FastMCP(Generic[LifespanResultT]):
                     )
 
                 # Register as template
-                self._resource_manager.add_template(
+                self._resource_manager.add_template_from_fn(
                     fn=fn,
                     uri_template=uri,
                     name=name,
                     description=description,
                     mime_type=mime_type or "text/plain",
+                    tags=tags,
                 )
             else:
                 # Register as regular resource
@@ -373,6 +414,7 @@ class FastMCP(Generic[LifespanResultT]):
                     description=description,
                     mime_type=mime_type or "text/plain",
                     fn=fn,
+                    tags=tags or set(),  # Default to empty set if None
                 )
                 self.add_resource(resource)
             return fn
@@ -388,13 +430,17 @@ class FastMCP(Generic[LifespanResultT]):
         self._prompt_manager.add_prompt(prompt)
 
     def prompt(
-        self, name: str | None = None, description: str | None = None
+        self,
+        name: str | None = None,
+        description: str | None = None,
+        tags: set[str] | None = None,
     ) -> Callable[[AnyFunction], AnyFunction]:
         """Decorator to register a prompt.
 
         Args:
             name: Optional name for the prompt (defaults to function name)
             description: Optional description of what the prompt does
+            tags: Optional set of tags for categorizing the prompt
 
         Example:
             @server.prompt()
@@ -431,7 +477,9 @@ class FastMCP(Generic[LifespanResultT]):
             )
 
         def decorator(func: AnyFunction) -> AnyFunction:
-            prompt = Prompt.from_function(func, name=name, description=description)
+            prompt = Prompt.from_function(
+                func, name=name, description=description, tags=tags
+            )
             self.add_prompt(prompt)
             return func
 
@@ -514,37 +562,56 @@ class FastMCP(Generic[LifespanResultT]):
             logger.error(f"Error getting prompt {name}: {e}")
             raise ValueError(str(e))
 
-    def mount(self, prefix: str, app: "FastMCP") -> None:
+    def mount(
+        self,
+        prefix: str,
+        app: "FastMCP",
+        tool_separator: str | None = None,
+        resource_separator: str | None = None,
+        prompt_separator: str | None = None,
+    ) -> None:
         """Mount another FastMCP application with a given prefix.
 
         When an application is mounted:
-        - The tools are imported with prefixed names
-          Example: If app has a tool named "get_weather", it will be available as "weather/get_weather"
-        - The resources are imported with prefixed URIs
+        - The tools are imported with prefixed names using the tool_separator
+          Example: If app has a tool named "get_weather", it will be available as "weatherget_weather"
+        - The resources are imported with prefixed URIs using the resource_separator
           Example: If app has a resource with URI "weather://forecast", it will be available as "weather+weather://forecast"
-        - The templates are imported with prefixed URI templates
+        - The templates are imported with prefixed URI templates using the resource_separator
           Example: If app has a template with URI "weather://location/{id}", it will be available as "weather+weather://location/{id}"
-        - The prompts are imported with prefixed names
-          Example: If app has a prompt named "weather_prompt", it will be available as "weather/weather_prompt"
+        - The prompts are imported with prefixed names using the prompt_separator
+          Example: If app has a prompt named "weather_prompt", it will be available as "weather_weather_prompt"
+        - The mounted app's lifespan will be executed when the parent app's lifespan runs,
+          ensuring that any setup needed by the mounted app is performed
 
         Args:
             prefix: The prefix to use for the mounted application
             app: The FastMCP application to mount
+            tool_separator: Separator for tool names (defaults to "_")
+            resource_separator: Separator for resource URIs (defaults to "+")
+            prompt_separator: Separator for prompt names (defaults to "_")
         """
+        if tool_separator is None:
+            tool_separator = "_"
+        if resource_separator is None:
+            resource_separator = "+"
+        if prompt_separator is None:
+            prompt_separator = "_"
+
         # Mount the app in the list of mounted apps
         self._mounted_apps[prefix] = app
 
-        # Import tools from the mounted app with / delimiter
-        tool_prefix = f"{prefix}/"
+        # Import tools from the mounted app
+        tool_prefix = f"{prefix}{tool_separator}"
         self._tool_manager.import_tools(app._tool_manager, tool_prefix)
 
-        # Import resources and templates from the mounted app with + delimiter
-        resource_prefix = f"{prefix}+"
+        # Import resources and templates from the mounted app
+        resource_prefix = f"{prefix}{resource_separator}"
         self._resource_manager.import_resources(app._resource_manager, resource_prefix)
         self._resource_manager.import_templates(app._resource_manager, resource_prefix)
 
-        # Import prompts with / delimiter
-        prompt_prefix = f"{prefix}/"
+        # Import prompts from the mounted app
+        prompt_prefix = f"{prefix}{prompt_separator}"
         self._prompt_manager.import_prompts(app._prompt_manager, prompt_prefix)
 
         logger.info(f"Mounted app with prefix '{prefix}'")

fastmcp/settings.py

@@ -1,5 +1,6 @@
 from __future__ import annotations as _annotations
 
+from enum import Enum
 from typing import TYPE_CHECKING, Literal
 
 from pydantic import Field
@@ -11,6 +12,13 @@ if TYPE_CHECKING:
 LOG_LEVEL = Literal["DEBUG", "INFO", "WARNING", "ERROR", "CRITICAL"]
 
 
+class DuplicateBehavior(Enum):
+    WARN = "warn"
+    ERROR = "error"
+    REPLACE = "replace"
+    IGNORE = "ignore"
+
+
 class Settings(BaseSettings):
     """FastMCP settings."""
 
@@ -47,13 +55,13 @@ class ServerSettings(BaseSettings):
     debug: bool = False
 
     # resource settings
-    warn_on_duplicate_resources: bool = True
+    on_duplicate_resources: DuplicateBehavior = DuplicateBehavior.WARN
 
     # tool settings
-    warn_on_duplicate_tools: bool = True
+    on_duplicate_tools: DuplicateBehavior = DuplicateBehavior.WARN
 
     # prompt settings
-    warn_on_duplicate_prompts: bool = True
+    on_duplicate_prompts: DuplicateBehavior = DuplicateBehavior.WARN
 
     dependencies: list[str] = Field(
         default_factory=list,

fastmcp/tools/__init__.py

@@ -1,4 +1,4 @@
-from .base import Tool
+from .tool import Tool
 from .tool_manager import ToolManager
 
 __all__ = ["Tool", "ToolManager"]

fastmcp/tools/{base.py → tool.py}

@@ -2,12 +2,14 @@ from __future__ import annotations as _annotations
 
 import inspect
 from collections.abc import Callable
-from typing import TYPE_CHECKING, Any
+from typing import TYPE_CHECKING, Annotated, Any
 
-from pydantic import BaseModel, Field
+from pydantic import BaseModel, BeforeValidator, Field
+from typing_extensions import Self
 
 from fastmcp.exceptions import ToolError
 from fastmcp.utilities.func_metadata import FuncMetadata, func_metadata
+from fastmcp.utilities.types import _convert_set_defaults
 
 if TYPE_CHECKING:
     from mcp.server.session import ServerSessionT
@@ -19,7 +21,7 @@ if TYPE_CHECKING:
 class Tool(BaseModel):
     """Internal tool registration info."""
 
-    fn: Callable[..., Any] = Field(exclude=True)
+    fn: Callable[..., Any]
     name: str = Field(description="Name of the tool")
     description: str = Field(description="Description of what the tool does")
     parameters: dict[str, Any] = Field(description="JSON schema for tool parameters")
@@ -31,6 +33,9 @@ class Tool(BaseModel):
     context_kwarg: str | None = Field(
         None, description="Name of the kwarg that should receive context"
     )
+    tags: Annotated[set[str], BeforeValidator(_convert_set_defaults)] = Field(
+        default_factory=set, description="Tags for the tool"
+    )
 
     @classmethod
     def from_function(
@@ -39,6 +44,7 @@ class Tool(BaseModel):
         name: str | None = None,
         description: str | None = None,
         context_kwarg: str | None = None,
+        tags: set[str] | None = None,
     ) -> Tool:
         """Create a Tool from a function."""
         from fastmcp import Context
@@ -72,6 +78,7 @@ class Tool(BaseModel):
             fn_metadata=func_arg_metadata,
             is_async=is_async,
             context_kwarg=context_kwarg,
+            tags=tags or set(),
         )
 
     async def run(
@@ -91,3 +98,15 @@ class Tool(BaseModel):
             )
         except Exception as e:
             raise ToolError(f"Error executing tool {self.name}: {e}") from e
+
+    def copy(self, updates: dict[str, Any] | None = None) -> Self:
+        """Copy the tool with optional updates."""
+        data = self.model_dump()
+        if updates:
+            data.update(updates)
+        return type(self)(**data)
+
+    def __eq__(self, other: object) -> bool:
+        if not isinstance(other, Tool):
+            return False
+        return self.model_dump() == other.model_dump()