fix(types): correct FastMCP.call_tool and convert_result return types (#1251)

Signed-off-by: SAY-5 <say.apm35@gmail.com>

Author: SAY-5

src/mcp/server/mcpserver/server.py

@@ -399,8 +399,18 @@ async def list_tools(self) -> list[MCPTool]:
 
     async def call_tool(
         self, name: str, arguments: dict[str, Any], context: Context[LifespanResultT, Any] | None = None
-    ) -> Sequence[ContentBlock] | dict[str, Any]:
-        """Call a tool by name with arguments."""
+    ) -> Sequence[ContentBlock] | CallToolResult | tuple[Sequence[ContentBlock], dict[str, Any]]:
+        """Call a tool by name with arguments.
+
+        Because ``convert_result=True`` is always passed to the tool manager, the
+        return value comes from ``FuncMetadata.convert_result``:
+
+        - ``Sequence[ContentBlock]`` when the tool has no output schema and
+          returned a regular value
+        - ``CallToolResult`` when the tool returned a ``CallToolResult`` directly
+        - ``tuple[Sequence[ContentBlock], dict[str, Any]]`` when the tool has
+          an output schema, where the second element is the structured content
+        """
         if context is None:
             context = Context(mcp_server=self)
         return await self._tool_manager.call_tool(name, arguments, context, convert_result=True)

src/mcp/server/mcpserver/utilities/func_metadata.py

@@ -88,12 +88,17 @@ async def call_fn_with_arg_validation(
         else:
             return await anyio.to_thread.run_sync(functools.partial(fn, **arguments_parsed_dict))
 
-    def convert_result(self, result: Any) -> Any:
+    def convert_result(
+        self, result: Any
+    ) -> Sequence[ContentBlock] | CallToolResult | tuple[Sequence[ContentBlock], dict[str, Any]]:
         """Convert a function call result to the format for the lowlevel tool call handler.
 
-        - If output_model is None, return the unstructured content directly.
-        - If output_model is not None, convert the result to structured output format
-            (dict[str, Any]) and return both unstructured and structured content.
+        - If the function returned a ``CallToolResult`` directly, return it unchanged.
+        - If ``output_model`` is None, return the unstructured content
+          (``Sequence[ContentBlock]``) directly.
+        - If ``output_model`` is not None, convert the result to structured output
+          format (``dict[str, Any]``) and return both unstructured and structured
+          content as a tuple.
 
         Note: we return unstructured content here **even though the lowlevel server
         tool call handler provides generic backwards compatibility serialization of