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

fastmcp/server/server.py

@@ -759,7 +759,7 @@ class FastMCP(Generic[LifespanResultT]):
         )
         return await self._apply_middleware(mw_context, _handler)
 
-    def add_tool(self, tool: Tool) -> None:
+    def add_tool(self, tool: Tool) -> Tool:
         """Add a tool to the server.
 
         The tool function can optionally request a Context object by adding a parameter
@@ -767,6 +767,9 @@ class FastMCP(Generic[LifespanResultT]):
 
         Args:
             tool: The Tool instance to register
+
+        Returns:
+            The tool instance that was added to the server.
         """
         self._tool_manager.add_tool(tool)
         self._cache.clear()
@@ -780,6 +783,8 @@ class FastMCP(Generic[LifespanResultT]):
         except RuntimeError:
             pass  # No context available
 
+        return tool
+
     def remove_tool(self, name: str) -> None:
         """Remove a tool from the server.
 
@@ -958,13 +963,15 @@ class FastMCP(Generic[LifespanResultT]):
             enabled=enabled,
         )
 
-    def add_resource(self, resource: Resource) -> None:
+    def add_resource(self, resource: Resource) -> Resource:
         """Add a resource to the server.
 
         Args:
             resource: A Resource instance to add
-        """
 
+        Returns:
+            The resource instance that was added to the server.
+        """
         self._resource_manager.add_resource(resource)
         self._cache.clear()
 
@@ -977,11 +984,16 @@ class FastMCP(Generic[LifespanResultT]):
         except RuntimeError:
             pass  # No context available
 
-    def add_template(self, template: ResourceTemplate) -> None:
+        return resource
+
+    def add_template(self, template: ResourceTemplate) -> ResourceTemplate:
         """Add a resource template to the server.
 
         Args:
             template: A ResourceTemplate instance to add
+
+        Returns:
+            The template instance that was added to the server.
         """
         self._resource_manager.add_template(template)
 
@@ -994,6 +1006,8 @@ class FastMCP(Generic[LifespanResultT]):
         except RuntimeError:
             pass  # No context available
 
+        return template
+
     def add_resource_fn(
         self,
         fn: AnyFunction,
@@ -1159,11 +1173,14 @@ class FastMCP(Generic[LifespanResultT]):
 
         return decorator
 
-    def add_prompt(self, prompt: Prompt) -> None:
+    def add_prompt(self, prompt: Prompt) -> Prompt:
         """Add a prompt to the server.
 
         Args:
             prompt: A Prompt instance to add
+
+        Returns:
+            The prompt instance that was added to the server.
         """
         self._prompt_manager.add_prompt(prompt)
         self._cache.clear()
@@ -1177,6 +1194,8 @@ class FastMCP(Generic[LifespanResultT]):
         except RuntimeError:
             pass  # No context available
 
+        return prompt
+
     @overload
     def prompt(
         self,
@@ -1643,8 +1662,7 @@ class FastMCP(Generic[LifespanResultT]):
             resource_separator: Deprecated. Separator character for resource URIs.
             prompt_separator: Deprecated. Separator character for prompt names.
         """
-        from fastmcp.client.transports import FastMCPTransport
-        from fastmcp.server.proxy import FastMCPProxy, ProxyClient
+        from fastmcp.server.proxy import FastMCPProxy
 
         # Deprecated since 2.9.0
         # Prior to 2.9.0, the first positional argument was the prefix and the
@@ -1696,7 +1714,7 @@ class FastMCP(Generic[LifespanResultT]):
             as_proxy = server._has_lifespan
 
         if as_proxy and not isinstance(server, FastMCPProxy):
-            server = FastMCPProxy(ProxyClient(transport=FastMCPTransport(server)))
+            server = FastMCP.as_proxy(server)
 
         # Delegate mounting to all three managers
         mounted_server = MountedServer(

fastmcp/settings.py

@@ -5,7 +5,7 @@ import warnings
 from pathlib import Path
 from typing import Annotated, Any, Literal
 
-from pydantic import Field, model_validator
+from pydantic import Field, field_validator
 from pydantic.fields import FieldInfo
 from pydantic_settings import (
     BaseSettings,
@@ -99,7 +99,16 @@ class Settings(BaseSettings):
     home: Path = Path.home() / ".fastmcp"
 
     test_mode: bool = False
+
     log_level: LOG_LEVEL = "INFO"
+
+    @field_validator("log_level", mode="before")
+    @classmethod
+    def normalize_log_level(cls, v):
+        if isinstance(v, str):
+            return v.upper()
+        return v
+
     enable_rich_tracebacks: Annotated[
         bool,
         Field(
@@ -162,17 +171,6 @@ class Settings(BaseSettings):
         ),
     ] = None
 
-    @model_validator(mode="after")
-    def setup_logging(self) -> Self:
-        """Finalize the settings."""
-        from fastmcp.utilities.logging import configure_logging
-
-        configure_logging(
-            self.log_level, enable_rich_tracebacks=self.enable_rich_tracebacks
-        )
-
-        return self
-
     # HTTP settings
     host: str = "127.0.0.1"
     port: int = 8000

fastmcp/tools/tool.py

@@ -185,8 +185,9 @@ class Tool(FastMCPComponent):
         tool: Tool,
         transform_fn: Callable[..., Any] | None = None,
         name: str | None = None,
+        title: str | None | NotSetT = NotSet,
         transform_args: dict[str, ArgTransform] | None = None,
-        description: str | None = None,
+        description: str | None | NotSetT = NotSet,
         tags: set[str] | None = None,
         annotations: ToolAnnotations | None = None,
         output_schema: dict[str, Any] | None | Literal[False] = None,
@@ -199,6 +200,7 @@ class Tool(FastMCPComponent):
             tool=tool,
             transform_fn=transform_fn,
             name=name,
+            title=title,
             transform_args=transform_args,
             description=description,
             tags=tags,
@@ -397,7 +399,7 @@ class ParsedFunction:
 
             try:
                 type_adapter = get_cached_typeadapter(clean_output_type)
-                base_schema = type_adapter.json_schema()
+                base_schema = type_adapter.json_schema(mode="serialization")
 
                 # Generate schema for wrapped type if it's non-object
                 # because MCP requires that output schemas are objects
@@ -408,7 +410,7 @@ class ParsedFunction:
                     # Use the wrapped result schema directly
                     wrapped_type = _WrappedResult[clean_output_type]
                     wrapped_adapter = get_cached_typeadapter(wrapped_type)
-                    output_schema = wrapped_adapter.json_schema()
+                    output_schema = wrapped_adapter.json_schema(mode="serialization")
                     output_schema["x-fastmcp-wrap-result"] = True
                 else:
                     output_schema = base_schema

fastmcp/tools/tool_manager.py

@@ -76,7 +76,7 @@ class ToolManager:
             except Exception as e:
                 # Skip failed mounts silently, matches existing behavior
                 logger.warning(
-                    f"Failed to get tools from mounted server '{mounted.prefix}': {e}"
+                    f"Failed to get tools from server: {mounted.server.name!r}, mounted at: {mounted.prefix!r}: {e}"
                 )
                 continue
 

fastmcp/tools/tool_transform.py

@@ -325,7 +325,8 @@ class TransformedTool(Tool):
         cls,
         tool: Tool,
         name: str | None = None,
-        description: str | None = None,
+        title: str | None | NotSetT = NotSet,
+        description: str | None | NotSetT = NotSet,
         tags: set[str] | None = None,
         transform_fn: Callable[..., Any] | None = None,
         transform_args: dict[str, ArgTransform] | None = None,
@@ -342,6 +343,7 @@ class TransformedTool(Tool):
                 to call the parent tool. Functions with **kwargs receive transformed
                 argument names.
             name: New name for the tool. Defaults to parent tool's name.
+            title: New title for the tool. Defaults to parent tool's title.
             transform_args: Optional transformations for parent tool arguments.
                 Only specified arguments are transformed, others pass through unchanged:
                 - Simple rename (str)
@@ -506,13 +508,18 @@ class TransformedTool(Tool):
                     f"{', '.join(sorted(duplicates))}"
                 )
 
-        final_description = description if description is not None else tool.description
+        final_name = name or tool.name
+        final_description = (
+            description if not isinstance(description, NotSetT) else tool.description
+        )
+        final_title = title if not isinstance(title, NotSetT) else tool.title
 
         transformed_tool = cls(
             fn=final_fn,
             forwarding_fn=forwarding_fn,
             parent_tool=tool,
-            name=name or tool.name,
+            name=final_name,
+            title=final_title,
             description=final_description,
             parameters=final_schema,
             output_schema=final_output_schema,

fastmcp/utilities/cli.py

@@ -14,11 +14,11 @@ if TYPE_CHECKING:
     from fastmcp import FastMCP
 
 LOGO_ASCII = r"""
-    _ __ ___ ______           __  __  _____________       ____    ____ 
-   _ __ ___ / ____/___ ______/ /_/  |/  / ____/ __ \     |___ \  / __ \
-  _ __ ___ / /_  / __ `/ ___/ __/ /|_/ / /   / /_/ /     ___/ / / / / /
- _ __ ___ / __/ / /_/ (__  ) /_/ /  / / /___/ ____/     /  __/_/ /_/ / 
-_ __ ___ /_/    \__,_/____/\__/_/  /_/\____/_/         /_____(_)____/  
+    _ __ ___ ______           __  __  _____________    ____    ____ 
+   _ __ ___ / ____/___ ______/ /_/  |/  / ____/ __ \  |___ \  / __ \
+  _ __ ___ / /_  / __ `/ ___/ __/ /|_/ / /   / /_/ /  ___/ / / / / /
+ _ __ ___ / __/ / /_/ (__  ) /_/ /  / / /___/ ____/  /  __/_/ /_/ / 
+_ __ ___ /_/    \__,_/____/\__/_/  /_/\____/_/      /_____(_)____/  
 
 """.lstrip("\n")
 
@@ -94,7 +94,7 @@ def log_server_banner(
         title="FastMCP 2.0",
         title_align="left",
         border_style="dim",
-        padding=(2, 5),
+        padding=(1, 4),
         expand=False,
     )
 

fastmcp/utilities/components.py

@@ -77,3 +77,46 @@ class FastMCPComponent(FastMCPBaseModel):
     def disable(self) -> None:
         """Disable the component."""
         self.enabled = False
+
+    def copy(self) -> Self:
+        """Create a copy of the component."""
+        return self.model_copy()
+
+
+class MirroredComponent(FastMCPComponent):
+    """Base class for components that are mirrored from a remote server.
+
+    Mirrored components cannot be enabled or disabled directly. Call copy() first
+    to create a local version you can modify.
+    """
+
+    _mirrored: bool = PrivateAttr(default=False)
+
+    def __init__(self, *, _mirrored: bool = False, **kwargs: Any) -> None:
+        super().__init__(**kwargs)
+        self._mirrored = _mirrored
+
+    def enable(self) -> None:
+        """Enable the component."""
+        if self._mirrored:
+            raise RuntimeError(
+                f"Cannot enable mirrored component '{self.name}'. "
+                f"Create a local copy first with {self.name}.copy() and add it to your server."
+            )
+        super().enable()
+
+    def disable(self) -> None:
+        """Disable the component."""
+        if self._mirrored:
+            raise RuntimeError(
+                f"Cannot disable mirrored component '{self.name}'. "
+                f"Create a local copy first with {self.name}.copy() and add it to your server."
+            )
+        super().disable()
+
+    def copy(self) -> Self:
+        """Create a copy of the component that can be modified."""
+        # Create a copy and mark it as not mirrored
+        copied = self.model_copy()
+        copied._mirrored = False
+        return copied

fastmcp/utilities/openapi.py

@@ -1,6 +1,6 @@
 import json
 import logging
-from typing import Any, Generic, Literal, TypeVar
+from typing import Any, Generic, Literal, TypeVar, cast
 
 from openapi_pydantic import (
     OpenAPI,
@@ -93,6 +93,40 @@ def format_array_parameter(
             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
+
+
 class ParameterInfo(FastMCPBaseModel):
     """Represents a single parameter for an HTTP operation in our IR."""
 
@@ -102,6 +136,7 @@ class ParameterInfo(FastMCPBaseModel):
     schema_: JsonSchema = Field(..., alias="schema")  # Target name in IR
     description: str | None = None
     explode: bool | None = None  # OpenAPI explode property for array parameters
+    style: str | None = None  # OpenAPI style property for parameter serialization
 
 
 class RequestBodyInfo(FastMCPBaseModel):
@@ -153,6 +188,7 @@ __all__ = [
     "JsonSchema",
     "parse_openapi_to_http_routes",
     "extract_output_schema_from_responses",
+    "format_deep_object_parameter",
 ]
 
 # Type variables for generic parser
@@ -415,8 +451,9 @@ class OpenAPIParser(
                         ):
                             param_schema_dict["default"] = resolved_media_schema.default
 
-                # Extract explode property if present
+                # Extract explode and style properties if present
                 explode = getattr(parameter, "explode", None)
+                style = getattr(parameter, "style", None)
 
                 # Create parameter info object
                 param_info = ParameterInfo(
@@ -426,6 +463,7 @@ class OpenAPIParser(
                     schema=param_schema_dict,
                     description=parameter.description,
                     explode=explode,
+                    style=style,
                 )
                 extracted_params.append(param_info)
             except Exception as e:
@@ -1030,15 +1068,16 @@ def _replace_ref_with_defs(
     """
     schema = info.copy()
     if ref_path := schema.get("$ref"):
-        if ref_path.startswith("#/components/schemas/"):
-            schema_name = ref_path.split("/")[-1]
-            schema["$ref"] = f"#/$defs/{schema_name}"
-        elif not ref_path.startswith("#/"):
-            raise ValueError(
-                f"External or non-local reference not supported: {ref_path}. "
-                f"FastMCP only supports local schema references starting with '#/'. "
-                f"Please include all schema definitions within the OpenAPI document."
-            )
+        if isinstance(ref_path, str):
+            if ref_path.startswith("#/components/schemas/"):
+                schema_name = ref_path.split("/")[-1]
+                schema["$ref"] = f"#/$defs/{schema_name}"
+            elif not ref_path.startswith("#/"):
+                raise ValueError(
+                    f"External or non-local reference not supported: {ref_path}. "
+                    f"FastMCP only supports local schema references starting with '#/'. "
+                    f"Please include all schema definitions within the OpenAPI document."
+                )
     elif properties := schema.get("properties"):
         if "$ref" in properties:
             schema["properties"] = _replace_ref_with_defs(properties)
@@ -1057,9 +1096,85 @@ def _replace_ref_with_defs(
     return schema
 
 
+def _make_optional_parameter_nullable(schema: dict[str, Any]) -> dict[str, Any]:
+    """
+    Make an optional parameter schema nullable to allow None values.
+
+    For optional parameters, we need to allow null values in addition to the
+    specified type to handle cases where None is passed for optional parameters.
+    """
+    # If schema already has multiple types or is already nullable, don't modify
+    if "anyOf" in schema or "oneOf" in schema or "allOf" in schema:
+        return schema
+
+    # If it's already nullable (type includes null), don't modify
+    if isinstance(schema.get("type"), list) and "null" in schema["type"]:
+        return schema
+
+    # Create a new schema that allows null in addition to the original type
+    if "type" in schema:
+        original_type = schema["type"]
+
+        if isinstance(original_type, str):
+            # Single type - make it a union with null
+            nullable_schema = schema.copy()
+
+            nested_non_nullable_schema = {
+                "type": original_type,
+            }
+
+            # If the original type is an array, move the array-specific properties into the now-nested schema
+            # https://json-schema.org/understanding-json-schema/reference/array
+            if original_type == "array":
+                for array_property in [
+                    "items",
+                    "prefixItems",
+                    "unevaluatedItems",
+                    "contains",
+                    "minContains",
+                    "maxContains",
+                    "minItems",
+                    "maxItems",
+                    "uniqueItems",
+                ]:
+                    if array_property in nullable_schema:
+                        nested_non_nullable_schema[array_property] = nullable_schema[
+                            array_property
+                        ]
+                        del nullable_schema[array_property]
+
+            # If the original type is an object, move the object-specific properties into the now-nested schema
+            # https://json-schema.org/understanding-json-schema/reference/object
+            elif original_type == "object":
+                for object_property in [
+                    "properties",
+                    "patternProperties",
+                    "additionalProperties",
+                    "unevaluatedProperties",
+                    "required",
+                    "propertyNames",
+                    "minProperties",
+                    "maxProperties",
+                ]:
+                    if object_property in nullable_schema:
+                        nested_non_nullable_schema[object_property] = nullable_schema[
+                            object_property
+                        ]
+                        del nullable_schema[object_property]
+
+            nullable_schema["anyOf"] = [nested_non_nullable_schema, {"type": "null"}]
+
+            # Remove the original type since we're using anyOf
+            del nullable_schema["type"]
+            return nullable_schema
+
+    return schema
+
+
 def _combine_schemas(route: HTTPRoute) -> dict[str, Any]:
     """
     Combines parameter and request body schemas into a single schema.
+    Handles parameter name collisions by adding location suffixes.
 
     Args:
         route: HTTPRoute object
@@ -1070,17 +1185,19 @@ def _combine_schemas(route: HTTPRoute) -> dict[str, Any]:
     properties = {}
     required = []
 
-    # Add path parameters
+    # First pass: collect parameter names by location and body properties
+    param_names_by_location = {
+        "path": set(),
+        "query": set(),
+        "header": set(),
+        "cookie": set(),
+    }
+    body_props = {}
+
     for param in route.parameters:
-        if param.required:
-            required.append(param.name)
-        properties[param.name] = _replace_ref_with_defs(
-            param.schema_.copy(), param.description
-        )
+        param_names_by_location[param.location].add(param.name)
 
-    # Add request body if it exists
     if route.request_body and route.request_body.content_schema:
-        # For now, just use the first content type's schema
         content_type = next(iter(route.request_body.content_schema))
         body_schema = _replace_ref_with_defs(
             route.request_body.content_schema[content_type].copy(),
@@ -1088,7 +1205,54 @@ def _combine_schemas(route: HTTPRoute) -> dict[str, Any]:
         )
         body_props = body_schema.get("properties", {})
 
-        # Add request body properties
+    # Detect collisions: parameters that exist in both body and path/query/header
+    all_non_body_params = set()
+    for location_params in param_names_by_location.values():
+        all_non_body_params.update(location_params)
+
+    body_param_names = set(body_props.keys())
+    colliding_params = all_non_body_params & body_param_names
+
+    # Add parameters with suffixes for collisions
+    for param in route.parameters:
+        if param.name in colliding_params:
+            # Add suffix for non-body parameters when collision detected
+            suffixed_name = f"{param.name}__{param.location}"
+            if param.required:
+                required.append(suffixed_name)
+
+            # Add location info to description
+            param_schema = _replace_ref_with_defs(
+                param.schema_.copy(), param.description
+            )
+            original_desc = param_schema.get("description", "")
+            location_desc = f"({param.location.capitalize()} parameter)"
+            if original_desc:
+                param_schema["description"] = f"{original_desc} {location_desc}"
+            else:
+                param_schema["description"] = location_desc
+
+            # Make optional parameters nullable to allow None values
+            if not param.required:
+                param_schema = _make_optional_parameter_nullable(param_schema)
+
+            properties[suffixed_name] = param_schema
+        else:
+            # No collision, use original name
+            if param.required:
+                required.append(param.name)
+            param_schema = _replace_ref_with_defs(
+                param.schema_.copy(), param.description
+            )
+
+            # Make optional parameters nullable to allow None values
+            if not param.required:
+                param_schema = _make_optional_parameter_nullable(param_schema)
+
+            properties[param.name] = param_schema
+
+    # Add request body properties (no suffixes for body parameters)
+    if route.request_body and route.request_body.content_schema:
         for prop_name, prop_schema in body_props.items():
             properties[prop_name] = prop_schema
 
@@ -1110,6 +1274,20 @@ def _combine_schemas(route: HTTPRoute) -> dict[str, Any]:
     return result
 
 
+def _adjust_union_types(
+    schema: dict[str, Any] | list[Any],
+) -> dict[str, Any] | list[Any]:
+    """Recursively replace 'oneOf' with 'anyOf' in schema to handle overlapping unions."""
+    if isinstance(schema, dict):
+        if "oneOf" in schema:
+            schema["anyOf"] = schema.pop("oneOf")
+        for k, v in schema.items():
+            schema[k] = _adjust_union_types(v)
+    elif isinstance(schema, list):
+        return [_adjust_union_types(item) for item in schema]
+    return schema
+
+
 def extract_output_schema_from_responses(
     responses: dict[str, ResponseInfo], schema_definitions: dict[str, Any] | None = None
 ) -> dict[str, Any] | None:
@@ -1198,4 +1376,7 @@ def extract_output_schema_from_responses(
     # Use compress_schema to remove unused definitions
     output_schema = compress_schema(output_schema)
 
+    # Adjust union types to handle overlapping unions
+    output_schema = cast(dict[str, Any], _adjust_union_types(output_schema))
+
     return output_schema

{fastmcp-2.10.4.dist-info → fastmcp-2.10.6.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: fastmcp
-Version: 2.10.4
+Version: 2.10.6
 Summary: The fast, Pythonic way to build MCP servers and clients.
 Project-URL: Homepage, https://gofastmcp.com
 Project-URL: Repository, https://github.com/jlowin/fastmcp
@@ -38,7 +38,7 @@ Description-Content-Type: text/markdown
 
 <strong>The fast, Pythonic way to build MCP servers and clients.</strong>
 
-*FastMCP is made with 💙 by [Prefect](https://www.prefect.io/)*
+*FastMCP is made with ☕️ by [Prefect](https://www.prefect.io/)*
 
 [![Docs](https://img.shields.io/badge/docs-gofastmcp.com-blue)](https://gofastmcp.com)
 [![PyPI - Version](https://img.shields.io/pypi/v/fastmcp.svg)](https://pypi.org/project/fastmcp)