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

fastmcp/experimental/utilities/openapi/formatters.py

@@ -0,0 +1,355 @@
+"""Parameter formatting functions for OpenAPI operations."""
+
+import json
+import logging
+from typing import Any
+
+from .models import JsonSchema, ParameterInfo, RequestBodyInfo
+
+logger = logging.getLogger(__name__)
+
+
+def format_array_parameter(
+    values: list, parameter_name: str, is_query_parameter: bool = False
+) -> str | list:
+    """
+    Format an array parameter according to OpenAPI specifications.
+
+    Args:
+        values: List of values to format
+        parameter_name: Name of the parameter (for error messages)
+        is_query_parameter: If True, can return list for explode=True behavior
+
+    Returns:
+        String (comma-separated) or list (for query params with explode=True)
+    """
+    # For arrays of simple types (strings, numbers, etc.), join with commas
+    if all(isinstance(item, str | int | float | bool) for item in values):
+        return ",".join(str(v) for v in values)
+
+    # For complex types, try to create a simpler representation
+    try:
+        # Try to create a simple string representation
+        formatted_parts = []
+        for item in values:
+            if isinstance(item, dict):
+                # For objects, serialize key-value pairs
+                item_parts = []
+                for k, v in item.items():
+                    item_parts.append(f"{k}:{v}")
+                formatted_parts.append(".".join(item_parts))
+            else:
+                formatted_parts.append(str(item))
+
+        return ",".join(formatted_parts)
+    except Exception as e:
+        param_type = "query" if is_query_parameter else "path"
+        logger.warning(
+            f"Failed to format complex array {param_type} parameter '{parameter_name}': {e}"
+        )
+
+        if is_query_parameter:
+            # For query parameters, fallback to original list
+            return values
+        else:
+            # For path parameters, fallback to string representation without Python syntax
+            str_value = (
+                str(values)
+                .replace("[", "")
+                .replace("]", "")
+                .replace("'", "")
+                .replace('"', "")
+            )
+            return str_value
+
+
+def format_deep_object_parameter(
+    param_value: dict, parameter_name: str
+) -> dict[str, str]:
+    """
+    Format a dictionary parameter for deepObject style serialization.
+
+    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
+
+    Args:
+        param_value: Dictionary value to format
+        parameter_name: Name of the parameter
+
+    Returns:
+        Dictionary with bracketed parameter names as keys
+    """
+    if not isinstance(param_value, dict):
+        logger.warning(
+            f"deepObject style parameter '{parameter_name}' expected dict, got {type(param_value)}"
+        )
+        return {}
+
+    result = {}
+    for key, value in param_value.items():
+        # Format as param[key]=value
+        bracketed_key = f"{parameter_name}[{key}]"
+        result[bracketed_key] = str(value)
+
+    return result
+
+
+def generate_example_from_schema(schema: JsonSchema | None) -> Any:
+    """
+    Generate a simple example value from a JSON schema dictionary.
+    Very basic implementation focusing on types.
+    """
+    if not schema or not isinstance(schema, dict):
+        return "unknown"  # Or None?
+
+    # Use default value if provided
+    if "default" in schema:
+        return schema["default"]
+    # Use first enum value if provided
+    if "enum" in schema and isinstance(schema["enum"], list) and schema["enum"]:
+        return schema["enum"][0]
+    # Use first example if provided
+    if (
+        "examples" in schema
+        and isinstance(schema["examples"], list)
+        and schema["examples"]
+    ):
+        return schema["examples"][0]
+    if "example" in schema:
+        return schema["example"]
+
+    schema_type = schema.get("type")
+
+    if schema_type == "object":
+        result = {}
+        properties = schema.get("properties", {})
+        if isinstance(properties, dict):
+            # Generate example for first few properties or required ones? Limit complexity.
+            required_props = set(schema.get("required", []))
+            props_to_include = list(properties.keys())[
+                :3
+            ]  # Limit to first 3 for brevity
+            for prop_name in props_to_include:
+                if prop_name in properties:
+                    result[prop_name] = generate_example_from_schema(
+                        properties[prop_name]
+                    )
+            # Ensure required props are present if possible
+            for req_prop in required_props:
+                if req_prop not in result and req_prop in properties:
+                    result[req_prop] = generate_example_from_schema(
+                        properties[req_prop]
+                    )
+        return result if result else {"key": "value"}  # Basic object if no props
+
+    elif schema_type == "array":
+        items_schema = schema.get("items")
+        if isinstance(items_schema, dict):
+            # Generate one example item
+            item_example = generate_example_from_schema(items_schema)
+            return [item_example] if item_example is not None else []
+        return ["example_item"]  # Fallback
+
+    elif schema_type == "string":
+        format_type = schema.get("format")
+        if format_type == "date-time":
+            return "2024-01-01T12:00:00Z"
+        if format_type == "date":
+            return "2024-01-01"
+        if format_type == "email":
+            return "user@example.com"
+        if format_type == "uuid":
+            return "123e4567-e89b-12d3-a456-426614174000"
+        if format_type == "byte":
+            return "ZXhhbXBsZQ=="  # "example" base64
+        return "string"
+
+    elif schema_type == "integer":
+        return 1
+    elif schema_type == "number":
+        return 1.5
+    elif schema_type == "boolean":
+        return True
+    elif schema_type == "null":
+        return None
+
+    # Fallback if type is unknown or missing
+    return "unknown_type"
+
+
+def format_json_for_description(data: Any, indent: int = 2) -> str:
+    """Formats Python data as a JSON string block for markdown."""
+    try:
+        json_str = json.dumps(data, indent=indent)
+        return f"```json\n{json_str}\n```"
+    except TypeError:
+        return f"```\nCould not serialize to JSON: {data}\n```"
+
+
+def format_description_with_responses(
+    base_description: str,
+    responses: dict[
+        str, Any
+    ],  # Changed from specific ResponseInfo type to avoid circular imports
+    parameters: list[ParameterInfo] | None = None,  # Add parameters parameter
+    request_body: RequestBodyInfo | None = None,  # Add request_body parameter
+) -> str:
+    """
+    Formats the base description string with response, parameter, and request body information.
+
+    Args:
+        base_description (str): The initial description to be formatted.
+        responses (dict[str, Any]): A dictionary of response information, keyed by status code.
+        parameters (list[ParameterInfo] | None, optional): A list of parameter information,
+            including path and query parameters. Each parameter includes details such as name,
+            location, whether it is required, and a description.
+        request_body (RequestBodyInfo | None, optional): Information about the request body,
+            including its description, whether it is required, and its content schema.
+
+    Returns:
+        str: The formatted description string with additional details about responses, parameters,
+        and the request body.
+    """
+    desc_parts = [base_description]
+
+    # Add parameter information
+    if parameters:
+        # Process path parameters
+        path_params = [p for p in parameters if p.location == "path"]
+        if path_params:
+            param_section = "\n\n**Path Parameters:**"
+            desc_parts.append(param_section)
+            for param in path_params:
+                required_marker = " (Required)" if param.required else ""
+                param_desc = f"\n- **{param.name}**{required_marker}: {param.description or 'No description.'}"
+                desc_parts.append(param_desc)
+
+        # Process query parameters
+        query_params = [p for p in parameters if p.location == "query"]
+        if query_params:
+            param_section = "\n\n**Query Parameters:**"
+            desc_parts.append(param_section)
+            for param in query_params:
+                required_marker = " (Required)" if param.required else ""
+                param_desc = f"\n- **{param.name}**{required_marker}: {param.description or 'No description.'}"
+                desc_parts.append(param_desc)
+
+    # Add request body information if present
+    if request_body and request_body.description:
+        req_body_section = "\n\n**Request Body:**"
+        desc_parts.append(req_body_section)
+        required_marker = " (Required)" if request_body.required else ""
+        desc_parts.append(f"\n{request_body.description}{required_marker}")
+
+        # Add request body property descriptions if available
+        if request_body.content_schema:
+            media_type = (
+                "application/json"
+                if "application/json" in request_body.content_schema
+                else next(iter(request_body.content_schema), None)
+            )
+            if media_type:
+                schema = request_body.content_schema.get(media_type, {})
+                if isinstance(schema, dict) and "properties" in schema:
+                    desc_parts.append("\n\n**Request Properties:**")
+                    for prop_name, prop_schema in schema["properties"].items():
+                        if (
+                            isinstance(prop_schema, dict)
+                            and "description" in prop_schema
+                        ):
+                            required = prop_name in schema.get("required", [])
+                            req_mark = " (Required)" if required else ""
+                            desc_parts.append(
+                                f"\n- **{prop_name}**{req_mark}: {prop_schema['description']}"
+                            )
+
+    # Add response information
+    if responses:
+        response_section = "\n\n**Responses:**"
+        added_response_section = False
+
+        # Determine success codes (common ones)
+        success_codes = {"200", "201", "202", "204"}  # As strings
+        success_status = next((s for s in success_codes if s in responses), None)
+
+        # Process all responses
+        responses_to_process = responses.items()
+
+        for status_code, resp_info in sorted(responses_to_process):
+            if not added_response_section:
+                desc_parts.append(response_section)
+                added_response_section = True
+
+            status_marker = " (Success)" if status_code == success_status else ""
+            desc_parts.append(
+                f"\n- **{status_code}**{status_marker}: {resp_info.description or 'No description.'}"
+            )
+
+            # Process content schemas for this response
+            if resp_info.content_schema:
+                # Prioritize json, then take first available
+                media_type = (
+                    "application/json"
+                    if "application/json" in resp_info.content_schema
+                    else next(iter(resp_info.content_schema), None)
+                )
+
+                if media_type:
+                    schema = resp_info.content_schema.get(media_type)
+                    desc_parts.append(f"  - Content-Type: `{media_type}`")
+
+                    # Add response property descriptions
+                    if isinstance(schema, dict):
+                        # Handle array responses
+                        if schema.get("type") == "array" and "items" in schema:
+                            items_schema = schema["items"]
+                            if (
+                                isinstance(items_schema, dict)
+                                and "properties" in items_schema
+                            ):
+                                desc_parts.append("\n  - **Response Item Properties:**")
+                                for prop_name, prop_schema in items_schema[
+                                    "properties"
+                                ].items():
+                                    if (
+                                        isinstance(prop_schema, dict)
+                                        and "description" in prop_schema
+                                    ):
+                                        desc_parts.append(
+                                            f"\n    - **{prop_name}**: {prop_schema['description']}"
+                                        )
+                        # Handle object responses
+                        elif "properties" in schema:
+                            desc_parts.append("\n  - **Response Properties:**")
+                            for prop_name, prop_schema in schema["properties"].items():
+                                if (
+                                    isinstance(prop_schema, dict)
+                                    and "description" in prop_schema
+                                ):
+                                    desc_parts.append(
+                                        f"\n    - **{prop_name}**: {prop_schema['description']}"
+                                    )
+
+                    # Generate Example
+                    if schema:
+                        example = generate_example_from_schema(schema)
+                        if example != "unknown_type" and example is not None:
+                            desc_parts.append("\n  - **Example:**")
+                            desc_parts.append(
+                                format_json_for_description(example, indent=2)
+                            )
+
+    return "\n".join(desc_parts)
+
+
+# Export public symbols
+__all__ = [
+    "format_array_parameter",
+    "format_deep_object_parameter",
+    "format_description_with_responses",
+    "format_json_for_description",
+    "generate_example_from_schema",
+]

fastmcp/experimental/utilities/openapi/json_schema_converter.py

@@ -0,0 +1,340 @@
+"""
+Clean OpenAPI 3.0 to JSON Schema converter for the experimental parser.
+
+This module provides a systematic approach to converting OpenAPI 3.0 schemas
+to JSON Schema, inspired by py-openapi-schema-to-json-schema but optimized
+for our specific use case.
+"""
+
+from typing import Any
+
+from fastmcp.utilities.logging import get_logger
+
+logger = get_logger(__name__)
+
+# OpenAPI-specific fields that should be removed from JSON Schema
+OPENAPI_SPECIFIC_FIELDS = {
+    "nullable",  # Handled by converting to type arrays
+    "discriminator",  # OpenAPI-specific
+    "readOnly",  # OpenAPI-specific metadata
+    "writeOnly",  # OpenAPI-specific metadata
+    "xml",  # OpenAPI-specific metadata
+    "externalDocs",  # OpenAPI-specific metadata
+    "deprecated",  # Can be kept but not part of JSON Schema core
+}
+
+# Fields that should be recursively processed
+RECURSIVE_FIELDS = {
+    "properties": dict,
+    "items": dict,
+    "additionalProperties": dict,
+    "allOf": list,
+    "anyOf": list,
+    "oneOf": list,
+    "not": dict,
+}
+
+
+def convert_openapi_schema_to_json_schema(
+    schema: dict[str, Any],
+    openapi_version: str | None = None,
+    remove_read_only: bool = False,
+    remove_write_only: bool = False,
+    convert_one_of_to_any_of: bool = True,
+) -> dict[str, Any]:
+    """
+    Convert an OpenAPI schema to JSON Schema format.
+
+    This is a clean, systematic approach that:
+    1. Removes OpenAPI-specific fields
+    2. Converts nullable fields to type arrays (for OpenAPI 3.0 only)
+    3. Converts oneOf to anyOf for overlapping union handling
+    4. Recursively processes nested schemas
+    5. Optionally removes readOnly/writeOnly properties
+
+    Args:
+        schema: OpenAPI schema dictionary
+        openapi_version: OpenAPI version for optimization
+        remove_read_only: Whether to remove readOnly properties
+        remove_write_only: Whether to remove writeOnly properties
+        convert_one_of_to_any_of: Whether to convert oneOf to anyOf
+
+    Returns:
+        JSON Schema compatible dictionary
+    """
+    if not isinstance(schema, dict):
+        return schema
+
+    # Early exit optimization - check if conversion is needed
+    needs_conversion = (
+        any(field in schema for field in OPENAPI_SPECIFIC_FIELDS)
+        or (remove_read_only and _has_read_only_properties(schema))
+        or (remove_write_only and _has_write_only_properties(schema))
+        or (convert_one_of_to_any_of and "oneOf" in schema)
+        or _needs_recursive_processing(
+            schema,
+            openapi_version,
+            remove_read_only,
+            remove_write_only,
+            convert_one_of_to_any_of,
+        )
+    )
+
+    if not needs_conversion:
+        return schema
+
+    # Work on a copy to avoid mutation
+    result = schema.copy()
+
+    # Step 1: Handle nullable field conversion (OpenAPI 3.0 only)
+    if openapi_version and openapi_version.startswith("3.0"):
+        result = _convert_nullable_field(result)
+
+    # Step 2: Convert oneOf to anyOf if requested
+    if convert_one_of_to_any_of and "oneOf" in result:
+        result["anyOf"] = result.pop("oneOf")
+
+    # Step 3: Remove OpenAPI-specific fields
+    for field in OPENAPI_SPECIFIC_FIELDS:
+        result.pop(field, None)
+
+    # Step 4: Handle readOnly/writeOnly property removal
+    if remove_read_only or remove_write_only:
+        result = _filter_properties_by_access(
+            result, remove_read_only, remove_write_only
+        )
+
+    # Step 5: Recursively process nested schemas
+    for field_name, field_type in RECURSIVE_FIELDS.items():
+        if field_name in result:
+            if field_type is dict and isinstance(result[field_name], dict):
+                if field_name == "properties":
+                    # Handle properties specially - each property is a schema
+                    result[field_name] = {
+                        prop_name: convert_openapi_schema_to_json_schema(
+                            prop_schema,
+                            openapi_version,
+                            remove_read_only,
+                            remove_write_only,
+                            convert_one_of_to_any_of,
+                        )
+                        if isinstance(prop_schema, dict)
+                        else prop_schema
+                        for prop_name, prop_schema in result[field_name].items()
+                    }
+                else:
+                    result[field_name] = convert_openapi_schema_to_json_schema(
+                        result[field_name],
+                        openapi_version,
+                        remove_read_only,
+                        remove_write_only,
+                        convert_one_of_to_any_of,
+                    )
+            elif field_type is list and isinstance(result[field_name], list):
+                result[field_name] = [
+                    convert_openapi_schema_to_json_schema(
+                        item,
+                        openapi_version,
+                        remove_read_only,
+                        remove_write_only,
+                        convert_one_of_to_any_of,
+                    )
+                    if isinstance(item, dict)
+                    else item
+                    for item in result[field_name]
+                ]
+
+    return result
+
+
+def _convert_nullable_field(schema: dict[str, Any]) -> dict[str, Any]:
+    """Convert OpenAPI nullable field to JSON Schema type array."""
+    if "nullable" not in schema:
+        return schema
+
+    result = schema.copy()
+    nullable_value = result.pop("nullable")
+
+    # Only convert if nullable is True and we have a type structure
+    if not nullable_value:
+        return result
+
+    if "type" in result:
+        current_type = result["type"]
+        if isinstance(current_type, str):
+            result["type"] = [current_type, "null"]
+        elif isinstance(current_type, list) and "null" not in current_type:
+            result["type"] = current_type + ["null"]
+    elif "oneOf" in result:
+        # Convert oneOf to anyOf with null
+        result["anyOf"] = result.pop("oneOf") + [{"type": "null"}]
+    elif "anyOf" in result:
+        # Add null to anyOf if not present
+        if not any(item.get("type") == "null" for item in result["anyOf"]):
+            result["anyOf"].append({"type": "null"})
+    elif "allOf" in result:
+        # Wrap allOf in anyOf with null option
+        result["anyOf"] = [{"allOf": result.pop("allOf")}, {"type": "null"}]
+
+    return result
+
+
+def _has_read_only_properties(schema: dict[str, Any]) -> bool:
+    """Quick check if schema has any readOnly properties."""
+    if "properties" not in schema:
+        return False
+    return any(
+        isinstance(prop, dict) and prop.get("readOnly")
+        for prop in schema["properties"].values()
+    )
+
+
+def _has_write_only_properties(schema: dict[str, Any]) -> bool:
+    """Quick check if schema has any writeOnly properties."""
+    if "properties" not in schema:
+        return False
+    return any(
+        isinstance(prop, dict) and prop.get("writeOnly")
+        for prop in schema["properties"].values()
+    )
+
+
+def _needs_recursive_processing(
+    schema: dict[str, Any],
+    openapi_version: str | None,
+    remove_read_only: bool,
+    remove_write_only: bool,
+    convert_one_of_to_any_of: bool,
+) -> bool:
+    """Check if the schema needs recursive processing (smarter than just checking for recursive fields)."""
+    for field_name, field_type in RECURSIVE_FIELDS.items():
+        if field_name in schema:
+            if field_type is dict and isinstance(schema[field_name], dict):
+                if field_name == "properties":
+                    # Check if any property needs conversion
+                    for prop_schema in schema[field_name].values():
+                        if isinstance(prop_schema, dict):
+                            nested_needs_conversion = (
+                                any(
+                                    field in prop_schema
+                                    for field in OPENAPI_SPECIFIC_FIELDS
+                                )
+                                or (remove_read_only and prop_schema.get("readOnly"))
+                                or (remove_write_only and prop_schema.get("writeOnly"))
+                                or (convert_one_of_to_any_of and "oneOf" in prop_schema)
+                                or _needs_recursive_processing(
+                                    prop_schema,
+                                    openapi_version,
+                                    remove_read_only,
+                                    remove_write_only,
+                                    convert_one_of_to_any_of,
+                                )
+                            )
+                            if nested_needs_conversion:
+                                return True
+                else:
+                    # Check if nested schema needs conversion
+                    nested_needs_conversion = (
+                        any(
+                            field in schema[field_name]
+                            for field in OPENAPI_SPECIFIC_FIELDS
+                        )
+                        or (
+                            remove_read_only
+                            and _has_read_only_properties(schema[field_name])
+                        )
+                        or (
+                            remove_write_only
+                            and _has_write_only_properties(schema[field_name])
+                        )
+                        or (convert_one_of_to_any_of and "oneOf" in schema[field_name])
+                        or _needs_recursive_processing(
+                            schema[field_name],
+                            openapi_version,
+                            remove_read_only,
+                            remove_write_only,
+                            convert_one_of_to_any_of,
+                        )
+                    )
+                    if nested_needs_conversion:
+                        return True
+            elif field_type is list and isinstance(schema[field_name], list):
+                # Check if any list item needs conversion
+                for item in schema[field_name]:
+                    if isinstance(item, dict):
+                        nested_needs_conversion = (
+                            any(field in item for field in OPENAPI_SPECIFIC_FIELDS)
+                            or (remove_read_only and _has_read_only_properties(item))
+                            or (remove_write_only and _has_write_only_properties(item))
+                            or (convert_one_of_to_any_of and "oneOf" in item)
+                            or _needs_recursive_processing(
+                                item,
+                                openapi_version,
+                                remove_read_only,
+                                remove_write_only,
+                                convert_one_of_to_any_of,
+                            )
+                        )
+                        if nested_needs_conversion:
+                            return True
+    return False
+
+
+def _filter_properties_by_access(
+    schema: dict[str, Any], remove_read_only: bool, remove_write_only: bool
+) -> dict[str, Any]:
+    """Remove readOnly and/or writeOnly properties from schema."""
+    if "properties" not in schema:
+        return schema
+
+    result = schema.copy()
+    filtered_properties = {}
+
+    for prop_name, prop_schema in result["properties"].items():
+        if not isinstance(prop_schema, dict):
+            filtered_properties[prop_name] = prop_schema
+            continue
+
+        should_remove = (remove_read_only and prop_schema.get("readOnly")) or (
+            remove_write_only and prop_schema.get("writeOnly")
+        )
+
+        if not should_remove:
+            filtered_properties[prop_name] = prop_schema
+
+    result["properties"] = filtered_properties
+
+    # Clean up required array if properties were removed
+    if "required" in result and filtered_properties:
+        result["required"] = [
+            prop for prop in result["required"] if prop in filtered_properties
+        ]
+        if not result["required"]:
+            result.pop("required")
+
+    return result
+
+
+def convert_schema_definitions(
+    schema_definitions: dict[str, Any] | None,
+    openapi_version: str | None = None,
+    **kwargs,
+) -> dict[str, Any]:
+    """
+    Convert a dictionary of OpenAPI schema definitions to JSON Schema.
+
+    Args:
+        schema_definitions: Dictionary of schema definitions
+        openapi_version: OpenAPI version for optimization
+        **kwargs: Additional arguments passed to convert_openapi_schema_to_json_schema
+
+    Returns:
+        Dictionary of converted schema definitions
+    """
+    if not schema_definitions:
+        return {}
+
+    return {
+        name: convert_openapi_schema_to_json_schema(schema, openapi_version, **kwargs)
+        for name, schema in schema_definitions.items()
+    }