fastmcp 2.2.6__py3-none-any.whl → 2.2.8__py3-none-any.whl

fastmcp/tools/tool.py

@@ -6,13 +6,19 @@ from collections.abc import Callable
 from typing import TYPE_CHECKING, Annotated, Any
 
 import pydantic_core
-from mcp.types import EmbeddedResource, ImageContent, TextContent
+from mcp.types import EmbeddedResource, ImageContent, TextContent, ToolAnnotations
 from mcp.types import Tool as MCPTool
 from pydantic import BaseModel, BeforeValidator, Field
 
 from fastmcp.exceptions import ToolError
-from fastmcp.utilities.func_metadata import FuncMetadata, func_metadata
-from fastmcp.utilities.types import Image, _convert_set_defaults
+from fastmcp.utilities.json_schema import prune_params
+from fastmcp.utilities.logging import get_logger
+from fastmcp.utilities.types import (
+    Image,
+    _convert_set_defaults,
+    find_kwarg_by_type,
+    get_cached_typeadapter,
+)
 
 if TYPE_CHECKING:
     from mcp.server.session import ServerSessionT
@@ -20,6 +26,12 @@ if TYPE_CHECKING:
 
     from fastmcp.server import Context
 
+logger = get_logger(__name__)
+
+
+def default_serializer(data: Any) -> str:
+    return pydantic_core.to_json(data, fallback=str, indent=2).decode()
+
 
 class Tool(BaseModel):
     """Internal tool registration info."""
@@ -28,17 +40,18 @@ class Tool(BaseModel):
     name: str = Field(description="Name of the tool")
     description: str = Field(description="Description of what the tool does")
     parameters: dict[str, Any] = Field(description="JSON schema for tool parameters")
-    fn_metadata: FuncMetadata = Field(
-        description="Metadata about the function including a pydantic model for tool"
-        " arguments"
-    )
-    is_async: bool = Field(description="Whether the tool is async")
     context_kwarg: str | None = Field(
         None, description="Name of the kwarg that should receive context"
     )
     tags: Annotated[set[str], BeforeValidator(_convert_set_defaults)] = Field(
         default_factory=set, description="Tags for the tool"
     )
+    annotations: ToolAnnotations | None = Field(
+        None, description="Additional annotations about the tool"
+    )
+    serializer: Callable[[Any], str] | None = Field(
+        None, description="Optional custom serializer for tool results"
+    )
 
     @classmethod
     def from_function(
@@ -48,50 +61,44 @@ class Tool(BaseModel):
         description: str | None = None,
         context_kwarg: str | None = None,
         tags: set[str] | None = None,
+        annotations: ToolAnnotations | None = None,
+        serializer: Callable[[Any], str] | None = None,
     ) -> Tool:
         """Create a Tool from a function."""
         from fastmcp import Context
 
+        # Reject functions with *args or **kwargs
+        sig = inspect.signature(fn)
+        for param in sig.parameters.values():
+            if param.kind == inspect.Parameter.VAR_POSITIONAL:
+                raise ValueError("Functions with *args are not supported as tools")
+            if param.kind == inspect.Parameter.VAR_KEYWORD:
+                raise ValueError("Functions with **kwargs are not supported as tools")
+
         func_name = name or fn.__name__
 
         if func_name == "<lambda>":
             raise ValueError("You must provide a name for lambda functions")
 
         func_doc = description or fn.__doc__ or ""
-        is_async = inspect.iscoroutinefunction(fn)
+
+        type_adapter = get_cached_typeadapter(fn)
+        schema = type_adapter.json_schema()
 
         if context_kwarg is None:
-            if inspect.ismethod(fn) and hasattr(fn, "__func__"):
-                sig = inspect.signature(fn.__func__)
-            else:
-                sig = inspect.signature(fn)
-            for param_name, param in sig.parameters.items():
-                if param.annotation is Context:
-                    context_kwarg = param_name
-                    break
-
-        # Use callable typing to ensure fn is treated as a callable despite being a classmethod
-        fn_callable: Callable[..., Any] = fn
-        func_arg_metadata = func_metadata(
-            fn_callable,
-            skip_names=[context_kwarg] if context_kwarg is not None else [],
-        )
-        try:
-            parameters = func_arg_metadata.arg_model.model_json_schema()
-        except Exception as e:
-            raise TypeError(
-                f'Unable to parse parameters for function "{fn.__name__}": {e}'
-            ) from e
+            context_kwarg = find_kwarg_by_type(fn, kwarg_type=Context)
+        if context_kwarg:
+            schema = prune_params(schema, params=[context_kwarg])
 
         return cls(
-            fn=fn_callable,
+            fn=fn,
             name=func_name,
             description=func_doc,
-            parameters=parameters,
-            fn_metadata=func_arg_metadata,
-            is_async=is_async,
+            parameters=schema,
             context_kwarg=context_kwarg,
             tags=tags or set(),
+            annotations=annotations,
+            serializer=serializer,
         )
 
     async def run(
@@ -101,18 +108,31 @@ class Tool(BaseModel):
     ) -> list[TextContent | ImageContent | EmbeddedResource]:
         """Run the tool with arguments."""
         try:
-            pass_args = (
-                {self.context_kwarg: context}
-                if self.context_kwarg is not None
-                else None
+            injected_args = (
+                {self.context_kwarg: context} if self.context_kwarg is not None else {}
             )
-            result = await self.fn_metadata.call_fn_with_arg_validation(
-                fn=self.fn,
-                fn_is_async=self.is_async,
-                arguments_to_validate=arguments,
-                arguments_to_pass_directly=pass_args,
-            )
-            return _convert_to_content(result)
+
+            parsed_args = arguments.copy()
+
+            # Pre-parse data from JSON in order to handle cases like `["a", "b", "c"]`
+            # being passed in as JSON inside a string rather than an actual list.
+            #
+            # Claude desktop is prone to this - in fact it seems incapable of NOT doing
+            # this. For sub-models, it tends to pass dicts (JSON objects) as JSON strings,
+            # which can be pre-parsed here.
+            for param_name in self.parameters["properties"]:
+                if isinstance(parsed_args.get(param_name, None), str):
+                    try:
+                        parsed_args[param_name] = json.loads(parsed_args[param_name])
+                    except json.JSONDecodeError:
+                        pass
+
+            type_adapter = get_cached_typeadapter(self.fn)
+            result = type_adapter.validate_python(parsed_args | injected_args)
+            if inspect.isawaitable(result):
+                result = await result
+
+            return _convert_to_content(result, serializer=self.serializer)
         except Exception as e:
             raise ToolError(f"Error executing tool {self.name}: {e}") from e
 
@@ -121,6 +141,7 @@ class Tool(BaseModel):
             "name": self.name,
             "description": self.description,
             "inputSchema": self.parameters,
+            "annotations": self.annotations,
         }
         return MCPTool(**kwargs | overrides)
 
@@ -132,6 +153,7 @@ class Tool(BaseModel):
 
 def _convert_to_content(
     result: Any,
+    serializer: Callable[[Any], str] | None = None,
     _process_as_single_item: bool = False,
 ) -> list[TextContent | ImageContent | EmbeddedResource]:
     """Convert a result to a sequence of content objects."""
@@ -166,23 +188,18 @@ def _convert_to_content(
 
         return other_content + mcp_types
 
-    # if the result is a bytes object, convert it to a text content object
     if not isinstance(result, str):
-        try:
-            jsonable_result = pydantic_core.to_jsonable_python(result)
-            if jsonable_result is None:
-                return [TextContent(type="text", text="null")]
-            elif isinstance(jsonable_result, bool):
-                return [
-                    TextContent(
-                        type="text", text="true" if jsonable_result else "false"
-                    )
-                ]
-            elif isinstance(jsonable_result, str | int | float):
-                return [TextContent(type="text", text=str(jsonable_result))]
-            else:
-                return [TextContent(type="text", text=json.dumps(jsonable_result))]
-        except Exception:
-            result = str(result)
+        if serializer is None:
+            result = default_serializer(result)
+        else:
+            try:
+                result = serializer(result)
+            except Exception as e:
+                logger.warning(
+                    "Error serializing tool result: %s",
+                    e,
+                    exc_info=True,
+                )
+                result = default_serializer(result)
 
     return [TextContent(type="text", text=result)]

fastmcp/tools/tool_manager.py

@@ -4,7 +4,7 @@ from collections.abc import Callable
 from typing import TYPE_CHECKING, Any
 
 from mcp.shared.context import LifespanContextT
-from mcp.types import EmbeddedResource, ImageContent, TextContent
+from mcp.types import EmbeddedResource, ImageContent, TextContent, ToolAnnotations
 
 from fastmcp.exceptions import NotFoundError
 from fastmcp.settings import DuplicateBehavior
@@ -22,8 +22,13 @@ logger = get_logger(__name__)
 class ToolManager:
     """Manages FastMCP tools."""
 
-    def __init__(self, duplicate_behavior: DuplicateBehavior | None = None):
+    def __init__(
+        self,
+        duplicate_behavior: DuplicateBehavior | None = None,
+        serializer: Callable[[Any], str] | None = None,
+    ):
         self._tools: dict[str, Tool] = {}
+        self._serializer = serializer
 
         # Default to "warn" if None is provided
         if duplicate_behavior is None:
@@ -61,9 +66,17 @@ class ToolManager:
         name: str | None = None,
         description: str | None = None,
         tags: set[str] | None = None,
+        annotations: ToolAnnotations | None = None,
     ) -> Tool:
         """Add a tool to the server."""
-        tool = Tool.from_function(fn, name=name, description=description, tags=tags)
+        tool = Tool.from_function(
+            fn,
+            name=name,
+            description=description,
+            tags=tags,
+            annotations=annotations,
+            serializer=self._serializer,
+        )
         return self.add_tool(tool)
 
     def add_tool(self, tool: Tool, key: str | None = None) -> Tool:

fastmcp/utilities/http.py

@@ -0,0 +1,44 @@
+from __future__ import annotations
+
+from contextlib import (
+    asynccontextmanager,
+)
+from contextvars import ContextVar
+
+from starlette.requests import Request
+
+from fastmcp.utilities.logging import get_logger
+
+logger = get_logger(__name__)
+
+
+_current_starlette_request: ContextVar[Request | None] = ContextVar(
+    "starlette_request",
+    default=None,
+)
+
+
+@asynccontextmanager
+async def starlette_request_context(request: Request):
+    token = _current_starlette_request.set(request)
+    try:
+        yield
+    finally:
+        _current_starlette_request.reset(token)
+
+
+def get_current_starlette_request() -> Request | None:
+    return _current_starlette_request.get()
+
+
+class RequestMiddleware:
+    """
+    Middleware that stores each request in a ContextVar
+    """
+
+    def __init__(self, app):
+        self.app = app
+
+    async def __call__(self, scope, receive, send):
+        async with starlette_request_context(Request(scope)):
+            await self.app(scope, receive, send)

fastmcp/utilities/json_schema.py

@@ -0,0 +1,59 @@
+from __future__ import annotations
+
+import copy
+from collections.abc import Mapping, Sequence
+
+
+def _prune_param(schema: dict, param: str) -> dict:
+    """Return a new schema with *param* removed from `properties`, `required`,
+    and (if no longer referenced) `$defs`.
+    """
+
+    # ── 1. drop from properties/required ──────────────────────────────
+    props = schema.get("properties", {})
+    removed = props.pop(param, None)
+    if removed is None:  # nothing to do
+        return schema
+    # Keep empty properties object rather than removing it entirely
+    schema["properties"] = props
+    if param in schema.get("required", []):
+        schema["required"].remove(param)
+        if not schema["required"]:
+            schema.pop("required")
+
+    # ── 2. collect all remaining local $ref targets ───────────────────
+    used_defs: set[str] = set()
+
+    def walk(node: object) -> None:  # depth-first traversal
+        if isinstance(node, Mapping):
+            ref = node.get("$ref")
+            if isinstance(ref, str) and ref.startswith("#/$defs/"):
+                used_defs.add(ref.split("/")[-1])
+            for v in node.values():
+                walk(v)
+        elif isinstance(node, Sequence) and not isinstance(node, str | bytes):
+            for v in node:
+                walk(v)
+
+    walk(schema)
+
+    # ── 3. remove orphaned definitions ────────────────────────────────
+    defs = schema.get("$defs", {})
+    for def_name in list(defs):
+        if def_name not in used_defs:
+            defs.pop(def_name)
+    if not defs:
+        schema.pop("$defs", None)
+
+    return schema
+
+
+def prune_params(schema: dict, params: list[str]) -> dict:
+    """
+    Remove the given parameters from the schema.
+
+    """
+    schema = copy.deepcopy(schema)
+    for param in params:
+        schema = _prune_param(schema, param=param)
+    return schema

fastmcp/utilities/openapi.py

@@ -1001,53 +1001,153 @@ def format_description_with_responses(
     responses: dict[
         str, Any
     ],  # Changed from specific ResponseInfo type to avoid circular imports
+    parameters: list[openapi.ParameterInfo] | None = None,  # Add parameters parameter
+    request_body: openapi.RequestBodyInfo | None = None,  # Add request_body parameter
 ) -> str:
-    """Formats the base description string with response information."""
-    if not responses:
-        return base_description
+    """
+    Formats the base description string with response, parameter, and request body information.
+
+    Args:
+        base_description (str): The initial description to be formatted.
+        responses (dict[str, Any]): A dictionary of response information, keyed by status code.
+        parameters (list[openapi.ParameterInfo] | None, optional): A list of parameter information,
+            including path and query parameters. Each parameter includes details such as name,
+            location, whether it is required, and a description.
+        request_body (openapi.RequestBodyInfo | None, optional): Information about the request body,
+            including its description, whether it is required, and its content schema.
 
+    Returns:
+        str: The formatted description string with additional details about responses, parameters,
+        and the request body.
+    """
     desc_parts = [base_description]
-    response_section = "\n\n**Responses:**"
-    added_response_section = False
 
-    # Determine success codes (common ones)
-    success_codes = {"200", "201", "202", "204"}  # As strings
-    success_status = next((s for s in success_codes if s in responses), None)
+    # Add parameter information
+    if parameters:
+        # Process path parameters
+        path_params = [p for p in parameters if p.location == "path"]
+        if path_params:
+            param_section = "\n\n**Path Parameters:**"
+            desc_parts.append(param_section)
+            for param in path_params:
+                required_marker = " (Required)" if param.required else ""
+                param_desc = f"\n- **{param.name}**{required_marker}: {param.description or 'No description.'}"
+                desc_parts.append(param_desc)
+
+        # Process query parameters
+        query_params = [p for p in parameters if p.location == "query"]
+        if query_params:
+            param_section = "\n\n**Query Parameters:**"
+            desc_parts.append(param_section)
+            for param in query_params:
+                required_marker = " (Required)" if param.required else ""
+                param_desc = f"\n- **{param.name}**{required_marker}: {param.description or 'No description.'}"
+                desc_parts.append(param_desc)
+
+    # Add request body information if present
+    if request_body and request_body.description:
+        req_body_section = "\n\n**Request Body:**"
+        desc_parts.append(req_body_section)
+        required_marker = " (Required)" if request_body.required else ""
+        desc_parts.append(f"\n{request_body.description}{required_marker}")
+
+        # Add request body property descriptions if available
+        if request_body.content_schema:
+            media_type = (
+                "application/json"
+                if "application/json" in request_body.content_schema
+                else next(iter(request_body.content_schema), None)
+            )
+            if media_type:
+                schema = request_body.content_schema.get(media_type, {})
+                if isinstance(schema, dict) and "properties" in schema:
+                    desc_parts.append("\n\n**Request Properties:**")
+                    for prop_name, prop_schema in schema["properties"].items():
+                        if (
+                            isinstance(prop_schema, dict)
+                            and "description" in prop_schema
+                        ):
+                            required = prop_name in schema.get("required", [])
+                            req_mark = " (Required)" if required else ""
+                            desc_parts.append(
+                                f"\n- **{prop_name}**{req_mark}: {prop_schema['description']}"
+                            )
 
-    # Process all responses
-    responses_to_process = responses.items()
+    # Add response information
+    if responses:
+        response_section = "\n\n**Responses:**"
+        added_response_section = False
 
-    for status_code, resp_info in sorted(responses_to_process):
-        if not added_response_section:
-            desc_parts.append(response_section)
-            added_response_section = True
+        # Determine success codes (common ones)
+        success_codes = {"200", "201", "202", "204"}  # As strings
+        success_status = next((s for s in success_codes if s in responses), None)
 
-        status_marker = " (Success)" if status_code == success_status else ""
-        desc_parts.append(
-            f"\n- **{status_code}**{status_marker}: {resp_info.description or 'No description.'}"
-        )
+        # Process all responses
+        responses_to_process = responses.items()
 
-        # Process content schemas for this response
-        if resp_info.content_schema:
-            # Prioritize json, then take first available
-            media_type = (
-                "application/json"
-                if "application/json" in resp_info.content_schema
-                else next(iter(resp_info.content_schema), None)
+        for status_code, resp_info in sorted(responses_to_process):
+            if not added_response_section:
+                desc_parts.append(response_section)
+                added_response_section = True
+
+            status_marker = " (Success)" if status_code == success_status else ""
+            desc_parts.append(
+                f"\n- **{status_code}**{status_marker}: {resp_info.description or 'No description.'}"
             )
 
-            if media_type:
-                schema = resp_info.content_schema.get(media_type)
-                desc_parts.append(f"  - Content-Type: `{media_type}`")
+            # Process content schemas for this response
+            if resp_info.content_schema:
+                # Prioritize json, then take first available
+                media_type = (
+                    "application/json"
+                    if "application/json" in resp_info.content_schema
+                    else next(iter(resp_info.content_schema), None)
+                )
+
+                if media_type:
+                    schema = resp_info.content_schema.get(media_type)
+                    desc_parts.append(f"  - Content-Type: `{media_type}`")
+
+                    # Add response property descriptions
+                    if isinstance(schema, dict):
+                        # Handle array responses
+                        if schema.get("type") == "array" and "items" in schema:
+                            items_schema = schema["items"]
+                            if (
+                                isinstance(items_schema, dict)
+                                and "properties" in items_schema
+                            ):
+                                desc_parts.append("\n  - **Response Item Properties:**")
+                                for prop_name, prop_schema in items_schema[
+                                    "properties"
+                                ].items():
+                                    if (
+                                        isinstance(prop_schema, dict)
+                                        and "description" in prop_schema
+                                    ):
+                                        desc_parts.append(
+                                            f"\n    - **{prop_name}**: {prop_schema['description']}"
+                                        )
+                        # Handle object responses
+                        elif "properties" in schema:
+                            desc_parts.append("\n  - **Response Properties:**")
+                            for prop_name, prop_schema in schema["properties"].items():
+                                if (
+                                    isinstance(prop_schema, dict)
+                                    and "description" in prop_schema
+                                ):
+                                    desc_parts.append(
+                                        f"\n    - **{prop_name}**: {prop_schema['description']}"
+                                    )
 
-                if schema:
                     # Generate Example
-                    example = generate_example_from_schema(schema)
-                    if example != "unknown_type" and example is not None:
-                        desc_parts.append("\n  - **Example:**")
-                        desc_parts.append(
-                            format_json_for_description(example, indent=2)
-                        )
+                    if schema:
+                        example = generate_example_from_schema(schema)
+                        if example != "unknown_type" and example is not None:
+                            desc_parts.append("\n  - **Example:**")
+                            desc_parts.append(
+                                format_json_for_description(example, indent=2)
+                            )
 
     return "\n".join(desc_parts)
 
@@ -1069,7 +1169,15 @@ def _combine_schemas(route: openapi.HTTPRoute) -> dict[str, Any]:
     for param in route.parameters:
         if param.required:
             required.append(param.name)
-        properties[param.name] = param.schema_
+
+        # Copy the schema and add description if available
+        param_schema = param.schema_.copy() if isinstance(param.schema_, dict) else {}
+
+        # Add parameter description to schema if available and not already present
+        if param.description and not param_schema.get("description"):
+            param_schema["description"] = param.description
+
+        properties[param.name] = param_schema
 
     # Add request body if it exists
     if route.request_body and route.request_body.content_schema:
@@ -1077,8 +1185,11 @@ def _combine_schemas(route: openapi.HTTPRoute) -> dict[str, Any]:
         content_type = next(iter(route.request_body.content_schema))
         body_schema = route.request_body.content_schema[content_type]
         body_props = body_schema.get("properties", {})
+
+        # Add request body properties
         for prop_name, prop_schema in body_props.items():
             properties[prop_name] = prop_schema
+
         if route.request_body.required:
             required.extend(body_schema.get("required", []))
 

fastmcp/utilities/types.py

@@ -1,14 +1,79 @@
 """Common types used across FastMCP."""
 
 import base64
+import inspect
+from collections.abc import Callable
+from functools import lru_cache
 from pathlib import Path
-from typing import TypeVar
+from types import UnionType
+from typing import Annotated, TypeVar, Union, get_args, get_origin
 
 from mcp.types import ImageContent
+from pydantic import TypeAdapter
 
 T = TypeVar("T")
 
 
+@lru_cache(maxsize=5000)
+def get_cached_typeadapter(cls: T) -> TypeAdapter[T]:
+    """
+    TypeAdapters are heavy objects, and in an application context we'd typically
+    create them once in a global scope and reuse them as often as possible.
+    However, this isn't feasible for user-generated functions. Instead, we use a
+    cache to minimize the cost of creating them as much as possible.
+    """
+    return TypeAdapter(cls)
+
+
+def issubclass_safe(cls: type, base: type) -> bool:
+    """Check if cls is a subclass of base, even if cls is a type variable."""
+    try:
+        if origin := get_origin(cls):
+            return issubclass_safe(origin, base)
+        return issubclass(cls, base)
+    except TypeError:
+        return False
+
+
+def is_class_member_of_type(cls: type, base: type) -> bool:
+    """
+    Check if cls is a member of base, even if cls is a type variable.
+
+    Base can be a type, a UnionType, or an Annotated type. Generic types are not
+    considered members (e.g. T is not a member of list[T]).
+    """
+    origin = get_origin(cls)
+    # Handle both types of unions: UnionType (from types module, used with | syntax)
+    # and typing.Union (used with Union[] syntax)
+    if origin is UnionType or origin == Union:
+        return any(is_class_member_of_type(arg, base) for arg in get_args(cls))
+    elif origin is Annotated:
+        # For Annotated[T, ...], check if T is a member of base
+        args = get_args(cls)
+        if args:
+            return is_class_member_of_type(args[0], base)
+        return False
+    else:
+        return issubclass_safe(cls, base)
+
+
+def find_kwarg_by_type(fn: Callable, kwarg_type: type) -> str | None:
+    """
+    Find the name of the kwarg that is of type kwarg_type.
+
+    Includes union types that contain the kwarg_type, as well as Annotated types.
+    """
+    if inspect.ismethod(fn) and hasattr(fn, "__func__"):
+        sig = inspect.signature(fn.__func__)
+    else:
+        sig = inspect.signature(fn)
+
+    for name, param in sig.parameters.items():
+        if is_class_member_of_type(param.annotation, kwarg_type):
+            return name
+    return None
+
+
 def _convert_set_defaults(maybe_set: set[T] | list[T] | None) -> set[T]:
     """Convert a set or list to a set, defaulting to an empty set if None."""
     if maybe_set is None: