π The fast, Pythonic way to build MCP servers and clients.
Improve OpenAPI-to-JSONSchema conversion utilities (#1283)
Jeremiah Lowin6125b1ebfcb5
diff --git a/src/fastmcp/experimental/server/openapi/server.py b/src/fastmcp/experimental/server/openapi/server.pyindex 80c9504cf..fd188ee3a 100644--- a/src/fastmcp/experimental/server/openapi/server.py+++ b/src/fastmcp/experimental/server/openapi/server.py@@ -5,7 +5,7 @@ from collections import Counterfrom typing import Any, Literalimport httpx-from openapi_core import Spec+from jsonschema_path import SchemaPath# Import from our new utilities and componentsfrom fastmcp.experimental.utilities.openapi import (@@ -149,7 +149,7 @@ class FastMCPOpenAPI(FastMCP):# Create openapi-core Spec and RequestDirector for stateless request buildingtry:- self._spec = Spec.from_dict(openapi_spec) # type: ignore[arg-type]+ 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"@@ -270,7 +270,7 @@ class FastMCPOpenAPI(FastMCP):# Extract output schema from OpenAPI responsesoutput_schema = extract_output_schema_from_responses(- route.responses, route.schema_definitions+ route.responses, route.schema_definitions, route.openapi_version)# Get a unique tool namediff --git a/src/fastmcp/experimental/utilities/openapi/README.md b/src/fastmcp/experimental/utilities/openapi/README.mdindex 78350d196..c63bc7170 100644--- a/src/fastmcp/experimental/utilities/openapi/README.md+++ b/src/fastmcp/experimental/utilities/openapi/README.md@@ -36,13 +36,13 @@ The new implementation follows a **stateless request building strategy** using `### Initialization Process```-OpenAPI Spec β Parser β HTTPRoute with Pre-calculated Fields β RequestDirector + openapi-core Spec+OpenAPI Spec β Parser β HTTPRoute with Pre-calculated Fields β RequestDirector + SchemaPath```1. **Input**: Raw OpenAPI specification (dict)2. **Parsing**: Extract operations to `HTTPRoute` models3. **Pre-calculation**: Generate combined schemas and parameter maps during parsing-4. **Director Setup**: Create `RequestDirector` with `openapi-core` Spec for request building+4. **Director Setup**: Create `RequestDirector` with `SchemaPath` for request building### Request Processing@@ -125,10 +125,10 @@ async with httpx.AsyncClient() as client:```pythonfrom fastmcp.experimental.utilities.openapi.director import RequestDirector-from openapi_core import Spec+from jsonschema_path import SchemaPath# Create RequestDirector manually-spec = Spec.from_dict(openapi_spec)+spec = SchemaPath.from_dict(openapi_spec)director = RequestDirector(spec)# Build HTTP request@@ -210,7 +210,7 @@ Tests are located in `/tests/server/openapi_new/`:### Common Issues1. **RequestDirector Initialization Fails**- - Check OpenAPI spec validity with `openapi-core`+ - Check OpenAPI spec validity with `jsonschema-path`- Verify spec format is correct JSON/YAML- Ensure all required OpenAPI fields are presentdiff --git a/src/fastmcp/experimental/utilities/openapi/__init__.py b/src/fastmcp/experimental/utilities/openapi/__init__.pyindex 4504bebe5..588f422f5 100644--- a/src/fastmcp/experimental/utilities/openapi/__init__.py+++ b/src/fastmcp/experimental/utilities/openapi/__init__.py@@ -30,7 +30,12 @@ from .schemas import (clean_schema_for_display,_replace_ref_with_defs,_make_optional_parameter_nullable,- _adjust_union_types,+)++# Import from json_schema_converter+from .json_schema_converter import (+ convert_openapi_schema_to_json_schema,+ convert_schema_definitions,)# Export public symbols - maintaining backward compatibility@@ -57,5 +62,7 @@ __all__ = ["clean_schema_for_display","_replace_ref_with_defs","_make_optional_parameter_nullable",- "_adjust_union_types",+ # JSON Schema Converter+ "convert_openapi_schema_to_json_schema",+ "convert_schema_definitions",]diff --git a/src/fastmcp/experimental/utilities/openapi/director.py b/src/fastmcp/experimental/utilities/openapi/director.pyindex 1b70ebdf5..b1dc47147 100644--- a/src/fastmcp/experimental/utilities/openapi/director.py+++ b/src/fastmcp/experimental/utilities/openapi/director.py@@ -4,7 +4,7 @@ from typing import Anyfrom urllib.parse import urljoinimport httpx-from openapi_core import Spec+from jsonschema_path import SchemaPathfrom fastmcp.utilities.logging import get_logger@@ -16,8 +16,8 @@ logger = get_logger(__name__)class RequestDirector:"""Builds httpx.Request objects from HTTPRoute and arguments using openapi-core."""- def __init__(self, spec: Spec):- """Initialize with a parsed openapi-core Spec object."""+ def __init__(self, spec: SchemaPath):+ """Initialize with a parsed SchemaPath object."""self._spec = specdef build(@@ -66,7 +66,7 @@ class RequestDirector:if isinstance(body, dict) or isinstance(body, list):request_data["json"] = bodyelse:- request_data["data"] = body+ request_data["content"] = body# Step 5: Create httpx.Requestreturn httpx.Request(**{k: v for k, v in request_data.items() if v is not None})diff --git a/src/fastmcp/experimental/utilities/openapi/json_schema_converter.py b/src/fastmcp/experimental/utilities/openapi/json_schema_converter.pynew file mode 100644index 000000000..70305d375--- /dev/null+++ b/src/fastmcp/experimental/utilities/openapi/json_schema_converter.py@@ -0,0 +1,339 @@+"""+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.+"""++import logging+from typing import Any++logger = logging.getLogger(__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()+ }diff --git a/src/fastmcp/experimental/utilities/openapi/models.py b/src/fastmcp/experimental/utilities/openapi/models.pyindex e3076a0a1..6116dc8c8 100644--- a/src/fastmcp/experimental/utilities/openapi/models.py+++ b/src/fastmcp/experimental/utilities/openapi/models.py@@ -62,6 +62,7 @@ class HTTPRoute(FastMCPBaseModel):default_factory=dict) # Store component schemasextensions: dict[str, Any] = Field(default_factory=dict)+ openapi_version: str | None = None# Pre-calculated fields for performanceflat_param_schema: JsonSchema = Field(diff --git a/src/fastmcp/experimental/utilities/openapi/parser.py b/src/fastmcp/experimental/utilities/openapi/parser.pyindex 551555f41..f8cec4c9f 100644--- a/src/fastmcp/experimental/utilities/openapi/parser.py+++ b/src/fastmcp/experimental/utilities/openapi/parser.py@@ -74,6 +74,7 @@ def parse_openapi_to_http_routes(openapi_dict: dict[str, Any]) -> list[HTTPRouteResponse_30,Operation_30,PathItem_30,+ openapi_version,)return parser.parse()else:@@ -91,6 +92,7 @@ def parse_openapi_to_http_routes(openapi_dict: dict[str, Any]) -> list[HTTPRouteResponse,Operation,PathItem,+ openapi_version,)return parser.parse()except ValidationError as e:@@ -124,6 +126,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@@ -134,6 +137,7 @@ class OpenAPIParser(self.response_cls = response_clsself.operation_cls = operation_clsself.path_item_cls = path_item_cls+ self.openapi_version = openapi_versiondef _convert_to_parameter_location(self, param_in: str) -> ParameterLocation:"""Convert string parameter location to our ParameterLocation type."""@@ -560,6 +564,7 @@ class OpenAPIParser(responses=responses,schema_definitions=schema_definitions,extensions=extensions,+ openapi_version=self.openapi_version,)# Pre-calculate schema and parameter mapping for performancediff --git a/src/fastmcp/experimental/utilities/openapi/schemas.py b/src/fastmcp/experimental/utilities/openapi/schemas.pyindex c7ea71f58..513d02b9e 100644--- a/src/fastmcp/experimental/utilities/openapi/schemas.py+++ b/src/fastmcp/experimental/utilities/openapi/schemas.py@@ -1,7 +1,7 @@"""Schema manipulation utilities for OpenAPI operations."""import logging-from typing import Any, cast+from typing import Anyfrom .models import HTTPRoute, JsonSchema, ResponseInfo@@ -199,86 +199,6 @@ def _make_optional_parameter_nullable(schema: dict[str, Any]) -> dict[str, Any]: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_and_map_params(route: HTTPRoute,) -> tuple[dict[str, Any], dict[str, dict[str, str]]]:@@ -450,68 +370,10 @@ def _combine_schemas(route: HTTPRoute) -> dict[str, Any]:return schema-def _has_one_of(obj: dict[str, Any] | list[Any]) -> bool:- """Quickly check if schema contains any 'oneOf' keys without deep traversal."""- if isinstance(obj, dict):- if "oneOf" in obj:- return True- # Only check likely schema containers, skip examples/defaults- for k, v in obj.items():- if k in [- "properties",- "items",- "allOf",- "anyOf",- "additionalProperties",- ] and isinstance(v, dict | list):- if _has_one_of(v):- return True- elif isinstance(obj, list):- for item in obj:- if isinstance(item, dict | list) and _has_one_of(item):- return True- return False---def _adjust_union_types(- schema: dict[str, Any] | list[Any], _depth: int = 0-) -> dict[str, Any] | list[Any]:- """Recursively replace 'oneOf' with 'anyOf' in schema to handle overlapping unions."""- # MAJOR OPTIMIZATION: Skip entirely if schema has no oneOf keys- if _depth == 0 and not _has_one_of(schema):- return schema-- # OPTIMIZATION: Early termination for very deep structures to prevent exponential slowdown- if _depth > 30: # Reduced from 50 for better performance- return schema-- if isinstance(schema, dict):- # Work on a copy to avoid mutating the input- result = schema.copy()- if "oneOf" in result:- result["anyOf"] = result.pop("oneOf")- # OPTIMIZATION: Only recurse into values that could contain more schemas- for k, v in result.items():- if isinstance(v, dict | list) and k not in [- "examples",- "example",- "default",- ]:- result[k] = _adjust_union_types(v, _depth + 1)- return result- elif isinstance(schema, list):- # Process list items without mutating the input list- return [- _adjust_union_types(item, _depth + 1)- if isinstance(item, dict | list)- else 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.@@ -523,6 +385,7 @@ def extract_output_schema_from_responses(Args:responses: Dictionary of ResponseInfo objects keyed by status codeschema_definitions: Optional schema definitions to include in the output schema+ openapi_version: OpenAPI version string, used to optimize nullable field handlingReturns:dict: MCP-compliant output schema with potential wrapping, or None if no suitable schema found@@ -588,9 +451,14 @@ def extract_output_schema_from_responses(# Replace $ref with the actual schema definitionoutput_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- output_schema = _handle_nullable_fields(output_schema)+ # Convert OpenAPI schema to JSON Schema format+ # Only needed for OpenAPI 3.0 - 3.1 uses standard JSON Schema null types+ if openapi_version and openapi_version.startswith("3.0"):+ from .json_schema_converter import convert_openapi_schema_to_json_schema++ output_schema = convert_openapi_schema_to_json_schema(+ output_schema, openapi_version+ )# 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@@ -609,7 +477,15 @@ def extract_output_schema_from_responses(if schema_definitions and "$ref" not in schema.copy():processed_defs = {}for def_name, def_schema in schema_definitions.items():- processed_defs[def_name] = _handle_nullable_fields(def_schema)+ # Convert OpenAPI schema definitions to JSON Schema format+ if openapi_version and openapi_version.startswith("3.0"):+ from .json_schema_converter import convert_openapi_schema_to_json_schema++ processed_defs[def_name] = convert_openapi_schema_to_json_schema(+ def_schema, openapi_version+ )+ else:+ processed_defs[def_name] = def_schemaoutput_schema["$defs"] = processed_defs# Use lightweight compression - prune additionalProperties and unused definitions@@ -647,9 +523,6 @@ def extract_output_schema_from_responses(else:output_schema.pop("$defs")- # Adjust union types to handle overlapping unions- output_schema = cast(dict[str, Any], _adjust_union_types(output_schema))-return output_schema@@ -661,6 +534,4 @@ __all__ = ["extract_output_schema_from_responses","_replace_ref_with_defs","_make_optional_parameter_nullable",- "_handle_nullable_fields",- "_adjust_union_types",]diff --git a/src/fastmcp/server/openapi.py b/src/fastmcp/server/openapi.pyindex 6aa39ed6f..e090957fd 100644--- a/src/fastmcp/server/openapi.py+++ b/src/fastmcp/server/openapi.py@@ -892,7 +892,7 @@ class FastMCPOpenAPI(FastMCP):# Extract output schema from OpenAPI responsesoutput_schema = extract_output_schema_from_responses(- route.responses, route.schema_definitions+ route.responses, route.schema_definitions, route.openapi_version)# Get a unique tool namediff --git a/src/fastmcp/utilities/openapi.py b/src/fastmcp/utilities/openapi.pyindex 121dd7249..1dd454498 100644--- a/src/fastmcp/utilities/openapi.py+++ b/src/fastmcp/utilities/openapi.py@@ -173,6 +173,7 @@ class HTTPRoute(FastMCPBaseModel):default_factory=dict) # Store component schemasextensions: dict[str, Any] = Field(default_factory=dict)+ openapi_version: str | None = None# Export public symbols@@ -227,6 +228,7 @@ def parse_openapi_to_http_routes(openapi_dict: dict[str, Any]) -> list[HTTPRouteResponse_30,Operation_30,PathItem_30,+ openapi_version,)return parser.parse()else:@@ -244,6 +246,7 @@ def parse_openapi_to_http_routes(openapi_dict: dict[str, Any]) -> list[HTTPRouteResponse,Operation,PathItem,+ openapi_version,)return parser.parse()except ValidationError as e:@@ -277,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@@ -287,6 +291,7 @@ class OpenAPIParser(self.response_cls = response_clsself.operation_cls = operation_clsself.path_item_cls = path_item_cls+ self.openapi_version = openapi_versiondef _convert_to_parameter_location(self, param_in: str) -> ParameterLocation:"""Convert string parameter location to our ParameterLocation type."""@@ -709,6 +714,7 @@ class OpenAPIParser(responses=responses,schema_definitions=schema_definitions,extensions=extensions,+ openapi_version=self.openapi_version,)routes.append(route)logger.info(@@ -1401,7 +1407,9 @@ def _adjust_union_types(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.@@ -1413,6 +1421,7 @@ def extract_output_schema_from_responses(Args:responses: Dictionary of ResponseInfo objects keyed by status codeschema_definitions: Optional schema definitions to include in the output schema+ openapi_version: OpenAPI version string, used to optimize nullable field handlingReturns:dict: MCP-compliant output schema with potential wrapping, or None if no suitable schema found@@ -1480,7 +1489,9 @@ def extract_output_schema_from_responses(# Handle OpenAPI nullable fields by converting them to JSON Schema format# This prevents "None is not of type 'string'" validation errors- output_schema = _handle_nullable_fields(output_schema)+ # 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@@ -1499,7 +1510,11 @@ def extract_output_schema_from_responses(if schema_definitions and "$ref" not in schema.copy():processed_defs = {}for def_name, def_schema in schema_definitions.items():- processed_defs[def_name] = _handle_nullable_fields(def_schema)+ # 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_schemaoutput_schema["$defs"] = processed_defs# Use lightweight compression - prune additionalProperties and unused definitionsdiff --git a/tests/experimental/utilities/openapi/test_director.py b/tests/experimental/utilities/openapi/test_director.pyindex 2de1b5052..e912fd1f6 100644--- a/tests/experimental/utilities/openapi/test_director.py+++ b/tests/experimental/utilities/openapi/test_director.py@@ -1,7 +1,7 @@"""Unit tests for RequestDirector."""import pytest-from openapi_core import Spec+from jsonschema_path import SchemaPathfrom fastmcp.experimental.utilities.openapi.director import RequestDirectorfrom fastmcp.experimental.utilities.openapi.models import (@@ -148,12 +148,12 @@ class TestRequestDirector:@pytest.fixturedef director(self, basic_openapi_30_spec):"""Create a RequestDirector instance."""- spec = Spec.from_dict(basic_openapi_30_spec)+ spec = SchemaPath.from_dict(basic_openapi_30_spec)return RequestDirector(spec)def test_director_initialization(self, basic_openapi_30_spec):"""Test RequestDirector initialization."""- spec = Spec.from_dict(basic_openapi_30_spec)+ spec = SchemaPath.from_dict(basic_openapi_30_spec)director = RequestDirector(spec)assert director._spec is not None@@ -350,7 +350,7 @@ class TestRequestDirector:request = director.build(route, flat_args, "https://api.example.com")assert request.method == "POST"- # For non-JSON content, httpx uses 'data' parameter which becomes bytes+ # For non-JSON content, httpx uses 'content' parameter which becomes bytesassert request.content == b"Hello, World!"def test_body_construction_multiple_properties_non_object_schema(self, director):@@ -392,7 +392,7 @@ class TestRequestDirectorIntegration:assert len(routes) == 1route = routes[0]- spec = Spec.from_dict(basic_openapi_30_spec)+ spec = SchemaPath.from_dict(basic_openapi_30_spec)director = RequestDirector(spec)flat_args = {"id": 42}@@ -407,7 +407,7 @@ class TestRequestDirectorIntegration:assert len(routes) == 1route = routes[0]- spec = Spec.from_dict(collision_spec)+ spec = SchemaPath.from_dict(collision_spec)director = RequestDirector(spec)# Use the parameter names from the actual parameter map@@ -440,7 +440,7 @@ class TestRequestDirectorIntegration:assert len(routes) == 1route = routes[0]- spec = Spec.from_dict(deepobject_spec)+ spec = SchemaPath.from_dict(deepobject_spec)director = RequestDirector(spec)# DeepObject parameters should be flattened in the parameter mapdiff --git a/tests/experimental/utilities/openapi/test_nullable_fields.py b/tests/experimental/utilities/openapi/test_nullable_fields.pyindex 9f8d185d6..50d91c1ea 100644--- a/tests/experimental/utilities/openapi/test_nullable_fields.py+++ b/tests/experimental/utilities/openapi/test_nullable_fields.py@@ -1,6 +1,8 @@"""Tests for nullable field handling in OpenAPI schemas."""-from fastmcp.experimental.utilities.openapi.schemas import _handle_nullable_fields+from fastmcp.experimental.utilities.openapi.json_schema_converter import (+ convert_openapi_schema_to_json_schema,+)class TestHandleNullableFields:@@ -10,21 +12,21 @@ class TestHandleNullableFields:"""Test nullable string at root level."""input_schema = {"type": "string", "nullable": True}expected = {"type": ["string", "null"]}- result = _handle_nullable_fields(input_schema)+ result = convert_openapi_schema_to_json_schema(input_schema, "3.0.0")assert result == expecteddef test_root_level_nullable_integer(self):"""Test nullable integer at root level."""input_schema = {"type": "integer", "nullable": True}expected = {"type": ["integer", "null"]}- result = _handle_nullable_fields(input_schema)+ result = convert_openapi_schema_to_json_schema(input_schema, "3.0.0")assert result == expecteddef test_root_level_nullable_boolean(self):"""Test nullable boolean at root level."""input_schema = {"type": "boolean", "nullable": True}expected = {"type": ["boolean", "null"]}- result = _handle_nullable_fields(input_schema)+ result = convert_openapi_schema_to_json_schema(input_schema, "3.0.0")assert result == expecteddef test_property_level_nullable_fields(self):@@ -47,7 +49,7 @@ class TestHandleNullableFields:"active": {"type": ["boolean", "null"]},},}- result = _handle_nullable_fields(input_schema)+ result = convert_openapi_schema_to_json_schema(input_schema, "3.0.0")assert result == expecteddef test_mixed_nullable_and_non_nullable(self):@@ -70,14 +72,14 @@ class TestHandleNullableFields:},"required": ["required_field"],}- result = _handle_nullable_fields(input_schema)+ result = convert_openapi_schema_to_json_schema(input_schema, "3.0.0")assert result == expecteddef test_nullable_false_ignored(self):"""Test that nullable: false is ignored (removed but no type change)."""input_schema = {"type": "string", "nullable": False}expected = {"type": "string"}- result = _handle_nullable_fields(input_schema)+ result = convert_openapi_schema_to_json_schema(input_schema, "3.0.0")assert result == expecteddef test_no_nullable_field_unchanged(self):@@ -87,14 +89,14 @@ class TestHandleNullableFields:"properties": {"name": {"type": "string"}},}expected = input_schema.copy()- result = _handle_nullable_fields(input_schema)+ result = convert_openapi_schema_to_json_schema(input_schema, "3.0.0")assert result == expecteddef test_nullable_without_type_removes_nullable(self):"""Test that nullable field is removed even without type."""input_schema = {"nullable": True, "description": "Some field"}expected = {"description": "Some field"}- result = _handle_nullable_fields(input_schema)+ result = convert_openapi_schema_to_json_schema(input_schema, "3.0.0")assert result == expecteddef test_preserves_other_fields(self):@@ -112,15 +114,15 @@ class TestHandleNullableFields:"example": "test","format": "email",}- result = _handle_nullable_fields(input_schema)+ result = convert_openapi_schema_to_json_schema(input_schema, "3.0.0")assert result == expecteddef test_non_dict_input_unchanged(self):"""Test that non-dict inputs are returned unchanged."""- assert _handle_nullable_fields("string") == "string" # type: ignore[arg-type]- assert _handle_nullable_fields(123) == 123 # type: ignore[arg-type]- assert _handle_nullable_fields(None) is None # type: ignore[arg-type]- assert _handle_nullable_fields([1, 2, 3]) == [1, 2, 3] # type: ignore[arg-type]+ assert convert_openapi_schema_to_json_schema("string", "3.0.0") == "string" # type: ignore[arg-type]+ assert convert_openapi_schema_to_json_schema(123, "3.0.0") == 123 # type: ignore[arg-type]+ assert convert_openapi_schema_to_json_schema(None, "3.0.0") is None # type: ignore[arg-type]+ assert convert_openapi_schema_to_json_schema([1, 2, 3], "3.0.0") == [1, 2, 3] # type: ignore[arg-type]def test_performance_optimization_no_copy_when_unchanged(self):"""Test that schemas without nullable fields return the same object (no copy)."""@@ -128,7 +130,7 @@ class TestHandleNullableFields:"type": "object","properties": {"name": {"type": "string"}},}- result = _handle_nullable_fields(input_schema)+ result = convert_openapi_schema_to_json_schema(input_schema, "3.0.0")# Should return the exact same object, not a copyassert result is input_schema@@ -136,14 +138,14 @@ class TestHandleNullableFields:"""Test nullable handling with existing union types (type as array)."""input_schema = {"type": ["string", "integer"], "nullable": True}expected = {"type": ["string", "integer", "null"]}- result = _handle_nullable_fields(input_schema)+ result = convert_openapi_schema_to_json_schema(input_schema, "3.0.0")assert result == expecteddef test_already_nullable_union_unchanged(self):"""Test that union types already containing null are not modified."""input_schema = {"type": ["string", "null"], "nullable": True}expected = {"type": ["string", "null"]}- result = _handle_nullable_fields(input_schema)+ result = convert_openapi_schema_to_json_schema(input_schema, "3.0.0")assert result == expecteddef test_property_level_union_with_nullable(self):@@ -156,19 +158,19 @@ class TestHandleNullableFields:"type": "object","properties": {"value": {"type": ["string", "integer", "null"]}},}- result = _handle_nullable_fields(input_schema)+ result = convert_openapi_schema_to_json_schema(input_schema, "3.0.0")assert result == expecteddef test_complex_union_nullable_scenarios(self):"""Test various complex union type scenarios."""# Already has null in different positioninput1 = {"type": ["null", "string", "integer"], "nullable": True}- result1 = _handle_nullable_fields(input1)+ result1 = convert_openapi_schema_to_json_schema(input1, "3.0.0")assert result1 == {"type": ["null", "string", "integer"]}# Single item arrayinput2 = {"type": ["string"], "nullable": True}- result2 = _handle_nullable_fields(input2)+ result2 = convert_openapi_schema_to_json_schema(input2, "3.0.0")assert result2 == {"type": ["string", "null"]}def test_oneof_with_nullable(self):@@ -180,7 +182,7 @@ class TestHandleNullableFields:expected = {"anyOf": [{"type": "string"}, {"type": "integer"}, {"type": "null"}]}- result = _handle_nullable_fields(input_schema)+ result = convert_openapi_schema_to_json_schema(input_schema, "3.0.0")assert result == expecteddef test_anyof_with_nullable(self):@@ -192,7 +194,7 @@ class TestHandleNullableFields:expected = {"anyOf": [{"type": "string"}, {"type": "integer"}, {"type": "null"}]}- result = _handle_nullable_fields(input_schema)+ result = convert_openapi_schema_to_json_schema(input_schema, "3.0.0")assert result == expecteddef test_anyof_already_nullable(self):@@ -202,7 +204,7 @@ class TestHandleNullableFields:"nullable": True,}expected = {"anyOf": [{"type": "string"}, {"type": "null"}]}- result = _handle_nullable_fields(input_schema)+ result = convert_openapi_schema_to_json_schema(input_schema, "3.0.0")assert result == expecteddef test_allof_with_nullable(self):@@ -217,7 +219,7 @@ class TestHandleNullableFields:{"type": "null"},]}- result = _handle_nullable_fields(input_schema)+ result = convert_openapi_schema_to_json_schema(input_schema, "3.0.0")assert result == expecteddef test_property_level_oneof_with_nullable(self):@@ -239,5 +241,5 @@ class TestHandleNullableFields:}},}- result = _handle_nullable_fields(input_schema)+ result = convert_openapi_schema_to_json_schema(input_schema, "3.0.0")assert result == expected