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

fastmcp/server/server.py

@@ -1,11 +1,10 @@
 """FastMCP - A more ergonomic interface for MCP servers."""
 
-import inspect
 import json
-import re
-from collections.abc import AsyncIterator, Callable, Sequence
+from collections.abc import AsyncIterator, Awaitable, Callable
 from contextlib import (
     AbstractAsyncContextManager,
+    AsyncExitStack,
     asynccontextmanager,
 )
 from typing import TYPE_CHECKING, Any, Generic, Literal
@@ -18,7 +17,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
@@ -43,8 +41,12 @@ import fastmcp
 import fastmcp.settings
 from fastmcp.exceptions import ResourceError
 from fastmcp.prompts import Prompt, PromptManager
-from fastmcp.resources import FunctionResource, Resource, ResourceManager
+from fastmcp.prompts.prompt import Message, PromptResult
+from fastmcp.resources import Resource, ResourceManager
+from fastmcp.resources.template import ResourceTemplate
 from fastmcp.tools import ToolManager
+from fastmcp.tools.tool import Tool
+from fastmcp.utilities.decorators import DecoratedFunction
 from fastmcp.utilities.logging import configure_logging, get_logger
 from fastmcp.utilities.types import Image
 
@@ -56,6 +58,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 +79,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 +104,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()
 
@@ -137,21 +168,32 @@ class FastMCP(Generic[LifespanResultT]):
         Args:
             transport: Transport protocol to use ("stdio" or "sse")
         """
+        logger.info(f'Starting server "{self.name}"...')
         anyio.run(self.run_async, transport)
 
     def _setup_handlers(self) -> None:
         """Set up core MCP protocol handlers."""
-        self._mcp_server.list_tools()(self.list_tools)
+        self._mcp_server.list_tools()(self._mcp_list_tools)
         self._mcp_server.call_tool()(self.call_tool)
-        self._mcp_server.list_resources()(self.list_resources)
-        self._mcp_server.read_resource()(self.read_resource)
-        self._mcp_server.list_prompts()(self.list_prompts)
-        self._mcp_server.get_prompt()(self.get_prompt)
-        self._mcp_server.list_resource_templates()(self.list_resource_templates)
-
-    async def list_tools(self) -> list[MCPTool]:
-        """List all available tools."""
-        tools = self._tool_manager.list_tools()
+        self._mcp_server.list_resources()(self._mcp_list_resources)
+        self._mcp_server.read_resource()(self._mcp_read_resource)
+        self._mcp_server.list_prompts()(self._mcp_list_prompts)
+        self._mcp_server.get_prompt()(self._mcp_get_prompt)
+        self._mcp_server.list_resource_templates()(self._mcp_list_resource_templates)
+
+    def list_tools(self) -> list[Tool]:
+        return self._tool_manager.list_tools()
+
+    async def _mcp_list_tools(self) -> list[MCPTool]:
+        """
+        List all available tools, in the format expected by the low-level MCP
+        server.
+
+        See `list_tools` for a more ergonomic way to list tools.
+        """
+
+        tools = self.list_tools()
+
         return [
             MCPTool(
                 name=info.name,
@@ -177,17 +219,25 @@ 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)
         converted_result = _convert_to_content(result)
         return converted_result
 
-    async def list_resources(self) -> list[MCPResource]:
-        """List all available resources."""
+    def list_resources(self) -> list[Resource]:
+        return self._resource_manager.list_resources()
 
-        resources = self._resource_manager.list_resources()
+    async def _mcp_list_resources(self) -> list[MCPResource]:
+        """
+        List all available resources, in the format expected by the low-level MCP
+        server.
+
+        See `list_resources` for a more ergonomic way to list resources.
+        """
+
+        resources = self.list_resources()
         return [
             MCPResource(
                 uri=resource.uri,
@@ -198,8 +248,18 @@ class FastMCP(Generic[LifespanResultT]):
             for resource in resources
         ]
 
-    async def list_resource_templates(self) -> list[MCPResourceTemplate]:
-        templates = self._resource_manager.list_templates()
+    def list_resource_templates(self) -> list[ResourceTemplate]:
+        return self._resource_manager.list_templates()
+
+    async def _mcp_list_resource_templates(self) -> list[MCPResourceTemplate]:
+        """
+        List all available resource templates, in the format expected by the low-level
+        MCP server.
+
+        See `list_resource_templates` for a more ergonomic way to list resource
+        templates.
+        """
+        templates = self.list_resource_templates()
         return [
             MCPResourceTemplate(
                 uriTemplate=template.uri_template,
@@ -209,15 +269,27 @@ class FastMCP(Generic[LifespanResultT]):
             for template in templates
         ]
 
-    async def read_resource(self, uri: AnyUrl | str) -> list[ReadResourceContents]:
+    async def read_resource(self, uri: AnyUrl | str) -> str | bytes:
         """Read a resource by URI."""
+        resource = await self._resource_manager.get_resource(uri)
+        if not resource:
+            raise ResourceError(f"Unknown resource: {uri}")
+        return await resource.read()
+
+    async def _mcp_read_resource(self, uri: AnyUrl | str) -> list[ReadResourceContents]:
+        """
+        Read a resource by URI, in the format expected by the low-level MCP
+        server.
+
+        See `read_resource` for a more ergonomic way to read resources.
+        """
 
         resource = await self._resource_manager.get_resource(uri)
         if not resource:
             raise ResourceError(f"Unknown resource: {uri}")
 
         try:
-            content = await resource.read()
+            content = await self.read_resource(uri)
             return [ReadResourceContents(content=content, mime_type=resource.mime_type)]
         except Exception as e:
             logger.error(f"Error reading resource {uri}: {e}")
@@ -228,6 +300,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 +311,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 +332,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()
@@ -269,6 +349,7 @@ class FastMCP(Generic[LifespanResultT]):
                 await context.report_progress(50, 100)
                 return str(x)
         """
+
         # Check if user passed function directly instead of calling decorator
         if callable(name):
             raise TypeError(
@@ -277,8 +358,8 @@ class FastMCP(Generic[LifespanResultT]):
             )
 
         def decorator(fn: AnyFunction) -> AnyFunction:
-            self.add_tool(fn, name=name, description=description)
-            return fn
+            self.add_tool(fn, name=name, description=description, tags=tags)
+            return DecoratedFunction(fn)
 
         return decorator
 
@@ -288,8 +369,40 @@ class FastMCP(Generic[LifespanResultT]):
         Args:
             resource: A Resource instance to add
         """
+
         self._resource_manager.add_resource(resource)
 
+    def add_resource_fn(
+        self,
+        fn: AnyFunction,
+        uri: str,
+        name: str | None = None,
+        description: str | None = None,
+        mime_type: str | None = None,
+        tags: set[str] | None = None,
+    ) -> None:
+        """Add a resource or template to the server from a function.
+
+        If the URI contains parameters (e.g. "resource://{param}") or the function
+        has parameters, it will be registered as a template resource.
+
+        Args:
+            fn: The function to register as a resource
+            uri: The URI for the resource
+            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
+        """
+        self._resource_manager.add_resource_or_template_from_fn(
+            fn=fn,
+            uri=uri,
+            name=name,
+            description=description,
+            mime_type=mime_type,
+            tags=tags,
+        )
+
     def resource(
         self,
         uri: str,
@@ -297,6 +410,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 +428,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")
@@ -342,59 +457,49 @@ class FastMCP(Generic[LifespanResultT]):
             )
 
         def decorator(fn: AnyFunction) -> AnyFunction:
-            # Check if this should be a template
-            has_uri_params = "{" in uri and "}" in uri
-            has_func_params = bool(inspect.signature(fn).parameters)
-
-            if has_uri_params or has_func_params:
-                # Validate that URI params match function params
-                uri_params = set(re.findall(r"{(\w+)}", uri))
-                func_params = set(inspect.signature(fn).parameters.keys())
-
-                if uri_params != func_params:
-                    raise ValueError(
-                        f"Mismatch between URI parameters {uri_params} "
-                        f"and function parameters {func_params}"
-                    )
-
-                # Register as template
-                self._resource_manager.add_template(
-                    fn=fn,
-                    uri_template=uri,
-                    name=name,
-                    description=description,
-                    mime_type=mime_type or "text/plain",
-                )
-            else:
-                # Register as regular resource
-                resource = FunctionResource(
-                    uri=AnyUrl(uri),
-                    name=name,
-                    description=description,
-                    mime_type=mime_type or "text/plain",
-                    fn=fn,
-                )
-                self.add_resource(resource)
-            return fn
+            self._resource_manager.add_resource_or_template_from_fn(
+                fn=fn,
+                uri=uri,
+                name=name,
+                description=description,
+                mime_type=mime_type,
+                tags=tags,
+            )
+            return DecoratedFunction(fn)
 
         return decorator
 
-    def add_prompt(self, prompt: Prompt) -> None:
+    def add_prompt(
+        self,
+        fn: Callable[..., PromptResult | Awaitable[PromptResult]],
+        name: str | None = None,
+        description: str | None = None,
+        tags: set[str] | None = None,
+    ) -> None:
         """Add a prompt to the server.
 
         Args:
             prompt: A Prompt instance to add
         """
-        self._prompt_manager.add_prompt(prompt)
+        self._prompt_manager.add_prompt_from_fn(
+            fn=fn,
+            name=name,
+            description=description,
+            tags=tags,
+        )
 
     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,9 +536,8 @@ class FastMCP(Generic[LifespanResultT]):
             )
 
         def decorator(func: AnyFunction) -> AnyFunction:
-            prompt = Prompt.from_function(func, name=name, description=description)
-            self.add_prompt(prompt)
-            return func
+            self.add_prompt(func, name=name, description=description, tags=tags)
+            return DecoratedFunction(func)
 
         return decorator
 
@@ -446,15 +550,20 @@ class FastMCP(Generic[LifespanResultT]):
                 self._mcp_server.create_initialization_options(),
             )
 
-    async def run_sse_async(self) -> None:
+    async def run_sse_async(
+        self,
+        host: str | None = None,
+        port: int | None = None,
+        log_level: str | None = None,
+    ) -> None:
         """Run the server using SSE transport."""
         starlette_app = self.sse_app()
 
         config = uvicorn.Config(
             starlette_app,
-            host=self.settings.host,
-            port=self.settings.port,
-            log_level=self.settings.log_level.lower(),
+            host=host or self.settings.host,
+            port=port or self.settings.port,
+            log_level=log_level or self.settings.log_level.lower(),
         )
         server = uvicorn.Server(config)
         await server.serve()
@@ -483,9 +592,20 @@ class FastMCP(Generic[LifespanResultT]):
             ],
         )
 
-    async def list_prompts(self) -> list[MCPPrompt]:
-        """List all available prompts."""
-        prompts = self._prompt_manager.list_prompts()
+    def list_prompts(self) -> list[Prompt]:
+        """
+        List all available prompts.
+        """
+        return self._prompt_manager.list_prompts()
+
+    async def _mcp_list_prompts(self) -> list[MCPPrompt]:
+        """
+        List all available prompts, in the format expected by the low-level MCP
+        server.
+
+        See `list_prompts` for a more ergonomic way to list prompts.
+        """
+        prompts = self.list_prompts()
         return [
             MCPPrompt(
                 name=prompt.name,
@@ -504,47 +624,77 @@ class FastMCP(Generic[LifespanResultT]):
 
     async def get_prompt(
         self, name: str, arguments: dict[str, Any] | None = None
-    ) -> GetPromptResult:
+    ) -> list[Message]:
         """Get a prompt by name with arguments."""
+        return await self._prompt_manager.render_prompt(name, arguments)
+
+    async def _mcp_get_prompt(
+        self, name: str, arguments: dict[str, Any] | None = None
+    ) -> GetPromptResult:
+        """
+        Get a prompt by name with arguments, in the format expected by the low-level
+        MCP server.
+
+        See `get_prompt` for a more ergonomic way to get prompts.
+        """
         try:
-            messages = await self._prompt_manager.render_prompt(name, arguments)
+            messages = await self.get_prompt(name, arguments)
 
             return GetPromptResult(messages=pydantic_core.to_jsonable_python(messages))
         except Exception as e:
             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"]