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

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}")
+                raise e
+
+            # Handle other exceptions
+            except Exception as e:
+                logger.exception(f"Error reading resource {uri_str!r}")
+                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}"
+                    )
+                    raise e
+                except Exception as e:
+                    logger.exception(
+                        f"Error reading resource from template {uri_str!r}"
+                    )
+                    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.")

fastmcp/resources/template.py

@@ -15,7 +15,7 @@ from pydantic import (
     validate_call,
 )
 
-from fastmcp.resources.types import Resource
+from fastmcp.resources.resource import Resource
 from fastmcp.server.dependencies import get_context
 from fastmcp.utilities.components import FastMCPComponent
 from fastmcp.utilities.json_schema import compress_schema
@@ -62,6 +62,25 @@ class ResourceTemplate(FastMCPComponent):
         description="JSON schema for function parameters"
     )
 
+    def __repr__(self) -> str:
+        return f"{self.__class__.__name__}(uri_template={self.uri_template!r}, name={self.name!r}, description={self.description!r}, tags={self.tags})"
+
+    def enable(self) -> None:
+        super().enable()
+        try:
+            context = get_context()
+            context._queue_resource_list_changed()  # type: ignore[private-use]
+        except RuntimeError:
+            pass  # No context available
+
+    def disable(self) -> None:
+        super().disable()
+        try:
+            context = get_context()
+            context._queue_resource_list_changed()  # type: ignore[private-use]
+        except RuntimeError:
+            pass  # No context available
+
     @staticmethod
     def from_function(
         fn: Callable[..., Any],
@@ -128,6 +147,29 @@ class ResourceTemplate(FastMCPComponent):
         }
         return MCPResourceTemplate(**kwargs | overrides)
 
+    @classmethod
+    def from_mcp_template(cls, mcp_template: MCPResourceTemplate) -> ResourceTemplate:
+        """Creates a FastMCP ResourceTemplate from a raw MCP ResourceTemplate object."""
+        # Note: This creates a simple ResourceTemplate instance. For function-based templates,
+        # the original function is lost, which is expected for remote templates.
+        return cls(
+            uri_template=mcp_template.uriTemplate,
+            name=mcp_template.name,
+            description=mcp_template.description,
+            mime_type=mcp_template.mimeType or "text/plain",
+            parameters={},  # Remote templates don't have local parameters
+        )
+
+    @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.uri_template
+
 
 class FunctionResourceTemplate(ResourceTemplate):
     """A template for dynamically creating resources."""
@@ -214,7 +256,7 @@ class FunctionResourceTemplate(ResourceTemplate):
                     f"URI parameters {uri_params} must be a subset of the function arguments: {func_params}"
                 )
 
-        description = description or fn.__doc__
+        description = description or 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):

fastmcp/server/auth/providers/bearer.py

@@ -17,13 +17,14 @@ from mcp.shared.auth import (
     OAuthClientInformationFull,
     OAuthToken,
 )
-from pydantic import SecretStr
+from pydantic import AnyHttpUrl, SecretStr, ValidationError
 
 from fastmcp.server.auth.auth import (
     ClientRegistrationOptions,
     OAuthProvider,
     RevocationOptions,
 )
+from fastmcp.utilities.logging import get_logger
 
 
 class JWKData(TypedDict, total=False):
@@ -89,7 +90,7 @@ class RSAKeyPair:
         self,
         subject: str = "fastmcp-user",
         issuer: str = "https://fastmcp.example.com",
-        audience: str | None = None,
+        audience: str | list[str] | None = None,
         scopes: list[str] | None = None,
         expires_in_seconds: int = 3600,
         additional_claims: dict[str, Any] | None = None,
@@ -102,7 +103,7 @@ class RSAKeyPair:
             private_key_pem: RSA private key in PEM format
             subject: Subject claim (usually user ID)
             issuer: Issuer claim
-            audience: Audience claim (optional)
+            audience: Audience claim - can be a string or list of strings (optional)
             scopes: List of scopes to include
             expires_in_seconds: Token expiration time in seconds
             additional_claims: Any additional claims to include
@@ -161,7 +162,7 @@ class BearerAuthProvider(OAuthProvider):
         public_key: str | None = None,
         jwks_uri: str | None = None,
         issuer: str | None = None,
-        audience: str | None = None,
+        audience: str | list[str] | None = None,
         required_scopes: list[str] | None = None,
     ):
         """
@@ -171,7 +172,7 @@ class BearerAuthProvider(OAuthProvider):
             public_key: RSA public key in PEM format (for static key)
             jwks_uri: URI to fetch keys from (for key rotation)
             issuer: Expected issuer claim (optional)
-            audience: Expected audience claim (optional)
+            audience: Expected audience claim - can be a string or list of strings (optional)
             required_scopes: List of required scopes for access (optional)
         """
         if not (public_key or jwks_uri):
@@ -179,8 +180,16 @@ class BearerAuthProvider(OAuthProvider):
         if public_key and jwks_uri:
             raise ValueError("Provide either public_key or jwks_uri, not both")
 
+        # Only pass issuer to parent if it's a valid URL, otherwise use default
+        # This allows the issuer claim validation to work with string issuers per RFC 7519
+        try:
+            issuer_url = AnyHttpUrl(issuer) if issuer else "https://fastmcp.example.com"
+        except ValidationError:
+            # Issuer is not a valid URL, use default for parent class
+            issuer_url = "https://fastmcp.example.com"
+
         super().__init__(
-            issuer_url=issuer or "https://fastmcp.example.com",
+            issuer_url=issuer_url,
             client_registration_options=ClientRegistrationOptions(enabled=False),
             revocation_options=RevocationOptions(enabled=False),
             required_scopes=required_scopes,
@@ -191,6 +200,7 @@ class BearerAuthProvider(OAuthProvider):
         self.public_key = public_key
         self.jwks_uri = jwks_uri
         self.jwt = JsonWebToken(["RS256"])
+        self.logger = get_logger(__name__)
 
         # Simple JWKS cache
         self._jwks_cache: dict[str, str] = {}
@@ -257,6 +267,9 @@ class BearerAuthProvider(OAuthProvider):
             # Select the appropriate key
             if kid:
                 if kid not in self._jwks_cache:
+                    self.logger.debug(
+                        "JWKS key lookup failed: key ID '%s' not found", kid
+                    )
                     raise ValueError(f"Key ID '{kid}' not found in JWKS")
                 return self._jwks_cache[kid]
             else:
@@ -271,6 +284,7 @@ class BearerAuthProvider(OAuthProvider):
                     raise ValueError("No keys found in JWKS")
 
         except Exception as e:
+            self.logger.debug("JWKS fetch failed: %s", str(e))
             raise ValueError(f"Failed to fetch JWKS: {e}")
 
     async def load_access_token(self, token: str) -> AccessToken | None:
@@ -290,28 +304,61 @@ class BearerAuthProvider(OAuthProvider):
             # Decode and verify the JWT token
             claims = self.jwt.decode(token, verification_key)
 
+            # Extract client ID early for logging
+            client_id = claims.get("client_id") or claims.get("sub") or "unknown"
+
             # Validate expiration
             exp = claims.get("exp")
             if exp and exp < time.time():
+                self.logger.debug(
+                    "Token validation failed: expired token for client %s", client_id
+                )
+                self.logger.info("Bearer token rejected for client %s", client_id)
                 return None
 
             # Validate issuer - note we use issuer instead of issuer_url here because
             # issuer is optional, allowing users to make this check optional
             if self.issuer:
                 if claims.get("iss") != self.issuer:
+                    self.logger.debug(
+                        "Token validation failed: issuer mismatch for client %s",
+                        client_id,
+                    )
+                    self.logger.info("Bearer token rejected for client %s", client_id)
                     return None
 
             # Validate audience if configured
             if self.audience:
                 aud = claims.get("aud")
-                if isinstance(aud, list):
-                    if self.audience not in aud:
-                        return None
-                elif aud != self.audience:
+
+                # Handle different combinations of audience types
+                audience_valid = False
+                if isinstance(self.audience, list):
+                    # self.audience is a list - check if any expected audience is present
+                    if isinstance(aud, list):
+                        # Both are lists - check for intersection
+                        audience_valid = any(
+                            expected in aud for expected in self.audience
+                        )
+                    else:
+                        # aud is a string - check if it's in our expected list
+                        audience_valid = aud in self.audience
+                else:
+                    # self.audience is a string - use original logic
+                    if isinstance(aud, list):
+                        audience_valid = self.audience in aud
+                    else:
+                        audience_valid = aud == self.audience
+
+                if not audience_valid:
+                    self.logger.debug(
+                        "Token validation failed: audience mismatch for client %s",
+                        client_id,
+                    )
+                    self.logger.info("Bearer token rejected for client %s", client_id)
                     return None
 
-            # Extract claims - prefer client_id over sub for OAuth application identification
-            client_id = claims.get("client_id") or claims.get("sub") or "unknown"
+            # Extract scopes
             scopes = self._extract_scopes(claims)
 
             return AccessToken(
@@ -322,8 +369,10 @@ class BearerAuthProvider(OAuthProvider):
             )
 
         except JoseError:
+            self.logger.debug("Token validation failed: JWT signature/format invalid")
             return None
-        except Exception:
+        except Exception as e:
+            self.logger.debug("Token validation failed: %s", str(e))
             return None
 
     def _extract_scopes(self, claims: dict[str, Any]) -> list[str]: