fastmcp 2.11.2__py3-none-any.whl → 2.12.0__py3-none-any.whl

fastmcp/server/auth/redirect_validation.py

@@ -0,0 +1,65 @@
+"""Utilities for validating client redirect URIs in OAuth flows."""
+
+import fnmatch
+
+from pydantic import AnyUrl
+
+
+def matches_allowed_pattern(uri: str, pattern: str) -> bool:
+    """Check if a URI matches an allowed pattern with wildcard support.
+
+    Patterns support * wildcard matching:
+    - http://localhost:* matches any localhost port
+    - http://127.0.0.1:* matches any 127.0.0.1 port
+    - https://*.example.com/* matches any subdomain of example.com
+    - https://app.example.com/auth/* matches any path under /auth/
+
+    Args:
+        uri: The redirect URI to validate
+        pattern: The allowed pattern (may contain wildcards)
+
+    Returns:
+        True if the URI matches the pattern
+    """
+    # Use fnmatch for wildcard matching
+    return fnmatch.fnmatch(uri, pattern)
+
+
+def validate_redirect_uri(
+    redirect_uri: str | AnyUrl | None,
+    allowed_patterns: list[str] | None,
+) -> bool:
+    """Validate a redirect URI against allowed patterns.
+
+    Args:
+        redirect_uri: The redirect URI to validate
+        allowed_patterns: List of allowed patterns. If None, all URIs are allowed (for DCR compatibility).
+                         If empty list, no URIs are allowed.
+                         To restrict to localhost only, explicitly pass DEFAULT_LOCALHOST_PATTERNS.
+
+    Returns:
+        True if the redirect URI is allowed
+    """
+    if redirect_uri is None:
+        return True  # None is allowed (will use client's default)
+
+    uri_str = str(redirect_uri)
+
+    # If no patterns specified, allow all for DCR compatibility
+    # (clients need to dynamically register with their own redirect URIs)
+    if allowed_patterns is None:
+        return True
+
+    # Check if URI matches any allowed pattern
+    for pattern in allowed_patterns:
+        if matches_allowed_pattern(uri_str, pattern):
+            return True
+
+    return False
+
+
+# Default patterns for localhost-only validation
+DEFAULT_LOCALHOST_PATTERNS = [
+    "http://localhost:*",
+    "http://127.0.0.1:*",
+]

fastmcp/server/auth/registry.py

@@ -6,7 +6,7 @@ from collections.abc import Callable
 from typing import TYPE_CHECKING, TypeVar
 
 if TYPE_CHECKING:
-    from fastmcp.server.auth.auth import AuthProvider
+    from fastmcp.server.auth import AuthProvider
 
 # Type variable for auth providers
 T = TypeVar("T", bound="AuthProvider")

fastmcp/server/context.py

@@ -2,7 +2,9 @@ from __future__ import annotations
 
 import asyncio
 import copy
+import inspect
 import warnings
+import weakref
 from collections.abc import Generator, Mapping
 from contextlib import contextmanager
 from contextvars import ContextVar, Token
@@ -15,15 +17,18 @@ 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 (
+    ClientCapabilities,
     ContentBlock,
     CreateMessageResult,
     IncludeContext,
     ModelHint,
     ModelPreferences,
     Root,
+    SamplingCapability,
     SamplingMessage,
     TextContent,
 )
+from mcp.types import CreateMessageRequestParams as SamplingParams
 from pydantic.networks import AnyUrl
 from starlette.requests import Request
 
@@ -43,7 +48,7 @@ from fastmcp.utilities.types import get_cached_typeadapter
 logger = get_logger(__name__)
 
 T = TypeVar("T")
-_current_context: ContextVar[Context | None] = ContextVar("context", default=None)
+_current_context: ContextVar[Context | None] = ContextVar("context", default=None)  # type: ignore[assignment]
 _flush_lock = asyncio.Lock()
 
 
@@ -115,11 +120,19 @@ class Context:
     """
 
     def __init__(self, fastmcp: FastMCP):
-        self.fastmcp = fastmcp
+        self._fastmcp: weakref.ref[FastMCP] = weakref.ref(fastmcp)
         self._tokens: list[Token] = []
         self._notification_queue: set[str] = set()  # Dedupe notifications
         self._state: dict[str, Any] = {}
 
+    @property
+    def fastmcp(self) -> FastMCP:
+        """Get the FastMCP instance."""
+        fastmcp = self._fastmcp()
+        if fastmcp is None:
+            raise RuntimeError("FastMCP instance is no longer available")
+        return fastmcp
+
     async def __aenter__(self) -> Context:
         """Enter the context manager and set this context as the current context."""
         parent_context = _current_context.get(None)
@@ -188,7 +201,8 @@ class Context:
         Returns:
             The resource content as either text or bytes
         """
-        assert self.fastmcp is not None, "Context is not available outside of a request"
+        if self.fastmcp is None:
+            raise ValueError("Context is not available outside of a request")
         return await self.fastmcp._mcp_read_resource(uri)
 
     async def log(
@@ -376,13 +390,50 @@ class Context:
                 for m in messages
             ]
 
+        should_fallback = (
+            self.fastmcp.sampling_handler_behavior == "fallback"
+            and not self.session.check_client_capability(
+                capability=ClientCapabilities(sampling=SamplingCapability())
+            )
+        )
+
+        if self.fastmcp.sampling_handler_behavior == "always" or should_fallback:
+            if self.fastmcp.sampling_handler is None:
+                raise ValueError("Client does not support sampling")
+
+            create_message_result = self.fastmcp.sampling_handler(
+                sampling_messages,
+                SamplingParams(
+                    systemPrompt=system_prompt,
+                    messages=sampling_messages,
+                    temperature=temperature,
+                    maxTokens=max_tokens,
+                    modelPreferences=_parse_model_preferences(model_preferences),
+                ),
+                self.request_context,
+            )
+
+            if inspect.isawaitable(create_message_result):
+                create_message_result = await create_message_result
+
+            if isinstance(create_message_result, str):
+                return TextContent(text=create_message_result, type="text")
+
+            if isinstance(create_message_result, CreateMessageResult):
+                return create_message_result.content
+
+            else:
+                raise ValueError(
+                    f"Unexpected sampling handler result: {create_message_result}"
+                )
+
         result: CreateMessageResult = await self.session.create_message(
             messages=sampling_messages,
             system_prompt=system_prompt,
             include_context=include_context,
             temperature=temperature,
             max_tokens=max_tokens,
-            model_preferences=self._parse_model_preferences(model_preferences),
+            model_preferences=_parse_model_preferences(model_preferences),
             related_request_id=self.request_id,
         )
 
@@ -497,7 +548,7 @@ class Context:
                 if isinstance(validated_data, ScalarElicitationType):
                     return AcceptedElicitation[T](data=validated_data.value)
                 else:
-                    return AcceptedElicitation[T](data=validated_data)
+                    return AcceptedElicitation[T](data=cast(T, validated_data))
             elif result.content:
                 raise ValueError(
                     "Elicitation expected an empty response, but received: "
@@ -582,44 +633,43 @@ class Context:
                 # Don't let notification failures break the request
                 pass
 
-    def _parse_model_preferences(
-        self, model_preferences: ModelPreferences | str | list[str] | None
-    ) -> ModelPreferences | None:
-        """
-        Validates and converts user input for model_preferences into a ModelPreferences object.
 
-        Args:
-            model_preferences (ModelPreferences | str | list[str] | None):
-                The model preferences to use. Accepts:
-                - ModelPreferences (returns as-is)
-                - str (single model hint)
-                - list[str] (multiple model hints)
-                - None (no preferences)
+def _parse_model_preferences(
+    model_preferences: ModelPreferences | str | list[str] | None,
+) -> ModelPreferences | None:
+    """
+    Validates and converts user input for model_preferences into a ModelPreferences object.
 
-        Returns:
-            ModelPreferences | None: The parsed ModelPreferences object, or None if not provided.
+    Args:
+        model_preferences (ModelPreferences | str | list[str] | None):
+            The model preferences to use. Accepts:
+            - ModelPreferences (returns as-is)
+            - str (single model hint)
+            - list[str] (multiple model hints)
+            - None (no preferences)
 
-        Raises:
-            ValueError: If the input is not a supported type or contains invalid values.
-        """
-        if model_preferences is None:
-            return None
-        elif isinstance(model_preferences, ModelPreferences):
-            return model_preferences
-        elif isinstance(model_preferences, str):
-            # Single model hint
-            return ModelPreferences(hints=[ModelHint(name=model_preferences)])
-        elif isinstance(model_preferences, list):
-            # List of model hints (strings)
-            if not all(isinstance(h, str) for h in model_preferences):
-                raise ValueError(
-                    "All elements of model_preferences list must be"
-                    " strings (model name hints)."
-                )
-            return ModelPreferences(
-                hints=[ModelHint(name=h) for h in model_preferences]
-            )
-        else:
+    Returns:
+        ModelPreferences | None: The parsed ModelPreferences object, or None if not provided.
+
+    Raises:
+        ValueError: If the input is not a supported type or contains invalid values.
+    """
+    if model_preferences is None:
+        return None
+    elif isinstance(model_preferences, ModelPreferences):
+        return model_preferences
+    elif isinstance(model_preferences, str):
+        # Single model hint
+        return ModelPreferences(hints=[ModelHint(name=model_preferences)])
+    elif isinstance(model_preferences, list):
+        # List of model hints (strings)
+        if not all(isinstance(h, str) for h in model_preferences):
             raise ValueError(
-                "model_preferences must be one of: ModelPreferences, str, list[str], or None."
+                "All elements of model_preferences list must be"
+                " strings (model name hints)."
             )
+        return ModelPreferences(hints=[ModelHint(name=h) for h in model_preferences])
+    else:
+        raise ValueError(
+            "model_preferences must be one of: ModelPreferences, str, list[str], or None."
+        )

fastmcp/server/dependencies.py

@@ -2,10 +2,13 @@ from __future__ import annotations
 
 from typing import TYPE_CHECKING, ParamSpec, TypeVar
 
-from mcp.server.auth.middleware.auth_context import get_access_token
-from mcp.server.auth.provider import AccessToken
+from mcp.server.auth.middleware.auth_context import (
+    get_access_token as _sdk_get_access_token,
+)
 from starlette.requests import Request
 
+from fastmcp.server.auth import AccessToken
+
 if TYPE_CHECKING:
     from fastmcp.server.context import Context
 
@@ -94,3 +97,30 @@ def get_http_headers(include_all: bool = False) -> dict[str, str]:
         return headers
     except RuntimeError:
         return {}
+
+
+# --- Access Token ---
+
+
+def get_access_token() -> AccessToken | None:
+    """
+    Get the FastMCP access token from the current context.
+
+    Returns:
+        The access token if an authenticated user is available, None otherwise.
+    """
+    #
+    obj = _sdk_get_access_token()
+    if obj is None or isinstance(obj, AccessToken):
+        return obj
+
+    # 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 it fails, it will raise a TypeError
+    try:
+        return AccessToken(**obj.model_dump())
+    except Exception as e:
+        raise TypeError(
+            f"Expected fastmcp.server.auth.auth.AccessToken, got {type(obj).__name__}. "
+            "Ensure the SDK is using the correct AccessToken type."
+        ) from e

fastmcp/server/elicitation.py

@@ -8,6 +8,8 @@ from mcp.server.elicitation import (
     DeclinedElicitation,
 )
 from pydantic import BaseModel
+from pydantic.json_schema import GenerateJsonSchema, JsonSchemaValue
+from pydantic_core import core_schema
 
 from fastmcp.utilities.json_schema import compress_schema
 from fastmcp.utilities.logging import get_logger
@@ -26,6 +28,60 @@ logger = get_logger(__name__)
 T = TypeVar("T")
 
 
+class ElicitationJsonSchema(GenerateJsonSchema):
+    """Custom JSON schema generator for MCP elicitation that always inlines enums.
+
+    MCP elicitation requires inline enum schemas without $ref/$defs references.
+    This generator ensures enums are always generated inline for compatibility.
+    Optionally adds enumNames for better UI display when available.
+    """
+
+    def generate_inner(self, schema: core_schema.CoreSchema) -> JsonSchemaValue:
+        """Override to prevent ref generation for enums."""
+        # For enum schemas, bypass the ref mechanism entirely
+        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)
+        # For all other types, use the default implementation
+        return super().generate_inner(schema)
+
+    def enum_schema(self, schema: core_schema.EnumSchema) -> JsonSchemaValue:
+        """Generate inline enum schema with optional enumNames for better UI.
+
+        If enum members have a _display_name_ attribute or custom __str__,
+        we'll include enumNames for better UI representation.
+        """
+        # Get the base schema from parent
+        result = super().enum_schema(schema)
+
+        # Try to add enumNames if the enum has display-friendly names
+        enum_cls = schema.get("cls")
+        if enum_cls:
+            members = schema.get("members", [])
+            enum_names = []
+            has_custom_names = False
+
+            for member in members:
+                # Check if member has a custom display name attribute
+                if hasattr(member, "_display_name_"):
+                    enum_names.append(member._display_name_)
+                    has_custom_names = True
+                # Or use the member name with better formatting
+                else:
+                    # Convert SNAKE_CASE to Title Case for display
+                    display_name = member.name.replace("_", " ").title()
+                    enum_names.append(display_name)
+                    if display_name != member.value:
+                        has_custom_names = True
+
+            # Only add enumNames if they differ from the values
+            if has_custom_names:
+                result["enumNames"] = enum_names
+
+        return result
+
+
 # we can't use the low-level AcceptedElicitation because it only works with BaseModels
 class AcceptedElicitation(BaseModel, Generic[T]):
     """Result when user accepts the elicitation."""
@@ -46,7 +102,10 @@ def get_elicitation_schema(response_type: type[T]) -> dict[str, Any]:
         response_type: The type of the response
     """
 
-    schema = get_cached_typeadapter(response_type).json_schema()
+    # Use custom schema generator that inlines enums for MCP compatibility
+    schema = get_cached_typeadapter(response_type).json_schema(
+        schema_generator=ElicitationJsonSchema
+    )
     schema = compress_schema(schema)
 
     # Validate the schema to ensure it follows MCP elicitation requirements

fastmcp/server/http.py

@@ -23,7 +23,7 @@ from starlette.responses import Response
 from starlette.routing import BaseRoute, Mount, Route
 from starlette.types import Lifespan, Receive, Scope, Send
 
-from fastmcp.server.auth.auth import AuthProvider
+from fastmcp.server.auth import AuthProvider
 from fastmcp.utilities.logging import get_logger
 
 if TYPE_CHECKING:
@@ -32,7 +32,39 @@ if TYPE_CHECKING:
 logger = get_logger(__name__)
 
 
-_current_http_request: ContextVar[Request | None] = ContextVar(
+class StreamableHTTPASGIApp:
+    """ASGI application wrapper for Streamable HTTP server transport."""
+
+    def __init__(self, session_manager):
+        self.session_manager = session_manager
+
+    async def __call__(self, scope: Scope, receive: Receive, send: Send) -> None:
+        try:
+            await self.session_manager.handle_request(scope, receive, send)
+        except RuntimeError as e:
+            if str(e) == "Task group is not initialized. Make sure to use run().":
+                logger.error(
+                    f"Original RuntimeError from mcp library: {e}", exc_info=True
+                )
+                new_error_message = (
+                    "FastMCP's StreamableHTTPSessionManager task group was not initialized. "
+                    "This commonly occurs when the FastMCP application's lifespan is not "
+                    "passed to the parent ASGI application (e.g., FastAPI or Starlette). "
+                    "Please ensure you are setting `lifespan=mcp_app.lifespan` in your "
+                    "parent app's constructor, where `mcp_app` is the application instance "
+                    "returned by `fastmcp_instance.http_app()`. \\n"
+                    "For more details, see the FastMCP ASGI integration documentation: "
+                    "https://gofastmcp.com/deployment/asgi"
+                )
+                # Raise a new RuntimeError that includes the original error's message
+                # for full context, but leads with the more helpful guidance.
+                raise RuntimeError(f"{new_error_message}\\nOriginal error: {e}") from e
+            else:
+                # Re-raise other RuntimeErrors if they don't match the specific message
+                raise
+
+
+_current_http_request: ContextVar[Request | None] = ContextVar(  # type: ignore[assignment]
     "http_request",
     default=None,
 )
@@ -40,7 +72,7 @@ _current_http_request: ContextVar[Request | None] = ContextVar(
 
 class StarletteWithLifespan(Starlette):
     @property
-    def lifespan(self) -> Lifespan:
+    def lifespan(self) -> Lifespan[Starlette]:
         return self.router.lifespan_context
 
 
@@ -197,7 +229,7 @@ def create_sse_app(
     # Add custom routes with lowest precedence
     if routes:
         server_routes.extend(routes)
-    server_routes.extend(server._additional_http_routes)
+    server_routes.extend(server._get_additional_http_routes())
 
     # Add middleware
     if middleware:
@@ -254,33 +286,8 @@ def create_streamable_http_app(
         stateless=stateless_http,
     )
 
-    # Create the ASGI handler
-    async def handle_streamable_http(
-        scope: Scope, receive: Receive, send: Send
-    ) -> None:
-        try:
-            await session_manager.handle_request(scope, receive, send)
-        except RuntimeError as e:
-            if str(e) == "Task group is not initialized. Make sure to use run().":
-                logger.error(
-                    f"Original RuntimeError from mcp library: {e}", exc_info=True
-                )
-                new_error_message = (
-                    "FastMCP's StreamableHTTPSessionManager task group was not initialized. "
-                    "This commonly occurs when the FastMCP application's lifespan is not "
-                    "passed to the parent ASGI application (e.g., FastAPI or Starlette). "
-                    "Please ensure you are setting `lifespan=mcp_app.lifespan` in your "
-                    "parent app's constructor, where `mcp_app` is the application instance "
-                    "returned by `fastmcp_instance.http_app()`. \\n"
-                    "For more details, see the FastMCP ASGI integration documentation: "
-                    "https://gofastmcp.com/deployment/asgi"
-                )
-                # Raise a new RuntimeError that includes the original error's message
-                # for full context, but leads with the more helpful guidance.
-                raise RuntimeError(f"{new_error_message}\\nOriginal error: {e}") from e
-            else:
-                # Re-raise other RuntimeErrors if they don't match the specific message
-                raise
+    # Create the ASGI app wrapper
+    streamable_http_app = StreamableHTTPASGIApp(session_manager)
 
     # Add StreamableHTTP routes with or without auth
     if auth:
@@ -305,26 +312,26 @@ def create_streamable_http_app(
 
         # Auth is enabled, wrap endpoint with RequireAuthMiddleware
         server_routes.append(
-            Mount(
+            Route(
                 streamable_http_path,
-                app=RequireAuthMiddleware(
-                    handle_streamable_http, required_scopes, resource_metadata_url
+                endpoint=RequireAuthMiddleware(
+                    streamable_http_app, required_scopes, resource_metadata_url
                 ),
             )
         )
     else:
         # No auth required
         server_routes.append(
-            Mount(
+            Route(
                 streamable_http_path,
-                app=handle_streamable_http,
+                endpoint=streamable_http_app,
             )
         )
 
     # Add custom routes with lowest precedence
     if routes:
         server_routes.extend(routes)
-    server_routes.extend(server._additional_http_routes)
+    server_routes.extend(server._get_additional_http_routes())
 
     # Add middleware
     if middleware: