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

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/__init__.py

@@ -3,4 +3,4 @@ from .context import Context
 from . import dependencies
 
 
-__all__ = ["FastMCP", "Context"]
+__all__ = ["Context", "FastMCP"]

fastmcp/server/auth/__init__.py

@@ -5,19 +5,23 @@ from .auth import (
     AccessToken,
     AuthProvider,
 )
+from .providers.debug import DebugTokenVerifier
 from .providers.jwt import JWTVerifier, StaticTokenVerifier
 from .oauth_proxy import OAuthProxy
+from .oidc_proxy import OIDCProxy
 
 
 __all__ = [
+    "AccessToken",
     "AuthProvider",
-    "OAuthProvider",
-    "TokenVerifier",
+    "DebugTokenVerifier",
     "JWTVerifier",
-    "StaticTokenVerifier",
-    "RemoteAuthProvider",
-    "AccessToken",
+    "OAuthProvider",
     "OAuthProxy",
+    "OIDCProxy",
+    "RemoteAuthProvider",
+    "StaticTokenVerifier",
+    "TokenVerifier",
 ]
 
 

fastmcp/server/auth/auth.py

@@ -1,12 +1,9 @@
 from __future__ import annotations
 
-from typing import Any
+from typing import Any, cast
 
 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,
 )
@@ -26,16 +23,20 @@ from mcp.server.auth.settings import (
     ClientRegistrationOptions,
     RevocationOptions,
 )
-from pydantic import AnyHttpUrl
+from pydantic import AnyHttpUrl, Field
 from starlette.middleware import Middleware
 from starlette.middleware.authentication import AuthenticationMiddleware
 from starlette.routing import Route
 
+from fastmcp.utilities.logging import get_logger
+
+logger = get_logger(__name__)
+
 
 class AccessToken(_SDKAccessToken):
     """AccessToken that includes all JWT claims."""
 
-    claims: dict[str, Any] = {}
+    claims: dict[str, Any] = Field(default_factory=dict)
 
 
 class AuthProvider(TokenVerifierProtocol):
@@ -81,10 +82,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 +94,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 +241,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)
@@ -284,20 +298,27 @@ class OAuthProvider(
             required_scopes: Scopes that are required for all requests.
         """
 
-        # Convert URLs to proper types
-        if isinstance(base_url, str):
-            base_url = AnyHttpUrl(base_url)
-
         super().__init__(base_url=base_url, required_scopes=required_scopes)
-        self.base_url = base_url
 
         if issuer_url is None:
-            self.issuer_url = base_url
+            self.issuer_url = self.base_url
         elif isinstance(issuer_url, str):
             self.issuer_url = AnyHttpUrl(issuer_url)
         else:
             self.issuer_url = issuer_url
 
+        # Log if issuer_url and base_url differ (requires additional setup)
+        if (
+            self.base_url is not None
+            and self.issuer_url is not None
+            and str(self.base_url) != str(self.issuer_url)
+        ):
+            logger.info(
+                f"OAuth endpoints at {self.base_url}, issuer at {self.issuer_url}. "
+                f"Ensure well-known routes are accessible at root ({self.issuer_url}/.well-known/). "
+                f"See: https://gofastmcp.com/deployment/http#mounting-authenticated-servers"
+            )
+
         # Initialize OAuth Authorization Server Provider
         OAuthAuthorizationServerProvider.__init__(self)
 
@@ -326,23 +347,29 @@ 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
         """
 
         # Create standard OAuth authorization server routes
+        # Pass base_url as issuer_url to ensure metadata declares endpoints where
+        # they're actually accessible (operational routes are mounted at
+        # base_url)
+        assert self.base_url is not None  # typing check
+        assert (
+            self.issuer_url is not None
+        )  # typing check (issuer_url defaults to base_url)
+
         oauth_routes = create_auth_routes(
             provider=self,
-            issuer_url=self.issuer_url,
+            issuer_url=self.base_url,
             service_documentation_url=self.service_documentation_url,
             client_registration_options=self.client_registration_options,
             revocation_options=self.revocation_options,
@@ -361,12 +388,12 @@ class OAuthProvider(
             )
             protected_routes = create_protected_resource_routes(
                 resource_url=resource_url,
-                authorization_servers=[self.issuer_url],
+                authorization_servers=[cast(AnyHttpUrl, self.issuer_url)],
                 scopes_supported=supported_scopes,
             )
             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