fastmcp 2.14.5__py3-none-any.whl → 3.0.0b1__py3-none-any.whl

fastmcp/client/client.py

@@ -4,9 +4,9 @@ import asyncio
 import copy
 import datetime
 import secrets
-import uuid
 import weakref
-from contextlib import AsyncExitStack, asynccontextmanager
+from collections.abc import Coroutine
+from contextlib import AsyncExitStack, asynccontextmanager, suppress
 from dataclasses import dataclass, field
 from pathlib import Path
 from typing import Any, Generic, Literal, TypeVar, cast, overload
@@ -14,22 +14,9 @@ from typing import Any, Generic, Literal, TypeVar, cast, overload
 import anyio
 import httpx
 import mcp.types
-import pydantic_core
 from exceptiongroup import catch
 from mcp import ClientSession, McpError
-from mcp.types import (
-    CancelTaskRequest,
-    CancelTaskRequestParams,
-    GetTaskPayloadRequest,
-    GetTaskPayloadRequestParams,
-    GetTaskPayloadResult,
-    GetTaskRequest,
-    GetTaskRequestParams,
-    GetTaskResult,
-    ListTasksRequest,
-    PaginatedRequestParams,
-    TaskStatusNotification,
-)
+from mcp.types import GetTaskResult, TaskStatusNotification
 from pydantic import AnyUrl
 
 import fastmcp
@@ -40,6 +27,12 @@ from fastmcp.client.logging import (
     default_log_handler,
 )
 from fastmcp.client.messages import MessageHandler, MessageHandlerT
+from fastmcp.client.mixins import (
+    ClientPromptsMixin,
+    ClientResourcesMixin,
+    ClientTaskManagementMixin,
+    ClientToolsMixin,
+)
 from fastmcp.client.progress import ProgressHandler, default_progress_handler
 from fastmcp.client.roots import (
     RootsHandler,
@@ -56,13 +49,14 @@ from fastmcp.client.tasks import (
     TaskNotificationHandler,
     ToolTask,
 )
-from fastmcp.exceptions import ToolError
 from fastmcp.mcp_config import MCPConfig
 from fastmcp.server import FastMCP
 from fastmcp.utilities.exceptions import get_catch_handlers
-from fastmcp.utilities.json_schema_type import json_schema_to_type
 from fastmcp.utilities.logging import get_logger
-from fastmcp.utilities.types import get_cached_typeadapter
+from fastmcp.utilities.timeout import (
+    normalize_timeout_to_seconds,
+    normalize_timeout_to_timedelta,
+)
 
 from .transports import (
     ClientTransport,
@@ -94,6 +88,7 @@ __all__ = [
 logger = get_logger(__name__)
 
 T = TypeVar("T", bound="ClientTransport")
+ResultT = TypeVar("ResultT")
 
 
 @dataclass
@@ -124,7 +119,13 @@ class CallToolResult:
     is_error: bool = False
 
 
-class Client(Generic[ClientTransportT]):
+class Client(
+    Generic[ClientTransportT],
+    ClientResourcesMixin,
+    ClientPromptsMixin,
+    ClientToolsMixin,
+    ClientTaskManagementMixin,
+):
     """
     MCP client that delegates connection management to a Transport instance.
 
@@ -273,19 +274,12 @@ class Client(Generic[ClientTransportT]):
         self._progress_handler = progress_handler
 
         # Convert timeout to timedelta if needed
-        if isinstance(timeout, int | float):
-            timeout = datetime.timedelta(seconds=float(timeout))
+        timeout = normalize_timeout_to_timedelta(timeout)
 
-        # handle init handshake timeout
+        # handle init handshake timeout (0 means disabled)
         if init_timeout is None:
             init_timeout = fastmcp.settings.client_init_timeout
-        if isinstance(init_timeout, datetime.timedelta):
-            init_timeout = init_timeout.total_seconds()
-        elif not init_timeout:
-            init_timeout = None
-        else:
-            init_timeout = float(init_timeout)
-        self._init_timeout = init_timeout
+        self._init_timeout = normalize_timeout_to_seconds(init_timeout)
 
         self.auto_initialize = auto_initialize
 
@@ -294,7 +288,7 @@ class Client(Generic[ClientTransportT]):
             "list_roots_callback": None,
             "logging_callback": create_log_callback(log_handler),
             "message_handler": message_handler or TaskNotificationHandler(self),
-            "read_timeout_seconds": timeout,  # ty: ignore[invalid-argument-type]
+            "read_timeout_seconds": timeout,
             "client_info": client_info,
         }
 
@@ -478,12 +472,8 @@ class Client(Generic[ClientTransportT]):
 
         if timeout is None:
             timeout = self._init_timeout
-
-        # Convert timeout if needed
-        if isinstance(timeout, datetime.timedelta):
-            timeout = timeout.total_seconds()
-        elif timeout is not None:
-            timeout = float(timeout)
+        else:
+            timeout = normalize_timeout_to_seconds(timeout)
 
         try:
             with anyio.fail_after(timeout):
@@ -655,6 +645,71 @@ class Client(Generic[ClientTransportT]):
             # Ensure ready event is set even if context manager entry fails
             self._session_state.ready_event.set()
 
+    async def _await_with_session_monitoring(
+        self, coro: Coroutine[Any, Any, ResultT]
+    ) -> ResultT:
+        """Await a coroutine while monitoring the session task for errors.
+
+        When using HTTP transports, server errors (4xx/5xx) are raised in the
+        background session task, not in the coroutine waiting for a response.
+        This causes the client to hang indefinitely since the response never
+        arrives. This method monitors the session task and propagates any
+        exceptions that occur, preventing the client from hanging.
+
+        Args:
+            coro: The coroutine to await (typically a session method call)
+
+        Returns:
+            The result of the coroutine
+
+        Raises:
+            The exception from the session task if it fails, or RuntimeError
+            if the session task completes unexpectedly without an exception.
+        """
+        session_task = self._session_state.session_task
+
+        # If no session task, just await directly
+        if session_task is None:
+            return await coro
+
+        # If session task already failed, raise immediately
+        if session_task.done():
+            # Close the coroutine to avoid "was never awaited" warning
+            coro.close()
+            exc = session_task.exception()
+            if exc:
+                raise exc
+            raise RuntimeError("Session task completed unexpectedly")
+
+        # Create task for our call
+        call_task = asyncio.create_task(coro)
+
+        try:
+            done, _ = await asyncio.wait(
+                {call_task, session_task},
+                return_when=asyncio.FIRST_COMPLETED,
+            )
+
+            if session_task in done:
+                # Session task completed (likely errored) before our call finished
+                call_task.cancel()
+                with anyio.CancelScope(shield=True), suppress(asyncio.CancelledError):
+                    await call_task
+
+                # Raise the session task exception
+                exc = session_task.exception()
+                if exc:
+                    raise exc
+                raise RuntimeError("Session task completed unexpectedly")
+
+            # Our call completed first - get the result
+            return call_task.result()
+        except asyncio.CancelledError:
+            call_task.cancel()
+            with anyio.CancelScope(shield=True), suppress(asyncio.CancelledError):
+                await call_task
+            raise
+
     def _handle_task_status_notification(
         self, notification: TaskStatusNotification
     ) -> None:
@@ -685,7 +740,7 @@ class Client(Generic[ClientTransportT]):
 
     async def ping(self) -> bool:
         """Send a ping request."""
-        result = await self.session.send_ping()
+        result = await self._await_with_session_monitoring(self.session.send_ping())
         return isinstance(result, mcp.types.EmptyResult)
 
     async def cancel(
@@ -719,434 +774,12 @@ class Client(Generic[ClientTransportT]):
 
     async def set_logging_level(self, level: mcp.types.LoggingLevel) -> None:
         """Send a logging/setLevel request."""
-        await self.session.set_logging_level(level)
+        await self._await_with_session_monitoring(self.session.set_logging_level(level))
 
     async def send_roots_list_changed(self) -> None:
         """Send a roots/list_changed notification."""
         await self.session.send_roots_list_changed()
 
-    # --- Resources ---
-
-    async def list_resources_mcp(self) -> mcp.types.ListResourcesResult:
-        """Send a resources/list request and return the complete MCP protocol result.
-
-        Returns:
-            mcp.types.ListResourcesResult: The complete response object from the protocol,
-                containing the list of resources and any additional metadata.
-
-        Raises:
-            RuntimeError: If called while the client is not connected.
-        """
-        logger.debug(f"[{self.name}] called list_resources")
-
-        result = await self.session.list_resources()
-        return result
-
-    async def list_resources(self) -> list[mcp.types.Resource]:
-        """Retrieve a list of resources available on the server.
-
-        Returns:
-            list[mcp.types.Resource]: A list of Resource objects.
-
-        Raises:
-            RuntimeError: If called while the client is not connected.
-        """
-        result = await self.list_resources_mcp()
-        return result.resources
-
-    async def list_resource_templates_mcp(
-        self,
-    ) -> mcp.types.ListResourceTemplatesResult:
-        """Send a resources/listResourceTemplates request and return the complete MCP protocol result.
-
-        Returns:
-            mcp.types.ListResourceTemplatesResult: The complete response object from the protocol,
-                containing the list of resource templates and any additional metadata.
-
-        Raises:
-            RuntimeError: If called while the client is not connected.
-        """
-        logger.debug(f"[{self.name}] called list_resource_templates")
-
-        result = await self.session.list_resource_templates()
-        return result
-
-    async def list_resource_templates(
-        self,
-    ) -> list[mcp.types.ResourceTemplate]:
-        """Retrieve a list of resource templates available on the server.
-
-        Returns:
-            list[mcp.types.ResourceTemplate]: A list of ResourceTemplate objects.
-
-        Raises:
-            RuntimeError: If called while the client is not connected.
-        """
-        result = await self.list_resource_templates_mcp()
-        return result.resourceTemplates
-
-    async def read_resource_mcp(
-        self, uri: AnyUrl | str, meta: dict[str, Any] | None = None
-    ) -> mcp.types.ReadResourceResult:
-        """Send a resources/read request and return the complete MCP protocol result.
-
-        Args:
-            uri (AnyUrl | str): The URI of the resource to read. Can be a string or an AnyUrl object.
-            meta (dict[str, Any] | None, optional): Request metadata (e.g., for SEP-1686 tasks). Defaults to None.
-
-        Returns:
-            mcp.types.ReadResourceResult: The complete response object from the protocol,
-                containing the resource contents and any additional metadata.
-
-        Raises:
-            RuntimeError: If called while the client is not connected.
-        """
-        logger.debug(f"[{self.name}] called read_resource: {uri}")
-
-        if isinstance(uri, str):
-            uri = AnyUrl(uri)  # Ensure AnyUrl
-
-        # If meta provided, use send_request for SEP-1686 task support
-        if meta:
-            task_dict = meta.get("modelcontextprotocol.io/task")
-            request = mcp.types.ReadResourceRequest(
-                params=mcp.types.ReadResourceRequestParams(
-                    uri=uri,
-                    task=mcp.types.TaskMetadata(**task_dict)
-                    if task_dict
-                    else None,  # SEP-1686: task as direct param (spec-compliant)
-                )
-            )
-            result = await self.session.send_request(
-                request=request,  # type: ignore[arg-type]
-                result_type=mcp.types.ReadResourceResult,
-            )
-        else:
-            result = await self.session.read_resource(uri)
-        return result
-
-    @overload
-    async def read_resource(
-        self,
-        uri: AnyUrl | str,
-        *,
-        task: Literal[False] = False,
-    ) -> list[mcp.types.TextResourceContents | mcp.types.BlobResourceContents]: ...
-
-    @overload
-    async def read_resource(
-        self,
-        uri: AnyUrl | str,
-        *,
-        task: Literal[True],
-        task_id: str | None = None,
-        ttl: int = 60000,
-    ) -> ResourceTask: ...
-
-    async def read_resource(
-        self,
-        uri: AnyUrl | str,
-        *,
-        task: bool = False,
-        task_id: str | None = None,
-        ttl: int = 60000,
-    ) -> (
-        list[mcp.types.TextResourceContents | mcp.types.BlobResourceContents]
-        | ResourceTask
-    ):
-        """Read the contents of a resource or resolved template.
-
-        Args:
-            uri (AnyUrl | str): The URI of the resource to read. Can be a string or an AnyUrl object.
-            task (bool): If True, execute as background task (SEP-1686). Defaults to False.
-            task_id (str | None): Optional client-provided task ID (auto-generated if not provided).
-            ttl (int): Time to keep results available in milliseconds (default 60s).
-
-        Returns:
-            list[mcp.types.TextResourceContents | mcp.types.BlobResourceContents] | ResourceTask:
-                A list of content objects if task=False, or a ResourceTask object if task=True.
-
-        Raises:
-            RuntimeError: If called while the client is not connected.
-        """
-        if task:
-            return await self._read_resource_as_task(uri, task_id, ttl)
-
-        if isinstance(uri, str):
-            try:
-                uri = AnyUrl(uri)  # Ensure AnyUrl
-            except Exception as e:
-                raise ValueError(
-                    f"Provided resource URI is invalid: {str(uri)!r}"
-                ) from e
-        result = await self.read_resource_mcp(uri)
-        return result.contents
-
-    async def _read_resource_as_task(
-        self,
-        uri: AnyUrl | str,
-        task_id: str | None = None,
-        ttl: int = 60000,
-    ) -> ResourceTask:
-        """Read a resource for background execution (SEP-1686).
-
-        Returns a ResourceTask object that handles both background and immediate execution.
-
-        Args:
-            uri: Resource URI to read
-            task_id: Optional client-provided task ID (ignored, for backward compatibility)
-            ttl: Time to keep results available in milliseconds (default 60s)
-
-        Returns:
-            ResourceTask: Future-like object for accessing task status and results
-        """
-        # Per SEP-1686 final spec: client sends only ttl, server generates taskId
-        # Read resource with task metadata (no taskId sent)
-        result = await self.read_resource_mcp(
-            uri=uri,
-            meta={
-                "modelcontextprotocol.io/task": {
-                    "ttl": ttl,
-                }
-            },
-        )
-
-        # Check if server accepted background execution
-        # If response includes task metadata with taskId, server accepted background mode
-        # If response includes returned_immediately=True, server declined and executed sync
-        task_meta = (result.meta or {}).get("modelcontextprotocol.io/task", {})
-        if task_meta.get("taskId"):
-            # Background execution accepted - extract server-generated taskId
-            server_task_id = task_meta["taskId"]
-            # Track this task ID for list_tasks()
-            self._submitted_task_ids.add(server_task_id)
-
-            # Create task object
-            task_obj = ResourceTask(
-                self, server_task_id, uri=str(uri), immediate_result=None
-            )
-
-            # Register for notification routing
-            self._task_registry[server_task_id] = weakref.ref(task_obj)  # type: ignore[assignment]
-
-            return task_obj
-        else:
-            # Server declined background execution (graceful degradation)
-            # Use a synthetic task ID for the immediate result
-            synthetic_task_id = task_id or str(uuid.uuid4())
-            return ResourceTask(
-                self, synthetic_task_id, uri=str(uri), immediate_result=result.contents
-            )
-
-    # async def subscribe_resource(self, uri: AnyUrl | str) -> None:
-    #     """Send a resources/subscribe request."""
-    #     if isinstance(uri, str):
-    #         uri = AnyUrl(uri)
-    #     await self.session.subscribe_resource(uri)
-
-    # async def unsubscribe_resource(self, uri: AnyUrl | str) -> None:
-    #     """Send a resources/unsubscribe request."""
-    #     if isinstance(uri, str):
-    #         uri = AnyUrl(uri)
-    #     await self.session.unsubscribe_resource(uri)
-
-    # --- Prompts ---
-
-    async def list_prompts_mcp(self) -> mcp.types.ListPromptsResult:
-        """Send a prompts/list request and return the complete MCP protocol result.
-
-        Returns:
-            mcp.types.ListPromptsResult: The complete response object from the protocol,
-                containing the list of prompts and any additional metadata.
-
-        Raises:
-            RuntimeError: If called while the client is not connected.
-        """
-        logger.debug(f"[{self.name}] called list_prompts")
-
-        result = await self.session.list_prompts()
-        return result
-
-    async def list_prompts(self) -> list[mcp.types.Prompt]:
-        """Retrieve a list of prompts available on the server.
-
-        Returns:
-            list[mcp.types.Prompt]: A list of Prompt objects.
-
-        Raises:
-            RuntimeError: If called while the client is not connected.
-        """
-        result = await self.list_prompts_mcp()
-        return result.prompts
-
-    # --- Prompt ---
-    async def get_prompt_mcp(
-        self,
-        name: str,
-        arguments: dict[str, Any] | None = None,
-        meta: dict[str, Any] | None = None,
-    ) -> mcp.types.GetPromptResult:
-        """Send a prompts/get request and return the complete MCP protocol result.
-
-        Args:
-            name (str): The name of the prompt to retrieve.
-            arguments (dict[str, Any] | None, optional): Arguments to pass to the prompt. Defaults to None.
-            meta (dict[str, Any] | None, optional): Request metadata (e.g., for SEP-1686 tasks). Defaults to None.
-
-        Returns:
-            mcp.types.GetPromptResult: The complete response object from the protocol,
-                containing the prompt messages and any additional metadata.
-
-        Raises:
-            RuntimeError: If called while the client is not connected.
-        """
-        logger.debug(f"[{self.name}] called get_prompt: {name}")
-
-        # Serialize arguments for MCP protocol - convert non-string values to JSON
-        serialized_arguments: dict[str, str] | None = None
-        if arguments:
-            serialized_arguments = {}
-            for key, value in arguments.items():
-                if isinstance(value, str):
-                    serialized_arguments[key] = value
-                else:
-                    # Use pydantic_core.to_json for consistent serialization
-                    serialized_arguments[key] = pydantic_core.to_json(value).decode(
-                        "utf-8"
-                    )
-
-        # If meta provided, use send_request for SEP-1686 task support
-        if meta:
-            task_dict = meta.get("modelcontextprotocol.io/task")
-            request = mcp.types.GetPromptRequest(
-                params=mcp.types.GetPromptRequestParams(
-                    name=name,
-                    arguments=serialized_arguments,
-                    task=mcp.types.TaskMetadata(**task_dict)
-                    if task_dict
-                    else None,  # SEP-1686: task as direct param (spec-compliant)
-                )
-            )
-            result = await self.session.send_request(
-                request=request,  # type: ignore[arg-type]
-                result_type=mcp.types.GetPromptResult,
-            )
-        else:
-            result = await self.session.get_prompt(
-                name=name, arguments=serialized_arguments
-            )
-        return result
-
-    @overload
-    async def get_prompt(
-        self,
-        name: str,
-        arguments: dict[str, Any] | None = None,
-        *,
-        task: Literal[False] = False,
-    ) -> mcp.types.GetPromptResult: ...
-
-    @overload
-    async def get_prompt(
-        self,
-        name: str,
-        arguments: dict[str, Any] | None = None,
-        *,
-        task: Literal[True],
-        task_id: str | None = None,
-        ttl: int = 60000,
-    ) -> PromptTask: ...
-
-    async def get_prompt(
-        self,
-        name: str,
-        arguments: dict[str, Any] | None = None,
-        *,
-        task: bool = False,
-        task_id: str | None = None,
-        ttl: int = 60000,
-    ) -> mcp.types.GetPromptResult | PromptTask:
-        """Retrieve a rendered prompt message list from the server.
-
-        Args:
-            name (str): The name of the prompt to retrieve.
-            arguments (dict[str, Any] | None, optional): Arguments to pass to the prompt. Defaults to None.
-            task (bool): If True, execute as background task (SEP-1686). Defaults to False.
-            task_id (str | None): Optional client-provided task ID (auto-generated if not provided).
-            ttl (int): Time to keep results available in milliseconds (default 60s).
-
-        Returns:
-            mcp.types.GetPromptResult | PromptTask: The complete response object if task=False,
-                or a PromptTask object if task=True.
-
-        Raises:
-            RuntimeError: If called while the client is not connected.
-        """
-        if task:
-            return await self._get_prompt_as_task(name, arguments, task_id, ttl)
-
-        result = await self.get_prompt_mcp(name=name, arguments=arguments)
-        return result
-
-    async def _get_prompt_as_task(
-        self,
-        name: str,
-        arguments: dict[str, Any] | None = None,
-        task_id: str | None = None,
-        ttl: int = 60000,
-    ) -> PromptTask:
-        """Get a prompt for background execution (SEP-1686).
-
-        Returns a PromptTask object that handles both background and immediate execution.
-
-        Args:
-            name: Prompt name to get
-            arguments: Prompt arguments
-            task_id: Optional client-provided task ID (ignored, for backward compatibility)
-            ttl: Time to keep results available in milliseconds (default 60s)
-
-        Returns:
-            PromptTask: Future-like object for accessing task status and results
-        """
-        # Per SEP-1686 final spec: client sends only ttl, server generates taskId
-        # Call prompt with task metadata (no taskId sent)
-        result = await self.get_prompt_mcp(
-            name=name,
-            arguments=arguments or {},
-            meta={
-                "modelcontextprotocol.io/task": {
-                    "ttl": ttl,
-                }
-            },
-        )
-
-        # Check if server accepted background execution
-        # If response includes task metadata with taskId, server accepted background mode
-        # If response includes returned_immediately=True, server declined and executed sync
-        task_meta = (result.meta or {}).get("modelcontextprotocol.io/task", {})
-        if task_meta.get("taskId"):
-            # Background execution accepted - extract server-generated taskId
-            server_task_id = task_meta["taskId"]
-            # Track this task ID for list_tasks()
-            self._submitted_task_ids.add(server_task_id)
-
-            # Create task object
-            task_obj = PromptTask(
-                self, server_task_id, prompt_name=name, immediate_result=None
-            )
-
-            # Register for notification routing
-            self._task_registry[server_task_id] = weakref.ref(task_obj)  # type: ignore[assignment]
-
-            return task_obj
-        else:
-            # Server declined background execution (graceful degradation)
-            # Use a synthetic task ID for the immediate result
-            synthetic_task_id = task_id or str(uuid.uuid4())
-            return PromptTask(
-                self, synthetic_task_id, prompt_name=name, immediate_result=result
-            )
-
     # --- Completion ---
 
     async def complete_mcp(
@@ -1169,11 +802,14 @@ class Client(Generic[ClientTransportT]):
 
         Raises:
             RuntimeError: If called while the client is not connected.
+            McpError: If the request results in a TimeoutError | JSONRPCError
         """
         logger.debug(f"[{self.name}] called complete: {ref}")
 
-        result = await self.session.complete(
-            ref=ref, argument=argument, context_arguments=context_arguments
+        result = await self._await_with_session_monitoring(
+            self.session.complete(
+                ref=ref, argument=argument, context_arguments=context_arguments
+            )
         )
         return result
 
@@ -1196,419 +832,13 @@ class Client(Generic[ClientTransportT]):
 
         Raises:
             RuntimeError: If called while the client is not connected.
+            McpError: If the request results in a TimeoutError | JSONRPCError
         """
         result = await self.complete_mcp(
             ref=ref, argument=argument, context_arguments=context_arguments
         )
         return result.completion
 
-    # --- Tools ---
-
-    async def list_tools_mcp(self) -> mcp.types.ListToolsResult:
-        """Send a tools/list request and return the complete MCP protocol result.
-
-        Returns:
-            mcp.types.ListToolsResult: The complete response object from the protocol,
-                containing the list of tools and any additional metadata.
-
-        Raises:
-            RuntimeError: If called while the client is not connected.
-        """
-        logger.debug(f"[{self.name}] called list_tools")
-
-        result = await self.session.list_tools()
-        return result
-
-    async def list_tools(self) -> list[mcp.types.Tool]:
-        """Retrieve a list of tools available on the server.
-
-        Returns:
-            list[mcp.types.Tool]: A list of Tool objects.
-
-        Raises:
-            RuntimeError: If called while the client is not connected.
-        """
-        result = await self.list_tools_mcp()
-        return result.tools
-
-    # --- Call Tool ---
-
-    async def call_tool_mcp(
-        self,
-        name: str,
-        arguments: dict[str, Any],
-        progress_handler: ProgressHandler | None = None,
-        timeout: datetime.timedelta | float | int | None = None,
-        meta: dict[str, Any] | None = None,
-    ) -> mcp.types.CallToolResult:
-        """Send a tools/call request and return the complete MCP protocol result.
-
-        This method returns the raw CallToolResult object, which includes an isError flag
-        and other metadata. It does not raise an exception if the tool call results in an error.
-
-        Args:
-            name (str): The name of the tool to call.
-            arguments (dict[str, Any]): Arguments to pass to the tool.
-            timeout (datetime.timedelta | float | int | None, optional): The timeout for the tool call. Defaults to None.
-            progress_handler (ProgressHandler | None, optional): The progress handler to use for the tool call. Defaults to None.
-            meta (dict[str, Any] | None, optional): Additional metadata to include with the request.
-                This is useful for passing contextual information (like user IDs, trace IDs, or preferences)
-                that shouldn't be tool arguments but may influence server-side processing. The server
-                can access this via `context.request_context.meta`. Defaults to None.
-
-        Returns:
-            mcp.types.CallToolResult: The complete response object from the protocol,
-                containing the tool result and any additional metadata.
-
-        Raises:
-            RuntimeError: If called while the client is not connected.
-        """
-        logger.debug(f"[{self.name}] called call_tool: {name}")
-
-        # Convert timeout to timedelta if needed
-        if isinstance(timeout, int | float):
-            timeout = datetime.timedelta(seconds=float(timeout))
-
-        # For task submissions, use send_request to bypass SDK validation
-        # Task acknowledgments don't have structured content, which would fail validation
-        if meta and "modelcontextprotocol.io/task" in meta:
-            task_dict = meta.get("modelcontextprotocol.io/task")
-            request = mcp.types.CallToolRequest(
-                params=mcp.types.CallToolRequestParams(
-                    name=name,
-                    arguments=arguments,
-                    task=mcp.types.TaskMetadata(**task_dict)
-                    if task_dict
-                    else None,  # SEP-1686: task as direct param (spec-compliant)
-                )
-            )
-            result = await self.session.send_request(
-                request=request,  # type: ignore[arg-type]
-                result_type=mcp.types.CallToolResult,
-                request_read_timeout_seconds=timeout,  # type: ignore[arg-type]
-                progress_callback=progress_handler or self._progress_handler,
-            )
-        else:
-            result = await self.session.call_tool(
-                name=name,
-                arguments=arguments,
-                read_timeout_seconds=timeout,  # ty: ignore[invalid-argument-type]
-                progress_callback=progress_handler or self._progress_handler,
-                meta=meta,
-            )
-        return result
-
-    async def _parse_call_tool_result(
-        self, name: str, result: mcp.types.CallToolResult, raise_on_error: bool = False
-    ) -> CallToolResult:
-        """Parse an mcp.types.CallToolResult into our CallToolResult dataclass.
-
-        Args:
-            name: Tool name (for schema lookup)
-            result: Raw MCP protocol result
-            raise_on_error: Whether to raise ToolError on errors
-
-        Returns:
-            CallToolResult: Parsed result with structured data
-        """
-        data = None
-        if result.isError and raise_on_error:
-            msg = cast(mcp.types.TextContent, result.content[0]).text
-            raise ToolError(msg)
-        elif result.structuredContent:
-            try:
-                if name not in self.session._tool_output_schemas:
-                    await self.session.list_tools()
-                if name in self.session._tool_output_schemas:
-                    output_schema = self.session._tool_output_schemas.get(name)
-                    if output_schema:
-                        if output_schema.get("x-fastmcp-wrap-result"):
-                            output_schema = output_schema.get("properties", {}).get(
-                                "result"
-                            )
-                            structured_content = result.structuredContent.get("result")
-                        else:
-                            structured_content = result.structuredContent
-                        output_type = json_schema_to_type(output_schema)
-                        type_adapter = get_cached_typeadapter(output_type)
-                        data = type_adapter.validate_python(structured_content)
-                    else:
-                        data = result.structuredContent
-            except Exception as e:
-                logger.error(f"[{self.name}] Error parsing structured content: {e}")
-
-        return CallToolResult(
-            content=result.content,
-            structured_content=result.structuredContent,
-            meta=result.meta,
-            data=data,
-            is_error=result.isError,
-        )
-
-    @overload
-    async def call_tool(
-        self,
-        name: str,
-        arguments: dict[str, Any] | None = None,
-        *,
-        timeout: datetime.timedelta | float | int | None = None,
-        progress_handler: ProgressHandler | None = None,
-        raise_on_error: bool = True,
-        meta: dict[str, Any] | None = None,
-        task: Literal[False] = False,
-    ) -> CallToolResult: ...
-
-    @overload
-    async def call_tool(
-        self,
-        name: str,
-        arguments: dict[str, Any] | None = None,
-        *,
-        timeout: datetime.timedelta | float | int | None = None,
-        progress_handler: ProgressHandler | None = None,
-        raise_on_error: bool = True,
-        meta: dict[str, Any] | None = None,
-        task: Literal[True],
-        task_id: str | None = None,
-        ttl: int = 60000,
-    ) -> ToolTask: ...
-
-    async def call_tool(
-        self,
-        name: str,
-        arguments: dict[str, Any] | None = None,
-        *,
-        timeout: datetime.timedelta | float | int | None = None,
-        progress_handler: ProgressHandler | None = None,
-        raise_on_error: bool = True,
-        meta: dict[str, Any] | None = None,
-        task: bool = False,
-        task_id: str | None = None,
-        ttl: int = 60000,
-    ) -> CallToolResult | ToolTask:
-        """Call a tool on the server.
-
-        Unlike call_tool_mcp, this method raises a ToolError if the tool call results in an error.
-
-        Args:
-            name (str): The name of the tool to call.
-            arguments (dict[str, Any] | None, optional): Arguments to pass to the tool. Defaults to None.
-            timeout (datetime.timedelta | float | int | None, optional): The timeout for the tool call. Defaults to None.
-            progress_handler (ProgressHandler | None, optional): The progress handler to use for the tool call. Defaults to None.
-            raise_on_error (bool, optional): Whether to raise an exception if the tool call results in an error. Defaults to True.
-            meta (dict[str, Any] | None, optional): Additional metadata to include with the request.
-                This is useful for passing contextual information (like user IDs, trace IDs, or preferences)
-                that shouldn't be tool arguments but may influence server-side processing. The server
-                can access this via `context.request_context.meta`. Defaults to None.
-            task (bool): If True, execute as background task (SEP-1686). Defaults to False.
-            task_id (str | None): Optional client-provided task ID (auto-generated if not provided).
-            ttl (int): Time to keep results available in milliseconds (default 60s).
-
-        Returns:
-            CallToolResult | ToolTask: The content returned by the tool if task=False,
-                or a ToolTask object if task=True. If the tool returns structured
-                outputs, they are returned as a dataclass (if an output schema
-                is available) or a dictionary; otherwise, a list of content
-                blocks is returned. Note: to receive both structured and
-                unstructured outputs, use call_tool_mcp instead and access the
-                raw result object.
-
-        Raises:
-            ToolError: If the tool call results in an error.
-            RuntimeError: If called while the client is not connected.
-        """
-        if task:
-            return await self._call_tool_as_task(name, arguments, task_id, ttl)
-
-        result = await self.call_tool_mcp(
-            name=name,
-            arguments=arguments or {},
-            timeout=timeout,
-            progress_handler=progress_handler,
-            meta=meta,
-        )
-        return await self._parse_call_tool_result(
-            name, result, raise_on_error=raise_on_error
-        )
-
-    async def _call_tool_as_task(
-        self,
-        name: str,
-        arguments: dict[str, Any] | None = None,
-        task_id: str | None = None,
-        ttl: int = 60000,
-    ) -> ToolTask:
-        """Call a tool for background execution (SEP-1686).
-
-        Returns a ToolTask object that handles both background and immediate execution.
-        If the server accepts background execution, ToolTask will poll for results.
-        If the server declines (graceful degradation), ToolTask wraps the immediate result.
-
-        Args:
-            name: Tool name to call
-            arguments: Tool arguments
-            task_id: Optional client-provided task ID (ignored, for backward compatibility)
-            ttl: Time to keep results available in milliseconds (default 60s)
-
-        Returns:
-            ToolTask: Future-like object for accessing task status and results
-        """
-        # Per SEP-1686 final spec: client sends only ttl, server generates taskId
-        # Call tool with task metadata (no taskId sent)
-        result = await self.call_tool_mcp(
-            name=name,
-            arguments=arguments or {},
-            meta={
-                "modelcontextprotocol.io/task": {
-                    "ttl": ttl,
-                }
-            },
-        )
-
-        # Check if server accepted background execution
-        # If response includes task metadata with taskId, server accepted background mode
-        # If response includes returned_immediately=True, server declined and executed sync
-        task_meta = (result.meta or {}).get("modelcontextprotocol.io/task", {})
-        if task_meta.get("taskId"):
-            # Background execution accepted - extract server-generated taskId
-            server_task_id = task_meta["taskId"]
-            # Track this task ID for list_tasks()
-            self._submitted_task_ids.add(server_task_id)
-
-            # Create task object
-            task_obj = ToolTask(
-                self, server_task_id, tool_name=name, immediate_result=None
-            )
-
-            # Register for notification routing
-            self._task_registry[server_task_id] = weakref.ref(task_obj)  # type: ignore[assignment]
-
-            return task_obj
-        else:
-            # Server declined background execution (graceful degradation)
-            # or returned_immediately=True - executed synchronously
-            # Wrap the immediate result
-            parsed_result = await self._parse_call_tool_result(name, result)
-            # Use a synthetic task ID for the immediate result
-            synthetic_task_id = task_id or str(uuid.uuid4())
-            return ToolTask(
-                self, synthetic_task_id, tool_name=name, immediate_result=parsed_result
-            )
-
-    async def get_task_status(self, task_id: str) -> GetTaskResult:
-        """Query the status of a background task.
-
-        Sends a 'tasks/get' MCP protocol request over the existing transport.
-
-        Args:
-            task_id: The task ID returned from call_tool_as_task
-
-        Returns:
-            GetTaskResult: Status information including taskId, status, pollInterval, etc.
-
-        Raises:
-            RuntimeError: If client not connected
-        """
-        request = GetTaskRequest(params=GetTaskRequestParams(taskId=task_id))
-        return await self.session.send_request(
-            request=request,  # type: ignore[arg-type]
-            result_type=GetTaskResult,  # type: ignore[arg-type]
-        )
-
-    async def get_task_result(self, task_id: str) -> Any:
-        """Retrieve the raw result of a completed background task.
-
-        Sends a 'tasks/result' MCP protocol request over the existing transport.
-        Returns the raw result - callers should parse it appropriately.
-
-        Args:
-            task_id: The task ID returned from call_tool_as_task
-
-        Returns:
-            Any: The raw result (could be tool, prompt, or resource result)
-
-        Raises:
-            RuntimeError: If client not connected, task not found, or task failed
-        """
-        request = GetTaskPayloadRequest(
-            params=GetTaskPayloadRequestParams(taskId=task_id)
-        )
-        # Return raw result - Task classes handle type-specific parsing
-        result = await self.session.send_request(
-            request=request,  # type: ignore[arg-type]
-            result_type=GetTaskPayloadResult,  # type: ignore[arg-type]
-        )
-        # Return as dict for compatibility with Task class parsing
-        return result.model_dump(exclude_none=True, by_alias=True)
-
-    async def list_tasks(
-        self,
-        cursor: str | None = None,
-        limit: int = 50,
-    ) -> dict[str, Any]:
-        """List background tasks.
-
-        Sends a 'tasks/list' MCP protocol request to the server. If the server
-        returns an empty list (indicating client-side tracking), falls back to
-        querying status for locally tracked task IDs.
-
-        Args:
-            cursor: Optional pagination cursor
-            limit: Maximum number of tasks to return (default 50)
-
-        Returns:
-            dict: Response with structure:
-                - tasks: List of task status dicts with taskId, status, etc.
-                - nextCursor: Optional cursor for next page
-
-        Raises:
-            RuntimeError: If client not connected
-        """
-        # Send protocol request
-        params = PaginatedRequestParams(cursor=cursor, limit=limit)
-        request = ListTasksRequest(params=params)
-        server_response = await self.session.send_request(
-            request=request,  # type: ignore[invalid-argument-type]
-            result_type=mcp.types.ListTasksResult,
-        )
-
-        # If server returned tasks, use those
-        if server_response.tasks:
-            return server_response.model_dump(by_alias=True)
-
-        # Server returned empty - fall back to client-side tracking
-        tasks = []
-        for task_id in list(self._submitted_task_ids)[:limit]:
-            try:
-                status = await self.get_task_status(task_id)
-                tasks.append(status.model_dump(by_alias=True))
-            except Exception:
-                # Task may have expired or been deleted, skip it
-                continue
-
-        return {"tasks": tasks, "nextCursor": None}
-
-    async def cancel_task(self, task_id: str) -> mcp.types.CancelTaskResult:
-        """Cancel a task, transitioning it to cancelled state.
-
-        Sends a 'tasks/cancel' MCP protocol request. Task will halt execution
-        and transition to cancelled state.
-
-        Args:
-            task_id: The task ID to cancel
-
-        Returns:
-            CancelTaskResult: The task status showing cancelled state
-
-        Raises:
-            RuntimeError: If task doesn't exist
-        """
-        request = CancelTaskRequest(params=CancelTaskRequestParams(taskId=task_id))
-        return await self.session.send_request(
-            request=request,  # type: ignore[invalid-argument-type]
-            result_type=mcp.types.CancelTaskResult,
-        )
-
     @classmethod
     def generate_name(cls, name: str | None = None) -> str:
         class_name = cls.__name__