π The fast, Pythonic way to build MCP servers and clients.
fix: stabilize task notification integration tests
Guillaume FORTAINE3d665d48c076
diff --git a/src/fastmcp/server/tasks/elicitation.py b/src/fastmcp/server/tasks/elicitation.pyindex b12d0f10e..299382df6 100644--- a/src/fastmcp/server/tasks/elicitation.py+++ b/src/fastmcp/server/tasks/elicitation.py@@ -5,7 +5,7 @@ in Docket workers. Unlike regular MCP requests, background tasks don't havean active request context, so elicitation requires special handling:1. Set task status to "input_required" via Redis-2. Send notifications/tasks/updated with elicitation metadata+2. Send notifications/tasks/status with elicitation metadata3. Wait for client to send input via tasks/sendInput4. Resume task execution with the provided input@@ -18,7 +18,8 @@ from __future__ import annotationsimport jsonimport loggingimport uuid-from typing import TYPE_CHECKING, Any+from datetime import datetime, timezone+from typing import TYPE_CHECKING, Any, castimport mcp.typesfrom mcp import ServerSession@@ -115,15 +116,23 @@ async def elicit_for_task(ex=ELICIT_TTL_SECONDS,)- # Send task status update notification with input_required status- # This follows SEP-1686 for background task status updates+ # Send task status update notification with input_required status.+ # Use notifications/tasks/status so typed MCP clients can consume it.## NOTE: We use the distributed notification queue instead of session.send_notification()# This enables notifications to work when workers run in separate processes# (Azure Web PubSub / Service Bus inspired pattern)+ timestamp = datetime.now(timezone.utc).isoformat()notification_dict = {- "method": "notifications/tasks/updated",- "params": {},+ "method": "notifications/tasks/status",+ "params": {+ "taskId": task_id,+ "status": "input_required",+ "statusMessage": message,+ "createdAt": timestamp,+ "lastUpdatedAt": timestamp,+ "ttl": ELICIT_TTL_SECONDS * 1000,+ },"_meta": {"modelcontextprotocol.io/related-task": {"taskId": task_id,@@ -172,9 +181,12 @@ async def elicit_for_task(async with docket.redis() as redis:# BLPOP blocks until an item is pushed to the list or timeout# Returns tuple of (key, value) or None on timeout- result = await redis.blpop(- docket.key(response_key),- timeout=max_wait_seconds,+ result = await cast(+ Any,+ redis.blpop(+ [docket.key(response_key)],+ timeout=max_wait_seconds,+ ),)if result:@@ -261,7 +273,7 @@ async def handle_task_input(# Push response to list - this wakes up the BLPOP in elicit_for_task# Using LPUSH instead of SET enables the efficient blocking wait pattern- await redis.lpush(+ await redis.lpush( # type: ignore[invalid-await] # redis-py union type (sync/async)docket.key(response_key),json.dumps(response),)diff --git a/src/fastmcp/server/tasks/handlers.py b/src/fastmcp/server/tasks/handlers.pyindex 646cf82dc..494fce87f 100644--- a/src/fastmcp/server/tasks/handlers.py+++ b/src/fastmcp/server/tasks/handlers.py@@ -112,21 +112,31 @@ async def submit_to_docket(register_task_session(session_id, ctx.session)- # Send notifications/tasks/created per SEP-1686 (mandatory)- # Send BEFORE queuing to avoid race where task completes before notification- notification = mcp.types.JSONRPCNotification(- jsonrpc="2.0",- method="notifications/tasks/created",- params={}, # Empty params per spec- _meta={ # type: ignore[call-arg] # _meta is Pydantic alias for meta field- "modelcontextprotocol.io/related-task": {+ # Send an initial tasks/status notification before queueing.+ # This guarantees clients can observe task creation immediately.+ notification = mcp.types.TaskStatusNotification.model_validate(+ {+ "method": "notifications/tasks/status",+ "params": {"taskId": server_task_id,- }- },+ "status": "working",+ "statusMessage": "Task submitted",+ "createdAt": created_at,+ "lastUpdatedAt": created_at,+ "ttl": ttl_ms,+ "pollInterval": poll_interval_ms,+ },+ "_meta": {+ "modelcontextprotocol.io/related-task": {+ "taskId": server_task_id,+ }+ },+ })+ server_notification = mcp.types.ServerNotification(notification)with suppress(Exception):# Don't let notification failures break task creation- await ctx.session.send_notification(notification) # type: ignore[arg-type]+ await ctx.session.send_notification(server_notification)# Queue function to Docket by key (result storage via execution_ttl)# Use component.add_to_docket() which handles calling conventionsdiff --git a/src/fastmcp/server/tasks/notifications.py b/src/fastmcp/server/tasks/notifications.pyindex 07fe95ff6..2c65e31e1 100644--- a/src/fastmcp/server/tasks/notifications.py+++ b/src/fastmcp/server/tasks/notifications.py@@ -23,7 +23,7 @@ import loggingimport weakreffrom contextlib import suppressfrom datetime import datetime, timezone-from typing import TYPE_CHECKING, Any+from typing import TYPE_CHECKING, Any, castimport mcp.types@@ -67,7 +67,7 @@ async def push_notification(})async with docket.redis() as redis:- await redis.lpush(key, message)+ await redis.lpush(key, message) # type: ignore[invalid-await] # redis-py union type (sync/async)await redis.expire(key, NOTIFICATION_TTL_SECONDS)@@ -104,8 +104,8 @@ async def notification_subscriber_loop(# Blocking wait for notification (timeout refreshes heartbeat)# Using BRPOP (right pop) for FIFO order with LPUSH (left push)- result = await redis.brpop(- queue_key, timeout=SUBSCRIBER_TIMEOUT_SECONDS+ result = await cast(+ Any, redis.brpop([queue_key], timeout=SUBSCRIBER_TIMEOUT_SECONDS))if not result:continue # Timeout - refresh heartbeat and retry@@ -129,7 +129,7 @@ async def notification_subscriber_loop(# Re-queue with incremented attempt (back of queue)message["attempt"] = attempt + 1message["last_error"] = str(send_error)- await redis.lpush(queue_key, json.dumps(message))+ await redis.lpush(queue_key, json.dumps(message)) # type: ignore[invalid-await]logger.debug("Requeued notification for session %s (attempt %d): %s",session_id,@@ -166,18 +166,20 @@ async def _send_mcp_notification(session: MCP ServerSessionnotification_dict: Notification as dict (method, params, _meta)"""- # Build JSONRPCNotification from dict- notification = mcp.types.JSONRPCNotification(- jsonrpc="2.0",- method=notification_dict.get("method", "notifications/tasks/updated"),- params=notification_dict.get("params", {}),- )+ method = notification_dict.get("method", "notifications/tasks/status")+ if method != "notifications/tasks/status":+ raise ValueError(f"Unsupported notification method for subscriber: {method}")- # Preserve _meta if present (contains related-task info for elicitation)- if "_meta" in notification_dict:- notification._meta = notification_dict["_meta"] # type: ignore[attr-defined]+ notification = mcp.types.TaskStatusNotification.model_validate(+ {+ "method": "notifications/tasks/status",+ "params": notification_dict.get("params", {}),+ "_meta": notification_dict.get("_meta"),+ }+ )+ server_notification = mcp.types.ServerNotification(notification)- await session.send_notification(notification) # type: ignore[arg-type]+ await session.send_notification(server_notification)# =============================================================================diff --git a/tests/server/tasks/test_context_background_task.py b/tests/server/tasks/test_context_background_task.pyindex 0cdc9636a..219a7ae21 100644--- a/tests/server/tasks/test_context_background_task.py+++ b/tests/server/tasks/test_context_background_task.py@@ -6,8 +6,10 @@ no mocking of Redis, Docket, or session internals."""import asyncio+from typing import castimport pytest+from mcp import ServerSessionfrom fastmcp import FastMCPfrom fastmcp.client import Client@@ -42,7 +44,7 @@ class TestContextBackgroundTaskSupport:mcp = FastMCP("test")ctx = Context(mcp, task_id="test-task-123")with pytest.raises(AttributeError):- ctx.task_id = "new-id" # type: ignore[misc]+ setattr(ctx, "task_id", "new-id")class TestContextSessionProperty:@@ -64,7 +66,9 @@ class TestContextSessionProperty:_fastmcp_state_prefix = "test-session"mock_session = MockSession()- ctx = Context(mcp, session=mock_session, task_id="test-task-123") # type: ignore[arg-type]+ ctx = Context(+ mcp, session=cast(ServerSession, mock_session), task_id="test-task-123"+ )assert ctx.session is mock_session@@ -76,7 +80,7 @@ class TestContextSessionProperty:_fastmcp_state_prefix = "test-session"mock_session = MockSession()- ctx = Context(mcp, session=mock_session) # type: ignore[arg-type]+ ctx = Context(mcp, session=cast(ServerSession, mock_session))assert ctx.session is mock_session@@ -92,7 +96,7 @@ class TestContextElicitBackgroundTask:class MockSession:_fastmcp_state_prefix = "test-session"- ctx._session = MockSession() # type: ignore[assignment]+ ctx._session = cast(ServerSession, MockSession())with pytest.raises(RuntimeError, match="Docket"):await ctx.elicit("Need input", str)diff --git a/tests/server/tasks/test_notifications.py b/tests/server/tasks/test_notifications.pyindex d669a5ed6..07b2b7f3b 100644--- a/tests/server/tasks/test_notifications.py+++ b/tests/server/tasks/test_notifications.py@@ -7,8 +7,11 @@ No mocking of Redis, sessions, or Docket internals.import asyncio+import mcp.types+from fastmcp import FastMCPfrom fastmcp.client import Client+from fastmcp.client.messages import MessageHandlerfrom fastmcp.server.context import Contextfrom fastmcp.server.elicitation import AcceptedElicitationfrom fastmcp.server.tasks.elicitation import handle_task_input@@ -17,6 +20,24 @@ from fastmcp.server.tasks.notifications import ()+class NotificationCaptureHandler(MessageHandler):+ """Capture server notifications for test assertions."""++ def __init__(self) -> None:+ super().__init__()+ self.notifications: list[mcp.types.ServerNotification] = []++ async def on_notification(self, message: mcp.types.ServerNotification) -> None:+ self.notifications.append(message)++ def for_method(self, method: str) -> list[mcp.types.ServerNotification]:+ return [+ notification+ for notification in self.notifications+ if notification.root.method == method+ ]++class TestNotificationIntegration:"""Integration tests for the notification queue using real Docket memory backend.@@ -27,8 +48,9 @@ class TestNotificationIntegration:"""async def test_notification_delivered_during_elicitation(self):- """Full E2E: notification queue delivers elicitation notification to client."""+ """Full E2E: notification queue delivers input_required metadata to client."""mcp = FastMCP("notification-test")+ notification_handler = NotificationCaptureHandler()elicit_started = asyncio.Event()captured: dict[str, str | None] = {"task_id": None, "session_id": None}@@ -43,11 +65,50 @@ class TestNotificationIntegration:return f"got: {result.data}"return "no value"- async with Client(mcp) as client:+ async with Client(mcp, message_handler=notification_handler) as client:task = await client.call_tool("elicit_tool", {}, task=True)await asyncio.wait_for(elicit_started.wait(), timeout=5.0)- # Poll until the task is waiting for input+ assert captured["task_id"] is not None+ assert captured["session_id"] is not None++ notification: mcp.types.ServerNotification | None = None+ for _ in range(40):+ candidates = notification_handler.for_method(+ "notifications/tasks/status"+ )+ for candidate in reversed(candidates):+ candidate_meta = getattr(candidate.root, "_meta", None)+ related_task = (+ candidate_meta.get("modelcontextprotocol.io/related-task")+ if isinstance(candidate_meta, dict)+ else None+ )+ if (+ isinstance(related_task, dict)+ and related_task.get("status") == "input_required"+ ):+ notification = candidate+ break+ if notification is not None:+ break+ await asyncio.sleep(0.05)++ assert notification is not None, "expected notifications/tasks/status"+ task_meta = getattr(notification.root, "_meta", None)+ assert isinstance(task_meta, dict)++ related_task = task_meta.get("modelcontextprotocol.io/related-task")+ assert isinstance(related_task, dict)+ assert related_task.get("taskId") == captured["task_id"]+ assert related_task.get("status") == "input_required"++ elicitation = related_task.get("elicitation")+ assert isinstance(elicitation, dict)+ assert elicitation.get("message") == "Enter value"+ assert isinstance(elicitation.get("requestId"), str)+ assert isinstance(elicitation.get("requestedSchema"), dict)+success = Falsefor _ in range(40):success = await handle_task_input(@@ -67,7 +128,7 @@ class TestNotificationIntegration:result = await task.result()assert result.data == "got: hello"- async def test_subscriber_lifecycle(self):+ async def test_subscriber_started_and_cleaned_up(self):"""Subscriber starts during background task and stops when client disconnects."""mcp = FastMCP("subscriber-test")tool_started = asyncio.Event()diff --git a/tests/server/tasks/test_task_protocol.py b/tests/server/tasks/test_task_protocol.pyindex 1d1daa02c..9c6a88d22 100644--- a/tests/server/tasks/test_task_protocol.py+++ b/tests/server/tasks/test_task_protocol.py@@ -48,7 +48,7 @@ async def test_task_metadata_includes_task_id_and_ttl(task_enabled_server):async def test_task_notification_sent_after_submission(task_enabled_server):- """Server sends notifications/tasks/created after task submission."""+ """Server sends an initial task status notification after submission."""@task_enabled_server.tool(task=True)async def background_tool(message: str) -> str: