fastmcp 2.3.5__py3-none-any.whl → 2.4.0__py3-none-any.whl

fastmcp/client/client.py

@@ -3,12 +3,18 @@ from contextlib import AsyncExitStack, asynccontextmanager
 from pathlib import Path
 from typing import Any, cast
 
+import anyio
 import mcp.types
 from exceptiongroup import catch
 from mcp import ClientSession
 from pydantic import AnyUrl
 
-from fastmcp.client.logging import LogHandler, MessageHandler, default_log_handler
+from fastmcp.client.logging import (
+    LogHandler,
+    MessageHandler,
+    create_log_callback,
+    default_log_handler,
+)
 from fastmcp.client.progress import ProgressHandler, default_progress_handler
 from fastmcp.client.roots import (
     RootsHandler,
@@ -19,6 +25,7 @@ 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.mcp_config import MCPConfig
 
 from .transports import ClientTransport, SessionKwargs, infer_transport
 
@@ -47,6 +54,7 @@ class Client:
             - FastMCP: In-process FastMCP server
             - AnyUrl | str: URL to connect to
             - Path: File path for local socket
+            - MCPConfig: MCP server configuration
             - dict: Transport configuration
         roots: Optional RootsList or RootsHandler for filesystem access
         sampling_handler: Optional handler for sampling requests
@@ -71,7 +79,13 @@ class Client:
 
     def __init__(
         self,
-        transport: ClientTransport | FastMCP | AnyUrl | Path | dict[str, Any] | str,
+        transport: ClientTransport
+        | FastMCP
+        | AnyUrl
+        | Path
+        | MCPConfig
+        | dict[str, Any]
+        | str,
         # Common args
         roots: RootsList | RootsHandler | None = None,
         sampling_handler: SamplingHandler | None = None,
@@ -100,7 +114,7 @@ class Client:
         self._session_kwargs: SessionKwargs = {
             "sampling_callback": None,
             "list_roots_callback": None,
-            "logging_callback": log_handler,
+            "logging_callback": create_log_callback(log_handler),
             "message_handler": message_handler,
             "read_timeout_seconds": timeout,
         }
@@ -153,10 +167,12 @@ class Client:
             ) as session:
                 self._session = session
                 # Initialize the session
-                self._initialize_result = await self._session.initialize()
-
                 try:
+                    with anyio.fail_after(1):
+                        self._initialize_result = await self._session.initialize()
                     yield
+                except TimeoutError:
+                    raise RuntimeError("Failed to initialize server session")
                 finally:
                     self._exit_stack = None
                     self._session = None

fastmcp/client/logging.py

@@ -1,9 +1,7 @@
+from collections.abc import Awaitable, Callable
 from typing import TypeAlias
 
-from mcp.client.session import (
-    LoggingFnT,
-    MessageHandlerFnT,
-)
+from mcp.client.session import LoggingFnT, MessageHandlerFnT
 from mcp.types import LoggingMessageNotificationParams
 
 from fastmcp.utilities.logging import get_logger
@@ -11,11 +9,19 @@ from fastmcp.utilities.logging import get_logger
 logger = get_logger(__name__)
 
 LogMessage: TypeAlias = LoggingMessageNotificationParams
-LogHandler: TypeAlias = LoggingFnT
+LogHandler: TypeAlias = Callable[[LogMessage], Awaitable[None]]
 MessageHandler: TypeAlias = MessageHandlerFnT
 
-__all__ = ["LogMessage", "LogHandler", "MessageHandler"]
 
+async def default_log_handler(message: LogMessage) -> None:
+    logger.debug(f"Log received: {message}")
 
-async def default_log_handler(params: LogMessage) -> None:
-    logger.debug(f"Log received: {params}")
+
+def create_log_callback(handler: LogHandler | None = None) -> LoggingFnT:
+    if handler is None:
+        handler = default_log_handler
+
+    async def log_callback(params: LoggingMessageNotificationParams) -> None:
+        await handler(params)
+
+    return log_callback

fastmcp/client/transports.py

@@ -6,8 +6,7 @@ import shutil
 import sys
 from collections.abc import AsyncIterator
 from pathlib import Path
-from typing import Any, TypedDict, cast
-from urllib.parse import urlparse
+from typing import TYPE_CHECKING, Any, TypedDict, cast
 
 from mcp import ClientSession, StdioServerParameters
 from mcp.client.session import (
@@ -25,7 +24,12 @@ from pydantic import AnyUrl
 from typing_extensions import Unpack
 
 from fastmcp.server import FastMCP as FastMCPServer
+from fastmcp.server.server import FastMCP
 from fastmcp.utilities.logging import get_logger
+from fastmcp.utilities.mcp_config import MCPConfig, infer_transport_type_from_url
+
+if TYPE_CHECKING:
+    from fastmcp.utilities.mcp_config import MCPConfig
 
 logger = get_logger(__name__)
 
@@ -71,7 +75,7 @@ class ClientTransport(abc.ABC):
             A mcp.ClientSession instance.
         """
         raise NotImplementedError
-        yield None  # type: ignore
+        yield  # type: ignore
 
     def __repr__(self) -> str:
         # Basic representation for subclasses
@@ -452,7 +456,7 @@ class FastMCPTransport(ClientTransport):
     """
 
     def __init__(self, mcp: FastMCPServer):
-        self._fastmcp = mcp  # Can be FastMCP or MCPServer
+        self.server = mcp  # Can be FastMCP or MCPServer
 
     @contextlib.asynccontextmanager
     async def connect_session(
@@ -460,17 +464,105 @@ class FastMCPTransport(ClientTransport):
     ) -> AsyncIterator[ClientSession]:
         # create_connected_server_and_client_session manages the session lifecycle itself
         async with create_connected_server_and_client_session(
-            server=self._fastmcp._mcp_server,
+            server=self.server._mcp_server,
             **session_kwargs,
         ) as session:
             yield session
 
     def __repr__(self) -> str:
-        return f"<FastMCP(server='{self._fastmcp.name}')>"
+        return f"<FastMCP(server='{self.server.name}')>"
+
+
+class MCPConfigTransport(ClientTransport):
+    """Transport for connecting to one or more MCP servers defined in an MCPConfig.
+
+    This transport provides a unified interface to multiple MCP servers defined in an MCPConfig
+    object or dictionary matching the MCPConfig schema. It supports two key scenarios:
+
+    1. If the MCPConfig contains exactly one server, it creates a direct transport to that server.
+    2. If the MCPConfig contains multiple servers, it creates a composite client by mounting
+       all servers on a single FastMCP instance, with each server's name used as its mounting prefix.
+
+    In the multi-server case, tools are accessible with the prefix pattern `{server_name}_{tool_name}`
+    and resources with the pattern `protocol://{server_name}/path/to/resource`.
+
+    This is particularly useful for creating clients that need to interact with multiple specialized
+    MCP servers through a single interface, simplifying client code.
+
+    Examples:
+        ```python
+        from fastmcp import Client
+        from fastmcp.utilities.mcp_config import MCPConfig
+
+        # Create a config with multiple servers
+        config = {
+            "mcpServers": {
+                "weather": {
+                    "url": "https://weather-api.example.com/mcp",
+                    "transport": "streamable-http"
+                },
+                "calendar": {
+                    "url": "https://calendar-api.example.com/mcp",
+                    "transport": "streamable-http"
+                }
+            }
+        }
+
+        # Create a client with the config
+        client = Client(config)
+
+        async with client:
+            # Access tools with prefixes
+            weather = await client.call_tool("weather_get_forecast", {"city": "London"})
+            events = await client.call_tool("calendar_list_events", {"date": "2023-06-01"})
+
+            # Access resources with prefixed URIs
+            icons = await client.read_resource("weather://weather/icons/sunny")
+        ```
+    """
+
+    def __init__(self, config: MCPConfig | dict):
+        from fastmcp.client.client import Client
+
+        if isinstance(config, dict):
+            config = MCPConfig.from_dict(config)
+        self.config = config
+
+        # if there's exactly one server, create a client for that server
+        if len(self.config.mcpServers) == 1:
+            self.transport = list(self.config.mcpServers.values())[0].to_transport()
+
+        # otherwise create a composite client
+        else:
+            composite_server = FastMCP()
+
+            for name, server in self.config.mcpServers.items():
+                server_client = Client(transport=server.to_transport())
+                composite_server.mount(
+                    prefix=name, server=FastMCP.as_proxy(server_client)
+                )
+
+            self.transport = FastMCPTransport(mcp=composite_server)
+
+    @contextlib.asynccontextmanager
+    async def connect_session(
+        self, **session_kwargs: Unpack[SessionKwargs]
+    ) -> AsyncIterator[ClientSession]:
+        async with self.transport.connect_session(**session_kwargs) as session:
+            yield session
+
+    def __repr__(self) -> str:
+        return f"<MCPConfig(config='{self.config}')>"
 
 
 def infer_transport(
-    transport: ClientTransport | FastMCPServer | AnyUrl | Path | dict[str, Any] | str,
+    transport: ClientTransport
+    | FastMCPServer
+    | AnyUrl
+    | Path
+    | MCPConfig
+    | dict[str, Any]
+    | str,
 ) -> ClientTransport:
     """
     Infer the appropriate transport type from the given transport argument.
@@ -479,8 +571,41 @@ def infer_transport(
     argument, handling various input types and converting them to the appropriate
     ClientTransport subclass.
 
+    The function supports these input types:
+    - ClientTransport: Used directly without modification
+    - FastMCPServer: Creates an in-memory FastMCPTransport
+    - Path or str (file path): Creates PythonStdioTransport (.py) or NodeStdioTransport (.js)
+    - AnyUrl or str (URL): Creates StreamableHttpTransport (default) or SSETransport (for /sse endpoints)
+    - MCPConfig or dict: Creates MCPConfigTransport, potentially connecting to multiple servers
+
     For HTTP URLs, they are assumed to be Streamable HTTP URLs unless they end in `/sse`.
+
+    For MCPConfig with multiple servers, a composite client is created where each server
+    is mounted with its name as prefix. This allows accessing tools and resources from multiple
+    servers through a single unified client interface, using naming patterns like
+    `servername_toolname` for tools and `protocol://servername/path` for resources.
+    If the MCPConfig contains only one server, a direct connection is established without prefixing.
+
+    Examples:
+        ```python
+        # Connect to a local Python script
+        transport = infer_transport("my_script.py")
+
+        # Connect to a remote server via HTTP
+        transport = infer_transport("http://example.com/mcp")
+
+        # Connect to multiple servers using MCPConfig
+        config = {
+            "mcpServers": {
+                "weather": {"url": "http://weather.example.com/mcp"},
+                "calendar": {"url": "http://calendar.example.com/mcp"}
+            }
+        }
+        transport = infer_transport(config)
+        ```
     """
+    from fastmcp.utilities.mcp_config import MCPConfig
+
     # the transport is already a ClientTransport
     if isinstance(transport, ClientTransport):
         return transport
@@ -500,45 +625,15 @@ def infer_transport(
 
     # the transport is an http(s) URL
     elif isinstance(transport, AnyUrl | str) and str(transport).startswith("http"):
-        transport_str = str(transport)
-        # Parse out just the path portion to check for /sse
-        parsed_url = urlparse(transport_str)
-        path = parsed_url.path
-
-        # Check if path contains /sse/ or ends with /sse
-        if "/sse/" in path or path.rstrip("/").endswith("/sse"):
+        inferred_transport_type = infer_transport_type_from_url(transport)
+        if inferred_transport_type == "sse":
             inferred_transport = SSETransport(url=transport)
         else:
             inferred_transport = StreamableHttpTransport(url=transport)
 
-    ## if the transport is a config dict
-    elif isinstance(transport, dict):
-        if "mcpServers" not in transport:
-            raise ValueError("Invalid transport dictionary: missing 'mcpServers' key")
-        else:
-            server = transport["mcpServers"]
-            if len(list(server.keys())) > 1:
-                raise ValueError(
-                    "Invalid transport dictionary: multiple servers found - only one expected"
-                )
-            server_name = list(server.keys())[0]
-            # Stdio transport
-            if "command" in server[server_name] and "args" in server[server_name]:
-                inferred_transport = StdioTransport(
-                    command=server[server_name]["command"],
-                    args=server[server_name]["args"],
-                    env=server[server_name].get("env", None),
-                    cwd=server[server_name].get("cwd", None),
-                )
-
-            # HTTP transport
-            elif "url" in server:
-                inferred_transport = SSETransport(
-                    url=server["url"],
-                    headers=server.get("headers", None),
-                )
-
-            raise ValueError("Cannot determine transport type from dictionary")
+    # if the transport is a config dict or MCPConfig
+    elif isinstance(transport, dict | MCPConfig):
+        inferred_transport = MCPConfigTransport(config=transport)
 
     # the transport is an unknown type
     else:

fastmcp/server/http.py

@@ -306,7 +306,29 @@ def create_streamable_http_app(
     async def handle_streamable_http(
         scope: Scope, receive: Receive, send: Send
     ) -> None:
-        await session_manager.handle_request(scope, receive, send)
+        try:
+            await session_manager.handle_request(scope, receive, send)
+        except RuntimeError as e:
+            if str(e) == "Task group is not initialized. Make sure to use run().":
+                logger.error(
+                    f"Original RuntimeError from mcp library: {e}", exc_info=True
+                )
+                new_error_message = (
+                    "FastMCP's StreamableHTTPSessionManager task group was not initialized. "
+                    "This commonly occurs when the FastMCP application's lifespan is not "
+                    "passed to the parent ASGI application (e.g., FastAPI or Starlette). "
+                    "Please ensure you are setting `lifespan=mcp_app.lifespan` in your "
+                    "parent app's constructor, where `mcp_app` is the application instance "
+                    "returned by `fastmcp_instance.http_app()`. \\n"
+                    "For more details, see the FastMCP ASGI integration documentation: "
+                    "https://gofastmcp.com/deployment/asgi"
+                )
+                # Raise a new RuntimeError that includes the original error's message
+                # for full context, but leads with the more helpful guidance.
+                raise RuntimeError(f"{new_error_message}\\nOriginal error: {e}") from e
+            else:
+                # Re-raise other RuntimeErrors if they don't match the specific message
+                raise
 
     # Get auth middleware and routes
     auth_middleware, auth_routes, required_scopes = setup_auth_middleware_and_routes(

fastmcp/server/openapi.py

@@ -47,7 +47,7 @@ class RouteType(enum.Enum):
 class RouteMap:
     """Mapping configuration for HTTP routes to FastMCP component types."""
 
-    methods: list[HttpMethod]
+    methods: list[HttpMethod] | Literal["*"]
     pattern: Pattern[str] | str
     route_type: RouteType
 
@@ -86,7 +86,7 @@ def _determine_route_type(
     # Check mappings in priority order (first match wins)
     for route_map in mappings:
         # Check if the HTTP method matches
-        if route.method in route_map.methods:
+        if route_map.methods == "*" or route.method in route_map.methods:
             # Handle both string patterns and compiled Pattern objects
             if isinstance(route_map.pattern, Pattern):
                 pattern_matches = route_map.pattern.search(route.path)
@@ -171,17 +171,120 @@ class OpenAPITool(Tool):
             raise ToolError(f"Missing required path parameters: {missing_params}")
 
         for param_name, param_value in path_params.items():
+            # Handle array path parameters with style 'simple' (comma-separated)
+            # In OpenAPI, 'simple' is the default style for path parameters
+            param_info = next(
+                (p for p in self._route.parameters if p.name == param_name), None
+            )
+
+            if param_info and isinstance(param_value, list):
+                # Check if schema indicates an array type
+                schema = param_info.schema_
+                is_array = schema.get("type") == "array"
+
+                if is_array:
+                    # Format array values as comma-separated string
+                    # This follows the OpenAPI 'simple' style (default for path)
+                    if all(
+                        isinstance(item, str | int | float | bool)
+                        for item in param_value
+                    ):
+                        # Handle simple array types
+                        path = path.replace(
+                            f"{{{param_name}}}", ",".join(str(v) for v in param_value)
+                        )
+                    else:
+                        # Handle complex array types (containing objects/dicts)
+                        try:
+                            # Try to create a simple representation without Python syntax artifacts
+                            formatted_parts = []
+                            for item in param_value:
+                                if isinstance(item, dict):
+                                    # For objects, serialize key-value pairs
+                                    item_parts = []
+                                    for k, v in item.items():
+                                        item_parts.append(f"{k}:{v}")
+                                    formatted_parts.append(".".join(item_parts))
+                                else:
+                                    # Fallback for other complex types
+                                    formatted_parts.append(str(item))
+
+                            # Join parts with commas
+                            formatted_value = ",".join(formatted_parts)
+                            path = path.replace(f"{{{param_name}}}", formatted_value)
+                        except Exception as e:
+                            logger.warning(
+                                f"Failed to format complex array path parameter '{param_name}': {e}"
+                            )
+                            # Fallback to string representation, but remove Python syntax artifacts
+                            str_value = (
+                                str(param_value)
+                                .replace("[", "")
+                                .replace("]", "")
+                                .replace("'", "")
+                                .replace('"', "")
+                            )
+                            path = path.replace(f"{{{param_name}}}", str_value)
+                    continue
+
+            # Default handling for non-array parameters or non-array schemas
             path = path.replace(f"{{{param_name}}}", str(param_value))
 
         # Prepare query parameters - filter out None and empty strings
-        query_params = {
-            p.name: kwargs.get(p.name)
-            for p in self._route.parameters
-            if p.location == "query"
-            and p.name in kwargs
-            and kwargs.get(p.name) is not None
-            and kwargs.get(p.name) != ""
-        }
+        query_params = {}
+        for p in self._route.parameters:
+            if (
+                p.location == "query"
+                and p.name in kwargs
+                and kwargs.get(p.name) is not None
+                and kwargs.get(p.name) != ""
+            ):
+                param_value = kwargs.get(p.name)
+
+                # Format array query parameters as comma-separated strings
+                # following OpenAPI form style (default for query parameters)
+                if isinstance(param_value, list) and p.schema_.get("type") == "array":
+                    # Get explode parameter from schema, default is True for query parameters
+                    # If explode is True, the array is serialized as separate parameters
+                    # If explode is False, the array is serialized as a comma-separated string
+                    explode = p.schema_.get("explode", True)
+
+                    if explode:
+                        # When explode=True, we pass the array directly, which HTTPX will serialize
+                        # as multiple parameters with the same name
+                        query_params[p.name] = param_value
+                    else:
+                        # For arrays of simple types (strings, numbers, etc.), join with commas
+                        if all(
+                            isinstance(item, str | int | float | bool)
+                            for item in param_value
+                        ):
+                            query_params[p.name] = ",".join(str(v) for v in param_value)
+                        else:
+                            # For complex types, try to create a simpler representation
+                            try:
+                                # Try to create a simple string representation
+                                formatted_parts = []
+                                for item in param_value:
+                                    if isinstance(item, dict):
+                                        # For objects, serialize key-value pairs
+                                        item_parts = []
+                                        for k, v in item.items():
+                                            item_parts.append(f"{k}:{v}")
+                                        formatted_parts.append(".".join(item_parts))
+                                    else:
+                                        formatted_parts.append(str(item))
+
+                                query_params[p.name] = ",".join(formatted_parts)
+                            except Exception as e:
+                                logger.warning(
+                                    f"Failed to format complex array query parameter '{p.name}': {e}"
+                                )
+                                # Fallback to string representation
+                                query_params[p.name] = param_value
+                else:
+                    # Non-array parameters are passed as is
+                    query_params[p.name] = param_value
 
         # Prepare headers - fix typing by ensuring all values are strings
         headers = {}