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

fastmcp/server/context.py

@@ -1,8 +1,8 @@
 from __future__ import annotations
 
-import asyncio
 import copy
 import inspect
+import logging
 import warnings
 import weakref
 from collections.abc import Generator, Mapping, Sequence
@@ -10,8 +10,10 @@ from contextlib import contextmanager
 from contextvars import ContextVar, Token
 from dataclasses import dataclass
 from enum import Enum
+from logging import Logger
 from typing import Any, Literal, cast, get_origin, overload
 
+import anyio
 from mcp import LoggingLevel, ServerSession
 from mcp.server.lowlevel.helper_types import ReadResourceContents
 from mcp.server.lowlevel.server import request_ctx
@@ -20,6 +22,7 @@ from mcp.types import (
     AudioContent,
     ClientCapabilities,
     CreateMessageResult,
+    GetPromptResult,
     ImageContent,
     IncludeContext,
     ModelHint,
@@ -30,6 +33,8 @@ from mcp.types import (
     TextContent,
 )
 from mcp.types import CreateMessageRequestParams as SamplingParams
+from mcp.types import Prompt as MCPPrompt
+from mcp.types import Resource as MCPResource
 from pydantic.networks import AnyUrl
 from starlette.requests import Request
 from typing_extensions import TypeVar
@@ -44,14 +49,21 @@ from fastmcp.server.elicitation import (
     get_elicitation_schema,
 )
 from fastmcp.server.server import FastMCP
-from fastmcp.utilities.logging import get_logger
+from fastmcp.utilities.logging import _clamp_logger, get_logger
 from fastmcp.utilities.types import get_cached_typeadapter
 
-logger = get_logger(__name__)
+logger: Logger = get_logger(name=__name__)
+to_client_logger: Logger = logger.getChild(suffix="to_client")
+
+# Convert all levels of server -> client messages to debug level
+# This clamp can be undone at runtime by calling `_unclamp_logger` or calling
+# `_clamp_logger` with a different max level.
+_clamp_logger(logger=to_client_logger, max_level="DEBUG")
+
 
 T = TypeVar("T", default=Any)
 _current_context: ContextVar[Context | None] = ContextVar("context", default=None)  # type: ignore[assignment]
-_flush_lock = asyncio.Lock()
+_flush_lock = anyio.Lock()
 
 
 @dataclass
@@ -66,6 +78,18 @@ class LogData:
     extra: Mapping[str, Any] | None = None
 
 
+_mcp_level_to_python_level = {
+    "debug": logging.DEBUG,
+    "info": logging.INFO,
+    "notice": logging.INFO,
+    "warning": logging.WARNING,
+    "error": logging.ERROR,
+    "critical": logging.CRITICAL,
+    "alert": logging.CRITICAL,
+    "emergency": logging.CRITICAL,
+}
+
+
 @contextmanager
 def set_context(context: Context) -> Generator[Context, None, None]:
     token = _current_context.set(context)
@@ -157,15 +181,33 @@ class Context:
             _current_context.reset(token)
 
     @property
-    def request_context(self) -> RequestContext[ServerSession, Any, Request]:
+    def request_context(self) -> RequestContext[ServerSession, Any, Request] | None:
         """Access to the underlying request context.
 
-        If called outside of a request context, this will raise a ValueError.
+        Returns None when the MCP session has not been established yet.
+        Returns the full RequestContext once the MCP session is available.
+
+        For HTTP request access in middleware, use `get_http_request()` from fastmcp.server.dependencies,
+        which works whether or not the MCP session is available.
+
+        Example in middleware:
+        ```python
+        async def on_request(self, context, call_next):
+            ctx = context.fastmcp_context
+            if ctx.request_context:
+                # MCP session available - can access session_id, request_id, etc.
+                session_id = ctx.session_id
+            else:
+                # MCP session not available yet - use HTTP helpers
+                from fastmcp.server.dependencies import get_http_request
+                request = get_http_request()
+            return await call_next(context)
+        ```
         """
         try:
             return request_ctx.get()
         except LookupError:
-            raise ValueError("Context is not available outside of a request")
+            return None
 
     async def report_progress(
         self, progress: float, total: float | None = None, message: str | None = None
@@ -179,7 +221,7 @@ class Context:
 
         progress_token = (
             self.request_context.meta.progressToken
-            if self.request_context.meta
+            if self.request_context and self.request_context.meta
             else None
         )
 
@@ -194,6 +236,36 @@ class Context:
             related_request_id=self.request_id,
         )
 
+    async def list_resources(self) -> list[MCPResource]:
+        """List all available resources from the server.
+
+        Returns:
+            List of Resource objects available on the server
+        """
+        return await self.fastmcp._list_resources_mcp()
+
+    async def list_prompts(self) -> list[MCPPrompt]:
+        """List all available prompts from the server.
+
+        Returns:
+            List of Prompt objects available on the server
+        """
+        return await self.fastmcp._list_prompts_mcp()
+
+    async def get_prompt(
+        self, name: str, arguments: dict[str, Any] | None = None
+    ) -> GetPromptResult:
+        """Get a prompt by name with optional arguments.
+
+        Args:
+            name: The name of the prompt to get
+            arguments: Optional arguments to pass to the prompt
+
+        Returns:
+            The prompt result
+        """
+        return await self.fastmcp._get_prompt_mcp(name, arguments)
+
     async def read_resource(self, uri: str | AnyUrl) -> list[ReadResourceContents]:
         """Read a resource by URI.
 
@@ -203,9 +275,7 @@ class Context:
         Returns:
             The resource content as either text or bytes
         """
-        if self.fastmcp is None:
-            raise ValueError("Context is not available outside of a request")
-        return await self.fastmcp._mcp_read_resource(uri)
+        return await self.fastmcp._read_resource_mcp(uri)
 
     async def log(
         self,
@@ -216,6 +286,8 @@ class Context:
     ) -> None:
         """Send a log message to the client.
 
+        Messages sent to Clients are also logged to the `fastmcp.server.context.to_client` logger with a level of `DEBUG`.
+
         Args:
             message: Log message
             level: Optional log level. One of "debug", "info", "notice", "warning", "error", "critical",
@@ -223,13 +295,13 @@ class Context:
             logger_name: Optional logger name
             extra: Optional mapping for additional arguments
         """
-        if level is None:
-            level = "info"
         data = LogData(msg=message, extra=extra)
-        await self.session.send_log_message(
-            level=level,
+
+        await _log_to_server_and_client(
             data=data,
-            logger=logger_name,
+            session=self.session,
+            level=level or "info",
+            logger_name=logger_name,
             related_request_id=self.request_id,
         )
 
@@ -238,13 +310,21 @@ class Context:
         """Get the client ID if available."""
         return (
             getattr(self.request_context.meta, "client_id", None)
-            if self.request_context.meta
+            if self.request_context and self.request_context.meta
             else None
         )
 
     @property
     def request_id(self) -> str:
-        """Get the unique ID for this request."""
+        """Get the unique ID for this request.
+
+        Raises RuntimeError if MCP request context is not available.
+        """
+        if self.request_context is None:
+            raise RuntimeError(
+                "request_id is not available because the MCP session has not been established yet. "
+                "Check `context.request_context` for None before accessing this attribute."
+            )
         return str(self.request_context.request_id)
 
     @property
@@ -259,6 +339,9 @@ class Context:
             The session ID for StreamableHTTP transports, or a generated ID
             for other transports.
 
+        Raises:
+            RuntimeError if MCP request context is not available.
+
         Example:
             ```python
             @server.tool
@@ -269,6 +352,11 @@ class Context:
             ```
         """
         request_ctx = self.request_context
+        if request_ctx is None:
+            raise RuntimeError(
+                "session_id is not available because the MCP session has not been established yet. "
+                "Check `context.request_context` for None before accessing this attribute."
+            )
         session = request_ctx.session
 
         # Try to get the session ID from the session attributes
@@ -288,12 +376,20 @@ class Context:
             session_id = str(uuid4())
 
         # Save the session id to the session attributes
-        setattr(session, "_fastmcp_id", session_id)
+        session._fastmcp_id = session_id
         return session_id
 
     @property
     def session(self) -> ServerSession:
-        """Access to the underlying session for advanced usage."""
+        """Access to the underlying session for advanced usage.
+
+        Raises RuntimeError if MCP request context is not available.
+        """
+        if self.request_context is None:
+            raise RuntimeError(
+                "session is not available because the MCP session has not been established yet. "
+                "Check `context.request_context` for None before accessing this attribute."
+            )
         return self.request_context.session
 
     # Convenience methods for common log levels
@@ -303,9 +399,14 @@ class Context:
         logger_name: str | None = None,
         extra: Mapping[str, Any] | None = None,
     ) -> None:
-        """Send a debug log message."""
+        """Send a `DEBUG`-level message to the connected MCP Client.
+
+        Messages sent to Clients are also logged to the `fastmcp.server.context.to_client` logger with a level of `DEBUG`."""
         await self.log(
-            level="debug", message=message, logger_name=logger_name, extra=extra
+            level="debug",
+            message=message,
+            logger_name=logger_name,
+            extra=extra,
         )
 
     async def info(
@@ -314,9 +415,14 @@ class Context:
         logger_name: str | None = None,
         extra: Mapping[str, Any] | None = None,
     ) -> None:
-        """Send an info log message."""
+        """Send a `INFO`-level message to the connected MCP Client.
+
+        Messages sent to Clients are also logged to the `fastmcp.server.context.to_client` logger with a level of `DEBUG`."""
         await self.log(
-            level="info", message=message, logger_name=logger_name, extra=extra
+            level="info",
+            message=message,
+            logger_name=logger_name,
+            extra=extra,
         )
 
     async def warning(
@@ -325,9 +431,14 @@ class Context:
         logger_name: str | None = None,
         extra: Mapping[str, Any] | None = None,
     ) -> None:
-        """Send a warning log message."""
+        """Send a `WARNING`-level message to the connected MCP Client.
+
+        Messages sent to Clients are also logged to the `fastmcp.server.context.to_client` logger with a level of `DEBUG`."""
         await self.log(
-            level="warning", message=message, logger_name=logger_name, extra=extra
+            level="warning",
+            message=message,
+            logger_name=logger_name,
+            extra=extra,
         )
 
     async def error(
@@ -336,9 +447,14 @@ class Context:
         logger_name: str | None = None,
         extra: Mapping[str, Any] | None = None,
     ) -> None:
-        """Send an error log message."""
+        """Send a `ERROR`-level message to the connected MCP Client.
+
+        Messages sent to Clients are also logged to the `fastmcp.server.context.to_client` logger with a level of `DEBUG`."""
         await self.log(
-            level="error", message=message, logger_name=logger_name, extra=extra
+            level="error",
+            message=message,
+            logger_name=logger_name,
+            extra=extra,
         )
 
     async def list_roots(self) -> list[Root]:
@@ -521,13 +637,11 @@ class Context:
                 choice_literal = Literal[tuple(response_type)]  # type: ignore
                 response_type = ScalarElicitationType[choice_literal]  # type: ignore
             # if the user provided a primitive scalar, wrap it in an object schema
-            elif response_type in {bool, int, float, str}:
-                response_type = ScalarElicitationType[response_type]  # type: ignore
-            # if the user provided a Literal type, wrap it in an object schema
-            elif get_origin(response_type) is Literal:
-                response_type = ScalarElicitationType[response_type]  # type: ignore
-            # if the user provided an Enum type, wrap it in an object schema
-            elif isinstance(response_type, type) and issubclass(response_type, Enum):
+            elif (
+                response_type in {bool, int, float, str}
+                or get_origin(response_type) is Literal
+                or (isinstance(response_type, type) and issubclass(response_type, Enum))
+            ):
                 response_type = ScalarElicitationType[response_type]  # type: ignore
 
             response_type = cast(type[T], response_type)
@@ -592,30 +706,14 @@ class Context:
     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."""
@@ -675,3 +773,31 @@ def _parse_model_preferences(
         raise ValueError(
             "model_preferences must be one of: ModelPreferences, str, list[str], or None."
         )
+
+
+async def _log_to_server_and_client(
+    data: LogData,
+    session: ServerSession,
+    level: LoggingLevel,
+    logger_name: str | None = None,
+    related_request_id: str | None = None,
+) -> None:
+    """Log a message to the server and client."""
+
+    msg_prefix = f"Sending {level.upper()} to client"
+
+    if logger_name:
+        msg_prefix += f" ({logger_name})"
+
+    to_client_logger.log(
+        level=_mcp_level_to_python_level[level],
+        msg=f"{msg_prefix}: {data.msg}",
+        extra=data.extra,
+    )
+
+    await session.send_log_message(
+        level=level,
+        data=data,
+        logger=logger_name,
+        related_request_id=related_request_id,
+    )

fastmcp/server/dependencies.py

@@ -1,26 +1,30 @@
 from __future__ import annotations
 
+import contextlib
 from typing import TYPE_CHECKING
 
 from mcp.server.auth.middleware.auth_context import (
     get_access_token as _sdk_get_access_token,
 )
+from mcp.server.auth.middleware.bearer_auth import AuthenticatedUser
 from mcp.server.auth.provider import (
     AccessToken as _SDKAccessToken,
 )
+from mcp.server.lowlevel.server import request_ctx
 from starlette.requests import Request
 
 from fastmcp.server.auth import AccessToken
+from fastmcp.server.http import _current_http_request
 
 if TYPE_CHECKING:
     from fastmcp.server.context import Context
 
 __all__ = [
+    "AccessToken",
+    "get_access_token",
     "get_context",
-    "get_http_request",
     "get_http_headers",
-    "get_access_token",
-    "AccessToken",
+    "get_http_request",
 ]
 
 
@@ -40,13 +44,15 @@ def get_context() -> Context:
 
 
 def get_http_request() -> Request:
-    from mcp.server.lowlevel.server import request_ctx
-
+    # Try MCP SDK's request_ctx first (set during normal MCP request handling)
     request = None
-    try:
+    with contextlib.suppress(LookupError):
         request = request_ctx.get().request
-    except LookupError:
-        pass
+
+    # Fallback to FastMCP's HTTP context variable
+    # This is needed during `on_initialize` middleware where request_ctx isn't set yet
+    if request is None:
+        request = _current_http_request.get()
 
     if request is None:
         raise RuntimeError("No active HTTP request found.")
@@ -106,17 +112,38 @@ def get_access_token() -> AccessToken | None:
     """
     Get the FastMCP access token from the current context.
 
+    This function first tries to get the token from the current HTTP request's scope,
+    which is more reliable for long-lived connections where the SDK's auth_context_var
+    may become stale after token refresh. Falls back to the SDK's context var if no
+    request is available.
+
     Returns:
         The access token if an authenticated user is available, None otherwise.
     """
-    #
-    access_token: _SDKAccessToken | None = _sdk_get_access_token()
+    access_token: _SDKAccessToken | None = None
+
+    # First, try to get from current HTTP request's scope (issue #1863)
+    # This is more reliable than auth_context_var for Streamable HTTP sessions
+    # where tokens may be refreshed between MCP messages
+    try:
+        request = get_http_request()
+        user = request.scope.get("user")
+        if isinstance(user, AuthenticatedUser):
+            access_token = user.access_token
+    except RuntimeError:
+        # No HTTP request available, fall back to context var
+        pass
+
+    # Fall back to SDK's context var if we didn't get a token from the request
+    if access_token is None:
+        access_token = _sdk_get_access_token()
 
     if access_token is None or isinstance(access_token, AccessToken):
         return access_token
 
-    # If the object is not a FastMCP AccessToken, convert it to one if the fields are compatible
-    # This is a workaround for the case where the SDK returns a different type
+    # If the object is not a FastMCP AccessToken, convert it to one if the
+    # fields are compatible (e.g. `claims` is not present in the SDK's AccessToken).
+    # This is a workaround for the case where the SDK or auth provider returns a different type
     # If it fails, it will raise a TypeError
     try:
         access_token_as_dict = access_token.model_dump()

fastmcp/server/elicitation.py

@@ -20,8 +20,8 @@ __all__ = [
     "AcceptedElicitation",
     "CancelledElicitation",
     "DeclinedElicitation",
-    "get_elicitation_schema",
     "ScalarElicitationType",
+    "get_elicitation_schema",
 ]
 
 logger = get_logger(__name__)

fastmcp/server/http.py

@@ -5,10 +5,12 @@ from contextlib import asynccontextmanager, contextmanager
 from contextvars import ContextVar
 from typing import TYPE_CHECKING
 
-from mcp.server.auth.middleware.bearer_auth import RequireAuthMiddleware
+from mcp.server.auth.routes import build_resource_metadata_url
 from mcp.server.lowlevel.server import LifespanResultT
 from mcp.server.sse import SseServerTransport
-from mcp.server.streamable_http import EventStore
+from mcp.server.streamable_http import (
+    EventStore,
+)
 from mcp.server.streamable_http_manager import StreamableHTTPSessionManager
 from starlette.applications import Starlette
 from starlette.middleware import Middleware
@@ -18,6 +20,7 @@ from starlette.routing import BaseRoute, Mount, Route
 from starlette.types import Lifespan, Receive, Scope, Send
 
 from fastmcp.server.auth import AuthProvider
+from fastmcp.server.auth.middleware import RequireAuthMiddleware
 from fastmcp.utilities.logging import get_logger
 
 if TYPE_CHECKING:
@@ -167,23 +170,38 @@ def create_sse_app(
         # Get auth middleware from the provider
         auth_middleware = auth.get_middleware()
 
-        # Get auth routes including protected MCP endpoint
-        auth_routes = auth.get_routes(
-            mcp_path=sse_path,
-            mcp_endpoint=handle_sse,
-        )
-
+        # Get auth provider's own routes (OAuth endpoints, metadata, etc)
+        auth_routes = auth.get_routes(mcp_path=sse_path)
         server_routes.extend(auth_routes)
         server_middleware.extend(auth_middleware)
 
-        # Manually wrap the SSE message endpoint with RequireAuthMiddleware
+        # Build RFC 9728-compliant metadata URL
+        resource_url = auth._get_resource_url(sse_path)
+        resource_metadata_url = (
+            build_resource_metadata_url(resource_url) if resource_url else None
+        )
+
+        # Create protected SSE endpoint route
+        server_routes.append(
+            Route(
+                sse_path,
+                endpoint=RequireAuthMiddleware(
+                    handle_sse,
+                    auth.required_scopes,
+                    resource_metadata_url,
+                ),
+                methods=["GET"],
+            )
+        )
+
+        # Wrap the SSE message endpoint with RequireAuthMiddleware
         server_routes.append(
             Mount(
                 message_path,
                 app=RequireAuthMiddleware(
                     sse.handle_post_message,
                     auth.required_scopes,
-                    auth._get_resource_url("/.well-known/oauth-protected-resource"),
+                    resource_metadata_url,
                 ),
             )
         )
@@ -215,11 +233,17 @@ def create_sse_app(
     if middleware:
         server_middleware.extend(middleware)
 
+    @asynccontextmanager
+    async def lifespan(app: Starlette) -> AsyncGenerator[None, None]:
+        async with server._lifespan_manager():
+            yield
+
     # Create and return the app
     app = create_base_app(
         routes=server_routes,
         middleware=server_middleware,
         debug=debug,
+        lifespan=lifespan,
     )
     # Store the FastMCP server instance on the Starlette app state
     app.state.fastmcp_server = server
@@ -274,14 +298,29 @@ def create_streamable_http_app(
         # Get auth middleware from the provider
         auth_middleware = auth.get_middleware()
 
-        # Get auth routes including protected MCP endpoint
-        auth_routes = auth.get_routes(
-            mcp_path=streamable_http_path,
-            mcp_endpoint=streamable_http_app,
-        )
-
+        # Get auth provider's own routes (OAuth endpoints, metadata, etc)
+        auth_routes = auth.get_routes(mcp_path=streamable_http_path)
         server_routes.extend(auth_routes)
         server_middleware.extend(auth_middleware)
+
+        # Build RFC 9728-compliant metadata URL
+        resource_url = auth._get_resource_url(streamable_http_path)
+        resource_metadata_url = (
+            build_resource_metadata_url(resource_url) if resource_url else None
+        )
+
+        # Create protected HTTP endpoint route
+        server_routes.append(
+            Route(
+                streamable_http_path,
+                endpoint=RequireAuthMiddleware(
+                    streamable_http_app,
+                    auth.required_scopes,
+                    resource_metadata_url,
+                ),
+                methods=["GET", "POST", "DELETE"],
+            )
+        )
     else:
         # No auth required
         server_routes.append(
@@ -303,7 +342,7 @@ def create_streamable_http_app(
     # Create a lifespan manager to start and stop the session manager
     @asynccontextmanager
     async def lifespan(app: Starlette) -> AsyncGenerator[None, None]:
-        async with session_manager.run():
+        async with server._lifespan_manager(), session_manager.run():
             yield
 
     # Create and return the app with lifespan