fastmcp 2.10.6__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(
@@ -1117,16 +1122,17 @@ def _make_optional_parameter_nullable(schema: dict[str, Any]) -> dict[str, Any]:
 
         if isinstance(original_type, str):
             # Single type - make it a union with null
-            nullable_schema = schema.copy()
-
+            # Optimize: avoid full schema copy by building directly
             nested_non_nullable_schema = {
                 "type": original_type,
             }
+            nullable_schema = {}
 
-            # If the original type is an array, move the array-specific properties into the now-nested schema
-            # https://json-schema.org/understanding-json-schema/reference/array
+            # Define type-specific properties that should move to nested schema
+            type_specific_properties = set()
             if original_type == "array":
-                for array_property in [
+                # https://json-schema.org/understanding-json-schema/reference/array
+                type_specific_properties = {
                     "items",
                     "prefixItems",
                     "unevaluatedItems",
@@ -1136,17 +1142,10 @@ def _make_optional_parameter_nullable(schema: dict[str, Any]) -> dict[str, Any]:
                     "minItems",
                     "maxItems",
                     "uniqueItems",
-                ]:
-                    if array_property in nullable_schema:
-                        nested_non_nullable_schema[array_property] = nullable_schema[
-                            array_property
-                        ]
-                        del nullable_schema[array_property]
-
-            # If the original type is an object, move the object-specific properties into the now-nested schema
-            # https://json-schema.org/understanding-json-schema/reference/object
+                }
             elif original_type == "object":
-                for object_property in [
+                # https://json-schema.org/understanding-json-schema/reference/object
+                type_specific_properties = {
                     "properties",
                     "patternProperties",
                     "additionalProperties",
@@ -1155,22 +1154,103 @@ def _make_optional_parameter_nullable(schema: dict[str, Any]) -> dict[str, Any]:
                     "propertyNames",
                     "minProperties",
                     "maxProperties",
-                ]:
-                    if object_property in nullable_schema:
-                        nested_non_nullable_schema[object_property] = nullable_schema[
-                            object_property
-                        ]
-                        del nullable_schema[object_property]
+                }
 
-            nullable_schema["anyOf"] = [nested_non_nullable_schema, {"type": "null"}]
+            # 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
 
-            # Remove the original type since we're using anyOf
-            del nullable_schema["type"]
+            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.
@@ -1232,9 +1312,8 @@ def _combine_schemas(route: HTTPRoute) -> dict[str, Any]:
             else:
                 param_schema["description"] = location_desc
 
-            # Make optional parameters nullable to allow None values
-            if not param.required:
-                param_schema = _make_optional_parameter_nullable(param_schema)
+            # 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:
@@ -1245,9 +1324,8 @@ def _combine_schemas(route: HTTPRoute) -> dict[str, Any]:
                 param.schema_.copy(), param.description
             )
 
-            # Make optional parameters nullable to allow None values
-            if not param.required:
-                param_schema = _make_optional_parameter_nullable(param_schema)
+            # 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
 
@@ -1266,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
 
@@ -1279,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.
@@ -1301,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
@@ -1357,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":
@@ -1369,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}")

fastmcp/utilities/types.py

@@ -8,11 +8,19 @@ from collections.abc import Callable
 from functools import lru_cache
 from pathlib import Path
 from types import EllipsisType, UnionType
-from typing import Annotated, TypeAlias, TypeVar, Union, get_args, get_origin
+from typing import (
+    Annotated,
+    TypeAlias,
+    TypeVar,
+    Union,
+    get_args,
+    get_origin,
+    get_type_hints,
+)
 
 import mcp.types
 from mcp.types import Annotations
-from pydantic import AnyUrl, BaseModel, ConfigDict, TypeAdapter, UrlConstraints
+from pydantic import AnyUrl, BaseModel, ConfigDict, Field, TypeAdapter, UrlConstraints
 
 T = TypeVar("T")
 
@@ -35,6 +43,66 @@ def get_cached_typeadapter(cls: T) -> TypeAdapter[T]:
     However, this isn't feasible for user-generated functions. Instead, we use a
     cache to minimize the cost of creating them as much as possible.
     """
+    # For functions, process annotations to handle forward references and convert
+    # Annotated[Type, "string"] to Annotated[Type, Field(description="string")]
+    if inspect.isfunction(cls) or inspect.ismethod(cls):
+        if hasattr(cls, "__annotations__") and cls.__annotations__:
+            try:
+                # Resolve forward references first
+                resolved_hints = get_type_hints(cls, include_extras=True)
+            except Exception:
+                # If forward reference resolution fails, use original annotations
+                resolved_hints = cls.__annotations__
+
+            # Process annotations to convert string descriptions to Fields
+            processed_hints = {}
+
+            for name, annotation in resolved_hints.items():
+                # Check if this is Annotated[Type, "string"] and convert to Annotated[Type, Field(description="string")]
+                if (
+                    get_origin(annotation) is Annotated
+                    and len(get_args(annotation)) == 2
+                    and isinstance(get_args(annotation)[1], str)
+                ):
+                    base_type, description = get_args(annotation)
+                    processed_hints[name] = Annotated[
+                        base_type, Field(description=description)
+                    ]
+                else:
+                    processed_hints[name] = annotation
+
+            # Create new function if annotations changed
+            if processed_hints != cls.__annotations__:
+                import types
+
+                # Handle both functions and methods
+                if inspect.ismethod(cls):
+                    actual_func = cls.__func__
+                    code = actual_func.__code__
+                    globals_dict = actual_func.__globals__
+                    name = actual_func.__name__
+                    defaults = actual_func.__defaults__
+                    closure = actual_func.__closure__
+                else:
+                    code = cls.__code__
+                    globals_dict = cls.__globals__
+                    name = cls.__name__
+                    defaults = cls.__defaults__
+                    closure = cls.__closure__
+
+                new_func = types.FunctionType(
+                    code,
+                    globals_dict,
+                    name,
+                    defaults,
+                    closure,
+                )
+                new_func.__dict__.update(cls.__dict__)
+                new_func.__module__ = cls.__module__
+                new_func.__qualname__ = getattr(cls, "__qualname__", cls.__name__)
+                new_func.__annotations__ = processed_hints
+                return TypeAdapter(new_func)
+
     return TypeAdapter(cls)
 
 
@@ -77,12 +145,21 @@ def find_kwarg_by_type(fn: Callable, kwarg_type: type) -> str | None:
     Includes union types that contain the kwarg_type, as well as Annotated types.
     """
     if inspect.ismethod(fn) and hasattr(fn, "__func__"):
-        sig = inspect.signature(fn.__func__)
-    else:
-        sig = inspect.signature(fn)
+        fn = fn.__func__
 
+    # Try to get resolved type hints
+    try:
+        # Use include_extras=True to preserve Annotated metadata
+        type_hints = get_type_hints(fn, include_extras=True)
+    except Exception:
+        # If resolution fails, use raw annotations if they exist
+        type_hints = getattr(fn, "__annotations__", {})
+
+    sig = inspect.signature(fn)
     for name, param in sig.parameters.items():
-        if is_class_member_of_type(param.annotation, kwarg_type):
+        # Use resolved hint if available, otherwise raw annotation
+        annotation = type_hints.get(name, param.annotation)
+        if is_class_member_of_type(annotation, kwarg_type):
             return name
     return None
 
@@ -303,12 +380,13 @@ def replace_type(type_, type_map: dict[type, type]):
         new_type: The type to replace old_type with.
 
     Examples:
-        >>> replace_type(list[int | bool], {int: str})
-        list[str | bool]
-
-        >>> replace_type(list[list[int]], {int: str})
-        list[list[str]]
+    ```python
+    >>> replace_type(list[int | bool], {int: str})
+    list[str | bool]
 
+    >>> replace_type(list[list[int]], {int: str})
+    list[list[str]]
+    ```
     """
     if type_ in type_map:
         return type_map[type_]