fastmcp 2.11.3__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/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/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

@@ -64,7 +64,7 @@ class StreamableHTTPASGIApp:
                 raise
 
 
-_current_http_request: ContextVar[Request | None] = ContextVar(
+_current_http_request: ContextVar[Request | None] = ContextVar(  # type: ignore[assignment]
     "http_request",
     default=None,
 )
@@ -229,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:
@@ -331,7 +331,7 @@ def create_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:

fastmcp/server/middleware/logging.py

@@ -2,11 +2,20 @@
 
 import json
 import logging
+from collections.abc import Callable
+from logging import Logger
 from typing import Any
 
+import pydantic_core
+
 from .middleware import CallNext, Middleware, MiddlewareContext
 
 
+def default_serializer(data: Any) -> str:
+    """The default serializer for Payloads in the logging middleware."""
+    return pydantic_core.to_json(data, fallback=str).decode()
+
+
 class LoggingMiddleware(Middleware):
     """Middleware that provides comprehensive request and response logging.
 
@@ -33,6 +42,7 @@ class LoggingMiddleware(Middleware):
         include_payloads: bool = False,
         max_payload_length: int = 1000,
         methods: list[str] | None = None,
+        payload_serializer: Callable[[Any], str] | None = None,
     ):
         """Initialize logging middleware.
 
@@ -43,13 +53,14 @@ class LoggingMiddleware(Middleware):
             max_payload_length: Maximum length of payload to log (prevents huge logs)
             methods: List of methods to log. If None, logs all methods.
         """
-        self.logger = logger or logging.getLogger("fastmcp.requests")
-        self.log_level = log_level
-        self.include_payloads = include_payloads
-        self.max_payload_length = max_payload_length
-        self.methods = methods
-
-    def _format_message(self, context: MiddlewareContext) -> str:
+        self.logger: Logger = logger or logging.getLogger("fastmcp.requests")
+        self.log_level: int = log_level
+        self.include_payloads: bool = include_payloads
+        self.max_payload_length: int = max_payload_length
+        self.methods: list[str] | None = methods
+        self.payload_serializer: Callable[[Any], str] | None = payload_serializer
+
+    def _format_message(self, context: MiddlewareContext[Any]) -> str:
         """Format a message for logging."""
         parts = [
             f"source={context.source}",
@@ -57,18 +68,29 @@ class LoggingMiddleware(Middleware):
             f"method={context.method or 'unknown'}",
         ]
 
-        if self.include_payloads and hasattr(context.message, "__dict__"):
-            try:
-                payload = json.dumps(context.message.__dict__, default=str)
-                if len(payload) > self.max_payload_length:
-                    payload = payload[: self.max_payload_length] + "..."
-                parts.append(f"payload={payload}")
-            except (TypeError, ValueError):
-                parts.append("payload=<non-serializable>")
+        if self.include_payloads:
+            payload: str
 
+            if not self.payload_serializer:
+                payload = default_serializer(context.message)
+            else:
+                try:
+                    payload = self.payload_serializer(context.message)
+                except Exception as e:
+                    self.logger.warning(
+                        f"Failed {e} to serialize payload: {context.type} {context.method} {context.source}."
+                    )
+                    payload = default_serializer(context.message)
+
+            if len(payload) > self.max_payload_length:
+                payload = payload[: self.max_payload_length] + "..."
+
+            parts.append(f"payload={payload}")
         return " ".join(parts)
 
-    async def on_message(self, context: MiddlewareContext, call_next: CallNext) -> Any:
+    async def on_message(
+        self, context: MiddlewareContext[Any], call_next: CallNext[Any, Any]
+    ) -> Any:
         """Log all messages."""
         message_info = self._format_message(context)
         if self.methods and context.method not in self.methods:
@@ -111,6 +133,7 @@ class StructuredLoggingMiddleware(Middleware):
         log_level: int = logging.INFO,
         include_payloads: bool = False,
         methods: list[str] | None = None,
+        payload_serializer: Callable[[Any], str] | None = None,
     ):
         """Initialize structured logging middleware.
 
@@ -119,15 +142,18 @@ class StructuredLoggingMiddleware(Middleware):
             log_level: Log level for messages (default: INFO)
             include_payloads: Whether to include message payloads in logs
             methods: List of methods to log. If None, logs all methods.
+            serializer: Callable that converts objects to a JSON string for the
+                payload. If not provided, uses FastMCP's default tool serializer.
         """
-        self.logger = logger or logging.getLogger("fastmcp.structured")
-        self.log_level = log_level
-        self.include_payloads = include_payloads
-        self.methods = methods
+        self.logger: Logger = logger or logging.getLogger("fastmcp.structured")
+        self.log_level: int = log_level
+        self.include_payloads: bool = include_payloads
+        self.methods: list[str] | None = methods
+        self.payload_serializer: Callable[[Any], str] | None = payload_serializer
 
     def _create_log_entry(
-        self, context: MiddlewareContext, event: str, **extra_fields
-    ) -> dict:
+        self, context: MiddlewareContext[Any], event: str, **extra_fields: Any
+    ) -> dict[str, Any]:
         """Create a structured log entry."""
         entry = {
             "event": event,
@@ -138,15 +164,27 @@ class StructuredLoggingMiddleware(Middleware):
             **extra_fields,
         }
 
-        if self.include_payloads and hasattr(context.message, "__dict__"):
-            try:
-                entry["payload"] = context.message.__dict__
-            except (TypeError, ValueError):
-                entry["payload"] = "<non-serializable>"
+        if self.include_payloads:
+            payload: str
+
+            if not self.payload_serializer:
+                payload = default_serializer(context.message)
+            else:
+                try:
+                    payload = self.payload_serializer(context.message)
+                except Exception as e:
+                    self.logger.warning(
+                        f"Failed {str(e)} to serialize payload: {context.type} {context.method} {context.source}."
+                    )
+                    payload = default_serializer(context.message)
+
+            entry["payload"] = payload
 
         return entry
 
-    async def on_message(self, context: MiddlewareContext, call_next: CallNext) -> Any:
+    async def on_message(
+        self, context: MiddlewareContext[Any], call_next: CallNext[Any, Any]
+    ) -> Any:
         """Log structured message information."""
         start_entry = self._create_log_entry(context, "request_start")
         if self.methods and context.method not in self.methods:

fastmcp/server/proxy.py

@@ -546,6 +546,8 @@ class ProxyClient(Client[ClientTransportT]):
         | str,
         **kwargs,
     ):
+        if "name" not in kwargs:
+            kwargs["name"] = self.generate_name()
         if "roots" not in kwargs:
             kwargs["roots"] = default_proxy_roots_handler
         if "sampling_handler" not in kwargs:

fastmcp/server/sampling/handler.py

@@ -0,0 +1,19 @@
+from collections.abc import Awaitable, Callable
+from typing import TypeAlias
+
+from mcp import CreateMessageResult
+from mcp.server.session import ServerSession
+from mcp.shared.context import LifespanContextT, RequestContext
+from mcp.types import CreateMessageRequestParams as SamplingParams
+from mcp.types import (
+    SamplingMessage,
+)
+
+ServerSamplingHandler: TypeAlias = Callable[
+    [
+        list[SamplingMessage],
+        SamplingParams,
+        RequestContext[ServerSession, LifespanContextT],
+    ],
+    str | CreateMessageResult | Awaitable[str | CreateMessageResult],
+]