π The fast, Pythonic way to build MCP servers and clients.
fix: validate task tool arguments against declared types (#4373)
Jeremiah Lowin0cffe411156b
diff --git a/fastmcp_slim/fastmcp/server/tasks/handlers.py b/fastmcp_slim/fastmcp/server/tasks/handlers.pyindex aa9d73bdc..b427a0dfe 100644--- a/fastmcp_slim/fastmcp/server/tasks/handlers.py+++ b/fastmcp_slim/fastmcp/server/tasks/handlers.py@@ -66,6 +66,13 @@ async def submit_to_docket(Returns:CreateTaskResult: Task stub with proper Task object"""+ # Validate and coerce arguments before creating any task state. A failure+ # here must surface before the Redis metadata and initial "working"+ # notification below are written, otherwise an invalid input would orphan a+ # task the client has already observed (#4349).+ if arguments is not None:+ arguments = component.coerce_task_arguments(arguments)+# Generate server-side task ID per SEP-1686 final spec (line 375-377)# Server MUST generate task IDs, clients no longer provide themserver_task_id = str(uuid.uuid4())diff --git a/fastmcp_slim/fastmcp/tools/function_tool.py b/fastmcp_slim/fastmcp/tools/function_tool.pyindex 18466a0f7..a882edc4e 100644--- a/fastmcp_slim/fastmcp/tools/function_tool.py+++ b/fastmcp_slim/fastmcp/tools/function_tool.py@@ -2,6 +2,7 @@from __future__ import annotations+import functoolsimport inspectimport warningsfrom collections.abc import Callable@@ -15,6 +16,7 @@ from typing import (Protocol,TypeVar,cast,+ get_type_hints,overload,runtime_checkable,)@@ -89,6 +91,31 @@ class ToolMeta:run_in_thread: bool = True+def _resolve_param_hints(fn: Callable[..., Any]) -> dict[str, Any]:+ """Resolve a callable's parameter type hints, tolerating partials.++ ``get_type_hints`` rejects ``functools.partial`` objects (and other+ non-function callables), which the synchronous TypeAdapter path handles+ natively. For those, resolve hints against the underlying function and keep+ only the parameters that remain in the partially-bound signature.+ """+ try:+ return get_type_hints(fn, include_extras=True)+ except TypeError:+ target = fn+ while isinstance(target, functools.partial):+ target = target.func+ try:+ resolved = get_type_hints(target, include_extras=True)+ except TypeError:+ return {}+ return {+ name: resolved[name]+ for name in inspect.signature(fn).parameters+ if name in resolved+ }++class FunctionTool(Tool):fn: SkipJsonSchema[Callable[..., Any]]return_type: Annotated[SkipJsonSchema[Any], Field(exclude=True)] = None@@ -393,6 +420,39 @@ class FunctionTool(Tool):kwargs["key"] = task_keyreturn await docket.add(lookup_key, **kwargs)(**arguments)+ def coerce_task_arguments(self, arguments: dict[str, Any]) -> dict[str, Any]:+ """Validate client arguments against their declared parameter types.++ The synchronous ``run()`` path validates arguments through the+ function's Pydantic TypeAdapter, so a parameter typed as a model+ arrives as a model instance. The task path hands the raw arguments to+ Docket, which binds them to the function signature without coercion β+ so without this a model-typed parameter would reach the function as a+ raw dict (#4349). ``submit_to_docket`` calls this up front so coerced+ values are what get queued, and validation errors surface before any+ task state is created. Coerced values survive the trip to the worker+ because Docket serializes task arguments with cloudpickle.++ Injected dependency parameters (Context, Depends()) are excluded via+ the same wrapper used by the synchronous path, so only client-supplied+ arguments are coerced and Docket's dependency resolution is untouched.+ """+ from fastmcp.server.dependencies import without_injected_parameters++ wrapper_fn = without_injected_parameters(+ self.fn, run_in_thread=self.run_in_thread+ )+ hints = _resolve_param_hints(wrapper_fn)++ coerced = dict(arguments)+ for name, value in arguments.items():+ annotation = hints.get(name)+ if annotation is None:+ continue+ adapter = get_cached_typeadapter(annotation)+ coerced[name] = adapter.validate_python(value)+ return coerced+@overloaddef tool(fn: F) -> F: ...diff --git a/fastmcp_slim/fastmcp/utilities/components.py b/fastmcp_slim/fastmcp/utilities/components.pyindex e481aac9e..d371ca495 100644--- a/fastmcp_slim/fastmcp/utilities/components.py+++ b/fastmcp_slim/fastmcp/utilities/components.py@@ -232,6 +232,19 @@ class FastMCPComponent(FastMCPBaseModel):"""# Base implementation: no-op (subclasses override)+ def coerce_task_arguments(self, arguments: dict[str, Any]) -> dict[str, Any]:+ """Validate and coerce task arguments before any task state is created.++ Called by ``submit_to_docket`` up front, so invalid inputs raise before+ the task's Redis metadata and initial status notification exist β+ otherwise a coercion failure during queueing would orphan a task the+ client has already observed. The base implementation is a no-op;+ components that splat arguments into a typed Python callable (e.g.+ ``FunctionTool``) override this to mirror the synchronous validation+ path.+ """+ return arguments+async def add_to_docket(self, docket: Docket, *args: Any, **kwargs: Any) -> Execution:diff --git a/tests/server/tasks/test_task_tools.py b/tests/server/tasks/test_task_tools.pyindex 282c2b46c..26fa1483c 100644--- a/tests/server/tasks/test_task_tools.py+++ b/tests/server/tasks/test_task_tools.py@@ -6,12 +6,18 @@ and test_task_resources.py."""import asyncio+import functools+import mcp.typesimport pytest+from pydantic import BaseModelfrom fastmcp import FastMCPfrom fastmcp.client import Client+from fastmcp.client.messages import MessageHandlerfrom fastmcp.client.tasks import ToolTask+from fastmcp.exceptions import ToolError+from fastmcp.tools.function_tool import _resolve_param_hints@pytest.fixture@@ -32,6 +38,86 @@ async def tool_server():return mcp+class _Item(BaseModel):+ value: str+++async def test_task_tool_validates_model_arguments():+ """Model-typed args are coerced to model instances for task calls (#4349).++ The synchronous path validates arguments through the function's+ TypeAdapter, so a parameter typed as a Pydantic model arrives as a model+ instance. The task path must coerce the same way rather than passing the+ raw dict through to the function.+ """+ mcp = FastMCP("tool-task-validation-server")++ @mcp.tool(task=True)+ async def inspect_items(item: _Item, items: list[_Item]) -> dict[str, str]:+ return {"item": type(item).__name__, "element": type(items[0]).__name__}++ arguments = {"item": {"value": "a"}, "items": [{"value": "b"}]}+ expected = {"item": "_Item", "element": "_Item"}++ async with Client(mcp) as client:+ sync_result = await client.call_tool("inspect_items", arguments)+ task = await client.call_tool("inspect_items", arguments, task=True)+ task_result = await task.result()++ assert sync_result.data == expected+ assert task_result.data == expected+++async def test_task_tool_invalid_arguments_fail_before_task_state():+ """Invalid task arguments are rejected before any task state is created.++ Coercion runs up front in submit_to_docket, so a validation failure surfaces+ before the task's Redis metadata and initial "working" status notification+ are written. Otherwise an invalid input would orphan a task the client had+ already observed via that notification.+ """++ class _Recorder(MessageHandler):+ def __init__(self):+ super().__init__()+ self.methods: list[str] = []++ async def on_notification(self, message: mcp.types.ServerNotification) -> None:+ self.methods.append(message.root.method)++ server = FastMCP("tool-task-invalid-args-server")++ @server.tool(task=True)+ async def needs_item(item: _Item) -> str:+ return item.value++ recorder = _Recorder()+ async with Client(server, message_handler=recorder) as client:+ # `item` is missing its required `value` field.+ task = await client.call_tool("needs_item", {"item": {}}, task=True)+ assert task.returned_immediately+ with pytest.raises(ToolError):+ await task.result()++ assert "notifications/tasks/status" not in recorder.methods+++def test_resolve_param_hints_handles_partials():+ """Partials aren't introspectable by get_type_hints; resolve via the func.++ Argument coercion must not raise for partial-wrapped callables β it should+ resolve hints for the still-unbound parameters.+ """++ async def base(prefix: str, items: list[_Item]) -> str:+ return prefix++ partial_fn = functools.partial(base, "bound")+ hints = _resolve_param_hints(partial_fn)++ assert hints["items"] == list[_Item]++async def test_synchronous_tool_call_unchanged(tool_server):"""Tools without task metadata execute synchronously as before."""async with Client(tool_server) as client: