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

fastmcp/server/context.py

@@ -1,13 +1,15 @@
 from __future__ import annotations as _annotations
 
+import asyncio
 import warnings
 from collections.abc import Generator
 from contextlib import contextmanager
 from contextvars import ContextVar, Token
 from dataclasses import dataclass
 
-from mcp import LoggingLevel
+from mcp import LoggingLevel, ServerSession
 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,
@@ -29,6 +31,7 @@ from fastmcp.utilities.types import MCPContent
 logger = get_logger(__name__)
 
 _current_context: ContextVar[Context | None] = ContextVar("context", default=None)
+_flush_lock = asyncio.Lock()
 
 
 @contextmanager
@@ -79,24 +82,34 @@ class Context:
     def __init__(self, fastmcp: FastMCP):
         self.fastmcp = fastmcp
         self._tokens: list[Token] = []
+        self._notification_queue: set[str] = set()  # Dedupe notifications
 
-    def __enter__(self) -> Context:
+    async def __aenter__(self) -> Context:
         """Enter the context manager and set this context as the current context."""
         # Always set this context and save the token
         token = _current_context.set(self)
         self._tokens.append(token)
         return self
 
-    def __exit__(self, exc_type, exc_val, exc_tb) -> None:
+    async def __aexit__(self, exc_type, exc_val, exc_tb) -> None:
         """Exit the context manager and reset the most recent token."""
+        # Flush any remaining notifications before exiting
+        await self._flush_notifications()
+
         if self._tokens:
             token = self._tokens.pop()
             _current_context.reset(token)
 
     @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
@@ -117,11 +130,12 @@ class Context:
         if progress_token is None:
             return
 
-        await self.request_context.session.send_progress_notification(
+        await self.session.send_progress_notification(
             progress_token=progress_token,
             progress=progress,
             total=total,
             message=message,
+            related_request_id=self.request_id,
         )
 
     async def read_resource(self, uri: str | AnyUrl) -> list[ReadResourceContents]:
@@ -152,7 +166,7 @@ class Context:
         """
         if level is None:
             level = "info"
-        await self.request_context.session.send_log_message(
+        await self.session.send_log_message(
             level=level, data=message, logger=logger_name
         )
 
@@ -171,7 +185,38 @@ class Context:
         return str(self.request_context.request_id)
 
     @property
-    def session(self):
+    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) -> ServerSession:
         """Access to the underlying session for advanced usage."""
         return self.request_context.session
 
@@ -194,9 +239,21 @@ class Context:
 
     async def list_roots(self) -> list[Root]:
         """List the roots available to the server, as indicated by the client."""
-        result = await self.request_context.session.list_roots()
+        result = await self.session.list_roots()
         return result.roots
 
+    async def send_tool_list_changed(self) -> None:
+        """Send a tool list changed notification to the client."""
+        await self.session.send_tool_list_changed()
+
+    async def send_resource_list_changed(self) -> None:
+        """Send a resource list changed notification to the client."""
+        await self.session.send_resource_list_changed()
+
+    async def send_prompt_list_changed(self) -> None:
+        """Send a prompt list changed notification to the client."""
+        await self.session.send_prompt_list_changed()
+
     async def sample(
         self,
         messages: str | list[str | SamplingMessage],
@@ -230,7 +287,7 @@ class Context:
                 for m in messages
             ]
 
-        result: CreateMessageResult = await self.request_context.session.create_message(
+        result: CreateMessageResult = await self.session.create_message(
             messages=sampling_messages,
             system_prompt=system_prompt,
             temperature=temperature,
@@ -255,6 +312,52 @@ class Context:
 
         return fastmcp.server.dependencies.get_http_request()
 
+    def _queue_tool_list_changed(self) -> None:
+        """Queue a tool list changed notification."""
+        self._notification_queue.add("notifications/tools/list_changed")
+        self._try_flush_notifications()
+
+    def _queue_resource_list_changed(self) -> None:
+        """Queue a resource list changed notification."""
+        self._notification_queue.add("notifications/resources/list_changed")
+        self._try_flush_notifications()
+
+    def _queue_prompt_list_changed(self) -> None:
+        """Queue a prompt list changed notification."""
+        self._notification_queue.add("notifications/prompts/list_changed")
+        self._try_flush_notifications()
+
+    def _try_flush_notifications(self) -> None:
+        """Synchronous method that attempts to flush notifications if we're in an async context."""
+        try:
+            # Check if we're in an async context
+            loop = asyncio.get_running_loop()
+            if loop and not loop.is_running():
+                return
+            # Schedule flush as a task (fire-and-forget)
+            asyncio.create_task(self._flush_notifications())
+        except RuntimeError:
+            # No event loop - will flush later
+            pass
+
+    async def _flush_notifications(self) -> None:
+        """Send all queued notifications."""
+        async with _flush_lock:
+            if not self._notification_queue:
+                return
+
+            try:
+                if "notifications/tools/list_changed" in self._notification_queue:
+                    await self.session.send_tool_list_changed()
+                if "notifications/resources/list_changed" in self._notification_queue:
+                    await self.session.send_resource_list_changed()
+                if "notifications/prompts/list_changed" in self._notification_queue:
+                    await self.session.send_prompt_list_changed()
+                self._notification_queue.clear()
+            except Exception:
+                # Don't let notification failures break the request
+                pass
+
     def _parse_model_preferences(
         self, model_preferences: ModelPreferences | str | list[str] | None
     ) -> ModelPreferences | None:

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

@@ -0,0 +1,35 @@
+from typing import Any
+
+from mcp.server.lowlevel.server import (
+    LifespanResultT,
+    NotificationOptions,
+    RequestT,
+    Server,
+)
+from mcp.server.models import InitializationOptions
+
+
+class LowLevelServer(Server[LifespanResultT, RequestT]):
+    def __init__(self, *args, **kwargs):
+        super().__init__(*args, **kwargs)
+        # FastMCP servers support notifications for all components
+        self.notification_options = NotificationOptions(
+            prompts_changed=True,
+            resources_changed=True,
+            tools_changed=True,
+        )
+
+    def create_initialization_options(
+        self,
+        notification_options: NotificationOptions | None = None,
+        experimental_capabilities: dict[str, dict[str, Any]] | None = None,
+        **kwargs: Any,
+    ) -> InitializationOptions:
+        # ensure we use the FastMCP notification options
+        if notification_options is None:
+            notification_options = self.notification_options
+        return super().create_initialization_options(
+            notification_options=notification_options,
+            experimental_capabilities=experimental_capabilities,
+            **kwargs,
+        )

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