fastmcp 2.9.1__py3-none-any.whl → 2.10.0__py3-none-any.whl

fastmcp/tools/tool.py

@@ -1,17 +1,16 @@
 from __future__ import annotations
 
 import inspect
-import json
 from collections.abc import Callable
 from dataclasses import dataclass
-from typing import TYPE_CHECKING, Any
+from typing import TYPE_CHECKING, Annotated, Any, Generic, Literal, TypeVar
 
+import mcp.types
 import pydantic_core
-from mcp.types import TextContent, ToolAnnotations
+from mcp.types import ContentBlock, TextContent, ToolAnnotations
 from mcp.types import Tool as MCPTool
-from pydantic import Field
+from pydantic import Field, PydanticSchemaGenerationError
 
-import fastmcp
 from fastmcp.server.dependencies import get_context
 from fastmcp.utilities.components import FastMCPComponent
 from fastmcp.utilities.json_schema import compress_schema
@@ -20,9 +19,11 @@ from fastmcp.utilities.types import (
     Audio,
     File,
     Image,
-    MCPContent,
+    NotSet,
+    NotSetT,
     find_kwarg_by_type,
     get_cached_typeadapter,
+    replace_type,
 )
 
 if TYPE_CHECKING:
@@ -30,21 +31,80 @@ if TYPE_CHECKING:
 
 logger = get_logger(__name__)
 
+T = TypeVar("T")
+
+
+@dataclass
+class _WrappedResult(Generic[T]):
+    """Generic wrapper for non-object return types."""
+
+    result: T
+
+
+class _UnserializableType:
+    pass
+
 
 def default_serializer(data: Any) -> str:
     return pydantic_core.to_json(data, fallback=str, indent=2).decode()
 
 
+class ToolResult:
+    def __init__(
+        self,
+        content: list[ContentBlock] | Any | None = None,
+        structured_content: dict[str, Any] | Any | None = None,
+    ):
+        if content is None and structured_content is None:
+            raise ValueError("Either content or structured_content must be provided")
+        elif content is None:
+            content = structured_content
+
+        self.content = _convert_to_content(content)
+
+        if structured_content is not None:
+            try:
+                structured_content = pydantic_core.to_jsonable_python(
+                    structured_content
+                )
+            except pydantic_core.PydanticSerializationError as e:
+                logger.error(
+                    f"Could not serialize structured content. If this is unexpected, set your tool's output_schema to None to disable automatic serialization: {e}"
+                )
+                raise
+            if not isinstance(structured_content, dict):
+                raise ValueError(
+                    "structured_content must be a dict or None. "
+                    f"Got {type(structured_content).__name__}: {structured_content!r}. "
+                    "Tools should wrap non-dict values based on their output_schema."
+                )
+        self.structured_content: dict[str, Any] | None = structured_content
+
+    def to_mcp_result(
+        self,
+    ) -> list[ContentBlock] | tuple[list[ContentBlock], dict[str, Any]]:
+        if self.structured_content is None:
+            return self.content
+        return self.content, self.structured_content
+
+
 class Tool(FastMCPComponent):
     """Internal tool registration info."""
 
-    parameters: dict[str, Any] = Field(description="JSON schema for tool parameters")
-    annotations: ToolAnnotations | None = Field(
-        default=None, description="Additional annotations about the tool"
-    )
-    serializer: Callable[[Any], str] | None = Field(
-        default=None, description="Optional custom serializer for tool results"
-    )
+    parameters: Annotated[
+        dict[str, Any], Field(description="JSON schema for tool parameters")
+    ]
+    output_schema: Annotated[
+        dict[str, Any] | None, Field(description="JSON schema for tool output")
+    ] = None
+    annotations: Annotated[
+        ToolAnnotations | None,
+        Field(description="Additional annotations about the tool"),
+    ] = None
+    serializer: Annotated[
+        Callable[[Any], str] | None,
+        Field(description="Optional custom serializer for tool results"),
+    ] = None
 
     def enable(self) -> None:
         super().enable()
@@ -63,11 +123,20 @@ class Tool(FastMCPComponent):
             pass  # No context available
 
     def to_mcp_tool(self, **overrides: Any) -> MCPTool:
+        if self.title:
+            title = self.title
+        elif self.annotations and self.annotations.title:
+            title = self.annotations.title
+        else:
+            title = None
+
         kwargs = {
             "name": self.name,
             "description": self.description,
             "inputSchema": self.parameters,
+            "outputSchema": self.output_schema,
             "annotations": self.annotations,
+            "title": title,
         }
         return MCPTool(**kwargs | overrides)
 
@@ -75,10 +144,12 @@ class Tool(FastMCPComponent):
     def from_function(
         fn: Callable[..., Any],
         name: str | None = None,
+        title: str | None = None,
         description: str | None = None,
         tags: set[str] | None = None,
         annotations: ToolAnnotations | None = None,
         exclude_args: list[str] | None = None,
+        output_schema: dict[str, Any] | None | NotSetT | Literal[False] = NotSet,
         serializer: Callable[[Any], str] | None = None,
         enabled: bool | None = None,
     ) -> FunctionTool:
@@ -86,16 +157,26 @@ class Tool(FastMCPComponent):
         return FunctionTool.from_function(
             fn=fn,
             name=name,
+            title=title,
             description=description,
             tags=tags,
             annotations=annotations,
             exclude_args=exclude_args,
+            output_schema=output_schema,
             serializer=serializer,
             enabled=enabled,
         )
 
-    async def run(self, arguments: dict[str, Any]) -> list[MCPContent]:
-        """Run the tool with arguments."""
+    async def run(self, arguments: dict[str, Any]) -> ToolResult:
+        """
+        Run the tool with arguments.
+
+        This method is not implemented in the base Tool class and must be
+        implemented by subclasses.
+
+        `run()` can EITHER return a list of ContentBlocks, or a tuple of
+        (list of ContentBlocks, dict of structured output).
+        """
         raise NotImplementedError("Subclasses must implement run()")
 
     @classmethod
@@ -108,6 +189,7 @@ class Tool(FastMCPComponent):
         description: str | None = None,
         tags: set[str] | None = None,
         annotations: ToolAnnotations | None = None,
+        output_schema: dict[str, Any] | None | Literal[False] = None,
         serializer: Callable[[Any], str] | None = None,
         enabled: bool | None = None,
     ) -> TransformedTool:
@@ -121,6 +203,7 @@ class Tool(FastMCPComponent):
             description=description,
             tags=tags,
             annotations=annotations,
+            output_schema=output_schema,
             serializer=serializer,
             enabled=enabled,
         )
@@ -134,10 +217,12 @@ class FunctionTool(Tool):
         cls,
         fn: Callable[..., Any],
         name: str | None = None,
+        title: str | None = None,
         description: str | None = None,
         tags: set[str] | None = None,
         annotations: ToolAnnotations | None = None,
         exclude_args: list[str] | None = None,
+        output_schema: dict[str, Any] | None | NotSetT | Literal[False] = NotSet,
         serializer: Callable[[Any], str] | None = None,
         enabled: bool | None = None,
     ) -> FunctionTool:
@@ -148,18 +233,33 @@ class FunctionTool(Tool):
         if name is None and parsed_fn.name == "<lambda>":
             raise ValueError("You must provide a name for lambda functions")
 
+        if isinstance(output_schema, NotSetT):
+            output_schema = parsed_fn.output_schema
+        elif output_schema is False:
+            output_schema = None
+        # Note: explicit schemas (dict) are used as-is without auto-wrapping
+
+        # Validate that explicit schemas are object type for structured content
+        if output_schema is not None and isinstance(output_schema, dict):
+            if output_schema.get("type") != "object":
+                raise ValueError(
+                    f'Output schemas must have "type" set to "object" due to MCP spec limitations. Received: {output_schema!r}'
+                )
+
         return cls(
             fn=parsed_fn.fn,
             name=name or parsed_fn.name,
+            title=title,
             description=description or parsed_fn.description,
-            parameters=parsed_fn.parameters,
-            tags=tags or set(),
+            parameters=parsed_fn.input_schema,
+            output_schema=output_schema,
             annotations=annotations,
+            tags=tags or set(),
             serializer=serializer,
             enabled=enabled if enabled is not None else True,
         )
 
-    async def run(self, arguments: dict[str, Any]) -> list[MCPContent]:
+    async def run(self, arguments: dict[str, Any]) -> ToolResult:
         """Run the tool with arguments."""
         from fastmcp.server.context import Context
 
@@ -169,41 +269,39 @@ class FunctionTool(Tool):
         if context_kwarg and context_kwarg not in arguments:
             arguments[context_kwarg] = get_context()
 
-        if fastmcp.settings.tool_attempt_parse_json_args:
-            # 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.
-            signature = inspect.signature(self.fn)
-            for param_name in self.parameters["properties"]:
-                arg = arguments.get(param_name, None)
-                # if not in signature, we won't have annotations, so skip logic
-                if param_name not in signature.parameters:
-                    continue
-                # if not a string, we won't have a JSON to parse, so skip logic
-                if not isinstance(arg, str):
-                    continue
-                # skip if the type is a simple type (int, float, bool)
-                if signature.parameters[param_name].annotation in (
-                    int,
-                    float,
-                    bool,
-                ):
-                    continue
-                try:
-                    arguments[param_name] = json.loads(arg)
-
-                except json.JSONDecodeError:
-                    pass
-
         type_adapter = get_cached_typeadapter(self.fn)
         result = type_adapter.validate_python(arguments)
+
         if inspect.isawaitable(result):
             result = await result
 
-        return _convert_to_content(result, serializer=self.serializer)
+        if isinstance(result, ToolResult):
+            return result
+
+        unstructured_result = _convert_to_content(result, serializer=self.serializer)
+
+        structured_output = None
+        # First handle structured content based on output schema, if any
+        if self.output_schema is not None:
+            if self.output_schema.get("x-fastmcp-wrap-result"):
+                # Schema says wrap - always wrap in result key
+                structured_output = {"result": result}
+            else:
+                structured_output = result
+        # If no output schema, try to serialize the result. If it is a dict, use
+        # it as structured content. If it is not a dict, ignore it.
+        if structured_output is None:
+            try:
+                structured_output = pydantic_core.to_jsonable_python(result)
+                if not isinstance(structured_output, dict):
+                    structured_output = None
+            except Exception:
+                pass
+
+        return ToolResult(
+            content=unstructured_result,
+            structured_content=structured_output,
+        )
 
 
 @dataclass
@@ -211,7 +309,8 @@ class ParsedFunction:
     fn: Callable[..., Any]
     name: str
     description: str | None
-    parameters: dict[str, Any]
+    input_schema: dict[str, Any]
+    output_schema: dict[str, Any] | None
 
     @classmethod
     def from_function(
@@ -219,6 +318,7 @@ class ParsedFunction:
         fn: Callable[..., Any],
         exclude_args: list[str] | None = None,
         validate: bool = True,
+        wrap_non_object_output_schema: bool = True,
     ) -> ParsedFunction:
         from fastmcp.server.context import Context
 
@@ -257,9 +357,6 @@ class ParsedFunction:
         if isinstance(fn, staticmethod):
             fn = fn.__func__
 
-        type_adapter = get_cached_typeadapter(fn)
-        schema = type_adapter.json_schema()
-
         prune_params: list[str] = []
         context_kwarg = find_kwarg_by_type(fn, kwarg_type=Context)
         if context_kwarg:
@@ -267,12 +364,67 @@ class ParsedFunction:
         if exclude_args:
             prune_params.extend(exclude_args)
 
-        schema = compress_schema(schema, prune_params=prune_params)
+        input_type_adapter = get_cached_typeadapter(fn)
+        input_schema = input_type_adapter.json_schema()
+        input_schema = compress_schema(input_schema, prune_params=prune_params)
+
+        output_schema = None
+        output_type = inspect.signature(fn).return_annotation
+
+        if output_type not in (inspect._empty, None, Any, ...):
+            # there are a variety of types that we don't want to attempt to
+            # serialize because they are either used by FastMCP internally,
+            # or are MCP content types that explicitly don't form structured
+            # content. By replacing them with an explicitly unserializable type,
+            # we ensure that no output schema is automatically generated.
+            clean_output_type = replace_type(
+                output_type,
+                {
+                    t: _UnserializableType
+                    for t in (
+                        Image,
+                        Audio,
+                        File,
+                        ToolResult,
+                        mcp.types.TextContent,
+                        mcp.types.ImageContent,
+                        mcp.types.AudioContent,
+                        mcp.types.ResourceLink,
+                        mcp.types.EmbeddedResource,
+                    )
+                },
+            )
+
+            try:
+                type_adapter = get_cached_typeadapter(clean_output_type)
+                base_schema = type_adapter.json_schema()
+
+                # Generate schema for wrapped type if it's non-object
+                # because MCP requires that output schemas are objects
+                if (
+                    wrap_non_object_output_schema
+                    and base_schema.get("type") != "object"
+                ):
+                    # 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["x-fastmcp-wrap-result"] = True
+                else:
+                    output_schema = base_schema
+
+                output_schema = compress_schema(output_schema)
+
+            except PydanticSchemaGenerationError as e:
+                if "_UnserializableType" not in str(e):
+                    logger.debug(f"Unable to generate schema for type {output_type!r}")
+
         return cls(
             fn=fn,
             name=fn_name,
             description=fn_doc,
-            parameters=schema,
+            input_schema=input_schema,
+            output_schema=output_schema or None,
         )
 
 
@@ -280,12 +432,12 @@ def _convert_to_content(
     result: Any,
     serializer: Callable[[Any], str] | None = None,
     _process_as_single_item: bool = False,
-) -> list[MCPContent]:
+) -> list[ContentBlock]:
     """Convert a result to a sequence of content objects."""
     if result is None:
         return []
 
-    if isinstance(result, MCPContent):
+    if isinstance(result, ContentBlock):
         return [result]
 
     if isinstance(result, Image):
@@ -308,7 +460,7 @@ def _convert_to_content(
         other_content = []
 
         for item in result:
-            if isinstance(item, MCPContent | Image | Audio | File):
+            if isinstance(item, ContentBlock | Image | Audio | File):
                 mcp_types.append(_convert_to_content(item)[0])
             else:
                 other_content.append(item)

fastmcp/tools/tool_manager.py

@@ -9,9 +9,8 @@ from mcp.types import ToolAnnotations
 from fastmcp import settings
 from fastmcp.exceptions import NotFoundError, ToolError
 from fastmcp.settings import DuplicateBehavior
-from fastmcp.tools.tool import Tool
+from fastmcp.tools.tool import Tool, ToolResult
 from fastmcp.utilities.logging import get_logger
-from fastmcp.utilities.types import MCPContent
 
 if TYPE_CHECKING:
     from fastmcp.server.server import MountedServer
@@ -170,7 +169,7 @@ class ToolManager:
         else:
             raise NotFoundError(f"Tool {key!r} not found")
 
-    async def call_tool(self, key: str, arguments: dict[str, Any]) -> list[MCPContent]:
+    async def call_tool(self, key: str, arguments: dict[str, Any]) -> ToolResult:
         """
         Internal API for servers: Finds and calls a tool, respecting the
         filtered protocol path.