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

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,8 @@ 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.server.tasks.capabilities import get_task_capabilities
 from fastmcp.utilities.logging import get_logger
 
 if TYPE_CHECKING:
@@ -113,7 +117,8 @@ def create_base_app(
         A Starlette application
     """
     # Always add RequestContextMiddleware as the outermost middleware
-    middleware.insert(0, Middleware(RequestContextMiddleware))
+    # TODO(ty): remove type ignore when ty supports Starlette Middleware typing
+    middleware.insert(0, Middleware(RequestContextMiddleware))  # type: ignore[arg-type]
 
     return StarletteWithLifespan(
         routes=routes,
@@ -155,10 +160,15 @@ def create_sse_app(
     # Create handler for SSE connections
     async def handle_sse(scope: Scope, receive: Receive, send: Send) -> Response:
         async with sse.connect_sse(scope, receive, send) as streams:
+            # Build experimental capabilities
+            experimental_capabilities = get_task_capabilities()
+
             await server._mcp_server.run(
                 streams[0],
                 streams[1],
-                server._mcp_server.create_initialization_options(),
+                server._mcp_server.create_initialization_options(
+                    experimental_capabilities=experimental_capabilities
+                ),
             )
         return Response()
 
@@ -167,23 +177,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 +240,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
@@ -232,6 +263,7 @@ def create_streamable_http_app(
     server: FastMCP[LifespanResultT],
     streamable_http_path: str,
     event_store: EventStore | None = None,
+    retry_interval: int | None = None,
     auth: AuthProvider | None = None,
     json_response: bool = False,
     stateless_http: bool = False,
@@ -244,7 +276,10 @@ def create_streamable_http_app(
     Args:
         server: The FastMCP server instance
         streamable_http_path: Path for StreamableHTTP connections
-        event_store: Optional event store for session management
+        event_store: Optional event store for SSE polling/resumability
+        retry_interval: Optional retry interval in milliseconds for SSE polling.
+            Controls how quickly clients should reconnect after server-initiated
+            disconnections. Requires event_store to be set. Defaults to SDK default.
         auth: Optional authentication provider (AuthProvider)
         json_response: Whether to use JSON response format
         stateless_http: Whether to use stateless mode (new transport per request)
@@ -262,6 +297,7 @@ def create_streamable_http_app(
     session_manager = StreamableHTTPSessionManager(
         app=server._mcp_server,
         event_store=event_store,
+        retry_interval=retry_interval,
         json_response=json_response,
         stateless=stateless_http,
     )
@@ -274,14 +310,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 +354,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

fastmcp/server/low_level.py

@@ -1,5 +1,13 @@
-from typing import Any
+from __future__ import annotations
 
+import weakref
+from contextlib import AsyncExitStack
+from typing import TYPE_CHECKING, Any
+
+import anyio
+import mcp.types
+from anyio.streams.memory import MemoryObjectReceiveStream, MemoryObjectSendStream
+from mcp import McpError
 from mcp.server.lowlevel.server import (
     LifespanResultT,
     NotificationOptions,
@@ -9,11 +17,122 @@ from mcp.server.lowlevel.server import (
     Server as _Server,
 )
 from mcp.server.models import InitializationOptions
+from mcp.server.session import ServerSession
+from mcp.server.stdio import stdio_server as stdio_server
+from mcp.shared.message import SessionMessage
+from mcp.shared.session import RequestResponder
+
+from fastmcp.utilities.logging import get_logger
+
+if TYPE_CHECKING:
+    from fastmcp.server.server import FastMCP
+
+logger = get_logger(__name__)
+
+
+class MiddlewareServerSession(ServerSession):
+    """ServerSession that routes initialization requests through FastMCP middleware."""
+
+    def __init__(self, fastmcp: FastMCP, *args, **kwargs):
+        super().__init__(*args, **kwargs)
+        self._fastmcp_ref: weakref.ref[FastMCP] = weakref.ref(fastmcp)
+        # Task group for subscription tasks (set during session run)
+        self._subscription_task_group: anyio.TaskGroup | None = None  # type: ignore[valid-type]
+
+    @property
+    def fastmcp(self) -> FastMCP:
+        """Get the FastMCP instance."""
+        fastmcp = self._fastmcp_ref()
+        if fastmcp is None:
+            raise RuntimeError("FastMCP instance is no longer available")
+        return fastmcp
+
+    async def _received_request(
+        self,
+        responder: RequestResponder[mcp.types.ClientRequest, mcp.types.ServerResult],
+    ):
+        """
+        Override the _received_request method to route special requests
+        through FastMCP middleware.
+
+        Handles initialization requests and SEP-1686 task methods.
+        """
+        import fastmcp.server.context
+        from fastmcp.server.middleware.middleware import MiddlewareContext
+
+        if isinstance(responder.request.root, mcp.types.InitializeRequest):
+            # The MCP SDK's ServerSession._received_request() handles the
+            # initialize request internally by calling responder.respond()
+            # to send the InitializeResult directly to the write stream, then
+            # returning None. This bypasses the middleware return path entirely,
+            # so middleware would only see the request, never the response.
+            #
+            # To expose the response to middleware (e.g., for logging server
+            # capabilities), we wrap responder.respond() to capture the
+            # InitializeResult before it's sent, then return it from
+            # call_original_handler so it flows back through the middleware chain.
+            captured_response: mcp.types.ServerResult | None = None
+            original_respond = responder.respond
+
+            async def capturing_respond(
+                response: mcp.types.ServerResult,
+            ) -> None:
+                nonlocal captured_response
+                captured_response = response
+                return await original_respond(response)
+
+            responder.respond = capturing_respond  # type: ignore[method-assign]
+
+            async def call_original_handler(
+                ctx: MiddlewareContext,
+            ) -> mcp.types.InitializeResult | None:
+                await super(MiddlewareServerSession, self)._received_request(responder)
+                if captured_response is not None and isinstance(
+                    captured_response.root, mcp.types.InitializeResult
+                ):
+                    return captured_response.root
+                return None
+
+            async with fastmcp.server.context.Context(
+                fastmcp=self.fastmcp
+            ) as fastmcp_ctx:
+                # Create the middleware context.
+                mw_context = MiddlewareContext(
+                    message=responder.request.root,
+                    source="client",
+                    type="request",
+                    method="initialize",
+                    fastmcp_context=fastmcp_ctx,
+                )
+
+                try:
+                    return await self.fastmcp._apply_middleware(
+                        mw_context, call_original_handler
+                    )
+                except McpError as e:
+                    # McpError can be thrown from middleware in `on_initialize`
+                    # send the error to responder.
+                    if not responder._completed:
+                        with responder:
+                            await responder.respond(e.error)
+                    else:
+                        # Don't re-raise: prevents responding to initialize request twice
+                        logger.warning(
+                            "Received McpError but responder is already completed. "
+                            "Cannot send error response as response was already sent.",
+                            exc_info=e,
+                        )
+
+        # Fall through to default handling (task methods now handled via registered handlers)
+        return await super()._received_request(responder)
 
 
 class LowLevelServer(_Server[LifespanResultT, RequestT]):
-    def __init__(self, *args, **kwargs):
+    def __init__(self, fastmcp: FastMCP, *args: Any, **kwargs: Any):
         super().__init__(*args, **kwargs)
+        # Store a weak reference to FastMCP to avoid circular references
+        self._fastmcp_ref: weakref.ref[FastMCP] = weakref.ref(fastmcp)
+
         # FastMCP servers support notifications for all components
         self.notification_options = NotificationOptions(
             prompts_changed=True,
@@ -21,6 +140,14 @@ class LowLevelServer(_Server[LifespanResultT, RequestT]):
             tools_changed=True,
         )
 
+    @property
+    def fastmcp(self) -> FastMCP:
+        """Get the FastMCP instance."""
+        fastmcp = self._fastmcp_ref()
+        if fastmcp is None:
+            raise RuntimeError("FastMCP instance is no longer available")
+        return fastmcp
+
     def create_initialization_options(
         self,
         notification_options: NotificationOptions | None = None,
@@ -35,3 +162,39 @@ class LowLevelServer(_Server[LifespanResultT, RequestT]):
             experimental_capabilities=experimental_capabilities,
             **kwargs,
         )
+
+    async def run(
+        self,
+        read_stream: MemoryObjectReceiveStream[SessionMessage | Exception],
+        write_stream: MemoryObjectSendStream[SessionMessage],
+        initialization_options: InitializationOptions,
+        raise_exceptions: bool = False,
+        stateless: bool = False,
+    ):
+        """
+        Overrides the run method to use the MiddlewareServerSession.
+        """
+        async with AsyncExitStack() as stack:
+            lifespan_context = await stack.enter_async_context(self.lifespan(self))
+            session = await stack.enter_async_context(
+                MiddlewareServerSession(
+                    self.fastmcp,
+                    read_stream,
+                    write_stream,
+                    initialization_options,
+                    stateless=stateless,
+                )
+            )
+
+            async with anyio.create_task_group() as tg:
+                # Store task group on session for subscription tasks (SEP-1686)
+                session._subscription_task_group = tg
+
+                async for message in session.incoming_messages:
+                    tg.start_soon(
+                        self._handle_message,
+                        message,
+                        session,
+                        lifespan_context,
+                        raise_exceptions,
+                    )

fastmcp/server/middleware/__init__.py

@@ -5,7 +5,7 @@ from .middleware import (
 )
 
 __all__ = [
+    "CallNext",
     "Middleware",
     "MiddlewareContext",
-    "CallNext",
 ]