fastmcp 2.9.2__py3-none-any.whl → 2.10.1__py3-none-any.whl

fastmcp/client/auth/oauth.py

@@ -9,14 +9,11 @@ from urllib.parse import urljoin, urlparse
 
 import anyio
 import httpx
-from mcp.client.auth import OAuthClientProvider as _MCPOAuthClientProvider
-from mcp.client.auth import TokenStorage
+from mcp.client.auth import OAuthClientProvider, TokenStorage
 from mcp.shared.auth import (
     OAuthClientInformationFull,
     OAuthClientMetadata,
-)
-from mcp.shared.auth import (
-    OAuthMetadata as _MCPServerOAuthMetadata,
+    OAuthMetadata,
 )
 from mcp.shared.auth import (
     OAuthToken as OAuthToken,
@@ -39,80 +36,6 @@ def default_cache_dir() -> Path:
     return fastmcp_global_settings.home / "oauth-mcp-client-cache"
 
 
-# Flexible OAuth models for real-world compatibility
-class ServerOAuthMetadata(_MCPServerOAuthMetadata):
-    """
-    More flexible OAuth metadata model that accepts broader ranges of values
-    than the restrictive MCP standard model.
-
-    This handles real-world OAuth servers like PayPal that may support
-    additional methods not in the MCP specification.
-    """
-
-    # Allow any code challenge methods, not just S256
-    code_challenge_methods_supported: list[str] | None = None
-
-    # Allow any token endpoint auth methods
-    token_endpoint_auth_methods_supported: list[str] | None = None
-
-    # Allow any grant types
-    grant_types_supported: list[str] | None = None
-
-    # Allow any response types
-    response_types_supported: list[str] = ["code"]
-
-    # Allow any response modes
-    response_modes_supported: list[str] | None = None
-
-
-class OAuthClientProvider(_MCPOAuthClientProvider):
-    """
-    OAuth client provider with more flexible OAuth metadata discovery.
-    """
-
-    async def _discover_oauth_metadata(
-        self, server_url: str
-    ) -> ServerOAuthMetadata | None:
-        """
-        Discover OAuth metadata with flexible validation.
-
-        This is nearly identical to the parent implementation but uses
-        ServerOAuthMetadata instead of the restrictive MCP OAuthMetadata.
-        """
-        # Extract base URL per MCP spec
-        auth_base_url = self._get_authorization_base_url(server_url)
-        url = urljoin(auth_base_url, "/.well-known/oauth-authorization-server")
-
-        from mcp.types import LATEST_PROTOCOL_VERSION
-
-        headers = {"MCP-Protocol-Version": LATEST_PROTOCOL_VERSION}
-
-        async with httpx.AsyncClient() as client:
-            try:
-                response = await client.get(url, headers=headers)
-                if response.status_code == 404:
-                    return None
-                response.raise_for_status()
-                metadata_json = response.json()
-                logger.debug(f"OAuth metadata discovered: {metadata_json}")
-                return ServerOAuthMetadata.model_validate(metadata_json)
-            except Exception:
-                # Retry without MCP header for CORS compatibility
-                try:
-                    response = await client.get(url)
-                    if response.status_code == 404:
-                        return None
-                    response.raise_for_status()
-                    metadata_json = response.json()
-                    logger.debug(
-                        f"OAuth metadata discovered (no MCP header): {metadata_json}"
-                    )
-                    return ServerOAuthMetadata.model_validate(metadata_json)
-                except Exception:
-                    logger.exception("Failed to discover OAuth metadata")
-                    return None
-
-
 class FileTokenStorage(TokenStorage):
     """
     File-based token storage implementation for OAuth credentials and tokens.
@@ -229,7 +152,7 @@ class FileTokenStorage(TokenStorage):
 
 async def discover_oauth_metadata(
     server_base_url: str, httpx_kwargs: dict[str, Any] | None = None
-) -> _MCPServerOAuthMetadata | None:
+) -> OAuthMetadata | None:
     """
     Discover OAuth metadata from the server using RFC 8414 well-known endpoint.
 
@@ -248,7 +171,7 @@ async def discover_oauth_metadata(
             response = await client.get(well_known_url, timeout=10.0)
             if response.status_code == 200:
                 logger.debug("Successfully discovered OAuth metadata")
-                return _MCPServerOAuthMetadata.model_validate(response.json())
+                return OAuthMetadata.model_validate(response.json())
             elif response.status_code == 404:
                 logger.debug(
                     "OAuth metadata not found (404) - server may not require auth"
@@ -298,7 +221,7 @@ def OAuth(
     client_name: str = "FastMCP Client",
     token_storage_cache_dir: Path | None = None,
     additional_client_metadata: dict[str, Any] | None = None,
-) -> _MCPOAuthClientProvider:
+) -> OAuthClientProvider:
     """
     Create an OAuthClientProvider for an MCP server.
 

fastmcp/client/client.py

@@ -1,6 +1,9 @@
+from __future__ import annotations
+
 import asyncio
 import datetime
 from contextlib import AsyncExitStack, asynccontextmanager
+from dataclasses import dataclass
 from pathlib import Path
 from typing import Any, Generic, Literal, cast, overload
 
@@ -13,6 +16,7 @@ from mcp import ClientSession
 from pydantic import AnyUrl
 
 import fastmcp
+from fastmcp.client.elicitation import ElicitationHandler, create_elicitation_callback
 from fastmcp.client.logging import (
     LogHandler,
     create_log_callback,
@@ -29,8 +33,10 @@ from fastmcp.client.sampling import SamplingHandler, create_sampling_callback
 from fastmcp.exceptions import ToolError
 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.mcp_config import MCPConfig
-from fastmcp.utilities.types import MCPContent
+from fastmcp.utilities.types import get_cached_typeadapter
 
 from .transports import (
     ClientTransportT,
@@ -53,9 +59,12 @@ __all__ = [
     "LogHandler",
     "MessageHandler",
     "SamplingHandler",
+    "ElicitationHandler",
     "ProgressHandler",
 ]
 
+logger = get_logger(__name__)
+
 
 class Client(Generic[ClientTransportT]):
     """
@@ -99,34 +108,39 @@ class Client(Generic[ClientTransportT]):
         cls,
         transport: ClientTransportT,
         **kwargs: Any,
-    ) -> "Client[ClientTransportT]": ...
+    ) -> Client[ClientTransportT]: ...
 
     @overload
     def __new__(
         cls, transport: AnyUrl, **kwargs
-    ) -> "Client[SSETransport|StreamableHttpTransport]": ...
+    ) -> Client[SSETransport | StreamableHttpTransport]: ...
 
     @overload
     def __new__(
         cls, transport: FastMCP | FastMCP1Server, **kwargs
-    ) -> "Client[FastMCPTransport]": ...
+    ) -> Client[FastMCPTransport]: ...
 
     @overload
     def __new__(
         cls, transport: Path, **kwargs
-    ) -> "Client[PythonStdioTransport|NodeStdioTransport]": ...
+    ) -> Client[PythonStdioTransport | NodeStdioTransport]: ...
 
     @overload
     def __new__(
         cls, transport: MCPConfig | dict[str, Any], **kwargs
-    ) -> "Client[MCPConfigTransport]": ...
+    ) -> Client[MCPConfigTransport]: ...
 
     @overload
     def __new__(
         cls, transport: str, **kwargs
-    ) -> "Client[PythonStdioTransport|NodeStdioTransport|SSETransport|StreamableHttpTransport]": ...
-
-    def __new__(cls, transport, **kwargs) -> "Client":
+    ) -> Client[
+        PythonStdioTransport
+        | NodeStdioTransport
+        | SSETransport
+        | StreamableHttpTransport
+    ]: ...
+
+    def __new__(cls, transport, **kwargs) -> Client:
         instance = super().__new__(cls)
         return instance
 
@@ -142,6 +156,7 @@ class Client(Generic[ClientTransportT]):
         # Common args
         roots: RootsList | RootsHandler | None = None,
         sampling_handler: SamplingHandler | None = None,
+        elicitation_handler: ElicitationHandler | None = None,
         log_handler: LogHandler | None = None,
         message_handler: MessageHandlerT | MessageHandler | None = None,
         progress_handler: ProgressHandler | None = None,
@@ -194,6 +209,11 @@ class Client(Generic[ClientTransportT]):
                 sampling_handler
             )
 
+        if elicitation_handler is not None:
+            self._session_kwargs["elicitation_callback"] = create_elicitation_callback(
+                elicitation_handler
+            )
+
         # session context management
         self._session: ClientSession | None = None
         self._exit_stack: AsyncExitStack | None = None
@@ -232,6 +252,14 @@ class Client(Generic[ClientTransportT]):
             sampling_callback
         )
 
+    def set_elicitation_callback(
+        self, elicitation_callback: ElicitationHandler
+    ) -> None:
+        """Set the elicitation callback for the client."""
+        self._session_kwargs["elicitation_callback"] = create_elicitation_callback(
+            elicitation_callback
+        )
+
     def is_connected(self) -> bool:
         """Check if the client is currently connected."""
         return self._session is not None
@@ -258,6 +286,21 @@ class Client(Generic[ClientTransportT]):
 
     async def __aenter__(self):
         await self._connect()
+
+        # Check if session task failed and raise error immediately
+        if (
+            self._session_task is not None
+            and self._session_task.done()
+            and not self._session_task.cancelled()
+        ):
+            exception = self._session_task.exception()
+            if isinstance(exception, httpx.HTTPStatusError):
+                raise exception
+            elif exception is not None:
+                raise RuntimeError(
+                    f"Client failed to connect: {exception}"
+                ) from exception
+
         return self
 
     async def __aexit__(self, exc_type, exc_val, exc_tb):
@@ -308,16 +351,21 @@ class Client(Generic[ClientTransportT]):
         self._initialize_result = None
 
     async def _session_runner(self):
-        async with AsyncExitStack() as stack:
-            try:
-                await stack.enter_async_context(self._context_manager())
-                # Session/context is now ready
-                self._ready_event.set()
-                # Wait until disconnect/stop is requested
-                await self._stop_event.wait()
-            finally:
-                # On exit, ensure ready event is set (idempotent)
-                self._ready_event.set()
+        try:
+            async with AsyncExitStack() as stack:
+                try:
+                    await stack.enter_async_context(self._context_manager())
+                    # Session/context is now ready
+                    self._ready_event.set()
+                    # Wait until disconnect/stop is requested
+                    await self._stop_event.wait()
+                finally:
+                    # On exit, ensure ready event is set (idempotent)
+                    self._ready_event.set()
+        except Exception:
+            # Ensure ready event is set even if context manager entry fails
+            self._ready_event.set()
+            raise
 
     async def close(self):
         await self._disconnect(force=True)
@@ -675,7 +723,8 @@ class Client(Generic[ClientTransportT]):
         arguments: dict[str, Any] | None = None,
         timeout: datetime.timedelta | float | int | None = None,
         progress_handler: ProgressHandler | None = None,
-    ) -> list[MCPContent]:
+        raise_on_error: bool = True,
+    ) -> CallToolResult:
         """Call a tool on the server.
 
         Unlike call_tool_mcp, this method raises a ToolError if the tool call results in an error.
@@ -687,8 +736,13 @@ class Client(Generic[ClientTransportT]):
             progress_handler (ProgressHandler | None, optional): The progress handler to use for the tool call. Defaults to None.
 
         Returns:
-            list[mcp.types.TextContent | mcp.types.ImageContent | mcp.types.AudioContent | mcp.types.EmbeddedResource]:
-                The content returned by the tool.
+            CallToolResult:
+                The content returned by the tool. 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.
@@ -700,7 +754,43 @@ class Client(Generic[ClientTransportT]):
             timeout=timeout,
             progress_handler=progress_handler,
         )
-        if result.isError:
+        data = None
+        if result.isError and raise_on_error:
             msg = cast(mcp.types.TextContent, result.content[0]).text
             raise ToolError(msg)
-        return result.content
+        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"Error parsing structured content: {e}")
+
+        return CallToolResult(
+            content=result.content,
+            structured_content=result.structuredContent,
+            data=data,
+            is_error=result.isError,
+        )
+
+
+@dataclass
+class CallToolResult:
+    content: list[mcp.types.ContentBlock]
+    structured_content: dict[str, Any] | None
+    data: Any = None
+    is_error: bool = False

fastmcp/client/elicitation.py

@@ -0,0 +1,63 @@
+from __future__ import annotations
+
+from collections.abc import Awaitable, Callable
+from typing import Any, Generic, TypeAlias, TypeVar
+
+import mcp.types
+from mcp import ClientSession
+from mcp.client.session import ElicitationFnT
+from mcp.shared.context import LifespanContextT, RequestContext
+from mcp.types import ElicitRequestParams
+from mcp.types import ElicitResult as MCPElicitResult
+from pydantic_core import to_jsonable_python
+
+from fastmcp.utilities.json_schema_type import json_schema_to_type
+
+__all__ = ["ElicitRequestParams", "ElicitResult", "ElicitationHandler"]
+
+T = TypeVar("T")
+
+
+class ElicitResult(MCPElicitResult, Generic[T]):
+    content: T | None = None
+
+
+ElicitationHandler: TypeAlias = Callable[
+    [
+        str,  # message
+        type[T],  # a class for creating a structured response
+        ElicitRequestParams,
+        RequestContext[ClientSession, LifespanContextT],
+    ],
+    Awaitable[T | dict[str, Any] | ElicitResult[T | dict[str, Any]]],
+]
+
+
+def create_elicitation_callback(
+    elicitation_handler: ElicitationHandler,
+) -> ElicitationFnT:
+    async def _elicitation_handler(
+        context: RequestContext[ClientSession, LifespanContextT],
+        params: ElicitRequestParams,
+    ) -> MCPElicitResult | mcp.types.ErrorData:
+        try:
+            if params.requestedSchema == {"type": "object", "properties": {}}:
+                response_type = None
+            else:
+                response_type = json_schema_to_type(params.requestedSchema)
+
+            result = await elicitation_handler(
+                params.message, response_type, params, context
+            )
+            # if the user returns data, we assume they've accepted the elicitation
+            if not isinstance(result, ElicitResult):
+                result = ElicitResult(action="accept", content=result)
+            content = to_jsonable_python(result.content)
+            return MCPElicitResult(**result.model_dump() | {"content": content})
+        except Exception as e:
+            return mcp.types.ErrorData(
+                code=mcp.types.INTERNAL_ERROR,
+                message=str(e),
+            )
+
+    return _elicitation_handler

fastmcp/client/transports.py

@@ -8,18 +8,23 @@ import sys
 import warnings
 from collections.abc import AsyncIterator, Callable
 from pathlib import Path
-from typing import Any, Literal, TypedDict, TypeVar, cast, overload
-from urllib.parse import urlparse, urlunparse
+from typing import Any, Literal, TypeVar, cast, overload
 
 import anyio
 import httpx
 import mcp.types
 from mcp import ClientSession, StdioServerParameters
-from mcp.client.session import ListRootsFnT, LoggingFnT, MessageHandlerFnT, SamplingFnT
+from mcp.client.session import (
+    ElicitationFnT,
+    ListRootsFnT,
+    LoggingFnT,
+    MessageHandlerFnT,
+    SamplingFnT,
+)
 from mcp.server.fastmcp import FastMCP as FastMCP1Server
 from mcp.shared.memory import create_client_server_memory_streams
 from pydantic import AnyUrl
-from typing_extensions import Unpack
+from typing_extensions import TypedDict, Unpack
 
 import fastmcp
 from fastmcp.client.auth.bearer import BearerAuth
@@ -56,6 +61,7 @@ class SessionKwargs(TypedDict, total=False):
     sampling_callback: SamplingFnT | None
     list_roots_callback: ListRootsFnT | None
     logging_callback: LoggingFnT | None
+    elicitation_callback: ElicitationFnT | None
     message_handler: MessageHandlerFnT | None
     client_info: mcp.types.Implementation | None
 
@@ -161,11 +167,8 @@ class SSETransport(ClientTransport):
         if not isinstance(url, str) or not url.startswith("http"):
             raise ValueError("Invalid HTTP/S URL provided for SSE.")
 
-        # Ensure the URL path ends with a trailing slash to avoid automatic redirects
-        parsed = urlparse(url)
-        if not parsed.path.endswith("/"):
-            parsed = parsed._replace(path=parsed.path + "/")
-            url = urlunparse(parsed)
+        # Don't modify the URL path - respect the exact URL provided by the user
+        # Some servers are strict about trailing slashes (e.g., PayPal MCP)
 
         self.url = url
         self.headers = headers or {}
@@ -236,11 +239,8 @@ class StreamableHttpTransport(ClientTransport):
         if not isinstance(url, str) or not url.startswith("http"):
             raise ValueError("Invalid HTTP/S URL provided for Streamable HTTP.")
 
-        # Ensure the URL path ends with a trailing slash to avoid automatic redirects
-        parsed = urlparse(url)
-        if not parsed.path.endswith("/"):
-            parsed = parsed._replace(path=parsed.path + "/")
-            url = urlunparse(parsed)
+        # Don't modify the URL path - respect the exact URL provided by the user
+        # Some servers are strict about trailing slashes (e.g., PayPal MCP)
 
         self.url = url
         self.headers = headers or {}
@@ -361,34 +361,48 @@ class StdioTransport(ClientTransport):
         async def _connect_task():
             from mcp.client.stdio import stdio_client
 
-            async with contextlib.AsyncExitStack() as stack:
-                try:
-                    server_params = StdioServerParameters(
-                        command=self.command, args=self.args, env=self.env, cwd=self.cwd
-                    )
-                    transport = await stack.enter_async_context(
-                        stdio_client(server_params)
-                    )
-                    read_stream, write_stream = transport
-                    self._session = await stack.enter_async_context(
-                        ClientSession(read_stream, write_stream, **session_kwargs)
-                    )
-
-                    logger.debug("Stdio transport connected")
-                    self._ready_event.set()
-
-                    # Wait until disconnect is requested (stop_event is set)
-                    await self._stop_event.wait()
-                finally:
-                    # Clean up client on exit
-                    self._session = None
-                    logger.debug("Stdio transport disconnected")
+            try:
+                async with contextlib.AsyncExitStack() as stack:
+                    try:
+                        server_params = StdioServerParameters(
+                            command=self.command,
+                            args=self.args,
+                            env=self.env,
+                            cwd=self.cwd,
+                        )
+                        transport = await stack.enter_async_context(
+                            stdio_client(server_params)
+                        )
+                        read_stream, write_stream = transport
+                        self._session = await stack.enter_async_context(
+                            ClientSession(read_stream, write_stream, **session_kwargs)
+                        )
+
+                        logger.debug("Stdio transport connected")
+                        self._ready_event.set()
+
+                        # Wait until disconnect is requested (stop_event is set)
+                        await self._stop_event.wait()
+                    finally:
+                        # Clean up client on exit
+                        self._session = None
+                        logger.debug("Stdio transport disconnected")
+            except Exception:
+                # Ensure ready event is set even if connection fails
+                self._ready_event.set()
+                raise
 
         # start the connection task
         self._connect_task = asyncio.create_task(_connect_task())
         # wait for the client to be ready before returning
         await self._ready_event.wait()
 
+        # Check if connect task completed with an exception (early failure)
+        if self._connect_task.done():
+            exception = self._connect_task.exception()
+            if exception is not None:
+                raise exception
+
     async def disconnect(self):
         if self._connect_task is None:
             return