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

fastmcp/client/mixins/task_management.py

@@ -0,0 +1,157 @@
+"""Task management methods for FastMCP Client."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+import mcp.types
+from mcp import McpError
+
+if TYPE_CHECKING:
+    from fastmcp.client.client import Client
+from mcp.types import (
+    CancelTaskRequest,
+    CancelTaskRequestParams,
+    GetTaskPayloadRequest,
+    GetTaskPayloadRequestParams,
+    GetTaskPayloadResult,
+    GetTaskRequest,
+    GetTaskRequestParams,
+    GetTaskResult,
+    ListTasksRequest,
+    PaginatedRequestParams,
+)
+
+from fastmcp.utilities.logging import get_logger
+
+logger = get_logger(__name__)
+
+
+class ClientTaskManagementMixin:
+    """Mixin providing task management methods for Client."""
+
+    async def get_task_status(self: Client, 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
+            McpError: If the request results in a TimeoutError | JSONRPCError
+        """
+        request = GetTaskRequest(params=GetTaskRequestParams(taskId=task_id))
+        return await self._await_with_session_monitoring(
+            self.session.send_request(
+                request=request,  # type: ignore[arg-type]
+                result_type=GetTaskResult,
+            )
+        )
+
+    async def get_task_result(self: Client, 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
+            McpError: If the request results in a TimeoutError | JSONRPCError
+        """
+        request = GetTaskPayloadRequest(
+            params=GetTaskPayloadRequestParams(taskId=task_id)
+        )
+        # Return raw result - Task classes handle type-specific parsing
+        result = await self._await_with_session_monitoring(
+            self.session.send_request(
+                request=request,  # type: ignore[arg-type]
+                result_type=GetTaskPayloadResult,
+            )
+        )
+        # Return as dict for compatibility with Task class parsing
+        return result.model_dump(exclude_none=True, by_alias=True)
+
+    async def list_tasks(
+        self: Client,
+        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
+            McpError: If the request results in a TimeoutError | JSONRPCError
+        """
+        # Send protocol request
+        params = PaginatedRequestParams(cursor=cursor, limit=limit)  # type: ignore[call-arg]  # Optional field in MCP SDK
+        request = ListTasksRequest(params=params)
+        server_response = await self._await_with_session_monitoring(
+            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 McpError:
+                # Task may have expired or been deleted, skip it
+                continue
+
+        return {"tasks": tasks, "nextCursor": None}
+
+    async def cancel_task(self: Client, 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
+            McpError: If the request results in a TimeoutError | JSONRPCError
+        """
+        request = CancelTaskRequest(params=CancelTaskRequestParams(taskId=task_id))
+        return await self._await_with_session_monitoring(
+            self.session.send_request(
+                request=request,  # type: ignore[invalid-argument-type]
+                result_type=mcp.types.CancelTaskResult,
+            )
+        )

fastmcp/client/mixins/tools.py

@@ -0,0 +1,397 @@
+"""Tool-related methods for FastMCP Client."""
+
+from __future__ import annotations
+
+import uuid
+import weakref
+from typing import TYPE_CHECKING, Any, Literal, overload
+
+import mcp.types
+from pydantic import RootModel
+
+if TYPE_CHECKING:
+    import datetime
+
+    from fastmcp.client.client import CallToolResult, Client
+from fastmcp.client.progress import ProgressHandler
+from fastmcp.client.tasks import ToolTask
+from fastmcp.client.telemetry import client_span
+from fastmcp.exceptions import ToolError
+from fastmcp.telemetry import inject_trace_context
+from fastmcp.utilities.json_schema_type import json_schema_to_type
+from fastmcp.utilities.logging import get_logger
+from fastmcp.utilities.timeout import normalize_timeout_to_timedelta
+from fastmcp.utilities.types import get_cached_typeadapter
+
+logger = get_logger(__name__)
+
+# Type alias for task response union (SEP-1686 graceful degradation)
+ToolTaskResponseUnion = RootModel[mcp.types.CreateTaskResult | mcp.types.CallToolResult]
+
+
+class ClientToolsMixin:
+    """Mixin providing tool-related methods for Client."""
+
+    # --- Tools ---
+
+    async def list_tools_mcp(
+        self: Client, *, cursor: str | None = None
+    ) -> mcp.types.ListToolsResult:
+        """Send a tools/list request and return the complete MCP protocol result.
+
+        Args:
+            cursor: Optional pagination cursor from a previous request's nextCursor.
+
+        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.
+            McpError: If the request results in a TimeoutError | JSONRPCError
+        """
+        logger.debug(f"[{self.name}] called list_tools")
+
+        result = await self._await_with_session_monitoring(
+            self.session.list_tools(cursor=cursor)
+        )
+        return result
+
+    async def list_tools(self: Client) -> list[mcp.types.Tool]:
+        """Retrieve all tools available on the server.
+
+        This method automatically fetches all pages if the server paginates results,
+        returning the complete list. For manual pagination control (e.g., to handle
+        large result sets incrementally), use list_tools_mcp() with the cursor parameter.
+
+        Returns:
+            list[mcp.types.Tool]: A list of all Tool objects.
+
+        Raises:
+            RuntimeError: If called while the client is not connected.
+            McpError: If the request results in a TimeoutError | JSONRPCError
+        """
+        all_tools: list[mcp.types.Tool] = []
+        cursor: str | None = None
+
+        while True:
+            result = await self.list_tools_mcp(cursor=cursor)
+            all_tools.extend(result.tools)
+            if result.nextCursor is None:
+                break
+            cursor = result.nextCursor
+
+        return all_tools
+
+    # --- Call Tool ---
+
+    async def call_tool_mcp(
+        self: Client,
+        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.
+            McpError: If the tool call requests results in a TimeoutError | JSONRPCError
+        """
+        with client_span(
+            f"tools/call {name}",
+            "tools/call",
+            name,
+            session_id=self.transport.get_session_id(),
+        ):
+            logger.debug(f"[{self.name}] called call_tool: {name}")
+
+            # Inject trace context into meta for propagation to server
+            propagated_meta = inject_trace_context(meta)
+
+            result = await self._await_with_session_monitoring(
+                self.session.call_tool(
+                    name=name,
+                    arguments=arguments,
+                    read_timeout_seconds=normalize_timeout_to_timedelta(timeout),
+                    progress_callback=progress_handler or self._progress_handler,
+                    meta=propagated_meta if propagated_meta else None,
+                )
+            )
+            return result
+
+    async def _parse_call_tool_result(
+        self: Client,
+        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
+        """
+
+        return await _parse_call_tool_result(
+            name=name,
+            result=result,
+            tool_output_schemas=self.session._tool_output_schemas,
+            list_tools_fn=self.session.list_tools,
+            client_name=self.name,
+            raise_on_error=raise_on_error,
+        )
+
+    @overload
+    async def call_tool(
+        self: Client,
+        name: str,
+        arguments: dict[str, Any] | None = None,
+        *,
+        version: str | 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: Client,
+        name: str,
+        arguments: dict[str, Any] | None = None,
+        *,
+        version: str | 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: Client,
+        name: str,
+        arguments: dict[str, Any] | None = None,
+        *,
+        version: str | 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.
+            version (str | None, optional): Specific tool version to call. If None, calls highest version.
+            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.
+            McpError: If the tool call request results in a TimeoutError | JSONRPCError
+            RuntimeError: If called while the client is not connected.
+        """
+        # Merge version into request-level meta (not arguments)
+        request_meta = dict(meta) if meta else {}
+        if version is not None:
+            request_meta["fastmcp"] = {
+                **request_meta.get("fastmcp", {}),
+                "version": version,
+            }
+
+        if task:
+            return await self._call_tool_as_task(
+                name, arguments, task_id, ttl, meta=request_meta or None
+            )
+
+        result = await self.call_tool_mcp(
+            name=name,
+            arguments=arguments or {},
+            timeout=timeout,
+            progress_handler=progress_handler,
+            meta=request_meta or None,
+        )
+        return await self._parse_call_tool_result(
+            name, result, raise_on_error=raise_on_error
+        )
+
+    async def _call_tool_as_task(
+        self: Client,
+        name: str,
+        arguments: dict[str, Any] | None = None,
+        task_id: str | None = None,
+        ttl: int = 60000,
+        meta: dict[str, Any] | None = None,
+    ) -> 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)
+            meta: Optional request metadata (e.g., version info)
+
+        Returns:
+            ToolTask: Future-like object for accessing task status and results
+        """
+        # Per SEP-1686 final spec: client sends only ttl, server generates taskId
+        # Inject trace context into meta for propagation to server
+        propagated_meta = inject_trace_context(meta)
+
+        # Build request with task metadata
+        request = mcp.types.CallToolRequest(
+            params=mcp.types.CallToolRequestParams(
+                name=name,
+                arguments=arguments or {},
+                task=mcp.types.TaskMetadata(ttl=ttl),
+                _meta=propagated_meta,  # type: ignore[unknown-argument]  # pydantic alias
+            )
+        )
+
+        # Server returns CreateTaskResult (task accepted) or CallToolResult (graceful degradation)
+        # Use RootModel with Union to handle both response types (SDK calls model_validate)
+        wrapped_result = await self._await_with_session_monitoring(
+            self.session.send_request(
+                request=request,  # type: ignore[arg-type]
+                result_type=ToolTaskResponseUnion,
+            )
+        )
+        raw_result = wrapped_result.root
+
+        if isinstance(raw_result, mcp.types.CreateTaskResult):
+            # Task was accepted - extract task info from CreateTaskResult
+            server_task_id = raw_result.task.taskId
+            self._submitted_task_ids.add(server_task_id)
+
+            task_obj = ToolTask(
+                self, server_task_id, tool_name=name, immediate_result=None
+            )
+            self._task_registry[server_task_id] = weakref.ref(task_obj)
+            return task_obj
+        else:
+            # Graceful degradation - server returned CallToolResult
+            parsed_result = await self._parse_call_tool_result(name, raw_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 _parse_call_tool_result(
+    name: str,
+    result: mcp.types.CallToolResult,
+    tool_output_schemas: dict[str, dict[str, Any] | None],
+    list_tools_fn: Any,  # Callable[[], Awaitable[None]]
+    client_name: str | None = None,
+    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
+        tool_output_schemas: Dictionary mapping tool names to their output schemas
+        list_tools_fn: Async function to refresh tool schemas if needed
+        client_name: Optional client name for logging
+        raise_on_error: Whether to raise ToolError on errors
+
+    Returns:
+        CallToolResult: Parsed result with structured data
+    """
+    from typing import cast
+
+    from fastmcp.client.client import CallToolResult
+
+    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 tool_output_schemas:
+                await list_tools_fn()
+            if name in tool_output_schemas:
+                output_schema = 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"[{client_name or 'client'}] Error parsing structured content: {e}"
+            )
+
+    return CallToolResult(
+        content=result.content,
+        structured_content=result.structuredContent,
+        meta=result.meta,
+        data=data,
+        is_error=result.isError,
+    )

fastmcp/client/sampling/handlers/anthropic.py

@@ -198,7 +198,7 @@ class AnthropicSamplingHandler:
                     anthropic_messages.append(
                         MessageParam(
                             role=message.role,
-                            content=content_blocks,  # type: ignore[arg-type]
+                            content=content_blocks,
                         )
                     )
                 continue
@@ -310,7 +310,7 @@ class AnthropicSamplingHandler:
                 ToolParam(
                     name=tool.name,
                     description=tool.description or "",
-                    input_schema=input_schema,  # type: ignore[arg-type]
+                    input_schema=input_schema,
                 )
             )
         return anthropic_tools

fastmcp/client/sampling/handlers/openai.py

@@ -368,7 +368,7 @@ class OpenAISamplingHandler:
                 # Skip non-function tool calls
                 if not hasattr(tool_call, "function"):
                     continue
-                func = tool_call.function  # type: ignore[union-attr]
+                func = tool_call.function
                 # Parse the arguments JSON string
                 try:
                     arguments = json.loads(func.arguments)  # type: ignore[union-attr]

fastmcp/client/tasks.py

@@ -378,15 +378,15 @@ class ToolTask(Task["CallToolResult"]):
                 ):
                     mcp_result = mcp.types.CallToolResult(
                         content=raw_result.content,
-                        structuredContent=raw_result.structured_content,  # type: ignore[arg-type]
-                        _meta=raw_result.meta,
+                        structuredContent=raw_result.structured_content,
+                        _meta=raw_result.meta,  # type: ignore[call-arg]  # _meta is Pydantic alias for meta field
                     )
                     result = await self._client._parse_call_tool_result(
                         self._tool_name, mcp_result, raise_on_error=True
                     )
                 else:
                     # Unknown type - just return it
-                    result = raw_result  # type: ignore[assignment]
+                    result = raw_result
 
         # Cache before returning
         self._cached_result = result

fastmcp/client/telemetry.py

@@ -0,0 +1,47 @@
+"""Client-side telemetry helpers."""
+
+from collections.abc import Generator
+from contextlib import contextmanager
+
+from opentelemetry.trace import Span, SpanKind, Status, StatusCode
+
+from fastmcp.telemetry import get_tracer
+
+
+@contextmanager
+def client_span(
+    name: str,
+    method: str,
+    component_key: str,
+    session_id: str | None = None,
+    resource_uri: str | None = None,
+) -> Generator[Span, None, None]:
+    """Create a CLIENT span with standard MCP attributes.
+
+    Automatically records any exception on the span and sets error status.
+    """
+    tracer = get_tracer()
+    with tracer.start_as_current_span(name, kind=SpanKind.CLIENT) as span:
+        attrs: dict[str, str] = {
+            # RPC semantic conventions
+            "rpc.system": "mcp",
+            "rpc.method": method,
+            # MCP semantic conventions
+            "mcp.method.name": method,
+            # FastMCP-specific attributes
+            "fastmcp.component.key": component_key,
+        }
+        if session_id:
+            attrs["mcp.session.id"] = session_id
+        if resource_uri:
+            attrs["mcp.resource.uri"] = resource_uri
+        span.set_attributes(attrs)
+        try:
+            yield span
+        except Exception as e:
+            span.record_exception(e)
+            span.set_status(Status(StatusCode.ERROR))
+            raise
+
+
+__all__ = ["client_span"]

fastmcp/client/transports/__init__.py

@@ -0,0 +1,38 @@
+# Re-export all public APIs for backward compatibility
+from mcp.server.fastmcp import FastMCP as FastMCP1Server
+
+from fastmcp.client.transports.base import (
+    ClientTransport,
+    ClientTransportT,
+    SessionKwargs,
+)
+from fastmcp.client.transports.config import MCPConfigTransport
+from fastmcp.client.transports.http import StreamableHttpTransport
+from fastmcp.client.transports.inference import infer_transport
+from fastmcp.client.transports.sse import SSETransport
+from fastmcp.client.transports.memory import FastMCPTransport
+from fastmcp.client.transports.stdio import (
+    FastMCPStdioTransport,
+    NodeStdioTransport,
+    NpxStdioTransport,
+    PythonStdioTransport,
+    StdioTransport,
+    UvStdioTransport,
+    UvxStdioTransport,
+)
+from fastmcp.server.server import FastMCP
+
+__all__ = [
+    "ClientTransport",
+    "FastMCPStdioTransport",
+    "FastMCPTransport",
+    "NodeStdioTransport",
+    "NpxStdioTransport",
+    "PythonStdioTransport",
+    "SSETransport",
+    "StdioTransport",
+    "StreamableHttpTransport",
+    "UvStdioTransport",
+    "UvxStdioTransport",
+    "infer_transport",
+]