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

fastmcp/client/logging.py

@@ -13,7 +13,31 @@ LogHandler: TypeAlias = Callable[[LogMessage], Awaitable[None]]
 
 
 async def default_log_handler(message: LogMessage) -> None:
-    logger.debug(f"Log received: {message}")
+    """Default handler that properly routes server log messages to appropriate log levels."""
+    msg = message.data.get("msg", str(message))
+    extra = message.data.get("extra", {})
+
+    # Map MCP log levels to Python logging levels
+    level_map = {
+        "debug": logger.debug,
+        "info": logger.info,
+        "notice": logger.info,  # Python doesn't have 'notice', map to info
+        "warning": logger.warning,
+        "error": logger.error,
+        "critical": logger.critical,
+        "alert": logger.critical,  # Map alert to critical
+        "emergency": logger.critical,  # Map emergency to critical
+    }
+
+    # Get the appropriate logging function based on the message level
+    log_fn = level_map.get(message.level.lower(), logger.info)
+
+    # Include logger name if available
+    if message.logger:
+        msg = f"[{message.logger}] {msg}"
+
+    # Log with appropriate level and extra data
+    log_fn(f"Server log: {msg}", extra=extra)
 
 
 def create_log_callback(handler: LogHandler | None = None) -> LoggingFnT:

fastmcp/client/transports.py

@@ -6,7 +6,7 @@ import os
 import shutil
 import sys
 import warnings
-from collections.abc import AsyncIterator, Callable
+from collections.abc import AsyncIterator
 from pathlib import Path
 from typing import Any, Literal, TypeVar, cast, overload
 
@@ -22,6 +22,7 @@ from mcp.client.session import (
     SamplingFnT,
 )
 from mcp.server.fastmcp import FastMCP as FastMCP1Server
+from mcp.shared._httpx_utils import McpHttpClientFactory
 from mcp.shared.memory import create_client_server_memory_streams
 from pydantic import AnyUrl
 from typing_extensions import TypedDict, Unpack
@@ -161,7 +162,7 @@ class SSETransport(ClientTransport):
         headers: dict[str, str] | None = None,
         auth: httpx.Auth | Literal["oauth"] | str | None = None,
         sse_read_timeout: datetime.timedelta | float | int | None = None,
-        httpx_client_factory: Callable[[], httpx.AsyncClient] | None = None,
+        httpx_client_factory: McpHttpClientFactory | None = None,
     ):
         if isinstance(url, AnyUrl):
             url = str(url)
@@ -233,7 +234,7 @@ class StreamableHttpTransport(ClientTransport):
         headers: dict[str, str] | None = None,
         auth: httpx.Auth | Literal["oauth"] | str | None = None,
         sse_read_timeout: datetime.timedelta | float | int | None = None,
-        httpx_client_factory: Callable[[], httpx.AsyncClient] | None = None,
+        httpx_client_factory: McpHttpClientFactory | None = None,
     ):
         if isinstance(url, AnyUrl):
             url = str(url)

fastmcp/experimental/server/openapi/routing.py

@@ -113,7 +113,7 @@ def _determine_route_type(
                 # We know mcp_type is not None here due to post_init validation
                 assert route_map.mcp_type is not None
                 logger.debug(
-                    f"Route {route.method} {route.path} matched mapping to {route_map.mcp_type.name}"
+                    f"Route {route.method} {route.path} mapped to {route_map.mcp_type.name}"
                 )
                 return route_map
 

fastmcp/experimental/server/openapi/server.py

@@ -11,7 +11,7 @@ from jsonschema_path import SchemaPath
 from fastmcp.experimental.utilities.openapi import (
     HTTPRoute,
     extract_output_schema_from_responses,
-    format_description_with_responses,
+    format_simple_description,
     parse_openapi_to_http_routes,
 )
 from fastmcp.experimental.utilities.openapi.director import RequestDirector
@@ -151,9 +151,6 @@ class FastMCPOpenAPI(FastMCP):
         try:
             self._spec = SchemaPath.from_dict(openapi_spec)  # type: ignore[arg-type]
             self._director = RequestDirector(self._spec)
-            logger.debug(
-                "Initialized OpenAPI RequestDirector for stateless request building"
-            )
         except Exception as e:
             logger.error(f"Failed to initialize RequestDirector: {e}")
             raise ValueError(f"Invalid OpenAPI specification: {e}") from e
@@ -270,7 +267,9 @@ class FastMCPOpenAPI(FastMCP):
 
         # Extract output schema from OpenAPI responses
         output_schema = extract_output_schema_from_responses(
-            route.responses, route.schema_definitions, route.openapi_version
+            route.responses,
+            route.response_schemas,
+            route.openapi_version,
         )
 
         # Get a unique tool name
@@ -282,10 +281,9 @@ class FastMCPOpenAPI(FastMCP):
             or f"Executes {route.method} {route.path}"
         )
 
-        # Format enhanced description with parameters and request body
-        enhanced_description = format_description_with_responses(
+        # Use simplified description formatter for tools
+        enhanced_description = format_simple_description(
             base_description=base_description,
-            responses=route.responses,
             parameters=route.parameters,
             request_body=route.request_body,
         )
@@ -318,9 +316,6 @@ class FastMCPOpenAPI(FastMCP):
 
         # Register the tool by directly assigning to the tools dictionary
         self._tool_manager._tools[final_tool_name] = tool
-        logger.debug(
-            f"Registered TOOL: {final_tool_name} ({route.method} {route.path}) with tags: {route.tags}"
-        )
 
     def _create_openapi_resource(
         self,
@@ -337,10 +332,9 @@ class FastMCPOpenAPI(FastMCP):
             route.description or route.summary or f"Represents {route.path}"
         )
 
-        # Format enhanced description with parameters and request body
-        enhanced_description = format_description_with_responses(
+        # Use simplified description for resources
+        enhanced_description = format_simple_description(
             base_description=base_description,
-            responses=route.responses,
             parameters=route.parameters,
             request_body=route.request_body,
         )
@@ -372,9 +366,6 @@ class FastMCPOpenAPI(FastMCP):
 
         # Register the resource by directly assigning to the resources dictionary
         self._resource_manager._resources[final_resource_uri] = resource
-        logger.debug(
-            f"Registered RESOURCE: {final_resource_uri} ({route.method} {route.path}) with tags: {route.tags}"
-        )
 
     def _create_openapi_template(
         self,
@@ -397,10 +388,9 @@ class FastMCPOpenAPI(FastMCP):
             route.description or route.summary or f"Template for {route.path}"
         )
 
-        # Format enhanced description with parameters and request body
-        enhanced_description = format_description_with_responses(
+        # Use simplified description for resource templates
+        enhanced_description = format_simple_description(
             base_description=base_description,
-            responses=route.responses,
             parameters=route.parameters,
             request_body=route.request_body,
         )
@@ -455,9 +445,6 @@ class FastMCPOpenAPI(FastMCP):
 
         # Register the template by directly assigning to the templates dictionary
         self._resource_manager._templates[final_template_uri] = template
-        logger.debug(
-            f"Registered TEMPLATE: {final_template_uri} ({route.method} {route.path}) with tags: {route.tags}"
-        )
 
 
 # Export public symbols

fastmcp/experimental/utilities/openapi/__init__.py

@@ -20,6 +20,7 @@ from .formatters import (
     format_deep_object_parameter,
     format_description_with_responses,
     format_json_for_description,
+    format_simple_description,
     generate_example_from_schema,
 )
 
@@ -28,7 +29,6 @@ from .schemas import (
     _combine_schemas,
     extract_output_schema_from_responses,
     clean_schema_for_display,
-    _replace_ref_with_defs,
     _make_optional_parameter_nullable,
 )
 
@@ -55,12 +55,12 @@ __all__ = [
     "format_deep_object_parameter",
     "format_description_with_responses",
     "format_json_for_description",
+    "format_simple_description",
     "generate_example_from_schema",
     # Schemas
     "_combine_schemas",
     "extract_output_schema_from_responses",
     "clean_schema_for_display",
-    "_replace_ref_with_defs",
     "_make_optional_parameter_nullable",
     # JSON Schema Converter
     "convert_openapi_schema_to_json_schema",

fastmcp/experimental/utilities/openapi/formatters.py

@@ -189,6 +189,39 @@ def format_json_for_description(data: Any, indent: int = 2) -> str:
         return f"```\nCould not serialize to JSON: {data}\n```"
 
 
+def format_simple_description(
+    base_description: str,
+    parameters: list[ParameterInfo] | None = None,
+    request_body: RequestBodyInfo | None = None,
+) -> str:
+    """
+    Formats a simple description for MCP objects (tools, resources, prompts).
+    Excludes response details, examples, and verbose status codes.
+
+    Args:
+        base_description (str): The initial description to be formatted.
+        parameters (list[ParameterInfo] | None, optional): A list of parameter information.
+        request_body (RequestBodyInfo | None, optional): Information about the request body.
+
+    Returns:
+        str: The formatted description string with minimal details.
+    """
+    desc_parts = [base_description]
+
+    # Only add critical parameter information if they have descriptions
+    if parameters:
+        path_params = [p for p in parameters if p.location == "path" and p.description]
+        if path_params:
+            desc_parts.append("\n\n**Path Parameters:**")
+            for param in path_params:
+                desc_parts.append(f"\n- **{param.name}**: {param.description}")
+
+    # Skip query parameters, request body details, and all response information
+    # These are already captured in the inputSchema
+
+    return "\n".join(desc_parts)
+
+
 def format_description_with_responses(
     base_description: str,
     responses: dict[
@@ -351,5 +384,6 @@ __all__ = [
     "format_deep_object_parameter",
     "format_description_with_responses",
     "format_json_for_description",
+    "format_simple_description",
     "generate_example_from_schema",
 ]

fastmcp/experimental/utilities/openapi/models.py

@@ -58,9 +58,12 @@ class HTTPRoute(FastMCPBaseModel):
     responses: dict[str, ResponseInfo] = Field(
         default_factory=dict
     )  # Key: status code str
-    schema_definitions: dict[str, JsonSchema] = Field(
+    request_schemas: dict[str, JsonSchema] = Field(
         default_factory=dict
-    )  # Store component schemas
+    )  # Store schemas needed for input (parameters/request body)
+    response_schemas: dict[str, JsonSchema] = Field(
+        default_factory=dict
+    )  # Store schemas needed for output (responses)
     extensions: dict[str, Any] = Field(default_factory=dict)
     openapi_version: str | None = None
 

fastmcp/experimental/utilities/openapi/parser.py

@@ -34,7 +34,10 @@ from .models import (
     RequestBodyInfo,
     ResponseInfo,
 )
-from .schemas import _combine_schemas_and_map_params, _replace_ref_with_defs
+from .schemas import (
+    _combine_schemas_and_map_params,
+    _replace_ref_with_defs,
+)
 
 logger = get_logger(__name__)
 
@@ -63,7 +66,7 @@ def parse_openapi_to_http_routes(openapi_dict: dict[str, Any]) -> list[HTTPRoute
         if openapi_version.startswith("3.0"):
             # Use OpenAPI 3.0 models
             openapi_30 = OpenAPI_30.model_validate(openapi_dict)
-            logger.info(
+            logger.debug(
                 f"Successfully parsed OpenAPI 3.0 schema version: {openapi_30.openapi}"
             )
             parser = OpenAPIParser(
@@ -81,7 +84,7 @@ def parse_openapi_to_http_routes(openapi_dict: dict[str, Any]) -> list[HTTPRoute
         else:
             # Default to OpenAPI 3.1 models
             openapi_31 = OpenAPI.model_validate(openapi_dict)
-            logger.info(
+            logger.debug(
                 f"Successfully parsed OpenAPI 3.1 schema version: {openapi_31.openapi}"
             )
             parser = OpenAPIParser(
@@ -207,7 +210,7 @@ class OpenAPIParser(
         try:
             resolved_schema = self._resolve_ref(schema_obj)
 
-            if isinstance(resolved_schema, (self.schema_cls)):
+            if isinstance(resolved_schema, self.schema_cls):
                 # Convert schema to dictionary
                 result = resolved_schema.model_dump(
                     mode="json", by_alias=True, exclude_none=True
@@ -220,7 +223,10 @@ class OpenAPIParser(
                 )
                 result = {}
 
-            return _replace_ref_with_defs(result)
+            # Convert refs from OpenAPI format to JSON Schema format using recursive approach
+
+            result = _replace_ref_with_defs(result)
+            return result
         except ValueError as e:
             # Re-raise ValueError for external reference errors and other validation issues
             if "External or non-local reference not supported" in str(e):
@@ -396,80 +402,235 @@ class OpenAPIParser(
             )
             return None
 
+    def _is_success_status_code(self, status_code: str) -> bool:
+        """Check if a status code represents a successful response (2xx)."""
+        try:
+            code_int = int(status_code)
+            return 200 <= code_int < 300
+        except (ValueError, TypeError):
+            # Handle special cases like 'default' or other non-numeric codes
+            return status_code.lower() in ["default", "2xx"]
+
+    def _get_primary_success_response(
+        self, operation_responses: dict[str, Any]
+    ) -> tuple[str, Any] | None:
+        """Get the primary success response for an MCP tool. We only need one success response."""
+        if not operation_responses:
+            return None
+
+        # Priority order: 200, 201, 202, 204, 207, then any other 2xx
+        priority_codes = ["200", "201", "202", "204", "207"]
+
+        # First check priority codes
+        for code in priority_codes:
+            if code in operation_responses:
+                return (code, operation_responses[code])
+
+        # Then check any other 2xx codes
+        for status_code, resp_or_ref in operation_responses.items():
+            if self._is_success_status_code(status_code):
+                return (status_code, resp_or_ref)
+
+        # If no success codes found, return None (tool will have no output schema)
+        return None
+
     def _extract_responses(
         self, operation_responses: dict[str, Any] | None
     ) -> dict[str, ResponseInfo]:
-        """Extract and resolve response information."""
+        """Extract and resolve response information. Only includes the primary success response for MCP tools."""
         extracted_responses: dict[str, ResponseInfo] = {}
 
         if not operation_responses:
             return extracted_responses
 
-        for status_code, resp_or_ref in operation_responses.items():
-            try:
-                response = self._resolve_ref(resp_or_ref)
+        # For MCP tools, we only need the primary success response
+        primary_response = self._get_primary_success_response(operation_responses)
+        if not primary_response:
+            logger.debug("No success responses found, tool will have no output schema")
+            return extracted_responses
 
-                if not isinstance(response, self.response_cls):
-                    logger.warning(
-                        f"Expected Response after resolving for status code {status_code}, "
-                        f"got {type(response)}. Skipping."
-                    )
-                    continue
+        status_code, resp_or_ref = primary_response
+        logger.debug(f"Using primary success response: {status_code}")
 
-                # Create response info
-                resp_info = ResponseInfo(description=response.description)
+        try:
+            response = self._resolve_ref(resp_or_ref)
 
-                # Extract content schemas
-                if hasattr(response, "content") and response.content:
-                    for media_type_str, media_type_obj in response.content.items():
-                        if (
-                            media_type_obj
-                            and hasattr(media_type_obj, "media_type_schema")
-                            and media_type_obj.media_type_schema
-                        ):
-                            try:
-                                schema_dict = self._extract_schema_as_dict(
-                                    media_type_obj.media_type_schema
-                                )
-                                resp_info.content_schema[media_type_str] = schema_dict
-                            except ValueError as e:
-                                # Re-raise ValueError for external reference errors
-                                if (
-                                    "External or non-local reference not supported"
-                                    in str(e)
-                                ):
-                                    raise
-                                logger.error(
-                                    f"Failed to extract schema for media type '{media_type_str}' "
-                                    f"in response {status_code}: {e}"
-                                )
-                            except Exception as e:
-                                logger.error(
-                                    f"Failed to extract schema for media type '{media_type_str}' "
-                                    f"in response {status_code}: {e}"
-                                )
-
-                extracted_responses[str(status_code)] = resp_info
-            except ValueError as e:
-                # Re-raise ValueError for external reference errors
-                if "External or non-local reference not supported" in str(e):
-                    raise
-                ref_name = getattr(resp_or_ref, "ref", "unknown")
-                logger.error(
-                    f"Failed to extract response for status code {status_code} "
-                    f"from reference '{ref_name}': {e}",
-                    exc_info=False,
-                )
-            except Exception as e:
-                ref_name = getattr(resp_or_ref, "ref", "unknown")
-                logger.error(
-                    f"Failed to extract response for status code {status_code} "
-                    f"from reference '{ref_name}': {e}",
-                    exc_info=False,
+            if not isinstance(response, self.response_cls):
+                logger.warning(
+                    f"Expected Response after resolving for status code {status_code}, "
+                    f"got {type(response)}. Returning empty responses."
                 )
+                return extracted_responses
+
+            # Create response info
+            resp_info = ResponseInfo(description=response.description)
+
+            # Extract content schemas
+            if hasattr(response, "content") and response.content:
+                for media_type_str, media_type_obj in response.content.items():
+                    if (
+                        media_type_obj
+                        and hasattr(media_type_obj, "media_type_schema")
+                        and media_type_obj.media_type_schema
+                    ):
+                        try:
+                            schema_dict = self._extract_schema_as_dict(
+                                media_type_obj.media_type_schema
+                            )
+                            resp_info.content_schema[media_type_str] = schema_dict
+                        except ValueError as e:
+                            # Re-raise ValueError for external reference errors
+                            if "External or non-local reference not supported" in str(
+                                e
+                            ):
+                                raise
+                            logger.error(
+                                f"Failed to extract schema for media type '{media_type_str}' "
+                                f"in response {status_code}: {e}"
+                            )
+                        except Exception as e:
+                            logger.error(
+                                f"Failed to extract schema for media type '{media_type_str}' "
+                                f"in response {status_code}: {e}"
+                            )
+
+            extracted_responses[str(status_code)] = resp_info
+        except ValueError as e:
+            # Re-raise ValueError for external reference errors
+            if "External or non-local reference not supported" in str(e):
+                raise
+            ref_name = getattr(resp_or_ref, "ref", "unknown")
+            logger.error(
+                f"Failed to extract response for status code {status_code} "
+                f"from reference '{ref_name}': {e}",
+                exc_info=False,
+            )
+        except Exception as e:
+            ref_name = getattr(resp_or_ref, "ref", "unknown")
+            logger.error(
+                f"Failed to extract response for status code {status_code} "
+                f"from reference '{ref_name}': {e}",
+                exc_info=False,
+            )
 
         return extracted_responses
 
+    def _extract_schema_dependencies(
+        self,
+        schema: dict,
+        all_schemas: dict[str, Any],
+        collected: set[str] | None = None,
+    ) -> set[str]:
+        """
+        Extract all schema names referenced by a schema (including transitive dependencies).
+
+        Args:
+            schema: The schema to analyze
+            all_schemas: All available schema definitions
+            collected: Set of already collected schema names (for recursion)
+
+        Returns:
+            Set of schema names that are referenced
+        """
+        if collected is None:
+            collected = set()
+
+        def find_refs(obj):
+            """Recursively find all $ref references."""
+            if isinstance(obj, dict):
+                if "$ref" in obj and isinstance(obj["$ref"], str):
+                    ref = obj["$ref"]
+                    # Handle both converted and unconverted refs
+                    if ref.startswith("#/$defs/"):
+                        schema_name = ref.split("/")[-1]
+                    elif ref.startswith("#/components/schemas/"):
+                        schema_name = ref.split("/")[-1]
+                    else:
+                        return
+
+                    # Add this schema and recursively find its dependencies
+                    if schema_name not in collected and schema_name in all_schemas:
+                        collected.add(schema_name)
+                        # Recursively find dependencies of this schema
+                        find_refs(all_schemas[schema_name])
+
+                # Continue searching in all values
+                for value in obj.values():
+                    find_refs(value)
+            elif isinstance(obj, list):
+                for item in obj:
+                    find_refs(item)
+
+        find_refs(schema)
+        return collected
+
+    def _extract_input_schema_dependencies(
+        self,
+        parameters: list[ParameterInfo],
+        request_body: RequestBodyInfo | None,
+        all_schemas: dict[str, Any],
+    ) -> dict[str, Any]:
+        """
+        Extract only the schema definitions needed for input (parameters and request body).
+
+        Args:
+            parameters: Route parameters
+            request_body: Route request body
+            all_schemas: All available schema definitions
+
+        Returns:
+            Dictionary containing only the schemas needed for input
+        """
+        needed_schemas = set()
+
+        # Check parameters for schema references
+        for param in parameters:
+            if param.schema_:
+                deps = self._extract_schema_dependencies(param.schema_, all_schemas)
+                needed_schemas.update(deps)
+
+        # Check request body for schema references
+        if request_body and request_body.content_schema:
+            for content_schema in request_body.content_schema.values():
+                deps = self._extract_schema_dependencies(content_schema, all_schemas)
+                needed_schemas.update(deps)
+
+        # Return only the needed input schemas
+        return {
+            name: all_schemas[name] for name in needed_schemas if name in all_schemas
+        }
+
+    def _extract_output_schema_dependencies(
+        self,
+        responses: dict[str, ResponseInfo],
+        all_schemas: dict[str, Any],
+    ) -> dict[str, Any]:
+        """
+        Extract only the schema definitions needed for outputs (responses).
+
+        Args:
+            responses: Route responses
+            all_schemas: All available schema definitions
+
+        Returns:
+            Dictionary containing only the schemas needed for outputs
+        """
+        needed_schemas = set()
+
+        # Check responses for schema references
+        for response in responses.values():
+            if response.content_schema:
+                for content_schema in response.content_schema.values():
+                    deps = self._extract_schema_dependencies(
+                        content_schema, all_schemas
+                    )
+                    needed_schemas.update(deps)
+
+        # Return only the needed output schemas
+        return {
+            name: all_schemas[name] for name in needed_schemas if name in all_schemas
+        }
+
     def parse(self) -> list[HTTPRoute]:
         """Parse the OpenAPI schema into HTTP routes."""
         routes: list[HTTPRoute] = []
@@ -499,6 +660,13 @@ class OpenAPIParser(
                             f"Failed to extract schema definition '{name}': {e}"
                         )
 
+        # Convert schema definitions refs from OpenAPI to JSON Schema format (once)
+        if schema_definitions:
+            # Convert each schema definition recursively
+            for name, schema in schema_definitions.items():
+                if isinstance(schema, dict):
+                    schema_definitions[name] = _replace_ref_with_defs(schema)
+
         # Process paths and operations
         for path_str, path_item_obj in self.openapi.paths.items():
             if not isinstance(path_item_obj, self.path_item_cls):
@@ -552,6 +720,17 @@ class OpenAPIParser(
                                 if k.startswith("x-")
                             }
 
+                        # Extract schemas separately for input and output
+                        input_schemas = self._extract_input_schema_dependencies(
+                            parameters,
+                            request_body_info,
+                            schema_definitions,
+                        )
+                        output_schemas = self._extract_output_schema_dependencies(
+                            responses,
+                            schema_definitions,
+                        )
+
                         # Create initial route without pre-calculated fields
                         route = HTTPRoute(
                             path=path_str,
@@ -563,7 +742,8 @@ class OpenAPIParser(
                             parameters=parameters,
                             request_body=request_body_info,
                             responses=responses,
-                            schema_definitions=schema_definitions,
+                            request_schemas=input_schemas,
+                            response_schemas=output_schemas,
                             extensions=extensions,
                             openapi_version=self.openapi_version,
                         )
@@ -571,7 +751,8 @@ class OpenAPIParser(
                         # Pre-calculate schema and parameter mapping for performance
                         try:
                             flat_schema, param_map = _combine_schemas_and_map_params(
-                                route
+                                route,
+                                convert_refs=False,  # Parser already converted refs
                             )
                             route.flat_param_schema = flat_schema
                             route.parameter_map = param_map
@@ -586,9 +767,6 @@ class OpenAPIParser(
                             }
                             route.parameter_map = {}
                         routes.append(route)
-                        logger.info(
-                            f"Successfully extracted route: {method_upper} {path_str}"
-                        )
                     except ValueError as op_error:
                         # Re-raise ValueError for external reference errors
                         if "External or non-local reference not supported" in str(
@@ -607,7 +785,7 @@ class OpenAPIParser(
                             exc_info=True,
                         )
 
-        logger.info(f"Finished parsing. Extracted {len(routes)} HTTP routes.")
+        logger.debug(f"Finished parsing. Extracted {len(routes)} HTTP routes.")
         return routes