fastmcp 2.12.5__py3-none-any.whl → 2.13.0__py3-none-any.whl

fastmcp/resources/resource_manager.py

@@ -5,7 +5,7 @@ from __future__ import annotations
 import inspect
 import warnings
 from collections.abc import Callable
-from typing import TYPE_CHECKING, Any
+from typing import Any
 
 from pydantic import AnyUrl
 
@@ -19,9 +19,6 @@ 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__)
 
 
@@ -43,7 +40,6 @@ 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
@@ -57,137 +53,13 @@ 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)
+        return dict(self._resources)
 
     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 and name
-                        prefixed_resource = resource.model_copy(
-                            update={"name": f"{mounted.prefix}_{resource.name}"},
-                            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 server: {mounted.server.name!r}, mounted at: {mounted.prefix!r}: {e}"
-                )
-                if settings.mounted_components_raise_on_load_error:
-                    raise
-                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 and name
-                        prefixed_template = template.model_copy(
-                            update={"name": f"{mounted.prefix}_{template.name}"},
-                            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 server: {mounted.server.name!r}, mounted at: {mounted.prefix!r}: {e}"
-                )
-                if settings.mounted_components_raise_on_load_error:
-                    raise
-                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())
+        return dict(self._templates)
 
     def add_resource_or_template_from_fn(
         self,
@@ -381,12 +253,12 @@ class ResourceManager:
         uri_str = str(uri)
         logger.debug("Getting resource", extra={"uri": uri_str})
 
-        # First check concrete resources (local and mounted)
+        # First check concrete resources
         resources = await self.get_resources()
         if resource := resources.get(uri_str):
             return resource
 
-        # Then check templates (local and mounted) - use the utility function to match against storage keys
+        # Then check templates
         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)
@@ -424,9 +296,6 @@ class ResourceManager:
         # 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()
 
@@ -471,32 +340,4 @@ class ResourceManager:
                             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

@@ -6,9 +6,9 @@ import inspect
 import re
 from collections.abc import Callable
 from typing import Any
-from urllib.parse import unquote
+from urllib.parse import parse_qs, unquote
 
-from mcp.types import Annotations
+from mcp.types import Annotations, Icon
 from mcp.types import ResourceTemplate as MCPResourceTemplate
 from pydantic import (
     Field,
@@ -26,8 +26,26 @@ from fastmcp.utilities.types import (
 )
 
 
+def extract_query_params(uri_template: str) -> set[str]:
+    """Extract query parameter names from RFC 6570 `{?param1,param2}` syntax."""
+    match = re.search(r"\{\?([^}]+)\}", uri_template)
+    if match:
+        return {p.strip() for p in match.group(1).split(",")}
+    return set()
+
+
 def build_regex(template: str) -> re.Pattern:
-    parts = re.split(r"(\{[^}]+\})", template)
+    """Build regex pattern for URI template, handling RFC 6570 syntax.
+
+    Supports:
+    - `{var}` - simple path parameter
+    - `{var*}` - wildcard path parameter (captures multiple segments)
+    - `{?var1,var2}` - query parameters (ignored in path matching)
+    """
+    # Remove query parameter syntax for path matching
+    template_without_query = re.sub(r"\{\?[^}]+\}", "", template)
+
+    parts = re.split(r"(\{[^}]+\})", template_without_query)
     pattern = ""
     for part in parts:
         if part.startswith("{") and part.endswith("}"):
@@ -43,11 +61,34 @@ def build_regex(template: str) -> re.Pattern:
 
 
 def match_uri_template(uri: str, uri_template: str) -> dict[str, str] | None:
+    """Match URI against template and extract both path and query parameters.
+
+    Supports RFC 6570 URI templates:
+    - Path params: `{var}`, `{var*}`
+    - Query params: `{?var1,var2}`
+    """
+    # Split URI into path and query parts
+    uri_path, _, query_string = uri.partition("?")
+
+    # Match path parameters
     regex = build_regex(uri_template)
-    match = regex.match(uri)
-    if match:
-        return {k: unquote(v) for k, v in match.groupdict().items()}
-    return None
+    match = regex.match(uri_path)
+    if not match:
+        return None
+
+    params = {k: unquote(v) for k, v in match.groupdict().items()}
+
+    # Extract query parameters if present in URI and template
+    if query_string:
+        query_param_names = extract_query_params(uri_template)
+        parsed_query = parse_qs(query_string)
+
+        for name in query_param_names:
+            if name in parsed_query:
+                # Take first value if multiple provided
+                params[name] = parsed_query[name][0]  # type: ignore[index]
+
+    return params
 
 
 class ResourceTemplate(FastMCPComponent):
@@ -92,6 +133,7 @@ class ResourceTemplate(FastMCPComponent):
         name: str | None = None,
         title: str | None = None,
         description: str | None = None,
+        icons: list[Icon] | None = None,
         mime_type: str | None = None,
         tags: set[str] | None = None,
         enabled: bool | None = None,
@@ -104,6 +146,7 @@ class ResourceTemplate(FastMCPComponent):
             name=name,
             title=title,
             description=description,
+            icons=icons,
             mime_type=mime_type,
             tags=tags,
             enabled=enabled,
@@ -161,6 +204,7 @@ class ResourceTemplate(FastMCPComponent):
             description=overrides.get("description", self.description),
             mimeType=overrides.get("mimeType", self.mime_type),
             title=overrides.get("title", self.title),
+            icons=overrides.get("icons", self.icons),
             annotations=overrides.get("annotations", self.annotations),
             _meta=overrides.get(
                 "_meta", self.get_meta(include_fastmcp_meta=include_fastmcp_meta)
@@ -206,6 +250,31 @@ class FunctionResourceTemplate(ResourceTemplate):
         if context_kwarg and context_kwarg not in kwargs:
             kwargs[context_kwarg] = get_context()
 
+        # Type coercion for query parameters (which arrive as strings)
+        # Get function signature for type hints
+        sig = inspect.signature(self.fn)
+        for param_name, param_value in list(kwargs.items()):
+            if param_name in sig.parameters and isinstance(param_value, str):
+                param = sig.parameters[param_name]
+                annotation = param.annotation
+
+                # Skip if no annotation or annotation is str
+                if annotation is inspect.Parameter.empty or annotation is str:
+                    continue
+
+                # Handle common type coercions
+                try:
+                    if annotation is int:
+                        kwargs[param_name] = int(param_value)
+                    elif annotation is float:
+                        kwargs[param_name] = float(param_value)
+                    elif annotation is bool:
+                        # Handle boolean strings
+                        kwargs[param_name] = param_value.lower() in ("true", "1", "yes")
+                except (ValueError, AttributeError):
+                    # Let validate_call handle the error
+                    pass
+
         result = self.fn(**kwargs)
         if inspect.isawaitable(result):
             result = await result
@@ -219,6 +288,7 @@ class FunctionResourceTemplate(ResourceTemplate):
         name: str | None = None,
         title: str | None = None,
         description: str | None = None,
+        icons: list[Icon] | None = None,
         mime_type: str | None = None,
         tags: set[str] | None = None,
         enabled: bool | None = None,
@@ -245,16 +315,19 @@ class FunctionResourceTemplate(ResourceTemplate):
 
         context_kwarg = find_kwarg_by_type(fn, kwarg_type=Context)
 
-        # Validate that URI params match function params
-        uri_params = set(re.findall(r"{(\w+)(?:\*)?}", uri_template))
-        if not uri_params:
+        # Extract path and query parameters from URI template
+        path_params = set(re.findall(r"{(\w+)(?:\*)?}", uri_template))
+        query_params = extract_query_params(uri_template)
+        all_uri_params = path_params | query_params
+
+        if not all_uri_params:
             raise ValueError("URI template must contain at least one parameter")
 
         func_params = set(sig.parameters.keys())
         if context_kwarg:
             func_params.discard(context_kwarg)
 
-        # get the parameters that are required
+        # Get required and optional function parameters
         required_params = {
             p
             for p in func_params
@@ -262,21 +335,37 @@ class FunctionResourceTemplate(ResourceTemplate):
             and sig.parameters[p].kind != inspect.Parameter.VAR_KEYWORD
             and p != context_kwarg
         }
+        optional_params = {
+            p
+            for p in func_params
+            if sig.parameters[p].default is not inspect.Parameter.empty
+            and sig.parameters[p].kind != inspect.Parameter.VAR_KEYWORD
+            and p != context_kwarg
+        }
+
+        # Validate RFC 6570 query parameters
+        # Query params must be optional (have defaults)
+        if query_params:
+            invalid_query_params = query_params - optional_params
+            if invalid_query_params:
+                raise ValueError(
+                    f"Query parameters {invalid_query_params} must be optional function parameters with default values"
+                )
 
-        # Check if required parameters are a subset of the URI parameters
-        if not required_params.issubset(uri_params):
+        # Check if required parameters are a subset of the path parameters
+        if not required_params.issubset(path_params):
             raise ValueError(
-                f"Required function arguments {required_params} must be a subset of the URI parameters {uri_params}"
+                f"Required function arguments {required_params} must be a subset of the URI path parameters {path_params}"
             )
 
-        # Check if the URI parameters are a subset of the function parameters (skip if **kwargs present)
+        # Check if all URI parameters are valid function parameters (skip if **kwargs present)
         if not any(
             param.kind == inspect.Parameter.VAR_KEYWORD
             for param in sig.parameters.values()
         ):
-            if not uri_params.issubset(func_params):
+            if not all_uri_params.issubset(func_params):
                 raise ValueError(
-                    f"URI parameters {uri_params} must be a subset of the function arguments: {func_params}"
+                    f"URI parameters {all_uri_params} must be a subset of the function arguments: {func_params}"
                 )
 
         description = description or inspect.getdoc(fn)
@@ -303,6 +392,7 @@ class FunctionResourceTemplate(ResourceTemplate):
             name=func_name,
             title=title,
             description=description,
+            icons=icons,
             mime_type=mime_type or "text/plain",
             fn=fn,
             parameters=parameters,

fastmcp/resources/types.py

@@ -5,11 +5,11 @@ from __future__ import annotations
 import json
 from pathlib import Path
 
-import anyio
-import anyio.to_thread
 import httpx
 import pydantic.json
+from anyio import Path as AsyncPath
 from pydantic import Field, ValidationInfo
+from typing_extensions import override
 
 from fastmcp.exceptions import ResourceError
 from fastmcp.resources.resource import Resource
@@ -54,6 +54,10 @@ class FileResource(Resource):
         description="MIME type of the resource content",
     )
 
+    @property
+    def _async_path(self) -> AsyncPath:
+        return AsyncPath(self.path)
+
     @pydantic.field_validator("path")
     @classmethod
     def validate_absolute_path(cls, path: Path) -> Path:
@@ -71,12 +75,13 @@ class FileResource(Resource):
         mime_type = info.data.get("mime_type", "text/plain")
         return not mime_type.startswith("text/")
 
+    @override
     async def read(self) -> str | bytes:
         """Read the file content."""
         try:
             if self.is_binary:
-                return await anyio.to_thread.run_sync(self.path.read_bytes)
-            return await anyio.to_thread.run_sync(self.path.read_text)
+                return await self._async_path.read_bytes()
+            return await self._async_path.read_text()
         except Exception as e:
             raise ResourceError(f"Error reading file {self.path}") from e
 
@@ -89,11 +94,12 @@ class HttpResource(Resource):
         default="application/json", description="MIME type of the resource content"
     )
 
+    @override
     async def read(self) -> str | bytes:
         """Read the HTTP content."""
         async with httpx.AsyncClient() as client:
             response = await client.get(self.url)
-            response.raise_for_status()
+            _ = response.raise_for_status()
             return response.text
 
 
@@ -111,6 +117,10 @@ class DirectoryResource(Resource):
         default="application/json", description="MIME type of the resource content"
     )
 
+    @property
+    def _async_path(self) -> AsyncPath:
+        return AsyncPath(self.path)
+
     @pydantic.field_validator("path")
     @classmethod
     def validate_absolute_path(cls, path: Path) -> Path:
@@ -119,33 +129,29 @@ class DirectoryResource(Resource):
             raise ValueError("Path must be absolute")
         return path
 
-    def list_files(self) -> list[Path]:
+    async def list_files(self) -> list[Path]:
         """List files in the directory."""
-        if not self.path.exists():
+        if not await self._async_path.exists():
             raise FileNotFoundError(f"Directory not found: {self.path}")
-        if not self.path.is_dir():
+        if not await self._async_path.is_dir():
             raise NotADirectoryError(f"Not a directory: {self.path}")
 
+        pattern = self.pattern or "*"
+
+        glob_fn = self._async_path.rglob if self.recursive else self._async_path.glob
         try:
-            if self.pattern:
-                return (
-                    list(self.path.glob(self.pattern))
-                    if not self.recursive
-                    else list(self.path.rglob(self.pattern))
-                )
-            return (
-                list(self.path.glob("*"))
-                if not self.recursive
-                else list(self.path.rglob("*"))
-            )
+            return [Path(p) async for p in glob_fn(pattern) if await p.is_file()]
         except Exception as e:
-            raise ResourceError(f"Error listing directory {self.path}: {e}")
+            raise ResourceError(f"Error listing directory {self.path}") from e
 
+    @override
     async def read(self) -> str:  # Always returns JSON string
         """Read the directory listing."""
         try:
-            files = await anyio.to_thread.run_sync(self.list_files)
-            file_list = [str(f.relative_to(self.path)) for f in files if f.is_file()]
+            files: list[Path] = await self.list_files()
+
+            file_list = [str(f.relative_to(self.path)) for f in files]
+
             return json.dumps({"files": file_list}, indent=2)
-        except Exception:
-            raise ResourceError(f"Error reading directory {self.path}")
+        except Exception as e:
+            raise ResourceError(f"Error reading directory {self.path}") from e

fastmcp/server/auth/auth.py

@@ -3,10 +3,7 @@ from __future__ import annotations
 from typing import Any
 
 from mcp.server.auth.middleware.auth_context import AuthContextMiddleware
-from mcp.server.auth.middleware.bearer_auth import (
-    BearerAuthBackend,
-    RequireAuthMiddleware,
-)
+from mcp.server.auth.middleware.bearer_auth import BearerAuthBackend
 from mcp.server.auth.provider import (
     AccessToken as _SDKAccessToken,
 )
@@ -81,10 +78,10 @@ class AuthProvider(TokenVerifierProtocol):
     def get_routes(
         self,
         mcp_path: str | None = None,
-        mcp_endpoint: Any | None = None,
     ) -> list[Route]:
-        """Get the routes for this authentication provider.
+        """Get all routes for this authentication provider.
 
+        This includes both well-known discovery routes and operational routes.
         Each provider is responsible for creating whatever routes it needs:
         - TokenVerifier: typically no routes (default implementation)
         - RemoteAuthProvider: protected resource metadata routes
@@ -93,30 +90,45 @@ class AuthProvider(TokenVerifierProtocol):
 
         Args:
             mcp_path: The path where the MCP endpoint is mounted (e.g., "/mcp")
-            mcp_endpoint: The MCP endpoint handler to protect with auth
+                This is used to advertise the resource URL in metadata, but the
+                provider does not create the actual MCP endpoint route.
 
         Returns:
-            List of routes for this provider, including protected MCP endpoints if provided
+            List of all routes for this provider (excluding the MCP endpoint itself)
         """
+        return []
 
-        routes = []
+    def get_well_known_routes(
+        self,
+        mcp_path: str | None = None,
+    ) -> list[Route]:
+        """Get well-known discovery routes for this authentication provider.
 
-        # Add protected MCP endpoint if provided
-        if mcp_path and mcp_endpoint:
-            resource_metadata_url = self._get_resource_url(
-                "/.well-known/oauth-protected-resource"
-            )
+        This is a utility method that filters get_routes() to return only
+        well-known discovery routes (those starting with /.well-known/).
 
-            routes.append(
-                Route(
-                    mcp_path,
-                    endpoint=RequireAuthMiddleware(
-                        mcp_endpoint, self.required_scopes, resource_metadata_url
-                    ),
-                )
-            )
+        Well-known routes provide OAuth metadata and discovery endpoints that
+        clients use to discover authentication capabilities. These routes should
+        be mounted at the root level of the application to comply with RFC 8414
+        and RFC 9728.
 
-        return routes
+        Common well-known routes:
+        - /.well-known/oauth-authorization-server (authorization server metadata)
+        - /.well-known/oauth-protected-resource/* (protected resource metadata)
+
+        Args:
+            mcp_path: The path where the MCP endpoint is mounted (e.g., "/mcp")
+                This is used to construct path-scoped well-known URLs.
+
+        Returns:
+            List of well-known discovery routes (typically mounted at root level)
+        """
+        all_routes = self.get_routes(mcp_path)
+        return [
+            route
+            for route in all_routes
+            if isinstance(route, Route) and route.path.startswith("/.well-known/")
+        ]
 
     def get_middleware(self) -> list:
         """Get HTTP application-level middleware for this auth provider.
@@ -225,14 +237,12 @@ class RemoteAuthProvider(AuthProvider):
     def get_routes(
         self,
         mcp_path: str | None = None,
-        mcp_endpoint: Any | None = None,
     ) -> list[Route]:
-        """Get OAuth routes for this provider.
+        """Get routes for this provider.
 
-        Creates protected resource metadata routes and optionally wraps MCP endpoints with auth.
+        Creates protected resource metadata routes (RFC 9728).
         """
-        # Start with base routes (protected MCP endpoint)
-        routes = super().get_routes(mcp_path, mcp_endpoint)
+        routes = []
 
         # Get the resource URL based on the MCP path
         resource_url = self._get_resource_url(mcp_path)
@@ -326,14 +336,12 @@ class OAuthProvider(
     def get_routes(
         self,
         mcp_path: str | None = None,
-        mcp_endpoint: Any | None = None,
     ) -> list[Route]:
         """Get OAuth authorization server routes and optional protected resource routes.
 
         This method creates the full set of OAuth routes including:
         - Standard OAuth authorization server routes (/.well-known/oauth-authorization-server, /authorize, /token, etc.)
         - Optional protected resource routes
-        - Protected MCP endpoints if provided
 
         Returns:
             List of OAuth routes
@@ -366,7 +374,7 @@ class OAuthProvider(
             )
             oauth_routes.extend(protected_routes)
 
-        # Add protected MCP endpoint from base class
-        oauth_routes.extend(super().get_routes(mcp_path, mcp_endpoint))
+        # Add base routes
+        oauth_routes.extend(super().get_routes(mcp_path))
 
         return oauth_routes