fastmcp 2.11.2__py3-none-any.whl → 2.12.0__py3-none-any.whl

fastmcp/experimental/utilities/openapi/__init__.py

@@ -20,6 +20,7 @@ from .formatters import (
     format_deep_object_parameter,
     format_description_with_responses,
     format_json_for_description,
+    format_simple_description,
     generate_example_from_schema,
 )
 
@@ -28,7 +29,6 @@ from .schemas import (
     _combine_schemas,
     extract_output_schema_from_responses,
     clean_schema_for_display,
-    _replace_ref_with_defs,
     _make_optional_parameter_nullable,
 )
 
@@ -55,12 +55,12 @@ __all__ = [
     "format_deep_object_parameter",
     "format_description_with_responses",
     "format_json_for_description",
+    "format_simple_description",
     "generate_example_from_schema",
     # Schemas
     "_combine_schemas",
     "extract_output_schema_from_responses",
     "clean_schema_for_display",
-    "_replace_ref_with_defs",
     "_make_optional_parameter_nullable",
     # JSON Schema Converter
     "convert_openapi_schema_to_json_schema",

fastmcp/experimental/utilities/openapi/formatters.py

@@ -189,6 +189,39 @@ def format_json_for_description(data: Any, indent: int = 2) -> str:
         return f"```\nCould not serialize to JSON: {data}\n```"
 
 
+def format_simple_description(
+    base_description: str,
+    parameters: list[ParameterInfo] | None = None,
+    request_body: RequestBodyInfo | None = None,
+) -> str:
+    """
+    Formats a simple description for MCP objects (tools, resources, prompts).
+    Excludes response details, examples, and verbose status codes.
+
+    Args:
+        base_description (str): The initial description to be formatted.
+        parameters (list[ParameterInfo] | None, optional): A list of parameter information.
+        request_body (RequestBodyInfo | None, optional): Information about the request body.
+
+    Returns:
+        str: The formatted description string with minimal details.
+    """
+    desc_parts = [base_description]
+
+    # Only add critical parameter information if they have descriptions
+    if parameters:
+        path_params = [p for p in parameters if p.location == "path" and p.description]
+        if path_params:
+            desc_parts.append("\n\n**Path Parameters:**")
+            for param in path_params:
+                desc_parts.append(f"\n- **{param.name}**: {param.description}")
+
+    # Skip query parameters, request body details, and all response information
+    # These are already captured in the inputSchema
+
+    return "\n".join(desc_parts)
+
+
 def format_description_with_responses(
     base_description: str,
     responses: dict[
@@ -351,5 +384,6 @@ __all__ = [
     "format_deep_object_parameter",
     "format_description_with_responses",
     "format_json_for_description",
+    "format_simple_description",
     "generate_example_from_schema",
 ]

fastmcp/experimental/utilities/openapi/models.py

@@ -58,9 +58,12 @@ class HTTPRoute(FastMCPBaseModel):
     responses: dict[str, ResponseInfo] = Field(
         default_factory=dict
     )  # Key: status code str
-    schema_definitions: dict[str, JsonSchema] = Field(
+    request_schemas: dict[str, JsonSchema] = Field(
         default_factory=dict
-    )  # Store component schemas
+    )  # Store schemas needed for input (parameters/request body)
+    response_schemas: dict[str, JsonSchema] = Field(
+        default_factory=dict
+    )  # Store schemas needed for output (responses)
     extensions: dict[str, Any] = Field(default_factory=dict)
     openapi_version: str | None = None
 

fastmcp/experimental/utilities/openapi/parser.py

@@ -34,7 +34,10 @@ from .models import (
     RequestBodyInfo,
     ResponseInfo,
 )
-from .schemas import _combine_schemas_and_map_params, _replace_ref_with_defs
+from .schemas import (
+    _combine_schemas_and_map_params,
+    _replace_ref_with_defs,
+)
 
 logger = get_logger(__name__)
 
@@ -63,7 +66,7 @@ def parse_openapi_to_http_routes(openapi_dict: dict[str, Any]) -> list[HTTPRoute
         if openapi_version.startswith("3.0"):
             # Use OpenAPI 3.0 models
             openapi_30 = OpenAPI_30.model_validate(openapi_dict)
-            logger.info(
+            logger.debug(
                 f"Successfully parsed OpenAPI 3.0 schema version: {openapi_30.openapi}"
             )
             parser = OpenAPIParser(
@@ -81,7 +84,7 @@ def parse_openapi_to_http_routes(openapi_dict: dict[str, Any]) -> list[HTTPRoute
         else:
             # Default to OpenAPI 3.1 models
             openapi_31 = OpenAPI.model_validate(openapi_dict)
-            logger.info(
+            logger.debug(
                 f"Successfully parsed OpenAPI 3.1 schema version: {openapi_31.openapi}"
             )
             parser = OpenAPIParser(
@@ -207,7 +210,7 @@ class OpenAPIParser(
         try:
             resolved_schema = self._resolve_ref(schema_obj)
 
-            if isinstance(resolved_schema, (self.schema_cls)):
+            if isinstance(resolved_schema, self.schema_cls):
                 # Convert schema to dictionary
                 result = resolved_schema.model_dump(
                     mode="json", by_alias=True, exclude_none=True
@@ -220,7 +223,10 @@ class OpenAPIParser(
                 )
                 result = {}
 
-            return _replace_ref_with_defs(result)
+            # Convert refs from OpenAPI format to JSON Schema format using recursive approach
+
+            result = _replace_ref_with_defs(result)
+            return result
         except ValueError as e:
             # Re-raise ValueError for external reference errors and other validation issues
             if "External or non-local reference not supported" in str(e):
@@ -396,80 +402,239 @@ class OpenAPIParser(
             )
             return None
 
+    def _is_success_status_code(self, status_code: str) -> bool:
+        """Check if a status code represents a successful response (2xx)."""
+        try:
+            code_int = int(status_code)
+            return 200 <= code_int < 300
+        except (ValueError, TypeError):
+            # Handle special cases like 'default' or other non-numeric codes
+            return status_code.lower() in ["default", "2xx"]
+
+    def _get_primary_success_response(
+        self, operation_responses: dict[str, Any]
+    ) -> tuple[str, Any] | None:
+        """Get the primary success response for an MCP tool. We only need one success response."""
+        if not operation_responses:
+            return None
+
+        # Priority order: 200, 201, 202, 204, 207, then any other 2xx
+        priority_codes = ["200", "201", "202", "204", "207"]
+
+        # First check priority codes
+        for code in priority_codes:
+            if code in operation_responses:
+                return (code, operation_responses[code])
+
+        # Then check any other 2xx codes
+        for status_code, resp_or_ref in operation_responses.items():
+            if self._is_success_status_code(status_code):
+                return (status_code, resp_or_ref)
+
+        # If no success codes found, return None (tool will have no output schema)
+        return None
+
     def _extract_responses(
         self, operation_responses: dict[str, Any] | None
     ) -> dict[str, ResponseInfo]:
-        """Extract and resolve response information."""
+        """Extract and resolve response information. Only includes the primary success response for MCP tools."""
         extracted_responses: dict[str, ResponseInfo] = {}
 
         if not operation_responses:
             return extracted_responses
 
-        for status_code, resp_or_ref in operation_responses.items():
-            try:
-                response = self._resolve_ref(resp_or_ref)
+        # For MCP tools, we only need the primary success response
+        primary_response = self._get_primary_success_response(operation_responses)
+        if not primary_response:
+            logger.debug("No success responses found, tool will have no output schema")
+            return extracted_responses
 
-                if not isinstance(response, self.response_cls):
-                    logger.warning(
-                        f"Expected Response after resolving for status code {status_code}, "
-                        f"got {type(response)}. Skipping."
-                    )
-                    continue
+        status_code, resp_or_ref = primary_response
+        logger.debug(f"Using primary success response: {status_code}")
 
-                # Create response info
-                resp_info = ResponseInfo(description=response.description)
+        try:
+            response = self._resolve_ref(resp_or_ref)
 
-                # Extract content schemas
-                if hasattr(response, "content") and response.content:
-                    for media_type_str, media_type_obj in response.content.items():
-                        if (
-                            media_type_obj
-                            and hasattr(media_type_obj, "media_type_schema")
-                            and media_type_obj.media_type_schema
-                        ):
-                            try:
-                                schema_dict = self._extract_schema_as_dict(
-                                    media_type_obj.media_type_schema
-                                )
-                                resp_info.content_schema[media_type_str] = schema_dict
-                            except ValueError as e:
-                                # Re-raise ValueError for external reference errors
-                                if (
-                                    "External or non-local reference not supported"
-                                    in str(e)
-                                ):
-                                    raise
-                                logger.error(
-                                    f"Failed to extract schema for media type '{media_type_str}' "
-                                    f"in response {status_code}: {e}"
-                                )
-                            except Exception as e:
-                                logger.error(
-                                    f"Failed to extract schema for media type '{media_type_str}' "
-                                    f"in response {status_code}: {e}"
-                                )
-
-                extracted_responses[str(status_code)] = resp_info
-            except ValueError as e:
-                # Re-raise ValueError for external reference errors
-                if "External or non-local reference not supported" in str(e):
-                    raise
-                ref_name = getattr(resp_or_ref, "ref", "unknown")
-                logger.error(
-                    f"Failed to extract response for status code {status_code} "
-                    f"from reference '{ref_name}': {e}",
-                    exc_info=False,
-                )
-            except Exception as e:
-                ref_name = getattr(resp_or_ref, "ref", "unknown")
-                logger.error(
-                    f"Failed to extract response for status code {status_code} "
-                    f"from reference '{ref_name}': {e}",
-                    exc_info=False,
+            if not isinstance(response, self.response_cls):
+                logger.warning(
+                    f"Expected Response after resolving for status code {status_code}, "
+                    f"got {type(response)}. Returning empty responses."
                 )
+                return extracted_responses
+
+            # Create response info
+            resp_info = ResponseInfo(description=response.description)
+
+            # Extract content schemas
+            if hasattr(response, "content") and response.content:
+                for media_type_str, media_type_obj in response.content.items():
+                    if (
+                        media_type_obj
+                        and hasattr(media_type_obj, "media_type_schema")
+                        and media_type_obj.media_type_schema
+                    ):
+                        try:
+                            schema_dict = self._extract_schema_as_dict(
+                                media_type_obj.media_type_schema
+                            )
+                            resp_info.content_schema[media_type_str] = schema_dict
+                        except ValueError as e:
+                            # Re-raise ValueError for external reference errors
+                            if "External or non-local reference not supported" in str(
+                                e
+                            ):
+                                raise
+                            logger.error(
+                                f"Failed to extract schema for media type '{media_type_str}' "
+                                f"in response {status_code}: {e}"
+                            )
+                        except Exception as e:
+                            logger.error(
+                                f"Failed to extract schema for media type '{media_type_str}' "
+                                f"in response {status_code}: {e}"
+                            )
+
+            extracted_responses[str(status_code)] = resp_info
+        except ValueError as e:
+            # Re-raise ValueError for external reference errors
+            if "External or non-local reference not supported" in str(e):
+                raise
+            ref_name = getattr(resp_or_ref, "ref", "unknown")
+            logger.error(
+                f"Failed to extract response for status code {status_code} "
+                f"from reference '{ref_name}': {e}",
+                exc_info=False,
+            )
+        except Exception as e:
+            ref_name = getattr(resp_or_ref, "ref", "unknown")
+            logger.error(
+                f"Failed to extract response for status code {status_code} "
+                f"from reference '{ref_name}': {e}",
+                exc_info=False,
+            )
 
         return extracted_responses
 
+    def _extract_schema_dependencies(
+        self,
+        schema: dict,
+        all_schemas: dict[str, Any],
+        collected: set[str] | None = None,
+    ) -> set[str]:
+        """
+        Extract all schema names referenced by a schema (including transitive dependencies).
+
+        Args:
+            schema: The schema to analyze
+            all_schemas: All available schema definitions
+            collected: Set of already collected schema names (for recursion)
+
+        Returns:
+            Set of schema names that are referenced
+        """
+        if collected is None:
+            collected = set()
+
+        def find_refs(obj):
+            """Recursively find all $ref references."""
+            if isinstance(obj, dict):
+                if "$ref" in obj and isinstance(obj["$ref"], str):
+                    ref = obj["$ref"]
+                    # Handle both converted and unconverted refs
+                    if ref.startswith("#/$defs/"):
+                        schema_name = ref.split("/")[-1]
+                    elif ref.startswith("#/components/schemas/"):
+                        schema_name = ref.split("/")[-1]
+                    else:
+                        return
+
+                    # Add this schema and recursively find its dependencies
+                    if (
+                        collected is not None
+                        and schema_name not in collected
+                        and schema_name in all_schemas
+                    ):
+                        collected.add(schema_name)
+                        # Recursively find dependencies of this schema
+                        find_refs(all_schemas[schema_name])
+
+                # Continue searching in all values
+                for value in obj.values():
+                    find_refs(value)
+            elif isinstance(obj, list):
+                for item in obj:
+                    find_refs(item)
+
+        find_refs(schema)
+        return collected
+
+    def _extract_input_schema_dependencies(
+        self,
+        parameters: list[ParameterInfo],
+        request_body: RequestBodyInfo | None,
+        all_schemas: dict[str, Any],
+    ) -> dict[str, Any]:
+        """
+        Extract only the schema definitions needed for input (parameters and request body).
+
+        Args:
+            parameters: Route parameters
+            request_body: Route request body
+            all_schemas: All available schema definitions
+
+        Returns:
+            Dictionary containing only the schemas needed for input
+        """
+        needed_schemas = set()
+
+        # Check parameters for schema references
+        for param in parameters:
+            if param.schema_:
+                deps = self._extract_schema_dependencies(param.schema_, all_schemas)
+                needed_schemas.update(deps)
+
+        # Check request body for schema references
+        if request_body and request_body.content_schema:
+            for content_schema in request_body.content_schema.values():
+                deps = self._extract_schema_dependencies(content_schema, all_schemas)
+                needed_schemas.update(deps)
+
+        # Return only the needed input schemas
+        return {
+            name: all_schemas[name] for name in needed_schemas if name in all_schemas
+        }
+
+    def _extract_output_schema_dependencies(
+        self,
+        responses: dict[str, ResponseInfo],
+        all_schemas: dict[str, Any],
+    ) -> dict[str, Any]:
+        """
+        Extract only the schema definitions needed for outputs (responses).
+
+        Args:
+            responses: Route responses
+            all_schemas: All available schema definitions
+
+        Returns:
+            Dictionary containing only the schemas needed for outputs
+        """
+        needed_schemas = set()
+
+        # Check responses for schema references
+        for response in responses.values():
+            if response.content_schema:
+                for content_schema in response.content_schema.values():
+                    deps = self._extract_schema_dependencies(
+                        content_schema, all_schemas
+                    )
+                    needed_schemas.update(deps)
+
+        # Return only the needed output schemas
+        return {
+            name: all_schemas[name] for name in needed_schemas if name in all_schemas
+        }
+
     def parse(self) -> list[HTTPRoute]:
         """Parse the OpenAPI schema into HTTP routes."""
         routes: list[HTTPRoute] = []
@@ -499,6 +664,13 @@ class OpenAPIParser(
                             f"Failed to extract schema definition '{name}': {e}"
                         )
 
+        # Convert schema definitions refs from OpenAPI to JSON Schema format (once)
+        if schema_definitions:
+            # Convert each schema definition recursively
+            for name, schema in schema_definitions.items():
+                if isinstance(schema, dict):
+                    schema_definitions[name] = _replace_ref_with_defs(schema)
+
         # Process paths and operations
         for path_str, path_item_obj in self.openapi.paths.items():
             if not isinstance(path_item_obj, self.path_item_cls):
@@ -552,6 +724,17 @@ class OpenAPIParser(
                                 if k.startswith("x-")
                             }
 
+                        # Extract schemas separately for input and output
+                        input_schemas = self._extract_input_schema_dependencies(
+                            parameters,
+                            request_body_info,
+                            schema_definitions,
+                        )
+                        output_schemas = self._extract_output_schema_dependencies(
+                            responses,
+                            schema_definitions,
+                        )
+
                         # Create initial route without pre-calculated fields
                         route = HTTPRoute(
                             path=path_str,
@@ -563,7 +746,8 @@ class OpenAPIParser(
                             parameters=parameters,
                             request_body=request_body_info,
                             responses=responses,
-                            schema_definitions=schema_definitions,
+                            request_schemas=input_schemas,
+                            response_schemas=output_schemas,
                             extensions=extensions,
                             openapi_version=self.openapi_version,
                         )
@@ -571,7 +755,8 @@ class OpenAPIParser(
                         # Pre-calculate schema and parameter mapping for performance
                         try:
                             flat_schema, param_map = _combine_schemas_and_map_params(
-                                route
+                                route,
+                                convert_refs=False,  # Parser already converted refs
                             )
                             route.flat_param_schema = flat_schema
                             route.parameter_map = param_map
@@ -586,9 +771,6 @@ class OpenAPIParser(
                             }
                             route.parameter_map = {}
                         routes.append(route)
-                        logger.info(
-                            f"Successfully extracted route: {method_upper} {path_str}"
-                        )
                     except ValueError as op_error:
                         # Re-raise ValueError for external reference errors
                         if "External or non-local reference not supported" in str(
@@ -607,7 +789,7 @@ class OpenAPIParser(
                             exc_info=True,
                         )
 
-        logger.info(f"Finished parsing. Extracted {len(routes)} HTTP routes.")
+        logger.debug(f"Finished parsing. Extracted {len(routes)} HTTP routes.")
         return routes