Skip to content

πŸš€ The fast, Pythonic way to build MCP servers and clients.

fix(tasks): let async-generator tools run as background tasks (#5730)

一片一片c66e1812a6f6
diff --git a/fastmcp_slim/fastmcp/utilities/tasks.py b/fastmcp_slim/fastmcp/utilities/tasks.py
index b6cd44e84..8d7d318cf 100644
--- a/fastmcp_slim/fastmcp/utilities/tasks.py
+++ b/fastmcp_slim/fastmcp/utilities/tasks.py
@@ -76,7 +76,15 @@ class TaskConfig:
if isinstance(fn_to_check, staticmethod):
fn_to_check = fn_to_check.__func__
- if not is_coroutine_function(fn_to_check):
+ # Async generators are async even though is_coroutine_function
+ # returns False for them, exactly as the timeout check in
+ # FunctionTool.from_function already allows for. Nothing about
+ # them is sync: the generator's iteration has checkpoints, and its
+ # result is materialized into a single value before it is used.
+ if not (
+ is_coroutine_function(fn_to_check)
+ or inspect.isasyncgenfunction(fn_to_check)
+ ):
raise ValueError(
f"'{name}' uses a sync function but has task execution enabled. "
"Background tasks require async functions."
diff --git a/fastmcp_tasks/fastmcp_tasks/input_loop.py b/fastmcp_tasks/fastmcp_tasks/input_loop.py
index f1f146c09..c6e95be7b 100644
--- a/fastmcp_tasks/fastmcp_tasks/input_loop.py
+++ b/fastmcp_tasks/fastmcp_tasks/input_loop.py
@@ -140,7 +140,16 @@ def reentrant_task_fn(
@functools.wraps(fn)
async def wrapper(*args: Any, **kwargs: Any) -> Any:
try:
- result = await fn(*args, **kwargs)
+ pending = fn(*args, **kwargs)
+ # A tool body may be an async generator: calling it returns the
+ # generator itself, not an awaitable, so awaiting it raises.
+ # The synchronous `tools/call` path consumes these through
+ # FunctionTool._materialize_generator, so the task path has to
+ # consume them the same way or the two paths disagree.
+ if inspect.isasyncgen(pending):
+ result = [item async for item in pending]
+ else:
+ result = await pending
except FastMCPError as exc:
return _error_result(tool_name, exc)
except MCPError:
diff --git a/tests/tasks/server/test_task_async_generator_tools.py b/tests/tasks/server/test_task_async_generator_tools.py
new file mode 100644
index 000000000..7217b9388
--- /dev/null
+++ b/tests/tasks/server/test_task_async_generator_tools.py
@@ -0,0 +1,165 @@
+"""Async-generator tools run as background tasks and match their sync result.
+
+`TaskConfig.validate_function` decided with `is_coroutine_function`, which is
+False for an `async def` containing `yield`, so an async-generator tool was
+rejected as a sync function. Accepting it is only half the fix: the task worker
+awaits the callable's result, and calling an async-generator function returns
+the generator rather than an awaitable, so every task completed with
+"object async_generator can't be used in 'await' expression". The worker now
+materializes the generator the same way the synchronous path does.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+import pytest
+
+from fastmcp import FastMCP
+from fastmcp.tools.function_tool import FunctionTool
+from fastmcp_tasks import TasksExtension
+from tests.tasks.task_helpers import (
+ call_tool_without_optin,
+ run_task,
+ running_task_server,
+)
+
+
+def _text(content: list[Any] | None) -> str | None:
+ """Content is objects on the sync path and plain dicts on the task path."""
+ if not content:
+ return None
+ first = content[0]
+ return first["text"] if isinstance(first, dict) else first.text
+
+
+async def _sync_outcome(
+ server: FastMCP, name: str, arguments: dict[str, Any]
+) -> tuple[str | None, bool]:
+ try:
+ result = await call_tool_without_optin(server, name, arguments)
+ except Exception as exc: # noqa: BLE001 - a tool error is an outcome here
+ return str(exc), True
+ return _text(result.content), False
+
+
+async def _task_outcome(
+ server: FastMCP, name: str, arguments: dict[str, Any]
+) -> tuple[str | None, bool]:
+ task = await run_task(server, name, arguments)
+ assert task.status == "completed"
+ assert task.result is not None
+ return _text(task.result.get("content")), bool(task.result.get("isError"))
+
+
+# --- registration ---------------------------------------------------------
+
+
+async def test_async_generator_tool_with_task_true_is_registered() -> None:
+ mcp = FastMCP("test")
+
+ @mcp.tool(task=True)
+ async def stream():
+ yield "a"
+
+ tool = await mcp.get_tool("stream")
+ assert isinstance(tool, FunctionTool)
+ assert tool.task_config.mode == "optional"
+
+
+async def test_async_generator_tool_with_inherited_task_true_is_registered() -> None:
+ mcp = FastMCP("test", tasks=True)
+
+ @mcp.tool
+ async def stream():
+ yield "a"
+
+ tool = await mcp.get_tool("stream")
+ assert isinstance(tool, FunctionTool)
+ assert tool.task_config.mode == "optional"
+
+
+async def test_async_coroutine_tool_with_task_true_is_registered() -> None:
+ mcp = FastMCP("test")
+
+ @mcp.tool(task=True)
+ async def async_tool(x: int) -> int:
+ return x * 2
+
+ tool = await mcp.get_tool("async_tool")
+ assert isinstance(tool, FunctionTool)
+ assert tool.task_config.mode == "optional"
+
+
+async def test_sync_generator_tool_with_task_true_still_raises() -> None:
+ mcp = FastMCP("test")
+
+ with pytest.raises(ValueError, match="uses a sync function"):
+
+ @mcp.tool(task=True)
+ def stream():
+ yield "a"
+
+
+async def test_sync_function_with_task_true_still_raises() -> None:
+ mcp = FastMCP("test")
+
+ with pytest.raises(ValueError, match="uses a sync function"):
+
+ @mcp.tool(task=True)
+ def sync_tool(x: int) -> int:
+ return x * 2
+
+
+# --- end to end -----------------------------------------------------------
+
+
+def _task_server() -> FastMCP:
+ mcp = FastMCP("generator-tasks")
+ mcp.add_extension(TasksExtension())
+
+ @mcp.tool(task=True)
+ async def agen(n: int):
+ for i in range(n):
+ yield f"item{i}"
+
+ # The annotation describes the materialized list this tool returns (it is
+ # what the output schema is built from), not the generator object itself.
+ @mcp.tool(task=True)
+ async def agen_typed(n: int) -> list[int]: # ty: ignore[invalid-return-type]
+ for i in range(n):
+ yield i
+
+ @mcp.tool(task=True)
+ async def agen_raises(n: int):
+ yield "first"
+ raise ValueError("boom")
+
+ @mcp.tool(task=True)
+ async def coroutine(n: int) -> int:
+ return n * 2
+
+ return mcp
+
+
+ ("name", "arguments"),
+ [
+ ("agen", {"n": 3}),
+ ("agen", {"n": 0}),
+ ("agen_typed", {"n": 3}),
+ ("agen_raises", {"n": 1}),
+ ("coroutine", {"n": 3}),
+ ],
+)
+async def test_task_result_matches_the_sync_result(
+ name: str, arguments: dict[str, Any]
+) -> None:
+ """A task runs the generator body once and reports what the sync path does."""
+ server = _task_server()
+
+ async with running_task_server(server):
+ sync = await _sync_outcome(server, name, arguments)
+ task = await _task_outcome(server, name, arguments)
+
+ assert task == sync