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

fastmcp/resources/template.py

@@ -62,6 +62,9 @@ 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})"
+
     @staticmethod
     def from_function(
         fn: Callable[..., Any],
@@ -128,6 +131,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 +240,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,7 +17,7 @@ from mcp.shared.auth import (
     OAuthClientInformationFull,
     OAuthToken,
 )
-from pydantic import SecretStr
+from pydantic import AnyHttpUrl, SecretStr, ValidationError
 
 from fastmcp.server.auth.auth import (
     ClientRegistrationOptions,
@@ -89,7 +89,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 +102,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 +161,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 +171,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 +179,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,
@@ -304,11 +312,25 @@ class BearerAuthProvider(OAuthProvider):
             # Validate audience if configured
             if self.audience:
                 aud = claims.get("aud")
-                if isinstance(aud, list):
-                    if self.audience not in aud:
+
+                # Handle different combinations of audience types
+                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
+                        if not any(expected in aud for expected in self.audience):
+                            return None
+                    else:
+                        # aud is a string - check if it's in our expected list
+                        if aud not in self.audience:
+                            return None
+                else:
+                    # self.audience is a string - use original logic
+                    if isinstance(aud, list):
+                        if self.audience not in aud:
+                            return None
+                    elif aud != self.audience:
                         return None
-                elif aud != self.audience:
-                    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"

fastmcp/server/context.py

@@ -8,6 +8,7 @@ from dataclasses import dataclass
 
 from mcp import LoggingLevel
 from mcp.server.lowlevel.helper_types import ReadResourceContents
+from mcp.server.lowlevel.server import request_ctx
 from mcp.shared.context import RequestContext
 from mcp.types import (
     CreateMessageResult,
@@ -95,8 +96,14 @@ class Context:
 
     @property
     def request_context(self) -> RequestContext:
-        """Access to the underlying request context."""
-        return self.fastmcp._mcp_server.request_context
+        """Access to the underlying request context.
+
+        If called outside of a request context, this will raise a ValueError.
+        """
+        try:
+            return request_ctx.get()
+        except LookupError:
+            raise ValueError("Context is not available outside of a request")
 
     async def report_progress(
         self, progress: float, total: float | None = None, message: str | None = None
@@ -122,6 +129,7 @@ class Context:
             progress=progress,
             total=total,
             message=message,
+            related_request_id=self.request_id,
         )
 
     async def read_resource(self, uri: str | AnyUrl) -> list[ReadResourceContents]:
@@ -170,6 +178,37 @@ class Context:
         """Get the unique ID for this request."""
         return str(self.request_context.request_id)
 
+    @property
+    def session_id(self) -> str | None:
+        """Get the MCP session ID for HTTP transports.
+
+        Returns the session ID that can be used as a key for session-based
+        data storage (e.g., Redis) to share data between tool calls within
+        the same client session.
+
+        Returns:
+            The session ID for HTTP transports (SSE, StreamableHTTP), or None
+            for stdio and in-memory transports which don't use session IDs.
+
+        Example:
+            ```python
+            @server.tool
+            def store_data(data: dict, ctx: Context) -> str:
+                if session_id := ctx.session_id:
+                    redis_client.set(f"session:{session_id}:data", json.dumps(data))
+                    return f"Data stored for session {session_id}"
+                return "No session ID available (stdio/memory transport)"
+            ```
+        """
+        try:
+            from fastmcp.server.dependencies import get_http_headers
+
+            headers = get_http_headers(include_all=True)
+            return headers.get("mcp-session-id")
+        except RuntimeError:
+            # No HTTP context available (stdio/in-memory transport)
+            return None
+
     @property
     def session(self):
         """Access to the underlying session for advanced usage."""

fastmcp/server/http.py

@@ -158,6 +158,10 @@ def create_sse_app(
         A Starlette application with RequestContextMiddleware
     """
 
+    # Ensure the message_path ends with a trailing slash to avoid automatic redirects
+    if not message_path.endswith("/"):
+        message_path = message_path + "/"
+
     server_routes: list[BaseRoute] = []
     server_middleware: list[Middleware] = []
 
@@ -305,6 +309,10 @@ def create_streamable_http_app(
                 # Re-raise other RuntimeErrors if they don't match the specific message
                 raise
 
+    # Ensure the streamable_http_path ends with a trailing slash to avoid automatic redirects
+    if not streamable_http_path.endswith("/"):
+        streamable_http_path = streamable_http_path + "/"
+
     # Add StreamableHTTP routes with or without auth
     if auth:
         auth_middleware, auth_routes, required_scopes = (

fastmcp/server/middleware/__init__.py

@@ -0,0 +1,6 @@
+from .middleware import Middleware, MiddlewareContext
+
+__all__ = [
+    "Middleware",
+    "MiddlewareContext",
+]

fastmcp/server/middleware/error_handling.py

@@ -0,0 +1,206 @@
+"""Error handling middleware for consistent error responses and tracking."""
+
+import asyncio
+import logging
+import traceback
+from collections.abc import Callable
+from typing import Any
+
+from mcp import McpError
+from mcp.types import ErrorData
+
+from .middleware import CallNext, Middleware, MiddlewareContext
+
+
+class ErrorHandlingMiddleware(Middleware):
+    """Middleware that provides consistent error handling and logging.
+
+    Catches exceptions, logs them appropriately, and converts them to
+    proper MCP error responses. Also tracks error patterns for monitoring.
+
+    Example:
+        ```python
+        from fastmcp.server.middleware.error_handling import ErrorHandlingMiddleware
+        import logging
+
+        # Configure logging to see error details
+        logging.basicConfig(level=logging.ERROR)
+
+        mcp = FastMCP("MyServer")
+        mcp.add_middleware(ErrorHandlingMiddleware())
+        ```
+    """
+
+    def __init__(
+        self,
+        logger: logging.Logger | None = None,
+        include_traceback: bool = False,
+        error_callback: Callable[[Exception, MiddlewareContext], None] | None = None,
+        transform_errors: bool = True,
+    ):
+        """Initialize error handling middleware.
+
+        Args:
+            logger: Logger instance for error logging. If None, uses 'fastmcp.errors'
+            include_traceback: Whether to include full traceback in error logs
+            error_callback: Optional callback function called for each error
+            transform_errors: Whether to transform non-MCP errors to McpError
+        """
+        self.logger = logger or logging.getLogger("fastmcp.errors")
+        self.include_traceback = include_traceback
+        self.error_callback = error_callback
+        self.transform_errors = transform_errors
+        self.error_counts = {}
+
+    def _log_error(self, error: Exception, context: MiddlewareContext) -> None:
+        """Log error with appropriate detail level."""
+        error_type = type(error).__name__
+        method = context.method or "unknown"
+
+        # Track error counts
+        error_key = f"{error_type}:{method}"
+        self.error_counts[error_key] = self.error_counts.get(error_key, 0) + 1
+
+        base_message = f"Error in {method}: {error_type}: {str(error)}"
+
+        if self.include_traceback:
+            self.logger.error(f"{base_message}\n{traceback.format_exc()}")
+        else:
+            self.logger.error(base_message)
+
+        # Call custom error callback if provided
+        if self.error_callback:
+            try:
+                self.error_callback(error, context)
+            except Exception as callback_error:
+                self.logger.error(f"Error in error callback: {callback_error}")
+
+    def _transform_error(self, error: Exception) -> Exception:
+        """Transform non-MCP errors to proper MCP errors."""
+        if isinstance(error, McpError):
+            return error
+
+        if not self.transform_errors:
+            return error
+
+        # Map common exceptions to appropriate MCP error codes
+        error_type = type(error)
+
+        if error_type in (ValueError, TypeError):
+            return McpError(
+                ErrorData(code=-32602, message=f"Invalid params: {str(error)}")
+            )
+        elif error_type in (FileNotFoundError, KeyError):
+            return McpError(
+                ErrorData(code=-32001, message=f"Resource not found: {str(error)}")
+            )
+        elif error_type is PermissionError:
+            return McpError(
+                ErrorData(code=-32000, message=f"Permission denied: {str(error)}")
+            )
+        elif error_type in (TimeoutError, asyncio.TimeoutError):
+            return McpError(
+                ErrorData(code=-32000, message=f"Request timeout: {str(error)}")
+            )
+        else:
+            return McpError(
+                ErrorData(code=-32603, message=f"Internal error: {str(error)}")
+            )
+
+    async def on_message(self, context: MiddlewareContext, call_next: CallNext) -> Any:
+        """Handle errors for all messages."""
+        try:
+            return await call_next(context)
+        except Exception as error:
+            self._log_error(error, context)
+
+            # Transform and re-raise
+            transformed_error = self._transform_error(error)
+            raise transformed_error
+
+    def get_error_stats(self) -> dict[str, int]:
+        """Get error statistics for monitoring."""
+        return self.error_counts.copy()
+
+
+class RetryMiddleware(Middleware):
+    """Middleware that implements automatic retry logic for failed requests.
+
+    Retries requests that fail with transient errors, using exponential
+    backoff to avoid overwhelming the server or external dependencies.
+
+    Example:
+        ```python
+        from fastmcp.server.middleware.error_handling import RetryMiddleware
+
+        # Retry up to 3 times with exponential backoff
+        retry_middleware = RetryMiddleware(
+            max_retries=3,
+            retry_exceptions=(ConnectionError, TimeoutError)
+        )
+
+        mcp = FastMCP("MyServer")
+        mcp.add_middleware(retry_middleware)
+        ```
+    """
+
+    def __init__(
+        self,
+        max_retries: int = 3,
+        base_delay: float = 1.0,
+        max_delay: float = 60.0,
+        backoff_multiplier: float = 2.0,
+        retry_exceptions: tuple[type[Exception], ...] = (ConnectionError, TimeoutError),
+        logger: logging.Logger | None = None,
+    ):
+        """Initialize retry middleware.
+
+        Args:
+            max_retries: Maximum number of retry attempts
+            base_delay: Initial delay between retries in seconds
+            max_delay: Maximum delay between retries in seconds
+            backoff_multiplier: Multiplier for exponential backoff
+            retry_exceptions: Tuple of exception types that should trigger retries
+            logger: Logger for retry attempts
+        """
+        self.max_retries = max_retries
+        self.base_delay = base_delay
+        self.max_delay = max_delay
+        self.backoff_multiplier = backoff_multiplier
+        self.retry_exceptions = retry_exceptions
+        self.logger = logger or logging.getLogger("fastmcp.retry")
+
+    def _should_retry(self, error: Exception) -> bool:
+        """Determine if an error should trigger a retry."""
+        return isinstance(error, self.retry_exceptions)
+
+    def _calculate_delay(self, attempt: int) -> float:
+        """Calculate delay for the given attempt number."""
+        delay = self.base_delay * (self.backoff_multiplier**attempt)
+        return min(delay, self.max_delay)
+
+    async def on_request(self, context: MiddlewareContext, call_next: CallNext) -> Any:
+        """Implement retry logic for requests."""
+        last_error = None
+
+        for attempt in range(self.max_retries + 1):
+            try:
+                return await call_next(context)
+            except Exception as error:
+                last_error = error
+
+                # Don't retry on the last attempt or if it's not a retryable error
+                if attempt == self.max_retries or not self._should_retry(error):
+                    break
+
+                delay = self._calculate_delay(attempt)
+                self.logger.warning(
+                    f"Request {context.method} failed (attempt {attempt + 1}/{self.max_retries + 1}): "
+                    f"{type(error).__name__}: {str(error)}. Retrying in {delay:.1f}s..."
+                )
+
+                await asyncio.sleep(delay)
+
+        # Re-raise the last error if all retries failed
+        if last_error:
+            raise last_error

fastmcp/server/middleware/logging.py

@@ -0,0 +1,165 @@
+"""Comprehensive logging middleware for FastMCP servers."""
+
+import json
+import logging
+from typing import Any
+
+from .middleware import CallNext, Middleware, MiddlewareContext
+
+
+class LoggingMiddleware(Middleware):
+    """Middleware that provides comprehensive request and response logging.
+
+    Logs all MCP messages with configurable detail levels. Useful for debugging,
+    monitoring, and understanding server usage patterns.
+
+    Example:
+        ```python
+        from fastmcp.server.middleware.logging import LoggingMiddleware
+        import logging
+
+        # Configure logging
+        logging.basicConfig(level=logging.INFO)
+
+        mcp = FastMCP("MyServer")
+        mcp.add_middleware(LoggingMiddleware())
+        ```
+    """
+
+    def __init__(
+        self,
+        logger: logging.Logger | None = None,
+        log_level: int = logging.INFO,
+        include_payloads: bool = False,
+        max_payload_length: int = 1000,
+    ):
+        """Initialize logging middleware.
+
+        Args:
+            logger: Logger instance to use. If None, creates a logger named 'fastmcp.requests'
+            log_level: Log level for messages (default: INFO)
+            include_payloads: Whether to include message payloads in logs
+            max_payload_length: Maximum length of payload to log (prevents huge logs)
+        """
+        self.logger = logger or logging.getLogger("fastmcp.requests")
+        self.log_level = log_level
+        self.include_payloads = include_payloads
+        self.max_payload_length = max_payload_length
+
+    def _format_message(self, context: MiddlewareContext) -> str:
+        """Format a message for logging."""
+        parts = [
+            f"source={context.source}",
+            f"type={context.type}",
+            f"method={context.method or 'unknown'}",
+        ]
+
+        if self.include_payloads and hasattr(context.message, "__dict__"):
+            try:
+                payload = json.dumps(context.message.__dict__, default=str)
+                if len(payload) > self.max_payload_length:
+                    payload = payload[: self.max_payload_length] + "..."
+                parts.append(f"payload={payload}")
+            except (TypeError, ValueError):
+                parts.append("payload=<non-serializable>")
+
+        return " ".join(parts)
+
+    async def on_message(self, context: MiddlewareContext, call_next: CallNext) -> Any:
+        """Log all messages."""
+        message_info = self._format_message(context)
+
+        self.logger.log(self.log_level, f"Processing message: {message_info}")
+
+        try:
+            result = await call_next(context)
+            self.logger.log(
+                self.log_level, f"Completed message: {context.method or 'unknown'}"
+            )
+            return result
+        except Exception as e:
+            self.logger.log(
+                logging.ERROR, f"Failed message: {context.method or 'unknown'} - {e}"
+            )
+            raise
+
+
+class StructuredLoggingMiddleware(Middleware):
+    """Middleware that provides structured JSON logging for better log analysis.
+
+    Outputs structured logs that are easier to parse and analyze with log
+    aggregation tools like ELK stack, Splunk, or cloud logging services.
+
+    Example:
+        ```python
+        from fastmcp.server.middleware.logging import StructuredLoggingMiddleware
+        import logging
+
+        mcp = FastMCP("MyServer")
+        mcp.add_middleware(StructuredLoggingMiddleware())
+        ```
+    """
+
+    def __init__(
+        self,
+        logger: logging.Logger | None = None,
+        log_level: int = logging.INFO,
+        include_payloads: bool = False,
+    ):
+        """Initialize structured logging middleware.
+
+        Args:
+            logger: Logger instance to use. If None, creates a logger named 'fastmcp.structured'
+            log_level: Log level for messages (default: INFO)
+            include_payloads: Whether to include message payloads in logs
+        """
+        self.logger = logger or logging.getLogger("fastmcp.structured")
+        self.log_level = log_level
+        self.include_payloads = include_payloads
+
+    def _create_log_entry(
+        self, context: MiddlewareContext, event: str, **extra_fields
+    ) -> dict:
+        """Create a structured log entry."""
+        entry = {
+            "event": event,
+            "timestamp": context.timestamp.isoformat(),
+            "source": context.source,
+            "type": context.type,
+            "method": context.method,
+            **extra_fields,
+        }
+
+        if self.include_payloads and hasattr(context.message, "__dict__"):
+            try:
+                entry["payload"] = context.message.__dict__
+            except (TypeError, ValueError):
+                entry["payload"] = "<non-serializable>"
+
+        return entry
+
+    async def on_message(self, context: MiddlewareContext, call_next: CallNext) -> Any:
+        """Log structured message information."""
+        start_entry = self._create_log_entry(context, "request_start")
+        self.logger.log(self.log_level, json.dumps(start_entry))
+
+        try:
+            result = await call_next(context)
+
+            success_entry = self._create_log_entry(
+                context,
+                "request_success",
+                result_type=type(result).__name__ if result else None,
+            )
+            self.logger.log(self.log_level, json.dumps(success_entry))
+
+            return result
+        except Exception as e:
+            error_entry = self._create_log_entry(
+                context,
+                "request_error",
+                error_type=type(e).__name__,
+                error_message=str(e),
+            )
+            self.logger.log(logging.ERROR, json.dumps(error_entry))
+            raise