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

fastmcp/server/middleware/logging.py

@@ -16,7 +16,131 @@ def default_serializer(data: Any) -> str:
     return pydantic_core.to_json(data, fallback=str).decode()
 
 
-class LoggingMiddleware(Middleware):
+class BaseLoggingMiddleware(Middleware):
+    """Base class for logging middleware."""
+
+    logger: Logger
+    log_level: int
+    include_payloads: bool
+    include_payload_length: bool
+    estimate_payload_tokens: bool
+    max_payload_length: int | None
+    methods: list[str] | None
+    structured_logging: bool
+    payload_serializer: Callable[[Any], str] | None
+
+    def _serialize_payload(self, context: MiddlewareContext[Any]) -> str:
+        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 to serialize payload due to {e}: {context.type} {context.method} {context.source}."
+                )
+                payload = default_serializer(context.message)
+
+        return payload
+
+    def _format_message(self, message: dict[str, str | int]) -> str:
+        """Format a message for logging."""
+        if self.structured_logging:
+            return json.dumps(message)
+        else:
+            return " ".join([f"{k}={v}" for k, v in message.items()])
+
+    def _get_timestamp_from_context(self, context: MiddlewareContext[Any]) -> str:
+        """Get a timestamp from the context."""
+        return context.timestamp.isoformat()
+
+    def _create_before_message(
+        self, context: MiddlewareContext[Any], event: str
+    ) -> dict[str, str | int]:
+        message = self._create_base_message(context, event)
+
+        if (
+            self.include_payloads
+            or self.include_payload_length
+            or self.estimate_payload_tokens
+        ):
+            payload = self._serialize_payload(context)
+
+            if self.include_payload_length or self.estimate_payload_tokens:
+                payload_length = len(payload)
+                payload_tokens = payload_length // 4
+                if self.estimate_payload_tokens:
+                    message["payload_tokens"] = payload_tokens
+                if self.include_payload_length:
+                    message["payload_length"] = payload_length
+
+            if self.max_payload_length and len(payload) > self.max_payload_length:
+                payload = payload[: self.max_payload_length] + "..."
+
+            if self.include_payloads:
+                message["payload"] = payload
+                message["payload_type"] = type(context.message).__name__
+
+        return message
+
+    def _create_after_message(
+        self, context: MiddlewareContext[Any], event: str
+    ) -> dict[str, str | int]:
+        return self._create_base_message(context, event)
+
+    def _create_base_message(
+        self,
+        context: MiddlewareContext[Any],
+        event: str,
+    ) -> dict[str, str | int]:
+        """Format a message for logging."""
+
+        parts: dict[str, str | int] = {
+            "event": event,
+            "timestamp": self._get_timestamp_from_context(context),
+            "method": context.method or "unknown",
+            "type": context.type,
+            "source": context.source,
+        }
+
+        return parts
+
+    async def on_message(
+        self, context: MiddlewareContext[Any], call_next: CallNext[Any, Any]
+    ) -> Any:
+        """Log all messages."""
+
+        if self.methods and context.method not in self.methods:
+            return await call_next(context)
+
+        request_start_log_message = self._create_before_message(
+            context, "request_start"
+        )
+
+        formatted_message = self._format_message(request_start_log_message)
+        self.logger.log(self.log_level, f"Processing message: {formatted_message}")
+
+        try:
+            result = await call_next(context)
+
+            request_success_log_message = self._create_after_message(
+                context, "request_success"
+            )
+
+            formatted_message = self._format_message(request_success_log_message)
+            self.logger.log(self.log_level, f"Completed message: {formatted_message}")
+
+            return result
+        except Exception as e:
+            self.logger.log(
+                logging.ERROR, f"Failed message: {context.method or 'unknown'} - {e}"
+            )
+            raise
+
+
+class LoggingMiddleware(BaseLoggingMiddleware):
     """Middleware that provides comprehensive request and response logging.
 
     Logs all MCP messages with configurable detail levels. Useful for debugging,
@@ -37,9 +161,12 @@ class LoggingMiddleware(Middleware):
 
     def __init__(
         self,
+        *,
         logger: logging.Logger | None = None,
         log_level: int = logging.INFO,
         include_payloads: bool = False,
+        include_payload_length: bool = False,
+        estimate_payload_tokens: bool = False,
         max_payload_length: int = 1000,
         methods: list[str] | None = None,
         payload_serializer: Callable[[Any], str] | None = None,
@@ -50,68 +177,25 @@ class LoggingMiddleware(Middleware):
             logger: Logger instance to use. If None, creates a logger named 'fastmcp.requests'
             log_level: Log level for messages (default: INFO)
             include_payloads: Whether to include message payloads in logs
+            include_payload_length: Whether to include response size in logs
+            estimate_payload_tokens: Whether to estimate response tokens
             max_payload_length: Maximum length of payload to log (prevents huge logs)
             methods: List of methods to log. If None, logs all methods.
+            payload_serializer: Callable that converts objects to a JSON string for the
+                payload. If not provided, uses FastMCP's default tool serializer.
         """
         self.logger: Logger = logger or logging.getLogger("fastmcp.requests")
-        self.log_level: int = log_level
+        self.log_level = log_level
         self.include_payloads: bool = include_payloads
+        self.include_payload_length: bool = include_payload_length
+        self.estimate_payload_tokens: bool = estimate_payload_tokens
         self.max_payload_length: int = max_payload_length
         self.methods: list[str] | None = methods
         self.payload_serializer: Callable[[Any], str] | None = payload_serializer
+        self.structured_logging: bool = False
 
-    def _format_message(self, context: MiddlewareContext[Any]) -> str:
-        """Format a message for logging."""
-        parts = [
-            f"source={context.source}",
-            f"type={context.type}",
-            f"method={context.method or 'unknown'}",
-        ]
-
-        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[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:
-            return await call_next(context)
-
-        self.logger.log(self.log_level, f"Processing message: {message_info}")
-
-        try:
-            result = await call_next(context)
-            self.logger.log(
-                self.log_level, f"Completed message: {context.method or 'unknown'}"
-            )
-            return result
-        except Exception as e:
-            self.logger.log(
-                logging.ERROR, f"Failed message: {context.method or 'unknown'} - {e}"
-            )
-            raise
-
-
-class StructuredLoggingMiddleware(Middleware):
+class StructuredLoggingMiddleware(BaseLoggingMiddleware):
     """Middleware that provides structured JSON logging for better log analysis.
 
     Outputs structured logs that are easier to parse and analyze with log
@@ -129,9 +213,12 @@ class StructuredLoggingMiddleware(Middleware):
 
     def __init__(
         self,
+        *,
         logger: logging.Logger | None = None,
         log_level: int = logging.INFO,
         include_payloads: bool = False,
+        include_payload_length: bool = False,
+        estimate_payload_tokens: bool = False,
         methods: list[str] | None = None,
         payload_serializer: Callable[[Any], str] | None = None,
     ):
@@ -141,74 +228,18 @@ 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
+            include_payload_length: Whether to include payload size in logs
+            estimate_payload_tokens: Whether to estimate token count using length // 4
             methods: List of methods to log. If None, logs all methods.
-            serializer: Callable that converts objects to a JSON string for the
+            payload_serializer: Callable that converts objects to a JSON string for the
                 payload. If not provided, uses FastMCP's default tool serializer.
         """
         self.logger: Logger = logger or logging.getLogger("fastmcp.structured")
         self.log_level: int = log_level
         self.include_payloads: bool = include_payloads
+        self.include_payload_length: bool = include_payload_length
+        self.estimate_payload_tokens: bool = estimate_payload_tokens
         self.methods: list[str] | None = methods
         self.payload_serializer: Callable[[Any], str] | None = payload_serializer
-
-    def _create_log_entry(
-        self, context: MiddlewareContext[Any], event: str, **extra_fields: Any
-    ) -> dict[str, Any]:
-        """Create a structured log entry."""
-        entry = {
-            "event": event,
-            "timestamp": context.timestamp.isoformat(),
-            "source": context.source,
-            "type": context.type,
-            "method": context.method,
-            **extra_fields,
-        }
-
-        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[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:
-            return await call_next(context)
-
-        self.logger.log(self.log_level, json.dumps(start_entry))
-
-        try:
-            result = await call_next(context)
-
-            success_entry = self._create_log_entry(
-                context,
-                "request_success",
-                result_type=type(result).__name__ if result else None,
-            )
-            self.logger.log(self.log_level, json.dumps(success_entry))
-
-            return result
-        except Exception as e:
-            error_entry = self._create_log_entry(
-                context,
-                "request_error",
-                error_type=type(e).__name__,
-                error_message=str(e),
-            )
-            self.logger.log(logging.ERROR, json.dumps(error_entry))
-            raise
+        self.max_payload_length: int | None = None
+        self.structured_logging: bool = True

fastmcp/server/middleware/middleware.py

@@ -15,6 +15,7 @@ from typing import (
 )
 
 import mcp.types as mt
+from mcp.server.lowlevel.helper_types import ReadResourceContents
 from typing_extensions import TypeVar
 
 from fastmcp.prompts.prompt import Prompt
@@ -154,8 +155,8 @@ class Middleware:
     async def on_read_resource(
         self,
         context: MiddlewareContext[mt.ReadResourceRequestParams],
-        call_next: CallNext[mt.ReadResourceRequestParams, mt.ReadResourceResult],
-    ) -> mt.ReadResourceResult:
+        call_next: CallNext[mt.ReadResourceRequestParams, list[ReadResourceContents]],
+    ) -> list[ReadResourceContents]:
         return await call_next(context)
 
     async def on_get_prompt(

fastmcp/server/openapi.py

@@ -785,6 +785,7 @@ class FastMCPOpenAPI(FastMCP):
         http_routes = openapi.parse_openapi_to_http_routes(openapi_spec)
 
         # Process routes
+        num_excluded = 0
         route_maps = (route_maps or []) + DEFAULT_ROUTE_MAPPINGS
         for route in http_routes:
             # Determine route type based on mappings or default rules
@@ -823,8 +824,11 @@ class FastMCPOpenAPI(FastMCP):
                 self._create_openapi_template(route, component_name, tags=route_tags)
             elif route_type == MCPType.EXCLUDE:
                 logger.info(f"Excluding route: {route.method} {route.path}")
+                num_excluded += 1
 
-        logger.info(f"Created FastMCP OpenAPI server with {len(http_routes)} routes")
+        logger.info(
+            f"Created FastMCP OpenAPI server with {len(http_routes) - num_excluded} routes"
+        )
 
     def _generate_default_name(
         self, route: openapi.HTTPRoute, mcp_names_map: dict[str, str] | None = None

fastmcp/server/server.py

@@ -8,11 +8,7 @@ import re
 import secrets
 import warnings
 from collections.abc import AsyncIterator, Awaitable, Callable
-from contextlib import (
-    AbstractAsyncContextManager,
-    AsyncExitStack,
-    asynccontextmanager,
-)
+from contextlib import AbstractAsyncContextManager, AsyncExitStack, asynccontextmanager
 from dataclasses import dataclass
 from functools import partial
 from pathlib import Path
@@ -65,7 +61,7 @@ from fastmcp.tools.tool import FunctionTool, Tool, ToolResult
 from fastmcp.tools.tool_transform import ToolTransformConfig
 from fastmcp.utilities.cli import log_server_banner
 from fastmcp.utilities.components import FastMCPComponent
-from fastmcp.utilities.logging import get_logger
+from fastmcp.utilities.logging import get_logger, temporary_log_level
 from fastmcp.utilities.types import NotSet, NotSetT
 
 if TYPE_CHECKING:
@@ -208,8 +204,8 @@ class FastMCP(Generic[LifespanResultT]):
         # if auth is `NotSet`, try to create a provider from the environment
         if auth is NotSet:
             if fastmcp.settings.server_auth is not None:
-                # ImportString returns the class itself
-                auth = fastmcp.settings.server_auth()
+                # server_auth_class returns the class itself
+                auth = fastmcp.settings.server_auth_class()
             else:
                 auth = None
         self.auth = cast(AuthProvider | None, auth)
@@ -329,6 +325,10 @@ class FastMCP(Generic[LifespanResultT]):
     def instructions(self) -> str | None:
         return self._mcp_server.instructions
 
+    @instructions.setter
+    def instructions(self, value: str | None) -> None:
+        self._mcp_server.instructions = value
+
     @property
     def version(self) -> str | None:
         return self._mcp_server.version
@@ -1481,9 +1481,15 @@ class FastMCP(Generic[LifespanResultT]):
             meta=meta,
         )
 
-    async def run_stdio_async(self, show_banner: bool = True) -> None:
-        """Run the server using stdio transport."""
+    async def run_stdio_async(
+        self, show_banner: bool = True, log_level: str | None = None
+    ) -> None:
+        """Run the server using stdio transport.
 
+        Args:
+            show_banner: Whether to display the server banner
+            log_level: Log level for the server
+        """
         # Display server banner
         if show_banner:
             log_server_banner(
@@ -1491,15 +1497,16 @@ class FastMCP(Generic[LifespanResultT]):
                 transport="stdio",
             )
 
-        async with stdio_server() as (read_stream, write_stream):
-            logger.info(f"Starting MCP server {self.name!r} with transport 'stdio'")
-            await self._mcp_server.run(
-                read_stream,
-                write_stream,
-                self._mcp_server.create_initialization_options(
-                    NotificationOptions(tools_changed=True)
-                ),
-            )
+        with temporary_log_level(log_level):
+            async with stdio_server() as (read_stream, write_stream):
+                logger.info(f"Starting MCP server {self.name!r} with transport 'stdio'")
+                await self._mcp_server.run(
+                    read_stream,
+                    write_stream,
+                    self._mcp_server.create_initialization_options(
+                        NotificationOptions(tools_changed=True)
+                    ),
+                )
 
     async def run_http_async(
         self,
@@ -1525,7 +1532,6 @@ class FastMCP(Generic[LifespanResultT]):
             middleware: A list of middleware to apply to the app
             stateless_http: Whether to use stateless HTTP (defaults to settings.stateless_http)
         """
-
         host = host or self._deprecated_settings.host
         port = port or self._deprecated_settings.port
         default_log_level_to_use = (
@@ -1566,14 +1572,15 @@ class FastMCP(Generic[LifespanResultT]):
         if "log_config" not in config_kwargs and "log_level" not in config_kwargs:
             config_kwargs["log_level"] = default_log_level_to_use
 
-        config = uvicorn.Config(app, host=host, port=port, **config_kwargs)
-        server = uvicorn.Server(config)
-        path = app.state.path.lstrip("/")  # type: ignore
-        logger.info(
-            f"Starting MCP server {self.name!r} with transport {transport!r} on http://{host}:{port}/{path}"
-        )
+        with temporary_log_level(log_level):
+            config = uvicorn.Config(app, host=host, port=port, **config_kwargs)
+            server = uvicorn.Server(config)
+            path = app.state.path.lstrip("/")  # type: ignore
+            logger.info(
+                f"Starting MCP server {self.name!r} with transport {transport!r} on http://{host}:{port}/{path}"
+            )
 
-        await server.serve()
+            await server.serve()
 
     async def run_sse_async(
         self,
@@ -2122,10 +2129,8 @@ class FastMCP(Generic[LifespanResultT]):
             # - Connected clients: reuse existing session for all requests
             # - Disconnected clients: create fresh sessions per request for isolation
             if client.is_connected():
-                from fastmcp.utilities.logging import get_logger
-
-                logger = get_logger(__name__)
-                logger.info(
+                _proxy_logger = get_logger(__name__)
+                _proxy_logger.info(
                     "Proxy detected connected client - reusing existing session for all requests. "
                     "This may cause context mixing in concurrent scenarios."
                 )

fastmcp/settings.py

@@ -3,7 +3,7 @@ from __future__ import annotations as _annotations
 import inspect
 import warnings
 from pathlib import Path
-from typing import Annotated, Any, Literal
+from typing import TYPE_CHECKING, Annotated, Any, Literal
 
 from pydantic import Field, ImportString, field_validator
 from pydantic.fields import FieldInfo
@@ -23,6 +23,9 @@ LOG_LEVEL = Literal["DEBUG", "INFO", "WARNING", "ERROR", "CRITICAL"]
 
 DuplicateBehavior = Literal["warn", "error", "replace", "ignore"]
 
+if TYPE_CHECKING:
+    from fastmcp.server.auth.auth import AuthProvider
+
 
 class ExtendedEnvSettingsSource(EnvSettingsSource):
     """
@@ -258,7 +261,7 @@ class Settings(BaseSettings):
 
     # Auth settings
     server_auth: Annotated[
-        ImportString | None,
+        str | None,
         Field(
             description=inspect.cleandoc(
                 """
@@ -266,9 +269,9 @@ class Settings(BaseSettings):
                 the full module path to an AuthProvider class (e.g., 
                 'fastmcp.server.auth.providers.google.GoogleProvider').
 
-                The specified class will be imported and instantiated automatically.
-                Any class that inherits from AuthProvider can be used, including
-                custom implementations.
+                The specified class will be imported and instantiated automatically
+                during FastMCP server creation. Any class that inherits from AuthProvider
+                can be used, including custom implementations.
 
                 If None, no automatic configuration will take place.
 
@@ -357,6 +360,25 @@ class Settings(BaseSettings):
         ),
     ] = True
 
+    @property
+    def server_auth_class(self) -> AuthProvider | None:
+        from fastmcp.utilities.types import get_cached_typeadapter
+
+        if not self.server_auth:
+            return None
+
+        # https://github.com/jlowin/fastmcp/issues/1749
+        # Pydantic imports the module in an ImportString during model validation, but we don't want the server
+        # auth module imported during settings creation as it imports dependencies we aren't ready for yet.
+        # To fix this while limiting breaking changes, we delay the import by only creating the ImportString
+        # when the class is actually needed
+
+        type_adapter = get_cached_typeadapter(ImportString)
+
+        auth_class = type_adapter.validate_python(self.server_auth)
+
+        return auth_class
+
 
 def __getattr__(name: str):
     """

fastmcp/tools/tool.py

@@ -413,7 +413,9 @@ class ParsedFunction:
 
         input_type_adapter = get_cached_typeadapter(fn)
         input_schema = input_type_adapter.json_schema()
-        input_schema = compress_schema(input_schema, prune_params=prune_params)
+        input_schema = compress_schema(
+            input_schema, prune_params=prune_params, prune_titles=True
+        )
 
         output_schema = None
         # Get the return annotation from the signature
@@ -473,7 +475,7 @@ class ParsedFunction:
                 else:
                     output_schema = base_schema
 
-                output_schema = compress_schema(output_schema)
+                output_schema = compress_schema(output_schema, prune_titles=True)
 
             except PydanticSchemaGenerationError as e:
                 if "_UnserializableType" not in str(e):

fastmcp/utilities/json_schema.py

@@ -109,8 +109,25 @@ def _single_pass_optimize(
                         root_refs.add(referenced_def)
 
             # Apply cleanups
+            # Only remove "title" if it's a schema metadata field
+            # Schema objects have keywords like "type", "properties", "$ref", etc.
+            # If we see these, then "title" is metadata, not a property name
             if prune_titles and "title" in node:
-                node.pop("title")
+                # Check if this looks like a schema node
+                if any(
+                    k in node
+                    for k in [
+                        "type",
+                        "properties",
+                        "$ref",
+                        "items",
+                        "allOf",
+                        "oneOf",
+                        "anyOf",
+                        "required",
+                    ]
+                ):
+                    node.pop("title")
 
             if (
                 prune_additional_properties