fastmcp 2.9.2__py3-none-any.whl → 2.10.1__py3-none-any.whl

fastmcp/server/elicitation.py

@@ -0,0 +1,160 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any, Generic, Literal, TypeVar
+
+from mcp.server.elicitation import (
+    CancelledElicitation,
+    DeclinedElicitation,
+)
+from pydantic import BaseModel
+
+from fastmcp.utilities.json_schema import compress_schema
+from fastmcp.utilities.logging import get_logger
+from fastmcp.utilities.types import get_cached_typeadapter
+
+__all__ = [
+    "AcceptedElicitation",
+    "CancelledElicitation",
+    "DeclinedElicitation",
+    "get_elicitation_schema",
+    "ScalarElicitationType",
+]
+
+logger = get_logger(__name__)
+
+T = TypeVar("T")
+
+
+# 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."""
+
+    action: Literal["accept"] = "accept"
+    data: T
+
+
+@dataclass
+class ScalarElicitationType(Generic[T]):
+    value: T
+
+
+def get_elicitation_schema(response_type: type[T]) -> dict[str, Any]:
+    """Get the schema for an elicitation response.
+
+    Args:
+        response_type: The type of the response
+    """
+
+    schema = get_cached_typeadapter(response_type).json_schema()
+    schema = compress_schema(schema)
+
+    # Validate the schema to ensure it follows MCP elicitation requirements
+    validate_elicitation_json_schema(schema)
+
+    return schema
+
+
+def validate_elicitation_json_schema(schema: dict[str, Any]) -> None:
+    """Validate that a JSON schema follows MCP elicitation requirements.
+
+    This ensures the schema is compatible with MCP elicitation requirements:
+    - Must be an object schema
+    - Must only contain primitive field types (string, number, integer, boolean)
+    - Must be flat (no nested objects or arrays of objects)
+    - Allows const fields (for Literal types) and enum fields (for Enum types)
+    - Only primitive types and their nullable variants are allowed
+
+    Args:
+        schema: The JSON schema to validate
+
+    Raises:
+        TypeError: If the schema doesn't meet MCP elicitation requirements
+    """
+    ALLOWED_TYPES = {"string", "number", "integer", "boolean"}
+
+    # Check that the schema is an object
+    if schema.get("type") != "object":
+        raise TypeError(
+            f"Elicitation schema must be an object schema, got type '{schema.get('type')}'. "
+            "Elicitation schemas are limited to flat objects with primitive properties only."
+        )
+
+    properties = schema.get("properties", {})
+
+    for prop_name, prop_schema in properties.items():
+        prop_type = prop_schema.get("type")
+
+        # Handle nullable types
+        if isinstance(prop_type, list):
+            if "null" in prop_type:
+                prop_type = [t for t in prop_type if t != "null"]
+                if len(prop_type) == 1:
+                    prop_type = prop_type[0]
+        elif prop_schema.get("nullable", False):
+            continue  # Nullable with no other type is fine
+
+        # Handle const fields (Literal types)
+        if "const" in prop_schema:
+            continue  # const fields are allowed regardless of type
+
+        # Handle enum fields (Enum types)
+        if "enum" in prop_schema:
+            continue  # enum fields are allowed regardless of type
+
+        # Handle references to definitions (like Enum types)
+        if "$ref" in prop_schema:
+            # Get the referenced definition
+            ref_path = prop_schema["$ref"]
+            if ref_path.startswith("#/$defs/"):
+                def_name = ref_path[8:]  # Remove "#/$defs/" prefix
+                ref_def = schema.get("$defs", {}).get(def_name, {})
+                # If the referenced definition has an enum, it's allowed
+                if "enum" in ref_def:
+                    continue
+                # If the referenced definition has a type that's allowed, it's allowed
+                ref_type = ref_def.get("type")
+                if ref_type in ALLOWED_TYPES:
+                    continue
+            # If we can't determine what the ref points to, reject it for safety
+            raise TypeError(
+                f"Elicitation schema field '{prop_name}' contains a reference '{ref_path}' "
+                "that could not be validated. Only references to enum types or primitive types are allowed."
+            )
+
+        # Handle union types (oneOf/anyOf)
+        if "oneOf" in prop_schema or "anyOf" in prop_schema:
+            union_schemas = prop_schema.get("oneOf", []) + prop_schema.get("anyOf", [])
+            for union_schema in union_schemas:
+                # Allow const and enum in unions
+                if "const" in union_schema or "enum" in union_schema:
+                    continue
+                union_type = union_schema.get("type")
+                if union_type not in ALLOWED_TYPES:
+                    raise TypeError(
+                        f"Elicitation schema field '{prop_name}' has union type '{union_type}' which is not "
+                        f"a primitive type. Only {ALLOWED_TYPES} are allowed in elicitation schemas."
+                    )
+            continue
+
+        # Check if it's a primitive type
+        if prop_type not in ALLOWED_TYPES:
+            raise TypeError(
+                f"Elicitation schema field '{prop_name}' has type '{prop_type}' which is not "
+                f"a primitive type. Only {ALLOWED_TYPES} are allowed in elicitation schemas."
+            )
+
+        # Check for nested objects or arrays of objects (not allowed)
+        if prop_type == "object":
+            raise TypeError(
+                f"Elicitation schema field '{prop_name}' is an object, but nested objects are not allowed. "
+                "Elicitation schemas must be flat objects with primitive properties only."
+            )
+
+        if prop_type == "array":
+            items_schema = prop_schema.get("items", {})
+            if items_schema.get("type") == "object":
+                raise TypeError(
+                    f"Elicitation schema field '{prop_name}' is an array of objects, but arrays of objects are not allowed. "
+                    "Elicitation schemas must be flat objects with primitive properties only."
+                )

fastmcp/server/http.py

@@ -87,7 +87,7 @@ def setup_auth_middleware_and_routes(
     middleware = [
         Middleware(
             AuthenticationMiddleware,
-            backend=BearerAuthBackend(provider=auth),
+            backend=BearerAuthBackend(auth),
         ),
         Middleware(AuthContextMiddleware),
     ]
@@ -158,10 +158,6 @@ def create_sse_app(
         A Starlette application with RequestContextMiddleware
     """
 
-    # Ensure the message_path ends with a trailing slash to avoid automatic redirects
-    if not message_path.endswith("/"):
-        message_path = message_path + "/"
-
     server_routes: list[BaseRoute] = []
     server_middleware: list[Middleware] = []
 
@@ -309,10 +305,6 @@ def create_streamable_http_app(
                 # Re-raise other RuntimeErrors if they don't match the specific message
                 raise
 
-    # Ensure the streamable_http_path ends with a trailing slash to avoid automatic redirects
-    if not streamable_http_path.endswith("/"):
-        streamable_http_path = streamable_http_path + "/"
-
     # Add StreamableHTTP routes with or without auth
     if auth:
         auth_middleware, auth_routes, required_scopes = (

fastmcp/server/low_level.py

@@ -4,12 +4,14 @@ from mcp.server.lowlevel.server import (
     LifespanResultT,
     NotificationOptions,
     RequestT,
-    Server,
+)
+from mcp.server.lowlevel.server import (
+    Server as _Server,
 )
 from mcp.server.models import InitializationOptions
 
 
-class LowLevelServer(Server[LifespanResultT, RequestT]):
+class LowLevelServer(_Server[LifespanResultT, RequestT]):
     def __init__(self, *args, **kwargs):
         super().__init__(*args, **kwargs)
         # FastMCP servers support notifications for all components

fastmcp/server/middleware/__init__.py

@@ -1,6 +1,19 @@
-from .middleware import Middleware, MiddlewareContext
+from .middleware import (
+    Middleware,
+    MiddlewareContext,
+    CallNext,
+    ListToolsResult,
+    ListResourcesResult,
+    ListResourceTemplatesResult,
+    ListPromptsResult,
+)
 
 __all__ = [
     "Middleware",
     "MiddlewareContext",
+    "CallNext",
+    "ListToolsResult",
+    "ListResourcesResult",
+    "ListResourceTemplatesResult",
+    "ListPromptsResult",
 ]

fastmcp/server/middleware/logging.py

@@ -32,6 +32,7 @@ class LoggingMiddleware(Middleware):
         log_level: int = logging.INFO,
         include_payloads: bool = False,
         max_payload_length: int = 1000,
+        methods: list[str] | None = None,
     ):
         """Initialize logging middleware.
 
@@ -40,11 +41,13 @@ class LoggingMiddleware(Middleware):
             log_level: Log level for messages (default: INFO)
             include_payloads: Whether to include message payloads in logs
             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:
         """Format a message for logging."""
@@ -68,6 +71,8 @@ class LoggingMiddleware(Middleware):
     async def on_message(self, context: MiddlewareContext, call_next: CallNext) -> Any:
         """Log all messages."""
         message_info = self._format_message(context)
+        if self.methods and context.method not in self.methods:
+            return await call_next(context)
 
         self.logger.log(self.log_level, f"Processing message: {message_info}")
 
@@ -105,6 +110,7 @@ class StructuredLoggingMiddleware(Middleware):
         logger: logging.Logger | None = None,
         log_level: int = logging.INFO,
         include_payloads: bool = False,
+        methods: list[str] | None = None,
     ):
         """Initialize structured logging middleware.
 
@@ -112,10 +118,12 @@ class StructuredLoggingMiddleware(Middleware):
             logger: Logger instance to use. If None, creates a logger named 'fastmcp.structured'
             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.
         """
         self.logger = logger or logging.getLogger("fastmcp.structured")
         self.log_level = log_level
         self.include_payloads = include_payloads
+        self.methods = methods
 
     def _create_log_entry(
         self, context: MiddlewareContext, event: str, **extra_fields
@@ -141,6 +149,9 @@ class StructuredLoggingMiddleware(Middleware):
     async def on_message(self, context: MiddlewareContext, call_next: CallNext) -> Any:
         """Log structured message information."""
         start_entry = self._create_log_entry(context, "request_start")
+        if self.methods and context.method not in self.methods:
+            return await call_next(context)
+
         self.logger.log(self.log_level, json.dumps(start_entry))
 
         try:

fastmcp/server/middleware/middleware.py

@@ -25,6 +25,16 @@ from fastmcp.tools.tool import Tool
 if TYPE_CHECKING:
     from fastmcp.server.context import Context
 
+__all__ = [
+    "Middleware",
+    "MiddlewareContext",
+    "CallNext",
+    "ListToolsResult",
+    "ListResourcesResult",
+    "ListResourceTemplatesResult",
+    "ListPromptsResult",
+]
+
 logger = logging.getLogger(__name__)
 
 
@@ -52,12 +62,6 @@ ServerResultT = TypeVar(
 )
 
 
-@dataclass(kw_only=True)
-class CallToolResult:
-    content: list[mt.Content]
-    isError: bool = False
-
-
 @dataclass(kw_only=True)
 class ListToolsResult:
     tools: dict[str, Tool]

fastmcp/server/openapi.py

@@ -21,15 +21,15 @@ from fastmcp.exceptions import ToolError
 from fastmcp.resources import Resource, ResourceTemplate
 from fastmcp.server.dependencies import get_http_headers
 from fastmcp.server.server import FastMCP
-from fastmcp.tools.tool import Tool, _convert_to_content
+from fastmcp.tools.tool import Tool, ToolResult
 from fastmcp.utilities import openapi
 from fastmcp.utilities.logging import get_logger
 from fastmcp.utilities.openapi import (
     HTTPRoute,
     _combine_schemas,
+    format_array_parameter,
     format_description_with_responses,
 )
-from fastmcp.utilities.types import MCPContent
 
 if TYPE_CHECKING:
     from fastmcp.server import Context
@@ -255,7 +255,7 @@ class OpenAPITool(Tool):
         """Custom representation to prevent recursion errors when printing."""
         return f"OpenAPITool(name={self.name!r}, method={self._route.method}, path={self._route.path})"
 
-    async def run(self, arguments: dict[str, Any]) -> list[MCPContent]:
+    async def run(self, arguments: dict[str, Any]) -> ToolResult:
         """Execute the HTTP request based on the route configuration."""
 
         # Prepare URL
@@ -297,46 +297,10 @@ class OpenAPITool(Tool):
                 if is_array:
                     # Format array values as comma-separated string
                     # This follows the OpenAPI 'simple' style (default for path)
-                    if all(
-                        isinstance(item, str | int | float | bool)
-                        for item in param_value
-                    ):
-                        # Handle simple array types
-                        path = path.replace(
-                            f"{{{param_name}}}", ",".join(str(v) for v in param_value)
-                        )
-                    else:
-                        # Handle complex array types (containing objects/dicts)
-                        try:
-                            # Try to create a simple representation without Python syntax artifacts
-                            formatted_parts = []
-                            for item in param_value:
-                                if isinstance(item, dict):
-                                    # For objects, serialize key-value pairs
-                                    item_parts = []
-                                    for k, v in item.items():
-                                        item_parts.append(f"{k}:{v}")
-                                    formatted_parts.append(".".join(item_parts))
-                                else:
-                                    # Fallback for other complex types
-                                    formatted_parts.append(str(item))
-
-                            # Join parts with commas
-                            formatted_value = ",".join(formatted_parts)
-                            path = path.replace(f"{{{param_name}}}", formatted_value)
-                        except Exception as e:
-                            logger.warning(
-                                f"Failed to format complex array path parameter '{param_name}': {e}"
-                            )
-                            # Fallback to string representation, but remove Python syntax artifacts
-                            str_value = (
-                                str(param_value)
-                                .replace("[", "")
-                                .replace("]", "")
-                                .replace("'", "")
-                                .replace('"', "")
-                            )
-                            path = path.replace(f"{{{param_name}}}", str_value)
+                    formatted_value = format_array_parameter(
+                        param_value, param_name, is_query_parameter=False
+                    )
+                    path = path.replace(f"{{{param_name}}}", str(formatted_value))
                     continue
 
             # Default handling for non-array parameters or non-array schemas
@@ -356,44 +320,21 @@ class OpenAPITool(Tool):
                 # Format array query parameters as comma-separated strings
                 # following OpenAPI form style (default for query parameters)
                 if isinstance(param_value, list) and p.schema_.get("type") == "array":
-                    # Get explode parameter from schema, default is True for query parameters
+                    # Get explode parameter from the parameter info, default is True for query parameters
                     # If explode is True, the array is serialized as separate parameters
                     # If explode is False, the array is serialized as a comma-separated string
-                    explode = p.schema_.get("explode", True)
+                    explode = p.explode if p.explode is not None else True
 
                     if explode:
                         # When explode=True, we pass the array directly, which HTTPX will serialize
                         # as multiple parameters with the same name
                         query_params[p.name] = param_value
                     else:
-                        # For arrays of simple types (strings, numbers, etc.), join with commas
-                        if all(
-                            isinstance(item, str | int | float | bool)
-                            for item in param_value
-                        ):
-                            query_params[p.name] = ",".join(str(v) for v in param_value)
-                        else:
-                            # For complex types, try to create a simpler representation
-                            try:
-                                # Try to create a simple string representation
-                                formatted_parts = []
-                                for item in param_value:
-                                    if isinstance(item, dict):
-                                        # For objects, serialize key-value pairs
-                                        item_parts = []
-                                        for k, v in item.items():
-                                            item_parts.append(f"{k}:{v}")
-                                        formatted_parts.append(".".join(item_parts))
-                                    else:
-                                        formatted_parts.append(str(item))
-
-                                query_params[p.name] = ",".join(formatted_parts)
-                            except Exception as e:
-                                logger.warning(
-                                    f"Failed to format complex array query parameter '{p.name}': {e}"
-                                )
-                                # Fallback to string representation
-                                query_params[p.name] = param_value
+                        # Format array as comma-separated string when explode=False
+                        formatted_value = format_array_parameter(
+                            param_value, p.name, is_query_parameter=True
+                        )
+                        query_params[p.name] = formatted_value
                 else:
                     # Non-array parameters are passed as is
                     query_params[p.name] = param_value
@@ -451,10 +392,11 @@ class OpenAPITool(Tool):
             # Try to parse as JSON first
             try:
                 result = response.json()
-            except (json.JSONDecodeError, ValueError):
-                # Return text content if not JSON
-                result = response.text
-            return _convert_to_content(result)
+                if not isinstance(result, dict):
+                    result = {"result": result}
+                return ToolResult(structured_content=result)
+            except json.JSONDecodeError:
+                return ToolResult(content=response.text)
 
         except httpx.HTTPStatusError as e:
             # Handle HTTP errors (4xx, 5xx)

fastmcp/server/proxy.py

@@ -22,10 +22,9 @@ from fastmcp.resources import Resource, ResourceTemplate
 from fastmcp.resources.resource_manager import ResourceManager
 from fastmcp.server.context import Context
 from fastmcp.server.server import FastMCP
-from fastmcp.tools.tool import Tool
+from fastmcp.tools.tool import Tool, ToolResult
 from fastmcp.tools.tool_manager import ToolManager
 from fastmcp.utilities.logging import get_logger
-from fastmcp.utilities.types import MCPContent
 
 if TYPE_CHECKING:
     from fastmcp.server import Context
@@ -67,7 +66,7 @@ class ProxyToolManager(ToolManager):
         tools_dict = await self.get_tools()
         return list(tools_dict.values())
 
-    async def call_tool(self, key: str, arguments: dict[str, Any]) -> list[MCPContent]:
+    async def call_tool(self, key: str, arguments: dict[str, Any]) -> ToolResult:
         """Calls a tool, trying local/mounted first, then proxy if not found."""
         try:
             # First try local and mounted tools
@@ -75,7 +74,11 @@ class ProxyToolManager(ToolManager):
         except NotFoundError:
             # If not found locally, try proxy
             async with self.client:
-                return await self.client.call_tool(key, arguments)
+                result = await self.client.call_tool(key, arguments)
+                return ToolResult(
+                    content=result.content,
+                    structured_content=result.structured_content,
+                )
 
 
 class ProxyResourceManager(ResourceManager):
@@ -224,13 +227,14 @@ class ProxyTool(Tool):
             description=mcp_tool.description,
             parameters=mcp_tool.inputSchema,
             annotations=mcp_tool.annotations,
+            output_schema=mcp_tool.outputSchema,
         )
 
     async def run(
         self,
         arguments: dict[str, Any],
         context: Context | None = None,
-    ) -> list[MCPContent]:
+    ) -> ToolResult:
         """Executes the tool by making a call through the client."""
         # This is where the remote execution logic lives.
         async with self._client:
@@ -240,7 +244,10 @@ class ProxyTool(Tool):
             )
         if result.isError:
             raise ToolError(cast(mcp.types.TextContent, result.content[0]).text)
-        return result.content
+        return ToolResult(
+            content=result.content,
+            structured_content=result.structuredContent,
+        )
 
 
 class ProxyResource(Resource):