fastmcp 2.12.5__py3-none-any.whl → 2.14.0__py3-none-any.whl

fastmcp/utilities/logging.py

@@ -6,6 +6,7 @@ from typing import Any, Literal, cast
 
 from rich.console import Console
 from rich.logging import RichHandler
+from typing_extensions import override
 
 import fastmcp
 
@@ -19,7 +20,10 @@ def get_logger(name: str) -> logging.Logger:
     Returns:
         a configured logger instance
     """
-    return logging.getLogger(f"fastmcp.{name}")
+    if name.startswith("fastmcp."):
+        return logging.getLogger(name=name)
+
+    return logging.getLogger(name=f"fastmcp.{name}")
 
 
 def configure_logging(
@@ -47,25 +51,52 @@ def configure_logging(
     if logger is None:
         logger = logging.getLogger("fastmcp")
 
-    # Only configure the FastMCP logger namespace
+    formatter = logging.Formatter("%(message)s")
+
+    # Don't propagate to the root logger
+    logger.propagate = False
+    logger.setLevel(level)
+
+    # Configure the handler for normal logs
     handler = RichHandler(
         console=Console(stderr=True),
-        rich_tracebacks=enable_rich_tracebacks,
         **rich_kwargs,
     )
-    formatter = logging.Formatter("%(message)s")
     handler.setFormatter(formatter)
 
-    logger.setLevel(level)
+    # filter to exclude tracebacks
+    handler.addFilter(lambda record: record.exc_info is None)
+
+    # Configure the handler for tracebacks, for tracebacks we use a compressed format:
+    # no path or level name to maximize width available for the traceback
+    # suppress framework frames and limit the number of frames to 3
+
+    import mcp
+    import pydantic
+
+    # Build traceback kwargs with defaults that can be overridden
+    traceback_kwargs = {
+        "console": Console(stderr=True),
+        "show_path": False,
+        "show_level": False,
+        "rich_tracebacks": enable_rich_tracebacks,
+        "tracebacks_max_frames": 3,
+        "tracebacks_suppress": [fastmcp, mcp, pydantic],
+    }
+    # Override defaults with user-provided values
+    traceback_kwargs.update(rich_kwargs)
+
+    traceback_handler = RichHandler(**traceback_kwargs)  # type: ignore[arg-type]
+    traceback_handler.setFormatter(formatter)
+
+    traceback_handler.addFilter(lambda record: record.exc_info is not None)
 
     # Remove any existing handlers to avoid duplicates on reconfiguration
     for hdlr in logger.handlers[:]:
         logger.removeHandler(hdlr)
 
     logger.addHandler(handler)
-
-    # Don't propagate to the root logger
-    logger.propagate = False
+    logger.addHandler(traceback_handler)
 
 
 @contextlib.contextmanager
@@ -118,3 +149,82 @@ def temporary_log_level(
             )
     else:
         yield
+
+
+_level_to_no: dict[
+    Literal["DEBUG", "INFO", "WARNING", "ERROR", "CRITICAL"] | None, int | None
+] = {
+    "DEBUG": logging.DEBUG,
+    "INFO": logging.INFO,
+    "WARNING": logging.WARNING,
+    "ERROR": logging.ERROR,
+    "CRITICAL": logging.CRITICAL,
+    None: None,
+}
+
+
+class _ClampedLogFilter(logging.Filter):
+    min_level: tuple[int, str] | None
+    max_level: tuple[int, str] | None
+
+    def __init__(
+        self,
+        min_level: Literal["DEBUG", "INFO", "WARNING", "ERROR", "CRITICAL"]
+        | None = None,
+        max_level: Literal["DEBUG", "INFO", "WARNING", "ERROR", "CRITICAL"]
+        | None = None,
+    ):
+        self.min_level = None
+        self.max_level = None
+
+        if min_level_no := _level_to_no.get(min_level):
+            self.min_level = (min_level_no, str(min_level))
+        if max_level_no := _level_to_no.get(max_level):
+            self.max_level = (max_level_no, str(max_level))
+
+        super().__init__()
+
+    @override
+    def filter(self, record: logging.LogRecord) -> bool:
+        if self.max_level:
+            max_level_no, max_level_name = self.max_level
+
+            if record.levelno > max_level_no:
+                record.levelno = max_level_no
+                record.levelname = max_level_name
+                return True
+
+        if self.min_level:
+            min_level_no, min_level_name = self.min_level
+            if record.levelno < min_level_no:
+                record.levelno = min_level_no
+                record.levelname = min_level_name
+                return True
+
+        return True
+
+
+def _clamp_logger(
+    logger: logging.Logger,
+    min_level: Literal["DEBUG", "INFO", "WARNING", "ERROR", "CRITICAL"] | None = None,
+    max_level: Literal["DEBUG", "INFO", "WARNING", "ERROR", "CRITICAL"] | None = None,
+) -> None:
+    """Clamp the logger to a minimum and maximum level.
+
+    If min_level is provided, messages logged at a lower level than `min_level` will have their level increased to `min_level`.
+    If max_level is provided, messages logged at a higher level than `max_level` will have their level decreased to `max_level`.
+
+    Args:
+        min_level: The lower bound of the clamp
+        max_level: The upper bound of the clamp
+    """
+    _unclamp_logger(logger=logger)
+
+    logger.addFilter(filter=_ClampedLogFilter(min_level=min_level, max_level=max_level))
+
+
+def _unclamp_logger(logger: logging.Logger) -> None:
+    """Remove all clamped log filters from the logger."""
+    for filter in logger.filters[:]:
+        if isinstance(filter, _ClampedLogFilter):
+            logger.removeFilter(filter)

fastmcp/utilities/mcp_config.py

@@ -43,8 +43,7 @@ def mcp_server_type_to_servers_and_transports(
 
     if isinstance(mcp_server, TransformingRemoteMCPServer | TransformingStdioMCPServer):
         server, transport = mcp_server._to_server_and_underlying_transport(
-            server_name=server_name,
-            client_name=client_name,
+            server_name=server_name, client_name=client_name
         )
     else:
         transport = mcp_server.to_transport()

fastmcp/utilities/mcp_server_config/__init__.py

@@ -15,11 +15,11 @@ from fastmcp.utilities.mcp_server_config.v1.sources.base import Source
 from fastmcp.utilities.mcp_server_config.v1.sources.filesystem import FileSystemSource
 
 __all__ = [
-    "Source",
     "Deployment",
     "Environment",
-    "UVEnvironment",
-    "MCPServerConfig",
     "FileSystemSource",
+    "MCPServerConfig",
+    "Source",
+    "UVEnvironment",
     "generate_schema",
 ]

fastmcp/utilities/mcp_server_config/v1/environments/base.py

@@ -19,7 +19,6 @@ class Environment(BaseModel, ABC):
         Returns:
             Full command ready for subprocess execution
         """
-        pass
 
     async def prepare(self, output_dir: Path | None = None) -> None:
         """Prepare the environment (optional, can be no-op).
@@ -27,4 +26,4 @@ class Environment(BaseModel, ABC):
         Args:
             output_dir: Directory for persistent environment setup
         """
-        pass  # Default no-op implementation
+        # Default no-op implementation

fastmcp/utilities/mcp_server_config/v1/environments/uv.py

@@ -28,19 +28,19 @@ class UVEnvironment(Environment):
         examples=[["fastmcp>=2.0,<3", "httpx", "pandas>=2.0"]],
     )
 
-    requirements: str | None = Field(
+    requirements: Path | None = Field(
         default=None,
         description="Path to requirements.txt file",
         examples=["requirements.txt", "../requirements/prod.txt"],
     )
 
-    project: str | None = Field(
+    project: Path | None = Field(
         default=None,
         description="Path to project directory containing pyproject.toml",
         examples=[".", "../my-project"],
     )
 
-    editable: list[str] | None = Field(
+    editable: list[Path] | None = Field(
         default=None,
         description="Directories to install in editable mode",
         examples=[[".", "../my-package"], ["/path/to/package"]],
@@ -64,7 +64,7 @@ class UVEnvironment(Environment):
 
         # Add project if specified
         if self.project:
-            args.extend(["--project", str(self.project)])
+            args.extend(["--project", str(self.project.resolve())])
 
         # Add Python version if specified (only if no project, as project has its own Python)
         if self.python and not self.project:
@@ -78,12 +78,12 @@ class UVEnvironment(Environment):
 
         # Add requirements file
         if self.requirements:
-            args.extend(["--with-requirements", str(self.requirements)])
+            args.extend(["--with-requirements", str(self.requirements.resolve())])
 
         # Add editable packages
         if self.editable:
             for editable_path in self.editable:
-                args.extend(["--with-editable", str(editable_path)])
+                args.extend(["--with-editable", str(editable_path.resolve())])
 
         # Add the command
         args.extend(command)

fastmcp/utilities/mcp_server_config/v1/mcp_server_config.py

@@ -192,7 +192,7 @@ class MCPServerConfig(BaseModel):
         """
         if isinstance(v, dict):
             return FileSystemSource(**v)
-        return v
+        return v  # type: ignore[return-value]
 
     @field_validator("environment", mode="before")
     @classmethod
@@ -217,7 +217,7 @@ class MCPServerConfig(BaseModel):
         """
         if isinstance(v, dict):
             return Deployment(**v)  # type: ignore[arg-type]
-        return cast(Deployment, v)
+        return cast(Deployment, v)  # type: ignore[return-value]
 
     @classmethod
     def from_file(cls, file_path: Path) -> MCPServerConfig:
@@ -291,9 +291,9 @@ class MCPServerConfig(BaseModel):
             environment = UVEnvironment(
                 python=python,
                 dependencies=dependencies,
-                requirements=requirements,
-                project=project,
-                editable=[editable] if editable else None,
+                requirements=Path(requirements) if requirements else None,
+                project=Path(project) if project else None,
+                editable=[Path(editable)] if editable else None,
             )
 
         # Build deployment config if any deployment args provided

fastmcp/utilities/mcp_server_config/v1/schema.json

@@ -250,6 +250,7 @@
         "requirements": {
           "anyOf": [
             {
+              "format": "path",
               "type": "string"
             },
             {
@@ -267,6 +268,7 @@
         "project": {
           "anyOf": [
             {
+              "format": "path",
               "type": "string"
             },
             {
@@ -285,6 +287,7 @@
           "anyOf": [
             {
               "items": {
+                "format": "path",
                 "type": "string"
               },
               "type": "array"

fastmcp/utilities/mcp_server_config/v1/sources/base.py

@@ -17,7 +17,6 @@ class Source(BaseModel, ABC):
         need preparation (e.g., local files), this is a no-op.
         """
         # Default implementation for sources that don't need preparation
-        pass
 
     @abstractmethod
     async def load_server(self) -> Any:

fastmcp/{experimental/utilities → utilities}/openapi/README.md

@@ -1,10 +1,10 @@
-# OpenAPI Utilities (New Implementation)
+# OpenAPI Utilities
 
-This directory contains the next-generation OpenAPI integration utilities for FastMCP, designed to replace the legacy `openapi.py` implementation.
+This directory contains the OpenAPI integration utilities for FastMCP.
 
 ## Architecture Overview
 
-The new implementation follows a **stateless request building strategy** using `openapi-core` for high-performance, per-request HTTP request construction, eliminating startup latency while maintaining robust OpenAPI compliance.
+The implementation follows a **stateless request building strategy** using `openapi-core` for high-performance, per-request HTTP request construction, eliminating startup latency while maintaining robust OpenAPI compliance.
 
 ### Core Components
 
@@ -83,7 +83,7 @@ MCP Tool Call → RequestDirector.build() → httpx.Request → HTTP Response
 
 ## Component Integration
 
-### Server Components (`/server/openapi_new/`)
+### Server Components (`/server/openapi/`)
 
 1. **`OpenAPITool`** - Simplified tool implementation using RequestDirector
 2. **`OpenAPIResource`** - Resource implementation with RequestDirector
@@ -104,7 +104,7 @@ All components use the same RequestDirector approach:
 
 ```python
 import httpx
-from fastmcp.server.openapi_new import FastMCPOpenAPI
+from fastmcp.server.openapi import FastMCPOpenAPI
 
 # OpenAPI spec (can be loaded from file/URL)
 openapi_spec = {...}
@@ -124,7 +124,7 @@ async with httpx.AsyncClient() as client:
 ### Direct RequestDirector Usage
 
 ```python
-from fastmcp.experimental.utilities.openapi.director import RequestDirector
+from fastmcp.utilities.openapi.director import RequestDirector
 from jsonschema_path import SchemaPath
 
 # Create RequestDirector manually
@@ -141,7 +141,7 @@ async with httpx.AsyncClient() as client:
 
 ## Testing Strategy
 
-Tests are located in `/tests/server/openapi_new/`:
+Tests are located in `/tests/server/openapi/`:
 
 ### Test Categories
 
@@ -160,34 +160,6 @@ Tests are located in `/tests/server/openapi_new/`:
 - **Performance Focus**: Test that initialization is fast and stateless
 - **Behavioral Testing**: Verify OpenAPI compliance without implementation details
 
-## Migration Guide
-
-### From Legacy Implementation
-
-1. **Import Changes**:
-   ```python
-   # Old
-   from fastmcp.server.openapi import FastMCPOpenAPI
-   
-   # New  
-   from fastmcp.server.openapi_new import FastMCPOpenAPI
-   ```
-
-2. **Constructor**: Same interface, no changes needed
-
-3. **Automatic Benefits**: 
-   - Eliminates startup latency (100-200ms improvement)
-   - Better OpenAPI compliance via openapi-core
-   - Serverless-friendly performance characteristics
-   - Simplified architecture without fallback complexity
-
-### Performance Improvements
-
-- **Cold Start**: Zero latency penalty for serverless deployments
-- **Memory Usage**: Lower memory footprint without generated client code
-- **Reliability**: No dynamic code generation failures
-- **Maintainability**: Simpler architecture with fewer moving parts
-
 ## Future Enhancements
 
 ### Planned Features

fastmcp/utilities/openapi/__init__.py

@@ -0,0 +1,63 @@
+"""OpenAPI utilities for FastMCP - refactored for better maintainability."""
+
+# Import from models
+from .models import (
+    HTTPRoute,
+    HttpMethod,
+    JsonSchema,
+    ParameterInfo,
+    ParameterLocation,
+    RequestBodyInfo,
+    ResponseInfo,
+)
+
+# Import from parser
+from .parser import parse_openapi_to_http_routes
+
+# Import from formatters
+from .formatters import (
+    format_array_parameter,
+    format_deep_object_parameter,
+    format_description_with_responses,
+    format_json_for_description,
+    format_simple_description,
+    generate_example_from_schema,
+)
+
+# Import from schemas
+from .schemas import (
+    _combine_schemas,
+    extract_output_schema_from_responses,
+    clean_schema_for_display,
+    _make_optional_parameter_nullable,
+)
+
+# 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
+__all__ = [
+    "HTTPRoute",
+    "HttpMethod",
+    "JsonSchema",
+    "ParameterInfo",
+    "ParameterLocation",
+    "RequestBodyInfo",
+    "ResponseInfo",
+    "_combine_schemas",
+    "_make_optional_parameter_nullable",
+    "clean_schema_for_display",
+    "convert_openapi_schema_to_json_schema",
+    "convert_schema_definitions",
+    "extract_output_schema_from_responses",
+    "format_array_parameter",
+    "format_deep_object_parameter",
+    "format_description_with_responses",
+    "format_json_for_description",
+    "format_simple_description",
+    "generate_example_from_schema",
+    "parse_openapi_to_http_routes",
+]

fastmcp/{experimental/utilities → utilities}/openapi/director.py

@@ -54,28 +54,27 @@ class RequestDirector:
         url = self._build_url(route.path, path_params, base_url)
 
         # Step 3: Prepare request data
-        request_data = {
-            "method": route.method.upper(),
-            "url": url,
-            "params": query_params if query_params else None,
-            "headers": header_params if header_params else None,
-        }
+        method: str = route.method.upper()
+        params = query_params if query_params else None
+        headers = header_params if header_params else None
+        json_body: dict[str, Any] | list[Any] | None = None
+        content: str | bytes | None = None
 
         # Step 4: Handle request body
         if body is not None:
-            if isinstance(body, dict) or isinstance(body, list):
-                request_data["json"] = body
+            if isinstance(body, dict | list):
+                json_body = body
             else:
-                request_data["content"] = body
+                content = body
 
         # Step 5: Create httpx.Request
         return httpx.Request(
-            method=request_data["method"],
-            url=request_data["url"],
-            params=request_data.get("params"),
-            headers=request_data.get("headers"),
-            json=request_data.get("json"),
-            content=request_data.get("content"),
+            method=method,
+            url=url,
+            params=params,
+            headers=headers,
+            json=json_body,
+            content=content,
         )
 
     def _unflatten_arguments(

fastmcp/{experimental/utilities → utilities}/openapi/formatters.py

@@ -67,13 +67,13 @@ def format_deep_object_parameter(
     param_value: dict, parameter_name: str
 ) -> dict[str, str]:
     """
-    Format a dictionary parameter for deepObject style serialization.
+    Format a dictionary parameter for deep-object 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
+    For example, `{"id": "123", "type": "user"}` becomes
+    `param[id]=123&param[type]=user`.
 
     Args:
         param_value: Dictionary value to format
@@ -84,7 +84,7 @@ def format_deep_object_parameter(
     """
     if not isinstance(param_value, dict):
         logger.warning(
-            f"deepObject style parameter '{parameter_name}' expected dict, got {type(param_value)}"
+            f"Deep-object style parameter '{parameter_name}' expected dict, got {type(param_value)}"
         )
         return {}
 
@@ -181,7 +181,7 @@ def generate_example_from_schema(schema: JsonSchema | None) -> Any:
 
 
 def format_json_for_description(data: Any, indent: int = 2) -> str:
-    """Formats Python data as a JSON string block for markdown."""
+    """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```"

fastmcp/{experimental/utilities → utilities}/openapi/json_schema_converter.py

@@ -60,7 +60,7 @@ def convert_openapi_schema_to_json_schema(
         convert_one_of_to_any_of: Whether to convert oneOf to anyOf
 
     Returns:
-        JSON Schema compatible dictionary
+        JSON Schema-compatible dictionary
     """
     if not isinstance(schema, dict):
         return schema
@@ -164,10 +164,10 @@ def _convert_nullable_field(schema: dict[str, Any]) -> dict[str, Any]:
         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"]
+            result["type"] = [*current_type, "null"]
     elif "oneOf" in result:
         # Convert oneOf to anyOf with null
-        result["anyOf"] = result.pop("oneOf") + [{"type": "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"]):
@@ -176,6 +176,10 @@ def _convert_nullable_field(schema: dict[str, Any]) -> dict[str, Any]:
         # Wrap allOf in anyOf with null option
         result["anyOf"] = [{"allOf": result.pop("allOf")}, {"type": "null"}]
 
+    # Handle enum fields - add null to enum values if present
+    if "enum" in result and None not in result["enum"]:
+        result["enum"] = result["enum"] + [None]
+
     return result
 
 

fastmcp/{experimental/utilities → utilities}/openapi/parser.py

@@ -178,7 +178,7 @@ class OpenAPIParser(
                         else:
                             # Special handling for components
                             if part == "components" and hasattr(target, "components"):
-                                target = getattr(target, "components")
+                                target = target.components
                             elif hasattr(target, part):  # Fallback check
                                 target = getattr(target, part, None)
                             else:
@@ -474,9 +474,22 @@ class OpenAPIParser(
                         and media_type_obj.media_type_schema
                     ):
                         try:
-                            schema_dict = self._extract_schema_as_dict(
-                                media_type_obj.media_type_schema
-                            )
+                            # Track if this is a top-level $ref before resolution
+                            top_level_schema_name = None
+                            media_schema = media_type_obj.media_type_schema
+                            if isinstance(media_schema, self.reference_cls):
+                                ref_str = media_schema.ref
+                                if isinstance(ref_str, str) and ref_str.startswith(
+                                    "#/components/schemas/"
+                                ):
+                                    top_level_schema_name = ref_str.split("/")[-1]
+
+                            schema_dict = self._extract_schema_as_dict(media_schema)
+                            # Add marker for top-level schema if it was a ref
+                            if top_level_schema_name:
+                                schema_dict["x-fastmcp-top-level-schema"] = (
+                                    top_level_schema_name
+                                )
                             resp_info.content_schema[media_type_str] = schema_dict
                         except ValueError as e:
                             # Re-raise ValueError for external reference errors
@@ -541,9 +554,7 @@ class OpenAPIParser(
                 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/"):
+                    if ref.startswith(("#/$defs/", "#/components/schemas/")):
                         schema_name = ref.split("/")[-1]
                     else:
                         return
@@ -619,18 +630,28 @@ class OpenAPIParser(
         Returns:
             Dictionary containing only the schemas needed for outputs
         """
-        needed_schemas = set()
+        if not responses or not all_schemas:
+            return {}
+
+        needed_schemas: set[str] = 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
+            if not response.content_schema:
+                continue
+
+            for content_schema in response.content_schema.values():
+                deps = self._extract_schema_dependencies(content_schema, all_schemas)
+                needed_schemas.update(deps)
+
+                schema_name = content_schema.get("x-fastmcp-top-level-schema")
+                if isinstance(schema_name, str) and schema_name in all_schemas:
+                    needed_schemas.add(schema_name)
+                    self._extract_schema_dependencies(
+                        all_schemas[schema_name],
+                        all_schemas,
+                        collected=needed_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
         }
@@ -795,6 +816,6 @@ class OpenAPIParser(
 
 # Export public symbols
 __all__ = [
-    "parse_openapi_to_http_routes",
     "OpenAPIParser",
+    "parse_openapi_to_http_routes",
 ]