Skip to main content

​
fastmcp.utilities.openapi

​
Functions

​
format_array_parameter 

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)

​
format_deep_object_parameter 

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

​
parse_openapi_to_http_routes 

parse_openapi_to_http_routes(openapi_dict: dict[str, Any]) -> list[HTTPRoute]
Parses an OpenAPI schema dictionary into a list of HTTPRoute objects using the openapi-pydantic library. Supports both OpenAPI 3.0.x and 3.1.x versions.

​
clean_schema_for_display 

clean_schema_for_display(schema: JsonSchema | None) -> JsonSchema | None
Clean up a schema dictionary for display by removing internal/complex fields.

​
generate_example_from_schema 

generate_example_from_schema(schema: JsonSchema | None) -> Any
Generate a simple example value from a JSON schema dictionary. Very basic implementation focusing on types.

​
format_json_for_description 

format_json_for_description(data: Any, indent: int = 2) -> str
Formats Python data as a JSON string block for markdown.

​
format_description_with_responses 

format_description_with_responses(base_description: str, responses: dict[str, Any], parameters: list[ParameterInfo] | None = None, request_body: RequestBodyInfo | None = None) -> str
Formats the base description string with response, parameter, and request body information. Args:
  • base_description: The initial description to be formatted.
  • responses: A dictionary of response information, keyed by status code.
  • parameters: 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: Information about the request body, including its description, whether it is required, and its content schema.
Returns:
  • The formatted description string with additional details about responses, parameters,
  • and the request body.

​
extract_output_schema_from_responses 

extract_output_schema_from_responses(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. This function finds the first successful response (200, 201, 202, 204) with a JSON-compatible content type and extracts its schema. If the schema is not an object type, it wraps it to comply with MCP requirements. 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:
  • MCP-compliant output schema with potential wrapping, or None if no suitable schema found

​
Classes

​
ParameterInfo

Represents a single parameter for an HTTP operation in our IR.

​
RequestBodyInfo

Represents the request body for an HTTP operation in our IR.

​
ResponseInfo

Represents response information in our IR.

​
HTTPRoute

Intermediate Representation for a single OpenAPI operation.

​
OpenAPIParser

Unified parser for OpenAPI schemas with generic type parameters to handle both 3.0 and 3.1. Methods:

​
parse 

parse(self) -> list[HTTPRoute]
Parse the OpenAPI schema into HTTP routes.