fastmcp 2.14.4__py3-none-any.whl → 3.0.0b1__py3-none-any.whl

fastmcp/server/elicitation.py

@@ -2,7 +2,7 @@ from __future__ import annotations
 
 from dataclasses import dataclass
 from enum import Enum
-from typing import Any, Generic, Literal, get_origin
+from typing import Any, Generic, Literal, cast, get_origin
 
 from mcp.server.elicitation import (
     CancelledElicitation,
@@ -47,10 +47,10 @@ class ElicitationJsonSchema(GenerateJsonSchema):
         if schema["type"] == "enum":
             # Directly call our custom enum_schema without going through handler
             # This prevents the ref/defs mechanism from being invoked
-            return self.enum_schema(schema)  # type: ignore[arg-type]
+            return self.enum_schema(schema)
         # For list schemas, check if items are enums
         if schema["type"] == "list":
-            return self.list_schema(schema)  # type: ignore[arg-type]
+            return self.list_schema(schema)
         # For all other types, use the default implementation
         return super().generate_inner(schema)
 
@@ -94,7 +94,7 @@ class ElicitationJsonSchema(GenerateJsonSchema):
     def enum_schema(self, schema: core_schema.EnumSchema) -> JsonSchemaValue:
         """Generate inline enum schema.
 
-        Always generates enum pattern: {"enum": [value, ...]}
+        Always generates enum pattern: `{"enum": [value, ...]}`
         Titled enums are handled separately via dict-based syntax in ctx.elicit().
         """
         # Get the base schema from parent - always use simple enum pattern
@@ -134,12 +134,12 @@ def parse_elicit_response_type(response_type: Any) -> ElicitConfig:
 
     Supports multiple syntaxes:
     - None: Empty object schema, expect empty response
-    - dict: {"low": {"title": "..."}} -> single-select titled enum
+    - dict: `{"low": {"title": "..."}}` -> single-select titled enum
     - list patterns:
-        - [["a", "b"]] -> multi-select untitled
-        - [{"low": {...}}] -> multi-select titled
-        - ["a", "b"] -> single-select untitled
-    - list[X] type annotation: multi-select with type
+        - `[["a", "b"]]` -> multi-select untitled
+        - `[{"low": {...}}]` -> multi-select titled
+        - `["a", "b"]` -> single-select untitled
+    - `list[X]` type annotation: multi-select with type
     - Scalar types (bool, int, float, str, Literal, Enum): single value
     - Other types (dataclass, BaseModel): use directly
     """
@@ -229,11 +229,13 @@ def _parse_list_syntax(lst: list[Any]) -> ElicitConfig:
 
     # ["a", "b", "c"] -> single-select untitled
     if lst and all(isinstance(item, str) for item in lst):
-        choice_literal = Literal[tuple(lst)]  # type: ignore[valid-type]
+        # Construct Literal type from tuple - use cast since we can't construct Literal dynamically
+        # but we know the values are all strings
+        choice_literal: type[Any] = cast(type[Any], Literal[tuple(lst)])  # type: ignore[valid-type]
         wrapped = ScalarElicitationType[choice_literal]  # type: ignore[valid-type]
         return ElicitConfig(
-            schema=get_elicitation_schema(wrapped),  # type: ignore[arg-type]
-            response_type=wrapped,  # type: ignore[assignment]
+            schema=get_elicitation_schema(wrapped),
+            response_type=wrapped,
             is_raw=False,
         )
 
@@ -242,20 +244,20 @@ def _parse_list_syntax(lst: list[Any]) -> ElicitConfig:
 
 def _parse_generic_list(response_type: Any) -> ElicitConfig:
     """Parse list[X] type annotation -> multi-select."""
-    wrapped = ScalarElicitationType[response_type]  # type: ignore[valid-type]
+    wrapped = ScalarElicitationType[response_type]
     return ElicitConfig(
-        schema=get_elicitation_schema(wrapped),  # type: ignore[arg-type]
-        response_type=wrapped,  # type: ignore[assignment]
+        schema=get_elicitation_schema(wrapped),
+        response_type=wrapped,
         is_raw=False,
     )
 
 
 def _parse_scalar_type(response_type: Any) -> ElicitConfig:
     """Parse scalar types (bool, int, float, str, Literal, Enum)."""
-    wrapped = ScalarElicitationType[response_type]  # type: ignore[valid-type]
+    wrapped = ScalarElicitationType[response_type]
     return ElicitConfig(
-        schema=get_elicitation_schema(wrapped),  # type: ignore[arg-type]
-        response_type=wrapped,  # type: ignore[assignment]
+        schema=get_elicitation_schema(wrapped),
+        response_type=wrapped,
         is_raw=False,
     )
 

fastmcp/server/event_store.py

@@ -16,14 +16,14 @@ from key_value.aio.stores.memory import MemoryStore
 from mcp.server.streamable_http import EventCallback, EventId, EventMessage, StreamId
 from mcp.server.streamable_http import EventStore as SDKEventStore
 from mcp.types import JSONRPCMessage
-from pydantic import BaseModel
 
 from fastmcp.utilities.logging import get_logger
+from fastmcp.utilities.types import FastMCPBaseModel
 
 logger = get_logger(__name__)
 
 
-class EventEntry(BaseModel):
+class EventEntry(FastMCPBaseModel):
     """Stored event entry."""
 
     event_id: str
@@ -31,7 +31,7 @@ class EventEntry(BaseModel):
     message: dict | None  # JSONRPCMessage serialized to dict
 
 
-class StreamEventList(BaseModel):
+class StreamEventList(FastMCPBaseModel):
     """List of event IDs for a stream."""
 
     event_ids: list[str]

fastmcp/server/http.py

@@ -61,7 +61,7 @@ class StreamableHTTPASGIApp:
                 raise
 
 
-_current_http_request: ContextVar[Request | None] = ContextVar(  # type: ignore[assignment]
+_current_http_request: ContextVar[Request | None] = ContextVar(
     "http_request",
     default=None,
 )
@@ -84,7 +84,7 @@ def set_http_request(request: Request) -> Generator[Request, None, None]:
 
 class RequestContextMiddleware:
     """
-    Middleware that stores each request in a ContextVar
+    Middleware that stores each request in a ContextVar and sets transport type.
     """
 
     def __init__(self, app):
@@ -92,8 +92,17 @@ class RequestContextMiddleware:
 
     async def __call__(self, scope, receive, send):
         if scope["type"] == "http":
-            with set_http_request(Request(scope)):
-                await self.app(scope, receive, send)
+            from fastmcp.server.context import reset_transport, set_transport
+
+            # Get transport type from app state (set during app creation)
+            transport_type = getattr(scope["app"].state, "transport_type", None)
+            transport_token = set_transport(transport_type) if transport_type else None
+            try:
+                with set_http_request(Request(scope)):
+                    await self.app(scope, receive, send)
+            finally:
+                if transport_token is not None:
+                    reset_transport(transport_token)
         else:
             await self.app(scope, receive, send)
 
@@ -209,7 +218,7 @@ def create_sse_app(
     else:
         # No auth required
         async def sse_endpoint(request: Request) -> Response:
-            return await handle_sse(request.scope, request.receive, request._send)  # type: ignore[reportPrivateUsage]
+            return await handle_sse(request.scope, request.receive, request._send)
 
         server_routes.append(
             Route(
@@ -249,6 +258,7 @@ def create_sse_app(
     # Store the FastMCP server instance on the Starlette app state
     app.state.fastmcp_server = server
     app.state.path = sse_path
+    app.state.transport_type = "sse"
 
     return app
 
@@ -360,7 +370,7 @@ def create_streamable_http_app(
     )
     # Store the FastMCP server instance on the Starlette app state
     app.state.fastmcp_server = server
-
     app.state.path = streamable_http_path
+    app.state.transport_type = "streamable-http"
 
     return app

fastmcp/server/lifespan.py

@@ -0,0 +1,198 @@
+"""Composable lifespans for FastMCP servers.
+
+This module provides a `@lifespan` decorator for creating composable server lifespans
+that can be combined using the `|` operator.
+
+Example:
+    ```python
+    from fastmcp import FastMCP
+    from fastmcp.server.lifespan import lifespan
+
+    @lifespan
+    async def db_lifespan(server):
+        conn = await connect_db()
+        yield {"db": conn}
+        await conn.close()
+
+    @lifespan
+    async def cache_lifespan(server):
+        cache = await connect_cache()
+        yield {"cache": cache}
+        await cache.close()
+
+    mcp = FastMCP("server", lifespan=db_lifespan | cache_lifespan)
+    ```
+
+To compose with existing `@asynccontextmanager` lifespans, wrap them explicitly:
+
+    ```python
+    from contextlib import asynccontextmanager
+    from fastmcp.server.lifespan import lifespan, ContextManagerLifespan
+
+    @asynccontextmanager
+    async def legacy_lifespan(server):
+        yield {"legacy": True}
+
+    @lifespan
+    async def new_lifespan(server):
+        yield {"new": True}
+
+    # Wrap the legacy lifespan explicitly
+    combined = ContextManagerLifespan(legacy_lifespan) | new_lifespan
+    ```
+"""
+
+from __future__ import annotations
+
+from collections.abc import AsyncIterator, Callable
+from contextlib import AbstractAsyncContextManager, asynccontextmanager
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+    from fastmcp.server.server import FastMCP
+
+
+LifespanFn = Callable[["FastMCP[Any]"], AsyncIterator[dict[str, Any] | None]]
+LifespanContextManagerFn = Callable[
+    ["FastMCP[Any]"], AbstractAsyncContextManager[dict[str, Any] | None]
+]
+
+
+class Lifespan:
+    """Composable lifespan wrapper.
+
+    Wraps an async generator function and enables composition via the `|` operator.
+    The wrapped function should yield a dict that becomes part of the lifespan context.
+    """
+
+    def __init__(self, fn: LifespanFn) -> None:
+        """Initialize a Lifespan wrapper.
+
+        Args:
+            fn: An async generator function that takes a FastMCP server and yields
+                a dict for the lifespan context.
+        """
+        self._fn = fn
+
+    @asynccontextmanager
+    async def __call__(self, server: FastMCP[Any]) -> AsyncIterator[dict[str, Any]]:
+        """Execute the lifespan as an async context manager.
+
+        Args:
+            server: The FastMCP server instance.
+
+        Yields:
+            The lifespan context dict.
+        """
+        async with asynccontextmanager(self._fn)(server) as result:
+            yield result if result is not None else {}
+
+    def __or__(self, other: Lifespan) -> ComposedLifespan:
+        """Compose with another lifespan using the | operator.
+
+        Args:
+            other: Another Lifespan instance.
+
+        Returns:
+            A ComposedLifespan that runs both lifespans.
+
+        Raises:
+            TypeError: If other is not a Lifespan instance.
+        """
+        if not isinstance(other, Lifespan):
+            raise TypeError(
+                f"Cannot compose Lifespan with {type(other).__name__}. "
+                f"Use @lifespan decorator or wrap with ContextManagerLifespan()."
+            )
+        return ComposedLifespan(self, other)
+
+
+class ContextManagerLifespan(Lifespan):
+    """Lifespan wrapper for already-wrapped context manager functions.
+
+    Use this for functions already decorated with @asynccontextmanager.
+    """
+
+    _fn: LifespanContextManagerFn  # Override type for this subclass
+
+    def __init__(self, fn: LifespanContextManagerFn) -> None:
+        """Initialize with a context manager factory function."""
+        self._fn = fn
+
+    @asynccontextmanager
+    async def __call__(self, server: FastMCP[Any]) -> AsyncIterator[dict[str, Any]]:
+        """Execute the lifespan as an async context manager.
+
+        Args:
+            server: The FastMCP server instance.
+
+        Yields:
+            The lifespan context dict.
+        """
+        # self._fn is already a context manager factory, just call it
+        async with self._fn(server) as result:
+            yield result if result is not None else {}
+
+
+class ComposedLifespan(Lifespan):
+    """Two lifespans composed together.
+
+    Enters the left lifespan first, then the right. Exits in reverse order.
+    Results are shallow-merged into a single dict.
+    """
+
+    def __init__(self, left: Lifespan, right: Lifespan) -> None:
+        """Initialize a composed lifespan.
+
+        Args:
+            left: The first lifespan to enter.
+            right: The second lifespan to enter.
+        """
+        # Don't call super().__init__ since we override __call__
+        self._left = left
+        self._right = right
+
+    @asynccontextmanager
+    async def __call__(self, server: FastMCP[Any]) -> AsyncIterator[dict[str, Any]]:
+        """Execute both lifespans, merging their results.
+
+        Args:
+            server: The FastMCP server instance.
+
+        Yields:
+            The merged lifespan context dict from both lifespans.
+        """
+        async with (
+            self._left(server) as left_result,
+            self._right(server) as right_result,
+        ):
+            yield {**left_result, **right_result}
+
+
+def lifespan(fn: LifespanFn) -> Lifespan:
+    """Decorator to create a composable lifespan.
+
+    Use this decorator on an async generator function to make it composable
+    with other lifespans using the `|` operator.
+
+    Example:
+        ```python
+        @lifespan
+        async def my_lifespan(server):
+            # Setup
+            resource = await create_resource()
+            yield {"resource": resource}
+            # Teardown
+            await resource.close()
+
+        mcp = FastMCP("server", lifespan=my_lifespan | other_lifespan)
+        ```
+
+    Args:
+        fn: An async generator function that takes a FastMCP server and yields
+            a dict for the lifespan context.
+
+    Returns:
+        A composable Lifespan wrapper.
+    """
+    return Lifespan(fn)

fastmcp/server/low_level.py

@@ -1,6 +1,7 @@
 from __future__ import annotations
 
 import weakref
+from collections.abc import Awaitable, Callable
 from contextlib import AsyncExitStack
 from typing import TYPE_CHECKING, Any
 
@@ -21,6 +22,7 @@ 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 pydantic import AnyUrl
 
 from fastmcp.utilities.logging import get_logger
 
@@ -94,7 +96,7 @@ class MiddlewareServerSession(ServerSession):
                 return None
 
             async with fastmcp.server.context.Context(
-                fastmcp=self.fastmcp
+                fastmcp=self.fastmcp, session=self
             ) as fastmcp_ctx:
                 # Create the middleware context.
                 mw_context = MiddlewareContext(
@@ -106,7 +108,7 @@ class MiddlewareServerSession(ServerSession):
                 )
 
                 try:
-                    return await self.fastmcp._apply_middleware(
+                    return await self.fastmcp._run_middleware(
                         mw_context, call_original_handler
                     )
                 except McpError as e:
@@ -223,3 +225,91 @@ class LowLevelServer(_Server[LifespanResultT, RequestT]):
                         lifespan_context,
                         raise_exceptions,
                     )
+
+    def read_resource(
+        self,
+    ) -> Callable[
+        [
+            Callable[
+                [AnyUrl],
+                Awaitable[mcp.types.ReadResourceResult | mcp.types.CreateTaskResult],
+            ]
+        ],
+        Callable[
+            [AnyUrl],
+            Awaitable[mcp.types.ReadResourceResult | mcp.types.CreateTaskResult],
+        ],
+    ]:
+        """
+        Decorator for registering a read_resource handler with CreateTaskResult support.
+
+        The MCP SDK's read_resource decorator does not support returning CreateTaskResult
+        for background task execution. This decorator wraps the result in ServerResult.
+
+        This decorator can be removed once the MCP SDK adds native CreateTaskResult support
+        for resources.
+        """
+
+        def decorator(
+            func: Callable[
+                [AnyUrl],
+                Awaitable[mcp.types.ReadResourceResult | mcp.types.CreateTaskResult],
+            ],
+        ) -> Callable[
+            [AnyUrl],
+            Awaitable[mcp.types.ReadResourceResult | mcp.types.CreateTaskResult],
+        ]:
+            async def handler(
+                req: mcp.types.ReadResourceRequest,
+            ) -> mcp.types.ServerResult:
+                result = await func(req.params.uri)
+                return mcp.types.ServerResult(result)
+
+            self.request_handlers[mcp.types.ReadResourceRequest] = handler
+            return func
+
+        return decorator
+
+    def get_prompt(
+        self,
+    ) -> Callable[
+        [
+            Callable[
+                [str, dict[str, Any] | None],
+                Awaitable[mcp.types.GetPromptResult | mcp.types.CreateTaskResult],
+            ]
+        ],
+        Callable[
+            [str, dict[str, Any] | None],
+            Awaitable[mcp.types.GetPromptResult | mcp.types.CreateTaskResult],
+        ],
+    ]:
+        """
+        Decorator for registering a get_prompt handler with CreateTaskResult support.
+
+        The MCP SDK's get_prompt decorator does not support returning CreateTaskResult
+        for background task execution. This decorator wraps the result in ServerResult.
+
+        This decorator can be removed once the MCP SDK adds native CreateTaskResult support
+        for prompts.
+        """
+
+        def decorator(
+            func: Callable[
+                [str, dict[str, Any] | None],
+                Awaitable[mcp.types.GetPromptResult | mcp.types.CreateTaskResult],
+            ],
+        ) -> Callable[
+            [str, dict[str, Any] | None],
+            Awaitable[mcp.types.GetPromptResult | mcp.types.CreateTaskResult],
+        ]:
+            async def handler(
+                req: mcp.types.GetPromptRequest,
+            ) -> mcp.types.ServerResult:
+                result = await func(req.params.name, req.params.arguments)
+                return mcp.types.ServerResult(result)
+
+            self.request_handlers[mcp.types.GetPromptRequest] = handler
+            return func
+
+        return decorator

fastmcp/server/middleware/__init__.py

@@ -1,11 +1,15 @@
+from .authorization import AuthMiddleware
 from .middleware import (
+    CallNext,
     Middleware,
     MiddlewareContext,
-    CallNext,
 )
+from .ping import PingMiddleware
 
 __all__ = [
+    "AuthMiddleware",
     "CallNext",
     "Middleware",
     "MiddlewareContext",
+    "PingMiddleware",
 ]