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

fastmcp/prompts/prompt_manager.py

@@ -13,7 +13,7 @@ from fastmcp.settings import DuplicateBehavior
 from fastmcp.utilities.logging import get_logger
 
 if TYPE_CHECKING:
-    pass
+    from fastmcp.server.server import MountedServer
 
 logger = get_logger(__name__)
 
@@ -27,6 +27,7 @@ class PromptManager:
         mask_error_details: bool | None = None,
     ):
         self._prompts: dict[str, Prompt] = {}
+        self._mounted_servers: list[MountedServer] = []
         self.mask_error_details = mask_error_details or settings.mask_error_details
 
         # Default to "warn" if None is provided
@@ -41,15 +42,74 @@ class PromptManager:
 
         self.duplicate_behavior = duplicate_behavior
 
-    def get_prompt(self, key: str) -> Prompt:
+    def mount(self, server: MountedServer) -> None:
+        """Adds a mounted server as a source for prompts."""
+        self._mounted_servers.append(server)
+
+    async def _load_prompts(self, *, via_server: bool = False) -> dict[str, Prompt]:
+        """
+        The single, consolidated recursive method for fetching prompts. 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_prompts: dict[str, Prompt] = {}
+
+        for mounted in self._mounted_servers:
+            try:
+                if via_server:
+                    # Use the server-to-server filtered path
+                    child_results = await mounted.server._list_prompts()
+                else:
+                    # Use the manager-to-manager unfiltered path
+                    child_results = await mounted.server._prompt_manager.list_prompts()
+
+                # The combination logic is the same for both paths
+                child_dict = {p.key: p for p in child_results}
+                if mounted.prefix:
+                    for prompt in child_dict.values():
+                        prefixed_prompt = prompt.with_key(
+                            f"{mounted.prefix}_{prompt.key}"
+                        )
+                        all_prompts[prefixed_prompt.key] = prefixed_prompt
+                else:
+                    all_prompts.update(child_dict)
+            except Exception as e:
+                # Skip failed mounts silently, matches existing behavior
+                logger.warning(
+                    f"Failed to get prompts from mounted server '{mounted.prefix}': {e}"
+                )
+                continue
+
+        # Finally, add local prompts, which always take precedence
+        all_prompts.update(self._prompts)
+        return all_prompts
+
+    async def has_prompt(self, key: str) -> bool:
+        """Check if a prompt exists."""
+        prompts = await self.get_prompts()
+        return key in prompts
+
+    async def get_prompt(self, key: str) -> Prompt:
         """Get prompt by key."""
-        if key in self._prompts:
-            return self._prompts[key]
+        prompts = await self.get_prompts()
+        if key in prompts:
+            return prompts[key]
         raise NotFoundError(f"Unknown prompt: {key}")
 
-    def get_prompts(self) -> dict[str, Prompt]:
-        """Get all registered prompts, indexed by registered key."""
-        return self._prompts
+    async def get_prompts(self) -> dict[str, Prompt]:
+        """
+        Gets the complete, unfiltered inventory of all prompts.
+        """
+        return await self._load_prompts(via_server=False)
+
+    async def list_prompts(self) -> list[Prompt]:
+        """
+        Lists all prompts, applying protocol filtering.
+        """
+        prompts_dict = await self._load_prompts(via_server=True)
+        return list(prompts_dict.values())
 
     def add_prompt_from_fn(
         self,
@@ -71,24 +131,22 @@ class PromptManager:
         )
         return self.add_prompt(prompt)  # type: ignore
 
-    def add_prompt(self, prompt: Prompt, key: str | None = None) -> Prompt:
+    def add_prompt(self, prompt: Prompt) -> Prompt:
         """Add a prompt to the manager."""
-        key = key or prompt.name
-
         # Check for duplicates
-        existing = self._prompts.get(key)
+        existing = self._prompts.get(prompt.key)
         if existing:
             if self.duplicate_behavior == "warn":
-                logger.warning(f"Prompt already exists: {key}")
-                self._prompts[key] = prompt
+                logger.warning(f"Prompt already exists: {prompt.key}")
+                self._prompts[prompt.key] = prompt
             elif self.duplicate_behavior == "replace":
-                self._prompts[key] = prompt
+                self._prompts[prompt.key] = prompt
             elif self.duplicate_behavior == "error":
-                raise ValueError(f"Prompt already exists: {key}")
+                raise ValueError(f"Prompt already exists: {prompt.key}")
             elif self.duplicate_behavior == "ignore":
                 return existing
         else:
-            self._prompts[key] = prompt
+            self._prompts[prompt.key] = prompt
         return prompt
 
     async def render_prompt(
@@ -96,30 +154,48 @@ class PromptManager:
         name: str,
         arguments: dict[str, Any] | None = None,
     ) -> GetPromptResult:
-        """Render a prompt by name with arguments."""
-        prompt = self.get_prompt(name)
-        if not prompt:
-            raise NotFoundError(f"Unknown prompt: {name}")
-
-        try:
-            messages = await prompt.render(arguments)
-            return GetPromptResult(description=prompt.description, messages=messages)
-
-        # Pass through PromptErrors as-is
-        except PromptError as e:
-            logger.exception(f"Error rendering prompt {name!r}: {e}")
-            raise e
-
-        # Handle other exceptions
-        except Exception as e:
-            logger.exception(f"Error rendering prompt {name!r}: {e}")
-            if self.mask_error_details:
-                # Mask internal details
-                raise PromptError(f"Error rendering prompt {name!r}")
-            else:
-                # Include original error details
-                raise PromptError(f"Error rendering prompt {name!r}: {e}")
-
-    def has_prompt(self, key: str) -> bool:
-        """Check if a prompt exists."""
-        return key in self._prompts
+        """
+        Internal API for servers: Finds and renders a prompt, respecting the
+        filtered protocol path.
+        """
+        # 1. Check local prompts first. The server will have already applied its filter.
+        if name in self._prompts:
+            prompt = await self.get_prompt(name)
+            if not prompt:
+                raise NotFoundError(f"Unknown prompt: {name}")
+
+            try:
+                messages = await prompt.render(arguments)
+                return GetPromptResult(
+                    description=prompt.description, messages=messages
+                )
+
+            # Pass through PromptErrors as-is
+            except PromptError as e:
+                logger.exception(f"Error rendering prompt {name!r}: {e}")
+                raise e
+
+            # Handle other exceptions
+            except Exception as e:
+                logger.exception(f"Error rendering prompt {name!r}: {e}")
+                if self.mask_error_details:
+                    # Mask internal details
+                    raise PromptError(f"Error rendering prompt {name!r}") from e
+                else:
+                    # Include original error details
+                    raise PromptError(f"Error rendering prompt {name!r}: {e}") from e
+
+        # 2. Check mounted servers using the filtered protocol path.
+        for mounted in reversed(self._mounted_servers):
+            prompt_key = name
+            if mounted.prefix:
+                if name.startswith(f"{mounted.prefix}_"):
+                    prompt_key = name.removeprefix(f"{mounted.prefix}_")
+                else:
+                    continue
+            try:
+                return await mounted.server._get_prompt(prompt_key, arguments)
+            except NotFoundError:
+                continue
+
+        raise NotFoundError(f"Unknown prompt: {name}")

fastmcp/resources/resource.py

@@ -101,6 +101,16 @@ class Resource(FastMCPComponent, abc.ABC):
     def __repr__(self) -> str:
         return f"{self.__class__.__name__}(uri={self.uri!r}, name={self.name!r}, description={self.description!r}, tags={self.tags})"
 
+    @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 str(self.uri)
+
 
 class FunctionResource(Resource):
     """A resource that defers data loading by wrapping a function.
@@ -135,7 +145,7 @@ class FunctionResource(Resource):
             fn=fn,
             uri=uri,
             name=name or fn.__name__,
-            description=description or fn.__doc__,
+            description=description or inspect.getdoc(fn),
             mime_type=mime_type or "text/plain",
             tags=tags or set(),
             enabled=enabled if enabled is not None else True,

fastmcp/resources/resource_manager.py

@@ -1,9 +1,11 @@
 """Resource manager functionality."""
 
+from __future__ import annotations
+
 import inspect
 import warnings
 from collections.abc import Callable
-from typing import Any
+from typing import TYPE_CHECKING, Any
 
 from pydantic import AnyUrl
 
@@ -17,6 +19,9 @@ from fastmcp.resources.template import (
 from fastmcp.settings import DuplicateBehavior
 from fastmcp.utilities.logging import get_logger
 
+if TYPE_CHECKING:
+    from fastmcp.server.server import MountedServer
+
 logger = get_logger(__name__)
 
 
@@ -38,6 +43,7 @@ class ResourceManager:
         """
         self._resources: dict[str, Resource] = {}
         self._templates: dict[str, ResourceTemplate] = {}
+        self._mounted_servers: list[MountedServer] = []
         self.mask_error_details = mask_error_details or settings.mask_error_details
 
         # Default to "warn" if None is provided
@@ -51,6 +57,128 @@ class ResourceManager:
             )
         self.duplicate_behavior = duplicate_behavior
 
+    def mount(self, server: MountedServer) -> None:
+        """Adds a mounted server as a source for resources and templates."""
+        self._mounted_servers.append(server)
+
+    async def get_resources(self) -> dict[str, Resource]:
+        """Get all registered resources, keyed by URI."""
+        return await self._load_resources(via_server=False)
+
+    async def get_resource_templates(self) -> dict[str, ResourceTemplate]:
+        """Get all registered templates, keyed by URI template."""
+        return await self._load_resource_templates(via_server=False)
+
+    async def _load_resources(self, *, via_server: bool = False) -> dict[str, Resource]:
+        """
+        The single, consolidated recursive method for fetching resources. 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_resources: dict[str, Resource] = {}
+
+        for mounted in self._mounted_servers:
+            try:
+                if via_server:
+                    # Use the server-to-server filtered path
+                    child_resources_list = await mounted.server._list_resources()
+                    child_resources = {
+                        resource.key: resource for resource in child_resources_list
+                    }
+                else:
+                    # Use the manager-to-manager unfiltered path
+                    child_resources = (
+                        await mounted.server._resource_manager.get_resources()
+                    )
+
+                # Apply prefix if needed
+                if mounted.prefix:
+                    from fastmcp.server.server import add_resource_prefix
+
+                    for uri, resource in child_resources.items():
+                        prefixed_uri = add_resource_prefix(
+                            uri, mounted.prefix, mounted.resource_prefix_format
+                        )
+                        # Create a copy of the resource with the prefixed key
+                        prefixed_resource = resource.with_key(prefixed_uri)
+                        all_resources[prefixed_uri] = prefixed_resource
+                else:
+                    all_resources.update(child_resources)
+            except Exception as e:
+                # Skip failed mounts silently, matches existing behavior
+                logger.warning(
+                    f"Failed to get resources from mounted server '{mounted.prefix}': {e}"
+                )
+                continue
+
+        # Finally, add local resources, which always take precedence
+        all_resources.update(self._resources)
+        return all_resources
+
+    async def _load_resource_templates(
+        self, *, via_server: bool = False
+    ) -> dict[str, ResourceTemplate]:
+        """
+        The single, consolidated recursive method for fetching templates. 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_templates: dict[str, ResourceTemplate] = {}
+
+        for mounted in self._mounted_servers:
+            try:
+                if via_server:
+                    # Use the server-to-server filtered path
+                    child_templates = await mounted.server._list_resource_templates()
+                else:
+                    # Use the manager-to-manager unfiltered path
+                    child_templates = (
+                        await mounted.server._resource_manager.list_resource_templates()
+                    )
+                child_dict = {template.key: template for template in child_templates}
+
+                # Apply prefix if needed
+                if mounted.prefix:
+                    from fastmcp.server.server import add_resource_prefix
+
+                    for uri_template, template in child_dict.items():
+                        prefixed_uri_template = add_resource_prefix(
+                            uri_template, mounted.prefix, mounted.resource_prefix_format
+                        )
+                        # Create a copy of the template with the prefixed key
+                        prefixed_template = template.with_key(prefixed_uri_template)
+                        all_templates[prefixed_uri_template] = prefixed_template
+                else:
+                    all_templates.update(child_dict)
+            except Exception as e:
+                # Skip failed mounts silently, matches existing behavior
+                logger.warning(
+                    f"Failed to get templates from mounted server '{mounted.prefix}': {e}"
+                )
+                continue
+
+        # Finally, add local templates, which always take precedence
+        all_templates.update(self._templates)
+        return all_templates
+
+    async def list_resources(self) -> list[Resource]:
+        """
+        Lists all resources, applying protocol filtering.
+        """
+        resources_dict = await self._load_resources(via_server=True)
+        return list(resources_dict.values())
+
+    async def list_resource_templates(self) -> list[ResourceTemplate]:
+        """
+        Lists all templates, applying protocol filtering.
+        """
+        templates_dict = await self._load_resource_templates(via_server=True)
+        return list(templates_dict.values())
+
     def add_resource_or_template_from_fn(
         self,
         fn: Callable[..., Any],
@@ -139,35 +267,26 @@ class ResourceManager:
         )
         return self.add_resource(resource)
 
-    def add_resource(self, resource: Resource, key: str | None = None) -> Resource:
+    def add_resource(self, resource: Resource) -> Resource:
         """Add a resource to the manager.
 
         Args:
-            resource: A Resource instance to add
-            key: Optional URI to use as the storage key (if different from resource.uri)
+            resource: A Resource instance to add. The resource's .key attribute
+                will be used as the storage key. To overwrite it, call
+                Resource.with_key() before calling this method.
         """
-        storage_key = key or str(resource.uri)
-        logger.debug(
-            "Adding resource",
-            extra={
-                "uri": resource.uri,
-                "storage_key": storage_key,
-                "type": type(resource).__name__,
-                "resource_name": resource.name,
-            },
-        )
-        existing = self._resources.get(storage_key)
+        existing = self._resources.get(resource.key)
         if existing:
             if self.duplicate_behavior == "warn":
-                logger.warning(f"Resource already exists: {storage_key}")
-                self._resources[storage_key] = resource
+                logger.warning(f"Resource already exists: {resource.key}")
+                self._resources[resource.key] = resource
             elif self.duplicate_behavior == "replace":
-                self._resources[storage_key] = resource
+                self._resources[resource.key] = resource
             elif self.duplicate_behavior == "error":
-                raise ValueError(f"Resource already exists: {storage_key}")
+                raise ValueError(f"Resource already exists: {resource.key}")
             elif self.duplicate_behavior == "ignore":
                 return existing
-        self._resources[storage_key] = resource
+        self._resources[resource.key] = resource
         return resource
 
     def add_template_from_fn(
@@ -197,52 +316,47 @@ class ResourceManager:
         )
         return self.add_template(template)
 
-    def add_template(
-        self, template: ResourceTemplate, key: str | None = None
-    ) -> ResourceTemplate:
+    def add_template(self, template: ResourceTemplate) -> ResourceTemplate:
         """Add a template to the manager.
 
         Args:
-            template: A ResourceTemplate instance to add
-            key: Optional URI template to use as the storage key (if different from template.uri_template)
+            template: A ResourceTemplate instance to add. The template's .key attribute
+                will be used as the storage key. To overwrite it, call
+                ResourceTemplate.with_key() before calling this method.
 
         Returns:
             The added template. If a template with the same URI already exists,
             returns the existing template.
         """
-        uri_template_str = str(template.uri_template)
-        storage_key = key or uri_template_str
-        logger.debug(
-            "Adding template",
-            extra={
-                "uri_template": uri_template_str,
-                "storage_key": storage_key,
-                "type": type(template).__name__,
-                "template_name": template.name,
-            },
-        )
-        existing = self._templates.get(storage_key)
+        existing = self._templates.get(template.key)
         if existing:
             if self.duplicate_behavior == "warn":
-                logger.warning(f"Template already exists: {storage_key}")
-                self._templates[storage_key] = template
+                logger.warning(f"Template already exists: {template.key}")
+                self._templates[template.key] = template
             elif self.duplicate_behavior == "replace":
-                self._templates[storage_key] = template
+                self._templates[template.key] = template
             elif self.duplicate_behavior == "error":
-                raise ValueError(f"Template already exists: {storage_key}")
+                raise ValueError(f"Template already exists: {template.key}")
             elif self.duplicate_behavior == "ignore":
                 return existing
-        self._templates[storage_key] = template
+        self._templates[template.key] = template
         return template
 
-    def has_resource(self, uri: AnyUrl | str) -> bool:
+    async def has_resource(self, uri: AnyUrl | str) -> bool:
         """Check if a resource exists."""
         uri_str = str(uri)
-        if uri_str in self._resources:
+
+        # First check concrete resources (local and mounted)
+        resources = await self.get_resources()
+        if uri_str in resources:
             return True
-        for template_key in self._templates.keys():
+
+        # Then check templates (local and mounted) only if not found in concrete resources
+        templates = await self.get_resource_templates()
+        for template_key in templates.keys():
             if match_uri_template(uri_str, template_key):
                 return True
+
         return False
 
     async def get_resource(self, uri: AnyUrl | str) -> Resource:
@@ -257,12 +371,14 @@ class ResourceManager:
         uri_str = str(uri)
         logger.debug("Getting resource", extra={"uri": uri_str})
 
-        # First check concrete resources
-        if resource := self._resources.get(uri_str):
+        # First check concrete resources (local and mounted)
+        resources = await self.get_resources()
+        if resource := resources.get(uri_str):
             return resource
 
-        # Then check templates - use the utility function to match against storage keys
-        for storage_key, template in self._templates.items():
+        # Then check templates (local and mounted) - use the utility function to match against storage keys
+        templates = await self.get_resource_templates()
+        for storage_key, template in templates.items():
             # Try to match against the storage key (which might be a custom key)
             if params := match_uri_template(uri_str, storage_key):
                 try:
@@ -289,31 +405,88 @@ class ResourceManager:
         raise NotFoundError(f"Unknown resource: {uri_str}")
 
     async def read_resource(self, uri: AnyUrl | str) -> str | bytes:
-        """Read a resource contents."""
-        resource = await self.get_resource(uri)
-
-        try:
-            return await resource.read()
-
-        # raise ResourceErrors as-is
-        except ResourceError as e:
-            logger.error(f"Error reading resource {uri!r}: {e}")
-            raise e
-
-        # Handle other exceptions
-        except Exception as e:
-            logger.error(f"Error reading resource {uri!r}: {e}")
-            if self.mask_error_details:
-                # Mask internal details
-                raise ResourceError(f"Error reading resource {uri!r}") from e
-            else:
-                # Include original error details
-                raise ResourceError(f"Error reading resource {uri!r}: {e}") from e
-
-    def get_resources(self) -> dict[str, Resource]:
-        """Get all registered resources, keyed by URI."""
-        return self._resources
+        """
+        Internal API for servers: Finds and reads a resource, respecting the
+        filtered protocol path.
+        """
+        uri_str = str(uri)
 
-    def get_templates(self) -> dict[str, ResourceTemplate]:
-        """Get all registered templates, keyed by URI template."""
-        return self._templates
+        # 1. Check local resources first. The server will have already applied its filter.
+        if uri_str in self._resources:
+            resource = await self.get_resource(uri_str)
+            if not resource:
+                raise NotFoundError(f"Resource {uri_str!r} not found")
+
+            try:
+                return await resource.read()
+
+            # raise ResourceErrors as-is
+            except ResourceError as e:
+                logger.exception(f"Error reading resource {uri_str!r}: {e}")
+                raise e
+
+            # Handle other exceptions
+            except Exception as e:
+                logger.exception(f"Error reading resource {uri_str!r}: {e}")
+                if self.mask_error_details:
+                    # Mask internal details
+                    raise ResourceError(f"Error reading resource {uri_str!r}") from e
+                else:
+                    # Include original error details
+                    raise ResourceError(
+                        f"Error reading resource {uri_str!r}: {e}"
+                    ) from e
+
+        # 1b. Check local templates if not found in concrete resources
+        for key, template in self._templates.items():
+            if params := match_uri_template(uri_str, key):
+                try:
+                    resource = await template.create_resource(uri_str, params=params)
+                    return await resource.read()
+                except ResourceError as e:
+                    logger.exception(
+                        f"Error reading resource from template {uri_str!r}: {e}"
+                    )
+                    raise e
+                except Exception as e:
+                    logger.exception(
+                        f"Error reading resource from template {uri_str!r}: {e}"
+                    )
+                    if self.mask_error_details:
+                        raise ResourceError(
+                            f"Error reading resource from template {uri_str!r}"
+                        ) from e
+                    else:
+                        raise ResourceError(
+                            f"Error reading resource from template {uri_str!r}: {e}"
+                        ) from e
+
+        # 2. Check mounted servers using the filtered protocol path.
+        from fastmcp.server.server import has_resource_prefix, remove_resource_prefix
+
+        for mounted in reversed(self._mounted_servers):
+            key = uri_str
+            try:
+                if mounted.prefix:
+                    if has_resource_prefix(
+                        key,
+                        mounted.prefix,
+                        mounted.resource_prefix_format,
+                    ):
+                        key = remove_resource_prefix(
+                            key,
+                            mounted.prefix,
+                            mounted.resource_prefix_format,
+                        )
+                    else:
+                        continue
+
+                try:
+                    result = await mounted.server._read_resource(key)
+                    return result[0].content
+                except NotFoundError:
+                    continue
+            except NotFoundError:
+                continue
+
+        raise NotFoundError(f"Resource {uri_str!r} not found.")