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

fastmcp/client/client.py

@@ -15,10 +15,10 @@ from pydantic import AnyUrl
 import fastmcp
 from fastmcp.client.logging import (
     LogHandler,
-    MessageHandler,
     create_log_callback,
     default_log_handler,
 )
+from fastmcp.client.messages import MessageHandler, MessageHandlerT
 from fastmcp.client.progress import ProgressHandler, default_progress_handler
 from fastmcp.client.roots import (
     RootsHandler,
@@ -143,7 +143,7 @@ class Client(Generic[ClientTransportT]):
         roots: RootsList | RootsHandler | None = None,
         sampling_handler: SamplingHandler | None = None,
         log_handler: LogHandler | None = None,
-        message_handler: MessageHandler | None = None,
+        message_handler: MessageHandlerT | MessageHandler | None = None,
         progress_handler: ProgressHandler | None = None,
         timeout: datetime.timedelta | float | int | None = None,
         init_timeout: datetime.timedelta | float | int | None = None,

fastmcp/client/logging.py

@@ -1,7 +1,7 @@
 from collections.abc import Awaitable, Callable
 from typing import TypeAlias
 
-from mcp.client.session import LoggingFnT, MessageHandlerFnT
+from mcp.client.session import LoggingFnT
 from mcp.types import LoggingMessageNotificationParams
 
 from fastmcp.utilities.logging import get_logger
@@ -10,7 +10,6 @@ logger = get_logger(__name__)
 
 LogMessage: TypeAlias = LoggingMessageNotificationParams
 LogHandler: TypeAlias = Callable[[LogMessage], Awaitable[None]]
-MessageHandler: TypeAlias = MessageHandlerFnT
 
 
 async def default_log_handler(message: LogMessage) -> None:

fastmcp/client/messages.py

@@ -0,0 +1,126 @@
+from typing import TypeAlias
+
+import mcp.types
+from mcp.client.session import MessageHandlerFnT
+from mcp.shared.session import RequestResponder
+
+Message: TypeAlias = (
+    RequestResponder[mcp.types.ServerRequest, mcp.types.ClientResult]
+    | mcp.types.ServerNotification
+    | Exception
+)
+
+MessageHandlerT: TypeAlias = MessageHandlerFnT
+
+
+class MessageHandler:
+    """
+    This class is used to handle MCP messages sent to the client. It is used to handle all messages,
+    requests, notifications, and exceptions. Users can override any of the hooks
+    """
+
+    async def __call__(
+        self,
+        message: RequestResponder[mcp.types.ServerRequest, mcp.types.ClientResult]
+        | mcp.types.ServerNotification
+        | Exception,
+    ) -> None:
+        return await self.dispatch(message)
+
+    async def dispatch(self, message: Message) -> None:
+        # handle all messages
+        await self.on_message(message)
+
+        match message:
+            # requests
+            case RequestResponder():
+                # handle all requests
+                await self.on_request(message)
+
+                # handle specific requests
+                match message.request.root:
+                    case mcp.types.PingRequest():
+                        await self.on_ping(message.request.root)
+                    case mcp.types.ListRootsRequest():
+                        await self.on_list_roots(message.request.root)
+                    case mcp.types.CreateMessageRequest():
+                        await self.on_create_message(message.request.root)
+
+            # notifications
+            case mcp.types.ServerNotification():
+                # handle all notifications
+                await self.on_notification(message)
+
+                # handle specific notifications
+                match message.root:
+                    case mcp.types.CancelledNotification():
+                        await self.on_cancelled(message.root)
+                    case mcp.types.ProgressNotification():
+                        await self.on_progress(message.root)
+                    case mcp.types.LoggingMessageNotification():
+                        await self.on_logging_message(message.root)
+                    case mcp.types.ToolListChangedNotification():
+                        await self.on_tool_list_changed(message.root)
+                    case mcp.types.ResourceListChangedNotification():
+                        await self.on_resource_list_changed(message.root)
+                    case mcp.types.PromptListChangedNotification():
+                        await self.on_prompt_list_changed(message.root)
+                    case mcp.types.ResourceUpdatedNotification():
+                        await self.on_resource_updated(message.root)
+
+            case Exception():
+                await self.on_exception(message)
+
+    async def on_message(self, message: Message) -> None:
+        pass
+
+    async def on_request(
+        self, message: RequestResponder[mcp.types.ServerRequest, mcp.types.ClientResult]
+    ) -> None:
+        pass
+
+    async def on_ping(self, message: mcp.types.PingRequest) -> None:
+        pass
+
+    async def on_list_roots(self, message: mcp.types.ListRootsRequest) -> None:
+        pass
+
+    async def on_create_message(self, message: mcp.types.CreateMessageRequest) -> None:
+        pass
+
+    async def on_notification(self, message: mcp.types.ServerNotification) -> None:
+        pass
+
+    async def on_exception(self, message: Exception) -> None:
+        pass
+
+    async def on_progress(self, message: mcp.types.ProgressNotification) -> None:
+        pass
+
+    async def on_logging_message(
+        self, message: mcp.types.LoggingMessageNotification
+    ) -> None:
+        pass
+
+    async def on_tool_list_changed(
+        self, message: mcp.types.ToolListChangedNotification
+    ) -> None:
+        pass
+
+    async def on_resource_list_changed(
+        self, message: mcp.types.ResourceListChangedNotification
+    ) -> None:
+        pass
+
+    async def on_prompt_list_changed(
+        self, message: mcp.types.PromptListChangedNotification
+    ) -> None:
+        pass
+
+    async def on_resource_updated(
+        self, message: mcp.types.ResourceUpdatedNotification
+    ) -> None:
+        pass
+
+    async def on_cancelled(self, message: mcp.types.CancelledNotification) -> None:
+        pass

fastmcp/prompts/prompt.py

@@ -70,6 +70,22 @@ class Prompt(FastMCPComponent, ABC):
         default=None, description="Arguments that can be passed to the prompt"
     )
 
+    def enable(self) -> None:
+        super().enable()
+        try:
+            context = get_context()
+            context._queue_prompt_list_changed()  # type: ignore[private-use]
+        except RuntimeError:
+            pass  # No context available
+
+    def disable(self) -> None:
+        super().disable()
+        try:
+            context = get_context()
+            context._queue_prompt_list_changed()  # type: ignore[private-use]
+        except RuntimeError:
+            pass  # No context available
+
     def to_mcp_prompt(self, **overrides: Any) -> MCPPrompt:
         """Convert the prompt to an MCP prompt."""
         arguments = [
@@ -339,6 +355,6 @@ class FunctionPrompt(Prompt):
                     raise PromptError("Could not convert prompt result to message.")
 
             return messages
-        except Exception as e:
-            logger.exception(f"Error rendering prompt {self.name}: {e}")
+        except Exception:
+            logger.exception(f"Error rendering prompt {self.name}")
             raise PromptError(f"Error rendering prompt {self.name}.")

fastmcp/prompts/prompt_manager.py

@@ -172,12 +172,12 @@ class PromptManager:
 
             # Pass through PromptErrors as-is
             except PromptError as e:
-                logger.exception(f"Error rendering prompt {name!r}: {e}")
+                logger.exception(f"Error rendering prompt {name!r}")
                 raise e
 
             # Handle other exceptions
             except Exception as e:
-                logger.exception(f"Error rendering prompt {name!r}: {e}")
+                logger.exception(f"Error rendering prompt {name!r}")
                 if self.mask_error_details:
                     # Mask internal details
                     raise PromptError(f"Error rendering prompt {name!r}") from e

fastmcp/resources/resource.py

@@ -44,6 +44,22 @@ class Resource(FastMCPComponent, abc.ABC):
         pattern=r"^[a-zA-Z0-9]+/[a-zA-Z0-9\-+.]+$",
     )
 
+    def enable(self) -> None:
+        super().enable()
+        try:
+            context = get_context()
+            context._queue_resource_list_changed()  # type: ignore[private-use]
+        except RuntimeError:
+            pass  # No context available
+
+    def disable(self) -> None:
+        super().disable()
+        try:
+            context = get_context()
+            context._queue_resource_list_changed()  # type: ignore[private-use]
+        except RuntimeError:
+            pass  # No context available
+
     @staticmethod
     def from_function(
         fn: Callable[[], Any],

fastmcp/resources/resource_manager.py

@@ -422,12 +422,12 @@ class ResourceManager:
 
             # raise ResourceErrors as-is
             except ResourceError as e:
-                logger.exception(f"Error reading resource {uri_str!r}: {e}")
+                logger.exception(f"Error reading resource {uri_str!r}")
                 raise e
 
             # Handle other exceptions
             except Exception as e:
-                logger.exception(f"Error reading resource {uri_str!r}: {e}")
+                logger.exception(f"Error reading resource {uri_str!r}")
                 if self.mask_error_details:
                     # Mask internal details
                     raise ResourceError(f"Error reading resource {uri_str!r}") from e
@@ -445,12 +445,12 @@ class ResourceManager:
                     return await resource.read()
                 except ResourceError as e:
                     logger.exception(
-                        f"Error reading resource from template {uri_str!r}: {e}"
+                        f"Error reading resource from template {uri_str!r}"
                     )
                     raise e
                 except Exception as e:
                     logger.exception(
-                        f"Error reading resource from template {uri_str!r}: {e}"
+                        f"Error reading resource from template {uri_str!r}"
                     )
                     if self.mask_error_details:
                         raise ResourceError(

fastmcp/resources/template.py

@@ -15,7 +15,7 @@ from pydantic import (
     validate_call,
 )
 
-from fastmcp.resources.types import Resource
+from fastmcp.resources.resource import Resource
 from fastmcp.server.dependencies import get_context
 from fastmcp.utilities.components import FastMCPComponent
 from fastmcp.utilities.json_schema import compress_schema
@@ -65,6 +65,22 @@ class ResourceTemplate(FastMCPComponent):
     def __repr__(self) -> str:
         return f"{self.__class__.__name__}(uri_template={self.uri_template!r}, name={self.name!r}, description={self.description!r}, tags={self.tags})"
 
+    def enable(self) -> None:
+        super().enable()
+        try:
+            context = get_context()
+            context._queue_resource_list_changed()  # type: ignore[private-use]
+        except RuntimeError:
+            pass  # No context available
+
+    def disable(self) -> None:
+        super().disable()
+        try:
+            context = get_context()
+            context._queue_resource_list_changed()  # type: ignore[private-use]
+        except RuntimeError:
+            pass  # No context available
+
     @staticmethod
     def from_function(
         fn: Callable[..., Any],

fastmcp/server/auth/providers/bearer.py

@@ -24,6 +24,7 @@ from fastmcp.server.auth.auth import (
     OAuthProvider,
     RevocationOptions,
 )
+from fastmcp.utilities.logging import get_logger
 
 
 class JWKData(TypedDict, total=False):
@@ -199,6 +200,7 @@ class BearerAuthProvider(OAuthProvider):
         self.public_key = public_key
         self.jwks_uri = jwks_uri
         self.jwt = JsonWebToken(["RS256"])
+        self.logger = get_logger(__name__)
 
         # Simple JWKS cache
         self._jwks_cache: dict[str, str] = {}
@@ -265,6 +267,9 @@ class BearerAuthProvider(OAuthProvider):
             # Select the appropriate key
             if kid:
                 if kid not in self._jwks_cache:
+                    self.logger.debug(
+                        "JWKS key lookup failed: key ID '%s' not found", kid
+                    )
                     raise ValueError(f"Key ID '{kid}' not found in JWKS")
                 return self._jwks_cache[kid]
             else:
@@ -279,6 +284,7 @@ class BearerAuthProvider(OAuthProvider):
                     raise ValueError("No keys found in JWKS")
 
         except Exception as e:
+            self.logger.debug("JWKS fetch failed: %s", str(e))
             raise ValueError(f"Failed to fetch JWKS: {e}")
 
     async def load_access_token(self, token: str) -> AccessToken | None:
@@ -298,15 +304,27 @@ class BearerAuthProvider(OAuthProvider):
             # Decode and verify the JWT token
             claims = self.jwt.decode(token, verification_key)
 
+            # Extract client ID early for logging
+            client_id = claims.get("client_id") or claims.get("sub") or "unknown"
+
             # Validate expiration
             exp = claims.get("exp")
             if exp and exp < time.time():
+                self.logger.debug(
+                    "Token validation failed: expired token for client %s", client_id
+                )
+                self.logger.info("Bearer token rejected for client %s", client_id)
                 return None
 
             # Validate issuer - note we use issuer instead of issuer_url here because
             # issuer is optional, allowing users to make this check optional
             if self.issuer:
                 if claims.get("iss") != self.issuer:
+                    self.logger.debug(
+                        "Token validation failed: issuer mismatch for client %s",
+                        client_id,
+                    )
+                    self.logger.info("Bearer token rejected for client %s", client_id)
                     return None
 
             # Validate audience if configured
@@ -314,26 +332,33 @@ class BearerAuthProvider(OAuthProvider):
                 aud = claims.get("aud")
 
                 # Handle different combinations of audience types
+                audience_valid = False
                 if isinstance(self.audience, list):
                     # self.audience is a list - check if any expected audience is present
                     if isinstance(aud, list):
                         # Both are lists - check for intersection
-                        if not any(expected in aud for expected in self.audience):
-                            return None
+                        audience_valid = any(
+                            expected in aud for expected in self.audience
+                        )
                     else:
                         # aud is a string - check if it's in our expected list
-                        if aud not in self.audience:
-                            return None
+                        audience_valid = aud in self.audience
                 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
+                        audience_valid = self.audience in aud
+                    else:
+                        audience_valid = aud == self.audience
 
-            # Extract claims - prefer client_id over sub for OAuth application identification
-            client_id = claims.get("client_id") or claims.get("sub") or "unknown"
+                if not audience_valid:
+                    self.logger.debug(
+                        "Token validation failed: audience mismatch for client %s",
+                        client_id,
+                    )
+                    self.logger.info("Bearer token rejected for client %s", client_id)
+                    return None
+
+            # Extract scopes
             scopes = self._extract_scopes(claims)
 
             return AccessToken(
@@ -344,8 +369,10 @@ class BearerAuthProvider(OAuthProvider):
             )
 
         except JoseError:
+            self.logger.debug("Token validation failed: JWT signature/format invalid")
             return None
-        except Exception:
+        except Exception as e:
+            self.logger.debug("Token validation failed: %s", str(e))
             return None
 
     def _extract_scopes(self, claims: dict[str, Any]) -> list[str]:

fastmcp/server/context.py

@@ -1,12 +1,13 @@
 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
@@ -30,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
@@ -80,16 +82,20 @@ 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)
@@ -124,7 +130,7 @@ 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,
@@ -160,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
         )
 
@@ -210,7 +216,7 @@ class Context:
             return None
 
     @property
-    def session(self):
+    def session(self) -> ServerSession:
         """Access to the underlying session for advanced usage."""
         return self.request_context.session
 
@@ -233,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],
@@ -269,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,
@@ -294,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/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,
+        )