fastmcp 2.10.5__py3-none-any.whl → 2.11.0__py3-none-any.whl

fastmcp/utilities/openapi.py

@@ -1,5 +1,4 @@
 import json
-import logging
 from typing import Any, Generic, Literal, TypeVar, cast
 
 from openapi_pydantic import (
@@ -24,10 +23,10 @@ from openapi_pydantic.v3.v3_0 import Response as Response_30
 from openapi_pydantic.v3.v3_0 import Schema as Schema_30
 from pydantic import BaseModel, Field, ValidationError
 
-from fastmcp.utilities.json_schema import compress_schema
+from fastmcp.utilities.logging import get_logger
 from fastmcp.utilities.types import FastMCPBaseModel
 
-logger = logging.getLogger(__name__)
+logger = get_logger(__name__)
 
 # --- Intermediate Representation (IR) Definition ---
 # (IR models remain the same)
@@ -102,8 +101,7 @@ def format_deep_object_parameter(
     According to OpenAPI 3.0 spec, deepObject style with explode=true serializes
     object properties as separate query parameters with bracket notation.
 
-    For example: {"id": "123", "type": "user"} becomes:
-    param[id]=123&param[type]=user
+    For example: `{"id": "123", "type": "user"}` becomes `param[id]=123&param[type]=user`.
 
     Args:
         param_value: Dictionary value to format
@@ -175,6 +173,7 @@ class HTTPRoute(FastMCPBaseModel):
         default_factory=dict
     )  # Store component schemas
     extensions: dict[str, Any] = Field(default_factory=dict)
+    openapi_version: str | None = None
 
 
 # Export public symbols
@@ -189,6 +188,7 @@ __all__ = [
     "parse_openapi_to_http_routes",
     "extract_output_schema_from_responses",
     "format_deep_object_parameter",
+    "_handle_nullable_fields",
 ]
 
 # Type variables for generic parser
@@ -228,6 +228,7 @@ def parse_openapi_to_http_routes(openapi_dict: dict[str, Any]) -> list[HTTPRoute
                 Response_30,
                 Operation_30,
                 PathItem_30,
+                openapi_version,
             )
             return parser.parse()
         else:
@@ -245,6 +246,7 @@ def parse_openapi_to_http_routes(openapi_dict: dict[str, Any]) -> list[HTTPRoute
                 Response,
                 Operation,
                 PathItem,
+                openapi_version,
             )
             return parser.parse()
     except ValidationError as e:
@@ -278,6 +280,7 @@ class OpenAPIParser(
         response_cls: type[TResponse],
         operation_cls: type[TOperation],
         path_item_cls: type[TPathItem],
+        openapi_version: str,
     ):
         """Initialize the parser with the OpenAPI schema and type classes."""
         self.openapi = openapi
@@ -288,6 +291,7 @@ class OpenAPIParser(
         self.response_cls = response_cls
         self.operation_cls = operation_cls
         self.path_item_cls = path_item_cls
+        self.openapi_version = openapi_version
 
     def _convert_to_parameter_location(self, param_in: str) -> ParameterLocation:
         """Convert string parameter location to our ParameterLocation type."""
@@ -710,6 +714,7 @@ class OpenAPIParser(
                             responses=responses,
                             schema_definitions=schema_definitions,
                             extensions=extensions,
+                            openapi_version=self.openapi_version,
                         )
                         routes.append(route)
                         logger.info(
@@ -1068,15 +1073,16 @@ def _replace_ref_with_defs(
     """
     schema = info.copy()
     if ref_path := schema.get("$ref"):
-        if ref_path.startswith("#/components/schemas/"):
-            schema_name = ref_path.split("/")[-1]
-            schema["$ref"] = f"#/$defs/{schema_name}"
-        elif not ref_path.startswith("#/"):
-            raise ValueError(
-                f"External or non-local reference not supported: {ref_path}. "
-                f"FastMCP only supports local schema references starting with '#/'. "
-                f"Please include all schema definitions within the OpenAPI document."
-            )
+        if isinstance(ref_path, str):
+            if ref_path.startswith("#/components/schemas/"):
+                schema_name = ref_path.split("/")[-1]
+                schema["$ref"] = f"#/$defs/{schema_name}"
+            elif not ref_path.startswith("#/"):
+                raise ValueError(
+                    f"External or non-local reference not supported: {ref_path}. "
+                    f"FastMCP only supports local schema references starting with '#/'. "
+                    f"Please include all schema definitions within the OpenAPI document."
+                )
     elif properties := schema.get("properties"):
         if "$ref" in properties:
             schema["properties"] = _replace_ref_with_defs(properties)
@@ -1095,6 +1101,156 @@ def _replace_ref_with_defs(
     return schema
 
 
+def _make_optional_parameter_nullable(schema: dict[str, Any]) -> dict[str, Any]:
+    """
+    Make an optional parameter schema nullable to allow None values.
+
+    For optional parameters, we need to allow null values in addition to the
+    specified type to handle cases where None is passed for optional parameters.
+    """
+    # If schema already has multiple types or is already nullable, don't modify
+    if "anyOf" in schema or "oneOf" in schema or "allOf" in schema:
+        return schema
+
+    # If it's already nullable (type includes null), don't modify
+    if isinstance(schema.get("type"), list) and "null" in schema["type"]:
+        return schema
+
+    # Create a new schema that allows null in addition to the original type
+    if "type" in schema:
+        original_type = schema["type"]
+
+        if isinstance(original_type, str):
+            # Single type - make it a union with null
+            # Optimize: avoid full schema copy by building directly
+            nested_non_nullable_schema = {
+                "type": original_type,
+            }
+            nullable_schema = {}
+
+            # Define type-specific properties that should move to nested schema
+            type_specific_properties = set()
+            if original_type == "array":
+                # https://json-schema.org/understanding-json-schema/reference/array
+                type_specific_properties = {
+                    "items",
+                    "prefixItems",
+                    "unevaluatedItems",
+                    "contains",
+                    "minContains",
+                    "maxContains",
+                    "minItems",
+                    "maxItems",
+                    "uniqueItems",
+                }
+            elif original_type == "object":
+                # https://json-schema.org/understanding-json-schema/reference/object
+                type_specific_properties = {
+                    "properties",
+                    "patternProperties",
+                    "additionalProperties",
+                    "unevaluatedProperties",
+                    "required",
+                    "propertyNames",
+                    "minProperties",
+                    "maxProperties",
+                }
+
+            # Efficiently distribute properties without copying the entire schema
+            for key, value in schema.items():
+                if key == "type":
+                    continue  # Already handled
+                elif key in type_specific_properties:
+                    nested_non_nullable_schema[key] = value
+                else:
+                    nullable_schema[key] = value
+
+            nullable_schema["anyOf"] = [nested_non_nullable_schema, {"type": "null"}]
+            return nullable_schema
+
+    return schema
+
+
+def _add_null_to_type(schema: dict[str, Any]) -> None:
+    """Add 'null' to the schema's type field or handle oneOf/anyOf/allOf constructs if not already present."""
+    if "type" in schema:
+        current_type = schema["type"]
+
+        if isinstance(current_type, str):
+            # Convert string type to array with null
+            schema["type"] = [current_type, "null"]
+        elif isinstance(current_type, list):
+            # Add null to array if not already present
+            if "null" not in current_type:
+                schema["type"] = current_type + ["null"]
+    elif "oneOf" in schema:
+        # Convert oneOf to anyOf with null type
+        schema["anyOf"] = schema.pop("oneOf") + [{"type": "null"}]
+    elif "anyOf" in schema:
+        # Add null type to anyOf if not already present
+        if not any(item.get("type") == "null" for item in schema["anyOf"]):
+            schema["anyOf"].append({"type": "null"})
+    elif "allOf" in schema:
+        # For allOf, wrap in anyOf with null - this means (all conditions) OR null
+        schema["anyOf"] = [{"allOf": schema.pop("allOf")}, {"type": "null"}]
+
+
+def _handle_nullable_fields(schema: dict[str, Any] | Any) -> dict[str, Any] | Any:
+    """Convert OpenAPI nullable fields to JSON Schema format: {"type": "string",
+    "nullable": true} -> {"type": ["string", "null"]}"""
+
+    if not isinstance(schema, dict):
+        return schema
+
+    # Check if we need to modify anything first to avoid unnecessary copying
+    has_root_nullable_field = "nullable" in schema
+    has_root_nullable_true = (
+        has_root_nullable_field
+        and schema["nullable"]
+        and (
+            "type" in schema
+            or "oneOf" in schema
+            or "anyOf" in schema
+            or "allOf" in schema
+        )
+    )
+
+    has_property_nullable_field = False
+    if "properties" in schema:
+        for prop_schema in schema["properties"].values():
+            if isinstance(prop_schema, dict) and "nullable" in prop_schema:
+                has_property_nullable_field = True
+                break
+
+    # If no nullable fields at all, return original schema unchanged
+    if not has_root_nullable_field and not has_property_nullable_field:
+        return schema
+
+    # Only copy if we need to modify
+    result = schema.copy()
+
+    # Handle root level nullable - always remove the field, convert type if true
+    if has_root_nullable_field:
+        result.pop("nullable")
+        if has_root_nullable_true:
+            _add_null_to_type(result)
+
+    # Handle properties nullable fields
+    if has_property_nullable_field and "properties" in result:
+        for prop_name, prop_schema in result["properties"].items():
+            if isinstance(prop_schema, dict) and "nullable" in prop_schema:
+                nullable_value = prop_schema.pop("nullable")
+                if nullable_value and (
+                    "type" in prop_schema
+                    or "oneOf" in prop_schema
+                    or "anyOf" in prop_schema
+                    or "allOf" in prop_schema
+                ):
+                    _add_null_to_type(prop_schema)
+
+    return result
+
+
 def _combine_schemas(route: HTTPRoute) -> dict[str, Any]:
     """
     Combines parameter and request body schemas into a single schema.
@@ -1156,15 +1312,23 @@ def _combine_schemas(route: HTTPRoute) -> dict[str, Any]:
             else:
                 param_schema["description"] = location_desc
 
+            # Don't make optional parameters nullable - they can simply be omitted
+            # The OpenAPI specification doesn't require optional parameters to accept null values
+
             properties[suffixed_name] = param_schema
         else:
             # No collision, use original name
             if param.required:
                 required.append(param.name)
-            properties[param.name] = _replace_ref_with_defs(
+            param_schema = _replace_ref_with_defs(
                 param.schema_.copy(), param.description
             )
 
+            # Don't make optional parameters nullable - they can simply be omitted
+            # The OpenAPI specification doesn't require optional parameters to accept null values
+
+            properties[param.name] = param_schema
+
     # Add request body properties (no suffixes for body parameters)
     if route.request_body and route.request_body.content_schema:
         for prop_name, prop_schema in body_props.items():
@@ -1180,10 +1344,42 @@ def _combine_schemas(route: HTTPRoute) -> dict[str, Any]:
     }
     # Add schema definitions if available
     if route.schema_definitions:
-        result["$defs"] = route.schema_definitions
-
-    # Use compress_schema to remove unused definitions
-    result = compress_schema(result)
+        result["$defs"] = route.schema_definitions.copy()
+
+    # Use lightweight compression - prune additionalProperties and unused definitions
+    if result.get("additionalProperties") is False:
+        result.pop("additionalProperties")
+
+    # Remove unused definitions (lightweight approach - just check direct $ref usage)
+    if "$defs" in result:
+        used_refs = set()
+
+        def find_refs_in_value(value):
+            if isinstance(value, dict):
+                if "$ref" in value and isinstance(value["$ref"], str):
+                    ref = value["$ref"]
+                    if ref.startswith("#/$defs/"):
+                        used_refs.add(ref.split("/")[-1])
+                for v in value.values():
+                    find_refs_in_value(v)
+            elif isinstance(value, list):
+                for item in value:
+                    find_refs_in_value(item)
+
+        # Find refs in the main schema (excluding $defs section)
+        for key, value in result.items():
+            if key != "$defs":
+                find_refs_in_value(value)
+
+        # Remove unused definitions
+        if used_refs:
+            result["$defs"] = {
+                name: def_schema
+                for name, def_schema in result["$defs"].items()
+                if name in used_refs
+            }
+        else:
+            result.pop("$defs")
 
     return result
 
@@ -1193,17 +1389,41 @@ def _adjust_union_types(
 ) -> dict[str, Any] | list[Any]:
     """Recursively replace 'oneOf' with 'anyOf' in schema to handle overlapping unions."""
     if isinstance(schema, dict):
-        if "oneOf" in schema:
-            schema["anyOf"] = schema.pop("oneOf")
-        for k, v in schema.items():
-            schema[k] = _adjust_union_types(v)
+        # Optimize: only copy if we need to modify something
+        has_one_of = "oneOf" in schema
+        needs_recursive_processing = False
+
+        # Check if we need recursive processing
+        for v in schema.values():
+            if isinstance(v, dict | list):
+                needs_recursive_processing = True
+                break
+
+        # If nothing to change, return original
+        if not has_one_of and not needs_recursive_processing:
+            return schema
+
+        # Work on a copy only when modification is needed
+        result = schema.copy()
+        if has_one_of:
+            result["anyOf"] = result.pop("oneOf")
+
+        # Only recurse where needed
+        if needs_recursive_processing:
+            for k, v in result.items():
+                if isinstance(v, dict | list):
+                    result[k] = _adjust_union_types(v)
+
+        return result
     elif isinstance(schema, list):
         return [_adjust_union_types(item) for item in schema]
     return schema
 
 
 def extract_output_schema_from_responses(
-    responses: dict[str, ResponseInfo], schema_definitions: dict[str, Any] | None = None
+    responses: dict[str, ResponseInfo],
+    schema_definitions: dict[str, Any] | None = None,
+    openapi_version: str | None = None,
 ) -> dict[str, Any] | None:
     """
     Extract output schema from OpenAPI responses for use as MCP tool output schema.
@@ -1215,6 +1435,7 @@ def extract_output_schema_from_responses(
     Args:
         responses: Dictionary of ResponseInfo objects keyed by status code
         schema_definitions: Optional schema definitions to include in the output schema
+        openapi_version: OpenAPI version string, used to optimize nullable field handling
 
     Returns:
         dict: MCP-compliant output schema with potential wrapping, or None if no suitable schema found
@@ -1271,6 +1492,21 @@ def extract_output_schema_from_responses(
     # Clean and copy the schema
     output_schema = schema.copy()
 
+    # If schema has a $ref, resolve it first before processing nullable fields
+    if "$ref" in output_schema and schema_definitions:
+        ref_path = output_schema["$ref"]
+        if ref_path.startswith("#/components/schemas/"):
+            schema_name = ref_path.split("/")[-1]
+            if schema_name in schema_definitions:
+                # Replace $ref with the actual schema definition
+                output_schema = schema_definitions[schema_name].copy()
+
+    # Handle OpenAPI nullable fields by converting them to JSON Schema format
+    # This prevents "None is not of type 'string'" validation errors
+    # Only needed for OpenAPI 3.0 - 3.1 uses standard JSON Schema null types
+    if openapi_version and openapi_version.startswith("3.0"):
+        output_schema = _handle_nullable_fields(output_schema)
+
     # MCP requires output schemas to be objects. If this schema is not an object,
     # we need to wrap it similar to how ParsedFunction.from_function() does it
     if output_schema.get("type") != "object":
@@ -1283,12 +1519,52 @@ def extract_output_schema_from_responses(
         }
         output_schema = wrapped_schema
 
-    # Add schema definitions if available
-    if schema_definitions:
-        output_schema["$defs"] = schema_definitions
-
-    # Use compress_schema to remove unused definitions
-    output_schema = compress_schema(output_schema)
+    # Add schema definitions if available and handle nullable fields in them
+    # Only add $defs if we didn't resolve the $ref inline above
+    if schema_definitions and "$ref" not in schema.copy():
+        processed_defs = {}
+        for def_name, def_schema in schema_definitions.items():
+            # Only handle nullable fields for OpenAPI 3.0 - 3.1 uses standard JSON Schema null types
+            if openapi_version and openapi_version.startswith("3.0"):
+                processed_defs[def_name] = _handle_nullable_fields(def_schema)
+            else:
+                processed_defs[def_name] = def_schema
+        output_schema["$defs"] = processed_defs
+
+    # Use lightweight compression - prune additionalProperties and unused definitions
+    if output_schema.get("additionalProperties") is False:
+        output_schema.pop("additionalProperties")
+
+    # Remove unused definitions (lightweight approach - just check direct $ref usage)
+    if "$defs" in output_schema:
+        used_refs = set()
+
+        def find_refs_in_value(value):
+            if isinstance(value, dict):
+                if "$ref" in value and isinstance(value["$ref"], str):
+                    ref = value["$ref"]
+                    if ref.startswith("#/$defs/"):
+                        used_refs.add(ref.split("/")[-1])
+                for v in value.values():
+                    find_refs_in_value(v)
+            elif isinstance(value, list):
+                for item in value:
+                    find_refs_in_value(item)
+
+        # Find refs in the main schema (excluding $defs section)
+        for key, value in output_schema.items():
+            if key != "$defs":
+                find_refs_in_value(value)
+
+        # Remove unused definitions
+        if used_refs:
+            output_schema["$defs"] = {
+                name: def_schema
+                for name, def_schema in output_schema["$defs"].items()
+                if name in used_refs
+            }
+        else:
+            output_schema.pop("$defs")
 
     # Adjust union types to handle overlapping unions
     output_schema = cast(dict[str, Any], _adjust_union_types(output_schema))

fastmcp/utilities/tests.py

@@ -8,10 +8,13 @@ import time
 from collections.abc import Callable, Generator
 from contextlib import contextmanager
 from typing import TYPE_CHECKING, Any, Literal
+from urllib.parse import parse_qs, urlparse
 
+import httpx
 import uvicorn
 
 from fastmcp import settings
+from fastmcp.client.auth.oauth import OAuth
 from fastmcp.utilities.http import find_available_port
 
 if TYPE_CHECKING:
@@ -37,21 +40,18 @@ def temporary_settings(**kwargs: Any):
         assert fastmcp.settings.log_level == 'INFO'
         ```
     """
-    old_settings = copy.deepcopy(settings.model_dump())
+    old_settings = copy.deepcopy(settings)
 
     try:
         # apply the new settings
         for attr, value in kwargs.items():
-            if not hasattr(settings, attr):
-                raise AttributeError(f"Setting {attr} does not exist.")
-            setattr(settings, attr, value)
+            settings.set_setting(attr, value)
         yield
 
     finally:
         # restore the old settings
         for attr in kwargs:
-            if hasattr(settings, attr):
-                setattr(settings, attr, old_settings[attr])
+            settings.set_setting(attr, old_settings.get_setting(attr))
 
 
 def _run_server(mcp_server: FastMCP, transport: Literal["sse"], port: int) -> None:
@@ -142,3 +142,51 @@ def caplog_for_fastmcp(caplog):
         yield
     finally:
         logger.removeHandler(caplog.handler)
+
+
+class HeadlessOAuth(OAuth):
+    """
+    OAuth provider that bypasses browser interaction for testing.
+
+    This simulates the complete OAuth flow programmatically by making HTTP requests
+    instead of opening a browser and running a callback server. Useful for automated testing.
+    """
+
+    def __init__(self, mcp_url: str, **kwargs):
+        """Initialize HeadlessOAuth with stored response tracking."""
+        self._stored_response = None
+        super().__init__(mcp_url, **kwargs)
+
+    async def redirect_handler(self, authorization_url: str) -> None:
+        """Make HTTP request to authorization URL and store response for callback handler."""
+        async with httpx.AsyncClient() as client:
+            response = await client.get(authorization_url, follow_redirects=False)
+            self._stored_response = response
+
+    async def callback_handler(self) -> tuple[str, str | None]:
+        """Parse stored response and return (auth_code, state)."""
+        if not self._stored_response:
+            raise RuntimeError(
+                "No authorization response stored. redirect_handler must be called first."
+            )
+
+        response = self._stored_response
+
+        # Extract auth code from redirect location
+        if response.status_code == 302:
+            redirect_url = response.headers["location"]
+            parsed = urlparse(redirect_url)
+            query_params = parse_qs(parsed.query)
+
+            if "error" in query_params:
+                error = query_params["error"][0]
+                error_desc = query_params.get("error_description", ["Unknown error"])[0]
+                raise RuntimeError(
+                    f"OAuth authorization failed: {error} - {error_desc}"
+                )
+
+            auth_code = query_params["code"][0]
+            state = query_params.get("state", [None])[0]
+            return auth_code, state
+        else:
+            raise RuntimeError(f"Authorization failed: {response.status_code}")