fastmcp 2.13.3__py3-none-any.whl → 2.14.1__py3-none-any.whl

fastmcp/server/tasks/keys.py

@@ -0,0 +1,93 @@
+"""Task key management for SEP-1686 background tasks.
+
+Task keys encode security scoping and metadata in the Docket key format:
+    {session_id}:{client_task_id}:{task_type}:{component_identifier}
+
+This format provides:
+- Session-based security scoping (prevents cross-session access)
+- Task type identification (tool/prompt/resource)
+- Component identification (name or URI for result conversion)
+"""
+
+from urllib.parse import quote, unquote
+
+
+def build_task_key(
+    session_id: str,
+    client_task_id: str,
+    task_type: str,
+    component_identifier: str,
+) -> str:
+    """Build Docket task key with embedded metadata.
+
+    Format: {session_id}:{client_task_id}:{task_type}:{component_identifier}
+
+    The component_identifier is URI-encoded to handle special characters (colons, slashes, etc.).
+
+    Args:
+        session_id: Session ID for security scoping
+        client_task_id: Client-provided task ID
+        task_type: Type of task ("tool", "prompt", "resource")
+        component_identifier: Tool name, prompt name, or resource URI
+
+    Returns:
+        Encoded task key for Docket
+
+    Examples:
+        >>> build_task_key("session123", "task456", "tool", "my_tool")
+        'session123:task456:tool:my_tool'
+
+        >>> build_task_key("session123", "task456", "resource", "file://data.txt")
+        'session123:task456:resource:file%3A%2F%2Fdata.txt'
+    """
+    encoded_identifier = quote(component_identifier, safe="")
+    return f"{session_id}:{client_task_id}:{task_type}:{encoded_identifier}"
+
+
+def parse_task_key(task_key: str) -> dict[str, str]:
+    """Parse Docket task key to extract metadata.
+
+    Args:
+        task_key: Encoded task key from Docket
+
+    Returns:
+        Dict with keys: session_id, client_task_id, task_type, component_identifier
+
+    Examples:
+        >>> parse_task_key("session123:task456:tool:my_tool")
+        {'session_id': 'session123', 'client_task_id': 'task456',
+         'task_type': 'tool', 'component_identifier': 'my_tool'}
+
+        >>> parse_task_key("session123:task456:resource:file%3A%2F%2Fdata.txt")
+        {'session_id': 'session123', 'client_task_id': 'task456',
+         'task_type': 'resource', 'component_identifier': 'file://data.txt'}
+    """
+    parts = task_key.split(":", 3)
+    if len(parts) != 4:
+        raise ValueError(
+            f"Invalid task key format: {task_key}. "
+            f"Expected: {{session_id}}:{{client_task_id}}:{{task_type}}:{{component_identifier}}"
+        )
+
+    return {
+        "session_id": parts[0],
+        "client_task_id": parts[1],
+        "task_type": parts[2],
+        "component_identifier": unquote(parts[3]),
+    }
+
+
+def get_client_task_id_from_key(task_key: str) -> str:
+    """Extract just the client task ID from a task key.
+
+    Args:
+        task_key: Full encoded task key
+
+    Returns:
+        Client-provided task ID (second segment)
+
+    Example:
+        >>> get_client_task_id_from_key("session123:task456:tool:my_tool")
+        'task456'
+    """
+    return task_key.split(":", 3)[1]

fastmcp/server/tasks/protocol.py

@@ -0,0 +1,355 @@
+"""SEP-1686 task protocol handlers.
+
+Implements MCP task protocol methods: tasks/get, tasks/result, tasks/list, tasks/cancel, tasks/delete.
+"""
+
+from __future__ import annotations
+
+from datetime import datetime, timedelta, timezone
+from typing import TYPE_CHECKING, Any
+
+import mcp.types
+from docket.execution import ExecutionState
+from mcp.shared.exceptions import McpError
+from mcp.types import (
+    INTERNAL_ERROR,
+    INVALID_PARAMS,
+    CancelTaskResult,
+    ErrorData,
+    GetTaskResult,
+    ListTasksResult,
+)
+
+from fastmcp.server.tasks.converters import (
+    convert_prompt_result,
+    convert_resource_result,
+    convert_tool_result,
+)
+from fastmcp.server.tasks.keys import parse_task_key
+
+if TYPE_CHECKING:
+    from fastmcp.server.server import FastMCP
+
+# Map Docket execution states to MCP task status strings
+# Per SEP-1686 final spec (line 381): tasks MUST begin in "working" status
+DOCKET_TO_MCP_STATE: dict[ExecutionState, str] = {
+    ExecutionState.SCHEDULED: "working",  # Initial state per spec
+    ExecutionState.QUEUED: "working",  # Initial state per spec
+    ExecutionState.RUNNING: "working",
+    ExecutionState.COMPLETED: "completed",
+    ExecutionState.FAILED: "failed",
+    ExecutionState.CANCELLED: "cancelled",
+}
+
+
+async def tasks_get_handler(server: FastMCP, params: dict[str, Any]) -> GetTaskResult:
+    """Handle MCP 'tasks/get' request (SEP-1686).
+
+    Args:
+        server: FastMCP server instance
+        params: Request params containing taskId
+
+    Returns:
+        GetTaskResult: Task status response with spec-compliant fields
+    """
+    import fastmcp.server.context
+
+    async with fastmcp.server.context.Context(fastmcp=server) as ctx:
+        client_task_id = params.get("taskId")
+        if not client_task_id:
+            raise McpError(
+                ErrorData(
+                    code=INVALID_PARAMS, message="Missing required parameter: taskId"
+                )
+            )
+
+        # Get session ID from Context
+        session_id = ctx.session_id
+
+        # Get execution from Docket (use instance attribute for cross-task access)
+        docket = server._docket
+        if docket is None:
+            raise McpError(
+                ErrorData(
+                    code=INTERNAL_ERROR,
+                    message="Background tasks require Docket",
+                )
+            )
+
+        # Look up full task key and creation timestamp from Redis
+        redis_key = f"fastmcp:task:{session_id}:{client_task_id}"
+        created_at_key = f"fastmcp:task:{session_id}:{client_task_id}:created_at"
+        async with docket.redis() as redis:
+            task_key_bytes = await redis.get(redis_key)
+            created_at_bytes = await redis.get(created_at_key)
+
+        task_key = None if task_key_bytes is None else task_key_bytes.decode("utf-8")
+        created_at = (
+            None if created_at_bytes is None else created_at_bytes.decode("utf-8")
+        )
+
+        if task_key is None:
+            # Task not found - raise error per MCP protocol
+            raise McpError(
+                ErrorData(
+                    code=INVALID_PARAMS, message=f"Task {client_task_id} not found"
+                )
+            )
+
+        execution = await docket.get_execution(task_key)
+        if execution is None:
+            # Task key exists but no execution - raise error
+            raise McpError(
+                ErrorData(
+                    code=INVALID_PARAMS,
+                    message=f"Task {client_task_id} execution not found",
+                )
+            )
+
+        # Sync state from Redis
+        await execution.sync()
+
+        # Map Docket state to MCP state
+        mcp_state = DOCKET_TO_MCP_STATE.get(execution.state, "failed")
+
+        # Build response (use default ttl since we don't track per-task values)
+        # createdAt is REQUIRED per SEP-1686 final spec (line 430)
+        # Per spec lines 447-448: SHOULD NOT include related-task metadata in tasks/get
+        error_message = None
+        status_message = None
+
+        if execution.state == ExecutionState.FAILED:
+            try:
+                await execution.get_result(timeout=timedelta(seconds=0))
+            except Exception as error:
+                error_message = str(error)
+                status_message = f"Task failed: {error_message}"
+        elif execution.progress and execution.progress.message:
+            # Extract progress message from Docket if available (spec line 403)
+            status_message = execution.progress.message
+
+        return GetTaskResult(
+            taskId=client_task_id,
+            status=mcp_state,  # type: ignore[arg-type]
+            createdAt=created_at,  # type: ignore[arg-type]
+            lastUpdatedAt=datetime.now(timezone.utc),
+            ttl=60000,
+            pollInterval=1000,
+            statusMessage=status_message,
+        )
+
+
+async def tasks_result_handler(server: FastMCP, params: dict[str, Any]) -> Any:
+    """Handle MCP 'tasks/result' request (SEP-1686).
+
+    Converts raw task return values to MCP types based on task type.
+
+    Args:
+        server: FastMCP server instance
+        params: Request params containing taskId
+
+    Returns:
+        MCP result (CallToolResult, GetPromptResult, or ReadResourceResult)
+    """
+    import fastmcp.server.context
+
+    async with fastmcp.server.context.Context(fastmcp=server) as ctx:
+        client_task_id = params.get("taskId")
+        if not client_task_id:
+            raise McpError(
+                ErrorData(
+                    code=INVALID_PARAMS, message="Missing required parameter: taskId"
+                )
+            )
+
+        # Get session ID from Context
+        session_id = ctx.session_id
+
+        # Get execution from Docket (use instance attribute for cross-task access)
+        docket = server._docket
+        if docket is None:
+            raise McpError(
+                ErrorData(
+                    code=INTERNAL_ERROR,
+                    message="Background tasks require Docket",
+                )
+            )
+
+        # Look up full task key from Redis
+        redis_key = f"fastmcp:task:{session_id}:{client_task_id}"
+        async with docket.redis() as redis:
+            task_key_bytes = await redis.get(redis_key)
+
+        task_key = None if task_key_bytes is None else task_key_bytes.decode("utf-8")
+
+        if task_key is None:
+            raise McpError(
+                ErrorData(
+                    code=INVALID_PARAMS,
+                    message=f"Invalid taskId: {client_task_id} not found",
+                )
+            )
+
+        execution = await docket.get_execution(task_key)
+        if execution is None:
+            raise McpError(
+                ErrorData(
+                    code=INVALID_PARAMS,
+                    message=f"Invalid taskId: {client_task_id} not found",
+                )
+            )
+
+        # Sync state from Redis
+        await execution.sync()
+
+        # Check if completed
+        if execution.state not in (ExecutionState.COMPLETED, ExecutionState.FAILED):
+            mcp_state = DOCKET_TO_MCP_STATE.get(execution.state, "failed")
+            raise McpError(
+                ErrorData(
+                    code=INVALID_PARAMS,
+                    message=f"Task not completed yet (current state: {mcp_state})",
+                )
+            )
+
+        # Get result from Docket
+        try:
+            raw_value = await execution.get_result(timeout=timedelta(seconds=0))
+        except Exception as error:
+            # Task failed - return error result
+            return mcp.types.CallToolResult(
+                content=[mcp.types.TextContent(type="text", text=str(error))],
+                isError=True,
+                _meta={
+                    "modelcontextprotocol.io/related-task": {
+                        "taskId": client_task_id,
+                    }
+                },
+            )
+
+        # Parse task key to get type and component info
+        key_parts = parse_task_key(task_key)
+        task_type = key_parts["task_type"]
+
+        # Convert based on task type (pass client_task_id for metadata)
+        if task_type == "tool":
+            return await convert_tool_result(
+                server, raw_value, key_parts["component_identifier"], client_task_id
+            )
+        elif task_type == "prompt":
+            return await convert_prompt_result(
+                server, raw_value, key_parts["component_identifier"], client_task_id
+            )
+        elif task_type == "resource":
+            return await convert_resource_result(
+                server, raw_value, key_parts["component_identifier"], client_task_id
+            )
+        else:
+            raise McpError(
+                ErrorData(
+                    code=INTERNAL_ERROR,
+                    message=f"Internal error: Unknown task type: {task_type}",
+                )
+            )
+
+
+async def tasks_list_handler(
+    server: FastMCP, params: dict[str, Any]
+) -> ListTasksResult:
+    """Handle MCP 'tasks/list' request (SEP-1686).
+
+    Note: With client-side tracking, this returns minimal info.
+
+    Args:
+        server: FastMCP server instance
+        params: Request params (cursor, limit)
+
+    Returns:
+        ListTasksResult: Response with tasks list and pagination
+    """
+    # Return empty list - client tracks tasks locally
+    return ListTasksResult(tasks=[], nextCursor=None)
+
+
+async def tasks_cancel_handler(
+    server: FastMCP, params: dict[str, Any]
+) -> CancelTaskResult:
+    """Handle MCP 'tasks/cancel' request (SEP-1686).
+
+    Cancels a running task, transitioning it to cancelled state.
+
+    Args:
+        server: FastMCP server instance
+        params: Request params containing taskId
+
+    Returns:
+        CancelTaskResult: Task status response showing cancelled state
+    """
+    import fastmcp.server.context
+
+    async with fastmcp.server.context.Context(fastmcp=server) as ctx:
+        client_task_id = params.get("taskId")
+        if not client_task_id:
+            raise McpError(
+                ErrorData(
+                    code=INVALID_PARAMS, message="Missing required parameter: taskId"
+                )
+            )
+
+        # Get session ID from Context
+        session_id = ctx.session_id
+
+        docket = server._docket
+        if docket is None:
+            raise McpError(
+                ErrorData(
+                    code=INTERNAL_ERROR,
+                    message="Background tasks require Docket",
+                )
+            )
+
+        # Look up full task key and creation timestamp from Redis
+        redis_key = f"fastmcp:task:{session_id}:{client_task_id}"
+        created_at_key = f"fastmcp:task:{session_id}:{client_task_id}:created_at"
+        async with docket.redis() as redis:
+            task_key_bytes = await redis.get(redis_key)
+            created_at_bytes = await redis.get(created_at_key)
+
+        task_key = None if task_key_bytes is None else task_key_bytes.decode("utf-8")
+        created_at = (
+            None if created_at_bytes is None else created_at_bytes.decode("utf-8")
+        )
+
+        if task_key is None:
+            raise McpError(
+                ErrorData(
+                    code=INVALID_PARAMS,
+                    message=f"Invalid taskId: {client_task_id} not found",
+                )
+            )
+
+        # Check if task exists
+        execution = await docket.get_execution(task_key)
+        if execution is None:
+            raise McpError(
+                ErrorData(
+                    code=INVALID_PARAMS,
+                    message=f"Invalid taskId: {client_task_id} not found",
+                )
+            )
+
+        # Cancel via Docket (now sets CANCELLED state natively)
+        await docket.cancel(task_key)
+
+        # Return task status with cancelled state
+        # createdAt is REQUIRED per SEP-1686 final spec (line 430)
+        # Per spec lines 447-448: SHOULD NOT include related-task metadata in tasks/cancel
+        return CancelTaskResult(
+            taskId=client_task_id,
+            status="cancelled",
+            createdAt=created_at or datetime.now(timezone.utc).isoformat(),
+            lastUpdatedAt=datetime.now(timezone.utc),
+            ttl=60_000,
+            pollInterval=1000,
+            statusMessage="Task cancelled",
+        )

fastmcp/server/tasks/subscriptions.py

@@ -0,0 +1,205 @@
+"""Task subscription helpers for sending MCP notifications (SEP-1686).
+
+Subscribes to Docket execution state changes and sends notifications/tasks/status
+to clients when their tasks change state.
+"""
+
+from __future__ import annotations
+
+from contextlib import suppress
+from datetime import datetime, timezone
+from typing import TYPE_CHECKING
+
+from docket.execution import ExecutionState
+from mcp.types import TaskStatusNotification, TaskStatusNotificationParams
+
+from fastmcp.server.tasks.protocol import DOCKET_TO_MCP_STATE
+from fastmcp.utilities.logging import get_logger
+
+if TYPE_CHECKING:
+    from docket import Docket
+    from docket.execution import Execution
+    from mcp.server.session import ServerSession
+
+logger = get_logger(__name__)
+
+
+async def subscribe_to_task_updates(
+    task_id: str,
+    task_key: str,
+    session: ServerSession,
+    docket: Docket,
+) -> None:
+    """Subscribe to Docket execution events and send MCP notifications.
+
+    Per SEP-1686 lines 436-444, servers MAY send notifications/tasks/status
+    when task state changes. This is an optional optimization that reduces
+    client polling frequency.
+
+    Args:
+        task_id: Client-visible task ID (server-generated UUID)
+        task_key: Internal Docket execution key (includes session, type, component)
+        session: MCP ServerSession for sending notifications
+        docket: Docket instance for subscribing to execution events
+    """
+    try:
+        execution = await docket.get_execution(task_key)
+        if execution is None:
+            logger.warning(f"No execution found for task {task_id}")
+            return
+
+        # Subscribe to state and progress events from Docket
+        async for event in execution.subscribe():
+            if event["type"] == "state":
+                # Send notifications/tasks/status when state changes
+                await _send_status_notification(
+                    session=session,
+                    task_id=task_id,
+                    task_key=task_key,
+                    docket=docket,
+                    state=event["state"],  # type: ignore[typeddict-item]
+                )
+            elif event["type"] == "progress":
+                # Send notification when progress message changes
+                await _send_progress_notification(
+                    session=session,
+                    task_id=task_id,
+                    task_key=task_key,
+                    docket=docket,
+                    execution=execution,
+                )
+
+    except Exception as e:
+        logger.warning(f"Subscription task failed for {task_id}: {e}", exc_info=True)
+
+
+async def _send_status_notification(
+    session: ServerSession,
+    task_id: str,
+    task_key: str,
+    docket: Docket,
+    state: ExecutionState,
+) -> None:
+    """Send notifications/tasks/status to client.
+
+    Per SEP-1686 line 454: notification SHOULD NOT include related-task metadata
+    (taskId is already in params).
+
+    Args:
+        session: MCP ServerSession
+        task_id: Client-visible task ID
+        task_key: Internal task key (for metadata lookup)
+        docket: Docket instance
+        state: Docket execution state (enum)
+    """
+    # Map Docket state to MCP status
+    mcp_status = DOCKET_TO_MCP_STATE.get(state, "failed")
+
+    # Extract session_id from task_key for Redis lookup
+    from fastmcp.server.tasks.keys import parse_task_key
+
+    key_parts = parse_task_key(task_key)
+    session_id = key_parts["session_id"]
+
+    # Retrieve createdAt timestamp from Redis
+    created_at_key = f"fastmcp:task:{session_id}:{task_id}:created_at"
+    async with docket.redis() as redis:
+        created_at_bytes = await redis.get(created_at_key)
+
+    created_at = (
+        created_at_bytes.decode("utf-8")
+        if created_at_bytes
+        else datetime.now(timezone.utc).isoformat()
+    )
+
+    # Build status message
+    status_message = None
+    if state == ExecutionState.COMPLETED:
+        status_message = "Task completed successfully"
+    elif state == ExecutionState.FAILED:
+        status_message = "Task failed"
+    elif state == ExecutionState.CANCELLED:
+        status_message = "Task cancelled"
+
+    params_dict = {
+        "taskId": task_id,
+        "status": mcp_status,
+        "createdAt": created_at,
+        "lastUpdatedAt": datetime.now(timezone.utc).isoformat(),
+        "ttl": 60000,
+        "pollInterval": 1000,
+    }
+
+    if status_message:
+        params_dict["statusMessage"] = status_message
+
+    # Create notification (no related-task metadata per spec line 454)
+    notification = TaskStatusNotification(
+        params=TaskStatusNotificationParams.model_validate(params_dict),
+    )
+
+    # Send notification (don't let failures break the subscription)
+    with suppress(Exception):
+        await session.send_notification(notification)  # type: ignore[arg-type]
+
+
+async def _send_progress_notification(
+    session: ServerSession,
+    task_id: str,
+    task_key: str,
+    docket: Docket,
+    execution: Execution,
+) -> None:
+    """Send notifications/tasks/status when progress updates.
+
+    Args:
+        session: MCP ServerSession
+        task_id: Client-visible task ID
+        task_key: Internal task key
+        docket: Docket instance
+        execution: Execution object with current progress
+    """
+    # Sync execution to get latest progress
+    await execution.sync()
+
+    # Only send if there's a progress message
+    if not execution.progress or not execution.progress.message:
+        return
+
+    # Map Docket state to MCP status
+    mcp_status = DOCKET_TO_MCP_STATE.get(execution.state, "failed")
+
+    # Extract session_id from task_key for Redis lookup
+    from fastmcp.server.tasks.keys import parse_task_key
+
+    key_parts = parse_task_key(task_key)
+    session_id = key_parts["session_id"]
+
+    # Retrieve createdAt timestamp from Redis
+    created_at_key = f"fastmcp:task:{session_id}:{task_id}:created_at"
+    async with docket.redis() as redis:
+        created_at_bytes = await redis.get(created_at_key)
+
+    created_at = (
+        created_at_bytes.decode("utf-8")
+        if created_at_bytes
+        else datetime.now(timezone.utc).isoformat()
+    )
+
+    params_dict = {
+        "taskId": task_id,
+        "status": mcp_status,
+        "createdAt": created_at,
+        "lastUpdatedAt": datetime.now(timezone.utc).isoformat(),
+        "ttl": 60000,
+        "pollInterval": 1000,
+        "statusMessage": execution.progress.message,
+    }
+
+    # Create and send notification
+    notification = TaskStatusNotification(
+        params=TaskStatusNotificationParams.model_validate(params_dict),
+    )
+
+    with suppress(Exception):
+        await session.send_notification(notification)  # type: ignore[arg-type]