camel-ai 0.2.61__py3-none-any.whl → 0.2.62__py3-none-any.whl

camel/utils/mcp_client.py

@@ -0,0 +1,979 @@
+# ========= Copyright 2023-2024 @ CAMEL-AI.org. All Rights Reserved. =========
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+# ========= Copyright 2023-2024 @ CAMEL-AI.org. All Rights Reserved. =========
+"""
+Unified MCP Client
+
+This module provides a unified interface for connecting to MCP servers
+using different transport protocols (stdio, sse, streamable-http, websocket).
+The client can automatically detect the transport type based on configuration.
+"""
+
+import inspect
+from contextlib import asynccontextmanager
+from datetime import timedelta
+from enum import Enum
+from pathlib import Path
+from typing import (
+    Any,
+    Callable,
+    Dict,
+    List,
+    Optional,
+    Set,
+    Union,
+)
+
+import httpx
+import mcp.types as types
+from pydantic import BaseModel, model_validator
+
+try:
+    from mcp.shared._httpx_utils import create_mcp_http_client
+except ImportError:
+
+    def create_mcp_http_client(
+        headers: Optional[Dict[str, str]] = None,
+        timeout: Optional[httpx.Timeout] = None,
+        auth: Optional[httpx.Auth] = None,
+    ) -> httpx.AsyncClient:
+        """Fallback implementation if not available."""
+        kwargs: Dict[str, Any] = {"follow_redirects": True}
+
+        if timeout is None:
+            kwargs["timeout"] = httpx.Timeout(30.0)
+        else:
+            kwargs["timeout"] = timeout
+
+        if headers is not None:
+            kwargs["headers"] = headers
+
+        if auth is not None:
+            kwargs["auth"] = auth
+
+        return httpx.AsyncClient(**kwargs)
+
+
+from mcp import ClientSession
+
+
+class TransportType(str, Enum):
+    r"""Supported transport types."""
+
+    STDIO = "stdio"
+    SSE = "sse"
+    STREAMABLE_HTTP = "streamable_http"
+    WEBSOCKET = "websocket"
+
+
+class ServerConfig(BaseModel):
+    r"""Unified server configuration that automatically detects transport type.
+
+    Examples:
+        # STDIO server
+        config = ServerConfig(
+            command="npx",
+            args=["-y", "@modelcontextprotocol/server-filesystem", "/path"]
+        )
+
+        # HTTP/SSE server
+        config = ServerConfig(
+            url="https://api.example.com/mcp",
+            headers={"Authorization": "Bearer token"}
+        )
+
+        # WebSocket server
+        config = ServerConfig(url="ws://localhost:8080/mcp")
+    """
+
+    # STDIO configuration
+    command: Optional[str] = None
+    args: Optional[List[str]] = None
+    env: Optional[Dict[str, str]] = None
+    cwd: Optional[Union[str, Path]] = None
+
+    # HTTP/WebSocket configuration
+    url: Optional[str] = None
+    headers: Optional[Dict[str, Any]] = None
+
+    # Common configuration
+    timeout: float = 30.0
+    encoding: str = "utf-8"
+
+    # Advanced options
+    sse_read_timeout: float = 300.0  # 5 minutes
+    terminate_on_close: bool = True
+    # For HTTP URLs, prefer SSE over StreamableHTTP
+    prefer_sse: bool = False
+
+    @model_validator(mode='after')
+    def validate_config(self):
+        r"""Validate that either command or url is provided."""
+        if not self.command and not self.url:
+            raise ValueError(
+                "Either 'command' (for stdio) or 'url' "
+                "(for http/websocket) must be provided"
+            )
+
+        if self.command and self.url:
+            raise ValueError("Cannot specify both 'command' and 'url'")
+
+        return self
+
+    @property
+    def transport_type(self) -> TransportType:
+        r"""Automatically detect transport type based on configuration."""
+        if self.command:
+            return TransportType.STDIO
+        elif self.url:
+            if self.url.startswith(("ws://", "wss://")):
+                return TransportType.WEBSOCKET
+            elif self.url.startswith(("http://", "https://")):
+                # Default to StreamableHTTP, unless user prefers SSE
+                if self.prefer_sse:
+                    return TransportType.SSE
+                else:
+                    return TransportType.STREAMABLE_HTTP
+            else:
+                raise ValueError(f"Unsupported URL scheme: {self.url}")
+        else:
+            raise ValueError("Cannot determine transport type")
+
+
+class MCPClient:
+    r"""Unified MCP client that automatically detects and connects to servers
+    using the appropriate transport protocol.
+
+    This client provides a unified interface for connecting to Model Context
+    Protocol (MCP) servers using different transport protocols including STDIO,
+    HTTP/HTTPS, WebSocket, and Server-Sent Events (SSE). The client
+    automatically detects the appropriate transport type based on the
+    configuration provided.
+
+    The client should be used as an async context manager for automatic
+    connectionmanagement.
+
+    Args:
+        config (Union[ServerConfig, Dict[str, Any]]): Server configuration
+            as either a :obj:`ServerConfig` object or a dictionary that will
+            be converted to a :obj:`ServerConfig`. The configuration determines
+            the transport type and connection parameters.
+        client_info (Optional[types.Implementation], optional): Client
+            implementation information to send to the server during
+            initialization. (default: :obj:`None`)
+        timeout (Optional[float], optional): Timeout for waiting for messages
+            from the server in seconds. (default: :obj:`10.0`)
+        strict (Optional[bool], optional): Strict mode for generating
+            FunctionTool objects. (default: :obj:`False`)
+
+    Examples:
+        STDIO server:
+
+        .. code-block:: python
+
+            async with MCPClient({
+                "command": "npx",
+                "args": [
+                    "-y",
+                    "@modelcontextprotocol/server-filesystem",
+                    "/path"
+                ]
+            }) as client:
+                tools = client.get_tools()
+                result = await client.call_tool("tool_name", {"arg": "value"})
+
+        HTTP server:
+
+        .. code-block:: python
+
+            async with MCPClient({
+                "url": "https://api.example.com/mcp",
+                "headers": {"Authorization": "Bearer token"}
+            }) as client:
+                tools = client.get_tools()
+
+        WebSocket server:
+
+        .. code-block:: python
+
+            async with MCPClient({"url": "ws://localhost:8080/mcp"}) as client:
+                tools = client.get_tools()
+
+        With strict mode enabled:
+
+        .. code-block:: python
+
+            async with MCPClient({
+                "command": "npx",
+                "args": [
+                    "-y",
+                    "@modelcontextprotocol/server-filesystem",
+                    "/path"
+                ]
+            }, strict=True) as client:
+                tools = client.get_tools()
+
+    Attributes:
+        config (ServerConfig): The server configuration object.
+        client_info (Optional[types.Implementation]): Client implementation
+            information.
+        read_timeout_seconds (timedelta): Timeout for reading from the server.
+    """
+
+    def __init__(
+        self,
+        config: Union[ServerConfig, Dict[str, Any]],
+        client_info: Optional[types.Implementation] = None,
+        timeout: Optional[float] = 10.0,
+        strict: Optional[bool] = False,
+    ):
+        # Convert dict config to ServerConfig if needed
+        if isinstance(config, dict):
+            config = ServerConfig(**config)
+
+        self.config = config
+        self.strict = strict
+
+        # Validate transport type early (this will raise ValueError if invalid)
+        _ = self.config.transport_type
+
+        self.client_info = client_info
+        self.read_timeout_seconds = timedelta(seconds=timeout or 10.0)
+
+        self._session: Optional[ClientSession] = None
+        self._tools: List[types.Tool] = []
+        self._connection_context = None
+
+    @property
+    def transport_type(self) -> TransportType:
+        r"""Get the detected transport type."""
+        return self.config.transport_type
+
+    async def __aenter__(self):
+        r"""Async context manager entry point.
+
+        Establishes connection to the MCP server and initializes the session.
+
+        Returns:
+            MCPClient: The connected client instance.
+        """
+        await self._establish_connection()
+        return self
+
+    async def __aexit__(self, exc_type, exc_val, exc_tb):
+        r"""Async context manager exit point.
+
+        Cleans up the connection and resources.
+        """
+        await self._cleanup_connection()
+
+    async def _establish_connection(self):
+        r"""Establish connection to the MCP server."""
+        try:
+            self._connection_context = self._create_transport()
+            streams = await self._connection_context.__aenter__()
+
+            # Handle extra returns safely
+            read_stream, write_stream = streams[:2]
+
+            self._session = ClientSession(
+                read_stream=read_stream,
+                write_stream=write_stream,
+                client_info=self.client_info,
+                read_timeout_seconds=self.read_timeout_seconds,
+            )
+
+            # Start the session's message processing loop
+            await self._session.__aenter__()
+
+            # Initialize the session and load tools
+            await self._session.initialize()
+            tools_response = await self._session.list_tools()
+            self._tools = tools_response.tools if tools_response else []
+
+        except Exception as e:
+            # Clean up on error
+            await self._cleanup_connection()
+
+            # Convert complex exceptions to simpler, more understandable ones
+            from camel.logger import get_logger
+
+            logger = get_logger(__name__)
+
+            error_msg = self._simplify_connection_error(e)
+            logger.error(f"MCP connection failed: {error_msg}")
+
+            # Raise a simpler exception
+            raise ConnectionError(error_msg) from e
+
+    async def _cleanup_connection(self):
+        r"""Clean up connection resources."""
+        try:
+            if self._session:
+                try:
+                    await self._session.__aexit__(None, None, None)
+                except Exception:
+                    pass  # Ignore cleanup errors
+                finally:
+                    self._session = None
+
+            if self._connection_context:
+                try:
+                    await self._connection_context.__aexit__(None, None, None)
+                except Exception:
+                    pass  # Ignore cleanup errors
+                finally:
+                    self._connection_context = None
+
+        finally:
+            # Ensure state is reset
+            self._tools = []
+
+    def _simplify_connection_error(self, error: Exception) -> str:
+        r"""Convert complex MCP connection errors to simple, understandable
+        messages.
+        """
+        error_str = str(error).lower()
+
+        # Handle different types of errors
+        if "exceptiongroup" in error_str or "taskgroup" in error_str:
+            # Often happens when the command fails to start
+            if "processlookuperror" in error_str:
+                return (
+                    f"Failed to start MCP server command "
+                    f"'{self.config.command}'. The command may have "
+                    "exited unexpectedly."
+                )
+            elif "cancelled" in error_str:
+                return (
+                    "Connection to MCP server was cancelled, "
+                    "likely due to timeout or server startup failure."
+                )
+            else:
+                return (
+                    f"MCP server process error. The server command "
+                    f"'{self.config.command}' failed to start properly."
+                )
+
+        elif "timeout" in error_str:
+            return (
+                f"Connection timeout after {self.config.timeout}s. "
+                "The MCP server may be taking too long to respond."
+            )
+
+        elif "not found" in error_str or "404" in error_str:
+            command_parts = []
+            if self.config.command:
+                command_parts.append(self.config.command)
+                if self.config.args:
+                    command_parts.extend(self.config.args)
+            command_str = (
+                ' '.join(command_parts) if command_parts else "unknown command"
+            )
+            return (
+                f"MCP server package not found. Check if '{command_str}' "
+                "is correct."
+            )
+
+        elif "permission" in error_str:
+            return (
+                f"Permission denied when trying to run MCP server "
+                f"command '{self.config.command}'."
+            )
+
+        elif "connection" in error_str:
+            if self.config.url:
+                return f"Failed to connect to MCP server at {self.config.url}."
+            else:
+                return "Connection failed to MCP server."
+
+        else:
+            # Generic fallback
+            command_info = (
+                f"'{self.config.command}'"
+                if self.config.command
+                else f"URL: {self.config.url}"
+            )
+            return (
+                f"MCP connection failed for {command_info}. Error: "
+                f"{str(error)[:100]}{'...' if len(str(error)) > 100 else ''}"
+            )
+
+    @asynccontextmanager
+    async def _create_transport(self):
+        """Create the appropriate transport based on detected type."""
+        transport_type = self.config.transport_type
+
+        if transport_type == TransportType.STDIO:
+            from mcp import StdioServerParameters
+            from mcp.client.stdio import stdio_client
+
+            # Ensure command is not None for STDIO
+            if not self.config.command:
+                raise ValueError("Command is required for STDIO transport")
+
+            server_params = StdioServerParameters(
+                command=self.config.command,
+                args=self.config.args or [],
+                env=self.config.env,
+                cwd=self.config.cwd,
+                encoding=self.config.encoding,
+            )
+
+            async with stdio_client(server_params) as (
+                read_stream,
+                write_stream,
+            ):
+                yield read_stream, write_stream
+
+        elif transport_type == TransportType.SSE:
+            from mcp.client.sse import sse_client
+
+            # Ensure URL is not None for SSE
+            if not self.config.url:
+                raise ValueError("URL is required for SSE transport")
+
+            try:
+                # Try with httpx_client_factory first (newer versions)
+                async with sse_client(
+                    url=self.config.url,
+                    headers=self.config.headers,
+                    timeout=self.config.timeout,
+                    sse_read_timeout=self.config.sse_read_timeout,
+                    httpx_client_factory=create_mcp_http_client,
+                ) as (read_stream, write_stream):
+                    yield read_stream, write_stream
+            except TypeError:
+                # Fall back to basic call without httpx_client_factory
+                async with sse_client(
+                    url=self.config.url,
+                    headers=self.config.headers,
+                    timeout=self.config.timeout,
+                    sse_read_timeout=self.config.sse_read_timeout,
+                ) as (read_stream, write_stream):
+                    yield read_stream, write_stream
+
+        elif transport_type == TransportType.STREAMABLE_HTTP:
+            from mcp.client.streamable_http import streamablehttp_client
+
+            # Ensure URL is not None for StreamableHTTP
+            if not self.config.url:
+                raise ValueError(
+                    "URL is required for StreamableHTTP transport"
+                )
+
+            try:
+                # Try with httpx_client_factory first (newer versions)
+                async with streamablehttp_client(
+                    url=self.config.url,
+                    headers=self.config.headers,
+                    timeout=timedelta(seconds=self.config.timeout),
+                    sse_read_timeout=timedelta(
+                        seconds=self.config.sse_read_timeout
+                    ),
+                    terminate_on_close=self.config.terminate_on_close,
+                    httpx_client_factory=create_mcp_http_client,
+                ) as (read_stream, write_stream, get_session_id):
+                    yield read_stream, write_stream, get_session_id
+            except TypeError:
+                # Fall back to basic call without httpx_client_factory
+                async with streamablehttp_client(
+                    url=self.config.url,
+                    headers=self.config.headers,
+                    timeout=timedelta(seconds=self.config.timeout),
+                    sse_read_timeout=timedelta(
+                        seconds=self.config.sse_read_timeout
+                    ),
+                    terminate_on_close=self.config.terminate_on_close,
+                ) as (read_stream, write_stream, get_session_id):
+                    yield read_stream, write_stream, get_session_id
+
+        elif transport_type == TransportType.WEBSOCKET:
+            from mcp.client.websocket import websocket_client
+
+            # Ensure URL is not None for WebSocket
+            if not self.config.url:
+                raise ValueError("URL is required for WebSocket transport")
+
+            async with websocket_client(url=self.config.url) as (
+                read_stream,
+                write_stream,
+            ):
+                yield read_stream, write_stream
+
+        else:
+            raise ValueError(f"Unsupported transport type: {transport_type}")
+
+    @property
+    def session(self) -> Optional[ClientSession]:
+        r"""Get the current session if connected."""
+        return self._session
+
+    def is_connected(self) -> bool:
+        r"""Check if the client is currently connected."""
+        return self._session is not None
+
+    async def list_mcp_tools(self):
+        r"""Retrieves the list of available tools from the connected MCP
+        server.
+
+        Returns:
+            ListToolsResult: Result containing available MCP tools.
+        """
+        if not self._session:
+            return "MCP Client is not connected. Call `connection()` first."
+        try:
+            return await self._session.list_tools()
+        except Exception as e:
+            raise e
+
+    def list_mcp_tools_sync(self):
+        r"""Synchronously retrieves the list of available tools from the
+        connected MCP server.
+
+        Returns:
+            ListToolsResult: Result containing available MCP tools.
+        """
+        from camel.utils.commons import run_async
+
+        return run_async(self.list_mcp_tools)()
+
+    def generate_function_from_mcp_tool(
+        self, mcp_tool: types.Tool
+    ) -> Callable:
+        r"""Dynamically generates a Python callable function corresponding to
+        a given MCP tool.
+
+        Args:
+            mcp_tool (types.Tool): The MCP tool definition received from the
+                MCP server.
+
+        Returns:
+            Callable: A dynamically created async Python function that wraps
+                the MCP tool.
+        """
+        func_name = mcp_tool.name
+        func_desc = mcp_tool.description or "No description provided."
+        parameters_schema = mcp_tool.inputSchema.get("properties", {})
+        required_params = mcp_tool.inputSchema.get("required", [])
+
+        type_map = {
+            "string": str,
+            "integer": int,
+            "number": float,
+            "boolean": bool,
+            "array": list,
+            "object": dict,
+        }
+        annotations = {}  # used to type hints
+        defaults: Dict[str, Any] = {}  # store default values
+
+        func_params = []
+        for param_name, param_schema in parameters_schema.items():
+            param_type = param_schema.get("type", "Any")
+            param_type = type_map.get(param_type, Any)
+
+            annotations[param_name] = param_type
+            if param_name not in required_params:
+                defaults[param_name] = None
+
+            func_params.append(param_name)
+
+        async def dynamic_function(**kwargs) -> str:
+            r"""Auto-generated function for MCP Tool interaction.
+
+            Args:
+                kwargs: Keyword arguments corresponding to MCP tool parameters.
+
+            Returns:
+                str: The textual result returned by the MCP tool.
+            """
+
+            missing_params: Set[str] = set(required_params) - set(
+                kwargs.keys()
+            )
+            if missing_params:
+                from camel.logger import get_logger
+
+                logger = get_logger(__name__)
+                logger.warning(
+                    f"Missing required parameters: {missing_params}"
+                )
+                return "Missing required parameters."
+
+            if not self._session:
+                from camel.logger import get_logger
+
+                logger = get_logger(__name__)
+                logger.error(
+                    "MCP Client is not connected. Call `connection()` first."
+                )
+                raise RuntimeError(
+                    "MCP Client is not connected. Call `connection()` first."
+                )
+
+            try:
+                result = await self._session.call_tool(func_name, kwargs)
+            except Exception as e:
+                from camel.logger import get_logger
+
+                logger = get_logger(__name__)
+                logger.error(f"Failed to call MCP tool '{func_name}': {e!s}")
+                raise e
+
+            if not result.content or len(result.content) == 0:
+                return "No data available for this request."
+
+            # Handle different content types
+            try:
+                content = result.content[0]
+                if content.type == "text":
+                    return content.text
+                elif content.type == "image":
+                    # Return image URL or data URI if available
+                    if hasattr(content, "url") and content.url:
+                        return f"Image available at: {content.url}"
+                    return "Image content received (data URI not shown)"
+                elif content.type == "embedded_resource":
+                    # Return resource information if available
+                    if hasattr(content, "name") and content.name:
+                        return f"Embedded resource: {content.name}"
+                    return "Embedded resource received"
+                else:
+                    msg = f"Received content of type '{content.type}'"
+                    return f"{msg} which is not fully supported yet."
+            except (IndexError, AttributeError) as e:
+                from camel.logger import get_logger
+
+                logger = get_logger(__name__)
+                logger.error(
+                    f"Error processing content from MCP tool response: {e!s}"
+                )
+                raise e
+
+        dynamic_function.__name__ = func_name
+        dynamic_function.__doc__ = func_desc
+        dynamic_function.__annotations__ = annotations
+
+        sig = inspect.Signature(
+            parameters=[
+                inspect.Parameter(
+                    name=param,
+                    kind=inspect.Parameter.KEYWORD_ONLY,
+                    default=defaults.get(param, inspect.Parameter.empty),
+                    annotation=annotations[param],
+                )
+                for param in func_params
+            ]
+        )
+        dynamic_function.__signature__ = sig  # type: ignore[attr-defined]
+
+        return dynamic_function
+
+    def _build_tool_schema(self, mcp_tool: types.Tool) -> Dict[str, Any]:
+        r"""Build tool schema for OpenAI function calling format."""
+        input_schema = mcp_tool.inputSchema
+        properties = input_schema.get("properties", {})
+        required = input_schema.get("required", [])
+
+        parameters = {
+            "type": "object",
+            "properties": properties,
+            "required": required,
+            "additionalProperties": False,
+        }
+
+        return {
+            "type": "function",
+            "function": {
+                "name": mcp_tool.name,
+                "description": mcp_tool.description
+                or "No description provided.",
+                "strict": self.strict,
+                "parameters": parameters,
+            },
+        }
+
+    def get_tools(self):
+        r"""Get available tools as CAMEL FunctionTool objects.
+
+        Retrieves all available tools from the connected MCP server and
+        converts them to CAMEL-compatible :obj:`FunctionTool` objects. The
+        tools are automatically wrapped to handle the MCP protocol
+        communication.
+
+        Returns:
+            List[FunctionTool]: A list of :obj:`FunctionTool` objects
+                representing the available tools from the MCP server. Returns
+                an empty list if the client is not connected.
+
+        Note:
+            This method requires an active connection to the MCP server.
+            If the client is not connected, an empty list will be returned.
+        """
+        if not self.is_connected():
+            return []
+
+        # Import FunctionTool here to avoid circular imports
+        try:
+            from camel.toolkits import FunctionTool
+        except ImportError:
+            from camel.logger import get_logger
+
+            logger = get_logger(__name__)
+            logger.error(
+                "Failed to import FunctionTool. Please ensure "
+                "camel.toolkits is available."
+            )
+            return []
+
+        camel_tools = []
+        for tool in self._tools:
+            try:
+                # Generate the function and build the tool schema
+                func = self.generate_function_from_mcp_tool(tool)
+                schema = self._build_tool_schema(tool)
+
+                # Create CAMEL FunctionTool
+                camel_tool = FunctionTool(
+                    func,
+                    openai_tool_schema=schema,
+                )
+                camel_tools.append(camel_tool)
+            except Exception as e:
+                # Log error but continue with other tools
+                from camel.logger import get_logger
+
+                logger = get_logger(__name__)
+                logger.warning(f"Failed to convert tool {tool.name}: {e}")
+
+        return camel_tools
+
+    def get_text_tools(self) -> str:
+        r"""Get a text description of available tools.
+
+        Returns:
+            str: Text description of tools
+        """
+        if not self.is_connected():
+            return "Client not connected"
+
+        if not self._tools:
+            return "No tools available"
+
+        tool_descriptions = []
+        for tool in self._tools:
+            desc = tool.description or 'No description'
+            description = f"- {tool.name}: {desc}"
+            tool_descriptions.append(description)
+
+        return "\n".join(tool_descriptions)
+
+    async def call_tool(
+        self, tool_name: str, arguments: Dict[str, Any]
+    ) -> Any:
+        r"""Call a tool by name with the provided arguments.
+
+        Executes a specific tool on the connected MCP server with the given
+        arguments. The tool must be available in the server's tool list.
+
+        Args:
+            tool_name (str): The name of the tool to call. Must match a tool
+                name returned by :obj:`get_tools()`.
+            arguments (Dict[str, Any]): A dictionary of arguments to pass to
+                the tool. The argument names and types must match the tool's
+                expected parameters.
+
+        Returns:
+            Any: The result returned by the tool execution. The type and
+                structure depend on the specific tool being called.
+
+        Raises:
+            RuntimeError: If the client is not connected to an MCP server.
+            ValueError: If the specified tool name is not found in the list
+                of available tools.
+
+        Example:
+            .. code-block:: python
+
+                # Call a file reading tool
+                result = await client.call_tool(
+                    "read_file",
+                    {"path": "/tmp/example.txt"}
+                )
+        """
+        if not self.is_connected():
+            raise RuntimeError("Client is not connected")
+
+        # Check if tool exists
+        tool_names = [tool.name for tool in self._tools]
+        if tool_name not in tool_names:
+            available_tools = ', '.join(tool_names)
+            raise ValueError(
+                f"Tool '{tool_name}' not found. "
+                f"Available tools: {available_tools}"
+            )
+
+        # Call the tool using the correct API
+        if self._session is None:
+            raise RuntimeError("Client session is not available")
+
+        result = await self._session.call_tool(
+            name=tool_name, arguments=arguments
+        )
+
+        return result
+
+    def call_tool_sync(self, tool_name: str, arguments: Dict[str, Any]) -> Any:
+        r"""Synchronously call a tool by name with the provided arguments.
+
+        Args:
+            tool_name (str): The name of the tool to call.
+            arguments (Dict[str, Any]): A dictionary of arguments to pass to
+                the tool.
+
+        Returns:
+            Any: The result returned by the tool execution.
+        """
+        from camel.utils.commons import run_async
+
+        return run_async(self.call_tool)(tool_name, arguments)
+
+
+def create_mcp_client(
+    config: Union[Dict[str, Any], ServerConfig], **kwargs: Any
+) -> MCPClient:
+    r"""Create an MCP client from configuration.
+
+    Factory function that creates an :obj:`MCPClient` instance from various
+    configuration formats. This is the recommended way to create MCP clients
+    as it handles configuration validation and type conversion automatically.
+
+    Args:
+        config (Union[Dict[str, Any], ServerConfig]): Server configuration
+            as either a dictionary or a :obj:`ServerConfig` object. If a
+            dictionary is provided, it will be automatically converted to
+            a :obj:`ServerConfig`.
+        **kwargs: Additional keyword arguments passed to the :obj:`MCPClient`
+            constructor, such as :obj:`client_info`, :obj:`timeout`, and
+            :obj:`strict`.
+
+    Returns:
+        MCPClient: A configured :obj:`MCPClient` instance ready for use as
+            an async context manager.
+
+    Examples:
+        STDIO server:
+
+        .. code-block:: python
+
+            async with create_mcp_client({
+                "command": "npx",
+                "args": [
+                    "-y",
+                    "@modelcontextprotocol/server-filesystem",
+                    "/path",
+                ],
+            }) as client:
+                tools = client.get_tools()
+
+        HTTP server:
+
+        .. code-block:: python
+
+            async with create_mcp_client({
+                "url": "https://api.example.com/mcp",
+                "headers": {"Authorization": "Bearer token"}
+            }) as client:
+                result = await client.call_tool("tool_name", {"arg": "value"})
+
+        WebSocket server:
+
+        .. code-block:: python
+
+            async with create_mcp_client({
+                "url": "ws://localhost:8080/mcp"
+            }) as client:
+                tools = client.get_tools()
+
+        With strict mode enabled:
+
+        .. code-block:: python
+
+            async with create_mcp_client({
+                "command": "npx",
+                "args": [
+                    "-y",
+                    "@modelcontextprotocol/server-filesystem",
+                    "/path",
+                ],
+            }, strict=True) as client:
+                tools = client.get_tools()
+    """
+    return MCPClient(config, **kwargs)
+
+
+def create_mcp_client_from_config_file(
+    config_path: Union[str, Path], server_name: str, **kwargs: Any
+) -> MCPClient:
+    r"""Create an MCP client from a configuration file.
+
+    Args:
+        config_path (Union[str, Path]): Path to configuration file (JSON).
+        server_name (str): Name of the server in the config.
+        **kwargs: Additional arguments passed to MCPClient constructor.
+
+    Returns:
+        MCPClient: MCPClient instance as an async context manager.
+    Example config file:
+        {
+          "mcpServers": {
+            "filesystem": {
+              "command": "npx",
+              "args": [
+                "-y",
+                "@modelcontextprotocol/server-filesystem",
+                "/path"
+              ]
+            },
+            "remote-server": {
+              "url": "https://api.example.com/mcp",
+              "headers": {"Authorization": "Bearer token"}
+            }
+          }
+        }
+
+    Usage:
+        .. code-block:: python
+
+            async with create_mcp_client_from_config_file(
+                "config.json", "filesystem"
+            ) as client:
+                tools = client.get_tools()
+    """
+    import json
+
+    config_path = Path(config_path)
+    with open(config_path, 'r') as f:
+        config_data = json.load(f)
+
+    servers = config_data.get("mcpServers", {})
+    if server_name not in servers:
+        available = list(servers.keys())
+        raise ValueError(
+            f"Server '{server_name}' not found in config. "
+            f"Available: {available}"
+        )
+
+    server_config = servers[server_name]
+    return create_mcp_client(server_config, **kwargs)