🐫 CAMEL: The first and the best multi-agent framework. Finding the Scaling Law of Agents. https://www.camel-ai.org
Python agentai-societiesartificial-intelligencecommunicative-aicooperative-aideep-learninglarge-language-modelsmulti-agent-systemsnatural-language-processing
refactor: improve mcp toolkit module (#2496)
Xiaotian Jinfcb2c552706a
diff --git a/camel/agents/mcp_agent.py b/camel/agents/mcp_agent.pyindex 780950e15..c1d13c45c 100644--- a/camel/agents/mcp_agent.py+++ b/camel/agents/mcp_agent.py@@ -191,7 +191,7 @@ class MCPAgent(ChatAgent):self.mcp_toolkit = self._initialize_mcp_toolkit()# If already connected, reconnect to apply changes- if self.mcp_toolkit and self.mcp_toolkit.is_connected():+ if self.mcp_toolkit and self.mcp_toolkit.is_connected:try:asyncio.run(self.disconnect())asyncio.run(self.connect())@@ -325,7 +325,7 @@ class MCPAgent(ChatAgent):Returns:ChatAgentResponse: The response from the agent."""- if self.mcp_toolkit and not self.mcp_toolkit.is_connected():+ if self.mcp_toolkit and not self.mcp_toolkit.is_connected:await self.connect()if self.function_calling_available:@@ -378,14 +378,14 @@ class MCPAgent(ChatAgent):if (not isinstance(server_idx, int)or server_idx < 0- or server_idx >= len(self.mcp_toolkit.servers)+ or server_idx >= len(self.mcp_toolkit.clients)):logger.warning(f"Invalid server index: {server_idx}")continue- server = self.mcp_toolkit.servers[server_idx]+ server = self.mcp_toolkit.clients[server_idx]result = await server.call_tool(tool_name, tool_args)# Safely access contentdiff --git a/camel/toolkits/mcp_toolkit.py b/camel/toolkits/mcp_toolkit.pyindex 8a46cb1c5..d2228264a 100644--- a/camel/toolkits/mcp_toolkit.py+++ b/camel/toolkits/mcp_toolkit.py@@ -11,868 +11,604 @@# See the License for the specific language governing permissions and# limitations under the License.# ========= Copyright 2023-2024 @ CAMEL-AI.org. All Rights Reserved. =========-import inspect+import jsonimport os-import shlex-from contextlib import AsyncExitStack, asynccontextmanager-from datetime import timedelta-from typing import (- TYPE_CHECKING,- Any,- AsyncGenerator,- Callable,- Dict,- List,- Optional,- Set,- Union,- cast,-)-from urllib.parse import urlparse--if TYPE_CHECKING:- from mcp import ClientSession, ListToolsResult, Tool-+from contextlib import AsyncExitStack+from typing import Any, Dict, List, Optionalfrom camel.logger import get_loggerfrom camel.toolkits import BaseToolkit, FunctionToolfrom camel.utils.commons import run_async+from camel.utils.mcp_client import MCPClient, create_mcp_clientlogger = get_logger(__name__)-class MCPClient(BaseToolkit):- r"""Internal class that provides an abstraction layer to interact with- external tools using the Model Context Protocol (MCP). It supports three- modes of connection:+class MCPConnectionError(Exception):+ r"""Raised when MCP connection fails."""++ pass- 1. stdio mode: Connects via standard input/output streams for local- command-line interactions.- 2. SSE mode (HTTP Server-Sent Events): Connects via HTTP for persistent,- event-based interactions.+class MCPToolError(Exception):+ r"""Raised when MCP tool execution fails."""- 3. streamable-http mode: Connects via HTTP for persistent, streamable- interactions.+ pass+++class MCPToolkit(BaseToolkit):+ r"""MCPToolkit provides a unified interface for managing multiple+ MCP server connections and their tools.++ This class handles the lifecycle of multiple MCP server connections and+ offers a centralized configuration mechanism for both local and remote+ MCP services. The toolkit manages multiple :obj:`MCPClient` instances and+ aggregates their tools into a unified interface compatible with the CAMEL+ framework.Connection Lifecycle:There are three ways to manage the connection lifecycle:- 1. Using the async context manager:- ```python- async with MCPClient(command_or_url="...") as client:- # Client is connected here- result = await client.some_tool()- # Client is automatically disconnected here- ```+ 1. Using the async context manager (recommended):++ .. code-block:: python++ async with MCPToolkit(config_path="config.json") as toolkit:+ # Toolkit is connected here+ tools = toolkit.get_tools()+ # Toolkit is automatically disconnected here2. Using the factory method:- ```python- client = await MCPClient.create(command_or_url="...")- # Client is connected here- result = await client.some_tool()- # Don't forget to disconnect when done!- await client.disconnect()- ```++ .. code-block:: python++ toolkit = await MCPToolkit.create(config_path="config.json")+ # Toolkit is connected here+ tools = toolkit.get_tools()+ # Don't forget to disconnect when done!+ await toolkit.disconnect()3. Using explicit connect/disconnect:- ```python- client = MCPClient(command_or_url="...")- await client.connect()- # Client is connected here- result = await client.some_tool()- # Don't forget to disconnect when done!- await client.disconnect()- ```- Attributes:- command_or_url (str): URL for SSE mode or command executable for stdio- mode. (default: :obj:`None`)- args (List[str]): List of command-line arguments if stdio mode is used.- (default: :obj:`None`)- env (Dict[str, str]): Environment variables for the stdio mode command.- (default: :obj:`None`)- timeout (Optional[float]): Connection timeout.- (default: :obj:`None`)- headers (Dict[str, str]): Headers for the HTTP request.+ .. code-block:: python++ toolkit = MCPToolkit(config_path="config.json")+ await toolkit.connect()+ # Toolkit is connected here+ tools = toolkit.get_tools()+ # Don't forget to disconnect when done!+ await toolkit.disconnect()++ Note:+ Both MCPClient and MCPToolkit now use the same async context manager+ pattern for consistent connection management. MCPToolkit automatically+ manages multiple MCPClient instances using AsyncExitStack.++ Args:+ clients (Optional[List[MCPClient]], optional): List of :obj:`MCPClient`+ instances to manage. (default: :obj:`None`)+ config_path (Optional[str], optional): Path to a JSON configuration+ file defining MCP servers. The file should contain server+ configurations in the standard MCP format. (default: :obj:`None`)+ config_dict (Optional[Dict[str, Any]], optional): Dictionary containing+ MCP server configurations in the same format as the config file.+ This allows for programmatic configuration without file I/O.(default: :obj:`None`)- mode (Optional[str]): Connection mode. Can be "sse" for Server-Sent- Events, "streamable-http" for streaming HTTP,- or None for stdio mode.+ timeout (Optional[float], optional): Timeout for connection attempts+ in seconds. This timeout applies to individual client connections.(default: :obj:`None`)- strict (Optional[bool]): Whether to enforce strict mode for the- function call. (default: :obj:`False`)++ Note:+ At least one of :obj:`clients`, :obj:`config_path`, or+ :obj:`config_dict` must be provided. If multiple sources are provided,+ clients from all sources will be combined.++ For web servers in the config, you can specify authorization headers+ using the "headers" field to connect to protected MCP server endpoints.++ Example configuration:++ .. code-block:: json++ {+ "mcpServers": {+ "filesystem": {+ "command": "npx",+ "args": ["-y", "@modelcontextprotocol/server-filesystem",+ "/path"]+ },+ "protected-server": {+ "url": "https://example.com/mcp",+ "timeout": 30,+ "headers": {+ "Authorization": "Bearer YOUR_TOKEN",+ "X-API-Key": "YOUR_API_KEY"+ }+ }+ }+ }++ Attributes:+ clients (List[MCPClient]): List of :obj:`MCPClient` instances being+ managed by this toolkit.++ Raises:+ ValueError: If no configuration sources are provided or if the+ configuration is invalid.+ MCPConnectionError: If connection to any MCP server fails during+ initialization."""def __init__(self,- command_or_url: str,- args: Optional[List[str]] = None,- env: Optional[Dict[str, str]] = None,+ clients: Optional[List[MCPClient]] = None,+ config_path: Optional[str] = None,+ config_dict: Optional[Dict[str, Any]] = None,timeout: Optional[float] = None,- headers: Optional[Dict[str, str]] = None,- mode: Optional[str] = None,- strict: Optional[bool] = False,):- from mcp import Tool-+ # Call parent constructor firstsuper().__init__(timeout=timeout)- self.command_or_url = command_or_url- self.args = args or []- self.env = env or {}- self.headers = headers or {}- self.strict = strict- self.mode = mode+ # Validate input parameters+ sources_provided = sum(+ 1 for src in [clients, config_path, config_dict] if src is not None+ )+ if sources_provided == 0:+ error_msg = (+ "At least one of clients, config_path, or "+ "config_dict must be provided"+ )+ raise ValueError(error_msg)- self._mcp_tools: List[Tool] = []- self._session: Optional['ClientSession'] = None- self._exit_stack = AsyncExitStack()+ self.clients: List[MCPClient] = clients or []self._is_connected = False+ self._exit_stack: Optional[AsyncExitStack] = None- async def connect(self):- r"""Explicitly connect to the MCP server.-- Returns:- MCPClient: The client used to connect to the server.- """- from mcp.client.session import ClientSession- from mcp.client.sse import sse_client- from mcp.client.stdio import StdioServerParameters, stdio_client- from mcp.client.streamable_http import streamablehttp_client+ # Load clients from config sources+ if config_path:+ self.clients.extend(self._load_clients_from_config(config_path))- if self._is_connected:- logger.warning("Server is already connected")- return self+ if config_dict:+ self.clients.extend(self._load_clients_from_dict(config_dict))- try:- if urlparse(self.command_or_url).scheme in ("http", "https"):- if self.mode == "sse" or self.mode is None:- (- read_stream,- write_stream,- ) = await self._exit_stack.enter_async_context(- sse_client(- self.command_or_url,- headers=self.headers,- timeout=self.timeout,- )- )- elif self.mode == "streamable-http":- try:- (- read_stream,- write_stream,- _,- ) = await self._exit_stack.enter_async_context(- streamablehttp_client(- self.command_or_url,- headers=self.headers,- timeout=timedelta(seconds=self.timeout),- )- )- except Exception as e:- # Handle anyio task group errors- logger.error(f"Streamable HTTP client error: {e}")- else:- raise ValueError(- f"Invalid mode '{self.mode}' for HTTP URL"- )- else:- command = self.command_or_url- arguments = self.args- if not self.args:- argv = shlex.split(command)- if not argv:- raise ValueError("Command is empty")-- command = argv[0]- arguments = argv[1:]-- if os.name == "nt" and command.lower() == "npx":- command = "npx.cmd"-- server_parameters = StdioServerParameters(- command=command, args=arguments, env=self.env- )- (- read_stream,- write_stream,- ) = await self._exit_stack.enter_async_context(- stdio_client(server_parameters)- )+ if not self.clients:+ raise ValueError("No valid MCP clients could be created")- self._session = await self._exit_stack.enter_async_context(- ClientSession(- read_stream,- write_stream,- timedelta(seconds=self.timeout) if self.timeout else None,- )- )- await self._session.initialize()- list_tools_result = await self.list_mcp_tools()- self._mcp_tools = list_tools_result.tools- self._is_connected = True- return self- except Exception as e:- # Ensure resources are cleaned up on connection failure- await self.disconnect()- logger.error(f"Failed to connect to MCP server: {e}")- raise e+ async def connect(self) -> "MCPToolkit":+ r"""Connect to all MCP servers using AsyncExitStack.- def connect_sync(self):- r"""Synchronously connect to the MCP server."""- return run_async(self.connect)()+ Establishes connections to all configured MCP servers sequentially.+ Uses :obj:`AsyncExitStack` to manage the lifecycle of all connections,+ ensuring proper cleanup on exit or error.- async def disconnect(self):- r"""Explicitly disconnect from the MCP server."""- # If the server is not connected, do nothing- if not self._is_connected:- return- self._is_connected = False+ Returns:+ MCPToolkit: Returns :obj:`self` for method chaining, allowing for+ fluent interface usage.- try:- await self._exit_stack.aclose()- except Exception as e:- logger.warning(f"{e}")- finally:- self._exit_stack = AsyncExitStack()- self._session = None+ Raises:+ MCPConnectionError: If connection to any MCP server fails. The+ error message will include details about which client failed+ to connect and the underlying error reason.- def disconnect_sync(self):- r"""Synchronously disconnect from the MCP server."""- return run_async(self.disconnect)()+ Warning:+ If any client fails to connect, all previously established+ connections will be automatically cleaned up before raising+ the exception.- @asynccontextmanager- async def connection(self):- r"""Async context manager for establishing and managing the connection- with the MCP server. Automatically selects SSE or stdio mode based- on the provided `command_or_url`.+ Example:+ .. code-block:: python- Yields:- MCPClient: Instance with active connection ready for tool- interaction.+ toolkit = MCPToolkit(config_dict=config)+ try:+ await toolkit.connect()+ # Use the toolkit+ tools = toolkit.get_tools()+ finally:+ await toolkit.disconnect()"""- try:- await self.connect()- yield self- finally:- try:- await self.disconnect()- except Exception as e:- logger.warning(f"Error: {e}")-- def connection_sync(self):- r"""Synchronously connect to the MCP server."""- return run_async(self.connection)()+ if self._is_connected:+ logger.warning("MCPToolkit is already connected")+ return self- async def list_mcp_tools(self) -> Union[str, "ListToolsResult"]:- r"""Retrieves the list of available tools from the connected MCP- server.+ self._exit_stack = AsyncExitStack()- 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:- logger.exception("Failed to list MCP tools")- raise e-- def list_mcp_tools_sync(self) -> Union[str, "ListToolsResult"]:- r"""Synchronously list the available tools from the connected MCP- server."""- return run_async(self.list_mcp_tools)()-- def generate_function_from_mcp_tool(self, mcp_tool: "Tool") -> Callable:- r"""Dynamically generates a Python callable function corresponding to- a given MCP tool.+ # Connect to all clients using AsyncExitStack+ for i, client in enumerate(self.clients):+ try:+ # Use MCPClient directly as async context manager+ await self._exit_stack.enter_async_context(client)+ msg = f"Connected to client {i+1}/{len(self.clients)}"+ logger.debug(msg)+ except Exception as e:+ logger.error(f"Failed to connect to client {i+1}: {e}")+ # AsyncExitStack will handle cleanup of already connected+ await self._exit_stack.aclose()+ self._exit_stack = None+ error_msg = f"Failed to connect to client {i+1}: {e}"+ raise MCPConnectionError(error_msg) from e- Args:- mcp_tool (Tool): The MCP tool definition received from the MCP- server.+ self._is_connected = True+ msg = f"Successfully connected to {len(self.clients)} MCP servers"+ logger.info(msg)+ return self- 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.- """- from mcp.types import CallToolResult-- missing_params: Set[str] = set(required_params) - set(- kwargs.keys()- )- if missing_params:- logger.warning(- f"Missing required parameters: {missing_params}"- )- return "Missing required parameters."+ except Exception:+ self._is_connected = False+ if self._exit_stack:+ await self._exit_stack.aclose()+ self._exit_stack = None+ raise- if not self._session:- logger.error(- "MCP Client is not connected. Call `connection()` first."- )- raise RuntimeError(- "MCP Client is not connected. Call `connection()` first."- )+ async def disconnect(self):+ r"""Disconnect from all MCP servers."""+ if not self._is_connected:+ return+ if self._exit_stack:try:- result: CallToolResult = await self._session.call_tool(- func_name, kwargs- )+ await self._exit_stack.aclose()except Exception as e:- logger.error(f"Failed to call MCP tool '{func_name}': {e!s}")- raise e+ logger.warning(f"Error during disconnect: {e}")+ finally:+ self._exit_stack = None- 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:- 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 generate_function_from_mcp_tool_sync(self, mcp_tool: "Tool") -> Any:- r"""Synchronously generate a function from an MCP tool."""- return run_async(self.generate_function_from_mcp_tool)(mcp_tool)-- def _build_tool_schema(self, mcp_tool: "Tool") -> Dict[str, Any]:- 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,- },- }+ self._is_connected = False+ logger.debug("Disconnected from all MCP servers")- def get_tools(self) -> List[FunctionTool]:- r"""Returns a list of FunctionTool objects representing the- functions in the toolkit. Each function is dynamically generated- based on the MCP tool definitions received from the server.+ @property+ def is_connected(self) -> bool:+ r"""Check if toolkit is connected.Returns:- List[FunctionTool]: A list of FunctionTool objects- representing the functions in the toolkit.+ bool: True if the toolkit is connected to all MCP servers,+ False otherwise."""- return [- FunctionTool(- self.generate_function_from_mcp_tool(mcp_tool),- openai_tool_schema=self._build_tool_schema(mcp_tool),- )- for mcp_tool in self._mcp_tools- ]+ if not self._is_connected:+ return False- def get_text_tools(self) -> str:- r"""Returns a string containing the descriptions of the tools- in the toolkit.+ # Check if all clients are connected+ return all(client.is_connected() for client in self.clients)- Returns:- str: A string containing the descriptions of the tools- in the toolkit.- """- return "\n".join(- f"tool_name: {tool.name}\n"- + f"description: {tool.description or 'No description'}\n"- + f"input Schema: {tool.inputSchema}\n"- for tool in self._mcp_tools- )+ def connect_sync(self):+ r"""Synchronously connect to all MCP servers."""+ return run_async(self.connect)()- async def call_tool(- self, tool_name: str, tool_args: Dict[str, Any]- ) -> Any:- r"""Calls the specified tool with the provided arguments.+ def disconnect_sync(self):+ r"""Synchronously disconnect from all MCP servers."""+ return run_async(self.disconnect)()- Args:- tool_name (str): Name of the tool to call.- tool_args (Dict[str, Any]): Arguments to pass to the tool- (default: :obj:`{}`).+ async def __aenter__(self) -> "MCPToolkit":+ r"""Async context manager entry point.- Returns:- Any: The result of the tool call.+ Usage:+ async with MCPToolkit(config_dict=config) as toolkit:+ tools = toolkit.get_tools()"""- if self._session is None:- raise RuntimeError("Session is not initialized.")+ await self.connect()+ return self- return await self._session.call_tool(tool_name, tool_args)+ def __enter__(self) -> "MCPToolkit":+ r"""Synchronously enter the async context manager."""+ return run_async(self.__aenter__)()- def call_tool_sync(self, tool_name: str, tool_args: Dict[str, Any]) -> Any:- r"""Synchronously call a tool."""- return run_async(self.call_tool)(tool_name, tool_args)+ async def __aexit__(self, exc_type, exc_val, exc_tb) -> None:+ r"""Async context manager exit point."""+ await self.disconnect()+ return None- @property- def session(self) -> Optional["ClientSession"]:- return self._session+ def __exit__(self, exc_type, exc_val, exc_tb) -> None:+ r"""Synchronously exit the async context manager."""+ return run_async(self.__aexit__)(exc_type, exc_val, exc_tb)@classmethodasync def create(cls,- command_or_url: str,- args: Optional[List[str]] = None,- env: Optional[Dict[str, str]] = None,+ clients: Optional[List[MCPClient]] = None,+ config_path: Optional[str] = None,+ config_dict: Optional[Dict[str, Any]] = None,timeout: Optional[float] = None,- headers: Optional[Dict[str, str]] = None,- mode: Optional[str] = None,- ) -> "MCPClient":- r"""Factory method that creates and connects to the MCP server.+ ) -> "MCPToolkit":+ r"""Factory method that creates and connects to all MCP servers.- This async factory method ensures the connection to the MCP server is- established before the client object is fully constructed.+ Creates a new :obj:`MCPToolkit` instance and automatically establishes+ connections to all configured MCP servers. This is a convenience method+ that combines instantiation and connection in a single call.Args:- command_or_url (str): URL for SSE mode or command executable- for stdio mode.- args (Optional[List[str]]): List of command-line arguments if- stdio mode is used. (default: :obj:`None`)- env (Optional[Dict[str, str]]): Environment variables for- the stdio mode command. (default: :obj:`None`)- timeout (Optional[float]): Connection timeout.- (default: :obj:`None`)- headers (Optional[Dict[str, str]]): Headers for the HTTP request.- (default: :obj:`None`)- mode (Optional[str]): Connection mode. Can be "sse" for- Server-Sent Events, "streamable-http" for- streaming HTTP, or None for stdio mode.- (default: :obj:`None`)+ clients (Optional[List[MCPClient]], optional): List of+ :obj:`MCPClient` instances to manage. (default: :obj:`None`)+ config_path (Optional[str], optional): Path to a JSON configuration+ file defining MCP servers. (default: :obj:`None`)+ config_dict (Optional[Dict[str, Any]], optional): Dictionary+ containing MCP server configurations in the same format as the+ config file. (default: :obj:`None`)+ timeout (Optional[float], optional): Timeout for connection+ attempts in seconds. (default: :obj:`None`)Returns:- MCPClient: A fully initialized and connected MCPClient instance.+ MCPToolkit: A fully initialized and connected :obj:`MCPToolkit`+ instance with all servers ready for use.Raises:- RuntimeError: If connection to the MCP server fails.+ MCPConnectionError: If connection to any MCP server fails during+ initialization. All successfully connected servers will be+ properly disconnected before raising the exception.+ ValueError: If no configuration sources are provided or if the+ configuration is invalid.++ Example:+ .. code-block:: python++ # Create and connect in one step+ toolkit = await MCPToolkit.create(config_path="servers.json")+ try:+ tools = toolkit.get_tools()+ # Use the toolkit...+ finally:+ await toolkit.disconnect()"""- client = cls(- command_or_url=command_or_url,- args=args,- env=env,+ toolkit = cls(+ clients=clients,+ config_path=config_path,+ config_dict=config_dict,timeout=timeout,- headers=headers,- mode=mode,)try:- await client.connect()- return client+ await toolkit.connect()+ return toolkitexcept Exception as e:# Ensure cleanup on initialization failure- await client.disconnect()- logger.error(f"Failed to initialize MCPClient: {e}")- raise RuntimeError(f"Failed to initialize MCPClient: {e}") from e+ await toolkit.disconnect()+ logger.error(f"Failed to initialize MCPToolkit: {e}")+ raise MCPConnectionError(+ f"Failed to initialize MCPToolkit: {e}"+ ) from e@classmethoddef create_sync(- self,- command_or_url: str,- args: Optional[List[str]] = None,- env: Optional[Dict[str, str]] = None,+ cls,+ clients: Optional[List[MCPClient]] = None,+ config_path: Optional[str] = None,+ config_dict: Optional[Dict[str, Any]] = None,timeout: Optional[float] = None,- headers: Optional[Dict[str, str]] = None,- mode: Optional[str] = None,- ) -> "MCPClient":- r"""Synchronously create and connect to the MCP server."""- return run_async(self.create)(- command_or_url, args, env, timeout, headers, mode+ ) -> "MCPToolkit":+ r"""Synchronously create and connect to all MCP servers."""+ return run_async(cls.create)(+ clients, config_path, config_dict, timeout)- async def __aenter__(self) -> "MCPClient":- r"""Async context manager entry point. Automatically connects to the- MCP server when used in an async with statement.+ def _load_clients_from_config(self, config_path: str) -> List[MCPClient]:+ r"""Load clients from configuration file."""+ if not os.path.exists(config_path):+ raise FileNotFoundError(f"Config file not found: '{config_path}'")- Returns:- MCPClient: Self with active connection.- """- await self.connect()- return self-- def __enter__(self) -> "MCPClient":- r"""Synchronously enter the async context manager."""- return run_async(self.__aenter__)()-- async def __aexit__(self) -> None:- r"""Async context manager exit point. Automatically disconnects from- the MCP server when exiting an async with statement.-- Returns:- None- """- await self.disconnect()-- def __exit__(self, exc_type, exc_val, exc_tb) -> None:- r"""Synchronously exit the async context manager.-- Args:- exc_type (Optional[Type[Exception]]): The type of exception that- occurred during the execution of the with statement.- exc_val (Optional[Exception]): The exception that occurred during- the execution of the with statement.- exc_tb (Optional[TracebackType]): The traceback of the exception- that occurred during the execution of the with statement.-- Returns:- None- """- return run_async(self.__aexit__)()---class MCPToolkit(BaseToolkit):- r"""MCPToolkit provides a unified interface for managing multiple- MCP server connections and their tools.-- This class handles the lifecycle of multiple MCP server connections and- offers a centralized configuration mechanism for both local and remote- MCP services.-- Connection Lifecycle:- There are three ways to manage the connection lifecycle:-- 1. Using the async context manager:- ```python- async with MCPToolkit(config_path="config.json") as toolkit:- # Toolkit is connected here- tools = toolkit.get_tools()- # Toolkit is automatically disconnected here- ```-- 2. Using the factory method:- ```python- toolkit = await MCPToolkit.create(config_path="config.json")- # Toolkit is connected here- tools = toolkit.get_tools()- # Don't forget to disconnect when done!- await toolkit.disconnect()- ```-- 3. Using explicit connect/disconnect:- ```python- toolkit = MCPToolkit(config_path="config.json")- await toolkit.connect()- # Toolkit is connected here- tools = toolkit.get_tools()- # Don't forget to disconnect when done!- await toolkit.disconnect()- ```-- Args:- servers (Optional[List[MCPClient]]): List of MCPClient- instances to manage. (default: :obj:`None`)- config_path (Optional[str]): Path to a JSON configuration file- defining MCP servers. (default: :obj:`None`)- config_dict (Optional[Dict[str, Any]]): Dictionary containing MCP- server configurations in the same format as the config file.- (default: :obj:`None`)- strict (Optional[bool]): Whether to enforce strict mode for the- function call. (default: :obj:`False`)-- Note:- Either `servers`, `config_path`, or `config_dict` must be provided.- If multiple are provided, servers from all sources will be combined.-- For web servers in the config, you can specify authorization- headers using the "headers" field to connect to protected MCP server- endpoints.-- Example configuration:-- .. code-block:: json-- {- "mcpServers": {- "protected-server": {- "url": "https://example.com/mcp",- "timeout": 30,- "headers": {- "Authorization": "Bearer YOUR_TOKEN",- "X-API-Key": "YOUR_API_KEY"- }- }- }- }-- Attributes:- servers (List[MCPClient]): List of MCPClient instances being managed.- """+ try:+ with open(config_path, "r", encoding="utf-8") as f:+ data = json.load(f)+ except json.JSONDecodeError as e:+ error_msg = f"Invalid JSON in config file '{config_path}': {e}"+ raise ValueError(error_msg) from e+ except Exception as e:+ error_msg = f"Error reading config file '{config_path}': {e}"+ raise IOError(error_msg) from e- def __init__(- self,- servers: Optional[List[MCPClient]] = None,- config_path: Optional[str] = None,- config_dict: Optional[Dict[str, Any]] = None,- strict: Optional[bool] = False,- ):- super().__init__()+ return self._load_clients_from_dict(data)- sources_provided = sum(- 1 for src in [servers, config_path, config_dict] if src is not None- )- if sources_provided > 1:- logger.warning(- "Multiple configuration sources provided "- f"({sources_provided}). Servers from all sources "- "will be combined."- )+ def _load_clients_from_dict(+ self, config: Dict[str, Any]+ ) -> List[MCPClient]:+ r"""Load clients from configuration dictionary."""+ if not isinstance(config, dict):+ raise ValueError("Config must be a dictionary")- self.servers: List[MCPClient] = servers or []+ mcp_servers = config.get("mcpServers", {})+ if not isinstance(mcp_servers, dict):+ raise ValueError("'mcpServers' must be a dictionary")- if config_path:- self.servers.extend(- self._load_servers_from_config(config_path, strict)- )+ clients = []- if config_dict:- self.servers.extend(self._load_servers_from_dict(config_dict))+ for name, cfg in mcp_servers.items():+ try:+ if "timeout" not in cfg and self.timeout is not None:+ cfg["timeout"] = self.timeout- self._connected = False+ client = self._create_client_from_config(name, cfg)+ clients.append(client)+ except Exception as e:+ logger.error(f"Failed to create client for '{name}': {e}")+ error_msg = f"Invalid configuration for server '{name}': {e}"+ raise ValueError(error_msg) from e- def _load_servers_from_config(- self, config_path: str, strict: Optional[bool] = False- ) -> List[MCPClient]:- r"""Loads MCP server configurations from a JSON file.+ return clients- Args:- config_path (str): Path to the JSON configuration file.- strict (bool): Whether to enforce strict mode for the- function call. (default: :obj:`False`)+ def _create_client_from_config(+ self, name: str, cfg: Dict[str, Any]+ ) -> MCPClient:+ r"""Create a single MCP client from configuration."""+ if not isinstance(cfg, dict):+ error_msg = f"Configuration for server '{name}' must be a dict"+ raise ValueError(error_msg)- Returns:- List[MCPClient]: List of configured MCPClient instances.- """try:- with open(config_path, "r", encoding="utf-8") as f:- try:- data = json.load(f)- except json.JSONDecodeError as e:- logger.warning(- f"Invalid JSON in config file '{config_path}': {e!s}"- )- raise e- except FileNotFoundError as e:- logger.warning(f"Config file not found: '{config_path}'")- raise e+ # Use the new mcp_client factory function+ # Pass timeout from toolkit if available+ kwargs = {}+ if hasattr(self, "timeout") and self.timeout is not None:+ kwargs["timeout"] = self.timeout- return self._load_servers_from_dict(config=data, strict=strict)+ client = create_mcp_client(cfg, **kwargs)+ return client+ except Exception as e:+ error_msg = f"Failed to create client for server '{name}': {e}"+ raise ValueError(error_msg) from e- def _load_servers_from_dict(- self, config: Dict[str, Any], strict: Optional[bool] = False- ) -> List[MCPClient]:- r"""Loads MCP server configurations from a dictionary.+ def get_tools(self) -> List[FunctionTool]:+ r"""Aggregates all tools from the managed MCP client instances.- Args:- config (Dict[str, Any]): Dictionary containing server- configurations.- strict (bool): Whether to enforce strict mode for the- function call. (default: :obj:`False`)+ Collects and combines tools from all connected MCP clients into a+ single unified list. Each tool is converted to a CAMEL-compatible+ :obj:`FunctionTool` that can be used with CAMEL agents.Returns:- List[MCPClient]: List of configured MCPClient instances.+ List[FunctionTool]: Combined list of all available function tools+ from all connected MCP servers. Returns an empty list if no+ clients are connected or if no tools are available.++ Note:+ This method can be called even when the toolkit is not connected,+ but it will log a warning and may return incomplete results.+ For best results, ensure the toolkit is connected before calling+ this method.++ Example:+ .. code-block:: python++ async with MCPToolkit(config_dict=config) as toolkit:+ tools = toolkit.get_tools()+ print(f"Available tools: {len(tools)}")+ for tool in tools:+ print(f" - {tool.func.__name__}")"""- all_servers = []-- mcp_servers = config.get("mcpServers", {})- if not isinstance(mcp_servers, dict):- logger.warning("'mcpServers' is not a dictionary, skipping...")- mcp_servers = {}-- for name, cfg in mcp_servers.items():- if not isinstance(cfg, dict):- logger.warning(- f"Configuration for server '{name}' must be a dictionary"- )- continue+ if not self.is_connected:+ logger.warning(+ "MCPToolkit is not connected. "+ "Tools may not be available until connected."+ )- if "command" not in cfg and "url" not in cfg:- logger.warning(- f"Missing required 'command' or 'url' field for server "- f"'{name}'"+ all_tools = []+ for i, client in enumerate(self.clients):+ try:+ client_tools = client.get_tools()+ all_tools.extend(client_tools)+ logger.debug(+ f"Client {i+1} contributed {len(client_tools)} tools")- continue-- # Include headers if provided in the configuration- headers = cfg.get("headers", {})-- cmd_or_url = cast(str, cfg.get("command") or cfg.get("url"))- server = MCPClient(- command_or_url=cmd_or_url,- args=cfg.get("args", []),- env={**os.environ, **cfg.get("env", {})},- timeout=cfg.get("timeout", None),- headers=headers,- mode=cfg.get("mode", None),- strict=strict,- )- all_servers.append(server)+ except Exception as e:+ logger.error(f"Failed to get tools from client {i+1}: {e}")- return all_servers+ logger.info(f"Total tools available: {len(all_tools)}")+ return all_tools- async def connect(self):- r"""Explicitly connect to all MCP servers.+ def get_text_tools(self) -> str:+ r"""Returns a string containing the descriptions of the tools.Returns:- MCPToolkit: The connected toolkit instance+ str: A string containing the descriptions of all tools."""- if self._connected:- logger.warning("MCPToolkit is already connected")- return self+ if not self.is_connected:+ logger.warning(+ "MCPToolkit is not connected. "+ "Tool descriptions may not be available until connected."+ )- try:- # Sequentially connect to each server- for server in self.servers:- await server.connect()- self._connected = True- return self- except Exception as e:- # Ensure resources are cleaned up on connection failure- await self.disconnect()- logger.error(f"Failed to connect to one or more MCP servers: {e}")- raise e+ tool_descriptions = []+ for i, client in enumerate(self.clients):+ try:+ client_tools_text = client.get_text_tools()+ if client_tools_text:+ tool_descriptions.append(+ f"=== Client {i+1} Tools ===\n{client_tools_text}"+ )+ except Exception as e:+ logger.error(+ f"Failed to get tool descriptions from client {i+1}: {e}"+ )- def connect_sync(self):- r"""Synchronously connect to all MCP servers."""- return run_async(self.connect)()+ return "\n\n".join(tool_descriptions)- async def disconnect(self):- r"""Explicitly disconnect from all MCP servers."""- if not self._connected:- return+ async def call_tool(+ self, tool_name: str, tool_args: Dict[str, Any]+ ) -> Any:+ r"""Call a tool by name across all managed clients.- for server in self.servers:- await server.disconnect()- self._connected = False+ Searches for and executes a tool with the specified name across all+ connected MCP clients. The method will try each client in sequence+ until the tool is found and successfully executed.- def disconnect_sync(self):- r"""Synchronously disconnect from all MCP servers."""- return run_async(self.disconnect)()+ Args:+ tool_name (str): Name of the tool to call. Must match a tool name+ available from one of the connected MCP servers.+ tool_args (Dict[str, Any]): Arguments to pass to the tool. The+ argument names and types must match the tool's expected+ parameters.- @asynccontextmanager- async def connection(self) -> AsyncGenerator["MCPToolkit", None]:- r"""Async context manager that simultaneously establishes connections- to all managed MCP server instances.+ Returns:+ Any: The result of the tool call. The type and structure depend+ on the specific tool being called.- Yields:- MCPToolkit: Self with all servers connected.+ Raises:+ MCPConnectionError: If the toolkit is not connected to any MCP+ servers.+ MCPToolError: If the tool is not found in any client, or if all+ attempts to call the tool fail. The error message will include+ details about the last failure encountered.++ Example:+ .. code-block:: python++ async with MCPToolkit(config_dict=config) as toolkit:+ # Call a file reading tool+ result = await toolkit.call_tool(+ "read_file",+ {"path": "/tmp/example.txt"}+ )+ print(f"File contents: {result}")"""- try:- await self.connect()- yield self- finally:- await self.disconnect()+ if not self.is_connected:+ raise MCPConnectionError(+ "MCPToolkit is not connected. Call connect() first."+ )- def connection_sync(self):- r"""Synchronously connect to all MCP servers."""- return run_async(self.connection)()+ # Try to find and call the tool from any client+ last_error = None+ for i, client in enumerate(self.clients):+ try:+ # Check if this client has the tool+ tools = client.get_tools()+ tool_names = [tool.func.__name__ for tool in tools]++ if tool_name in tool_names:+ result = await client.call_tool(tool_name, tool_args)+ logger.debug(+ f"Tool '{tool_name}' called successfully "+ f"on client {i+1}"+ )+ return result+ except Exception as e:+ last_error = e+ logger.debug(f"Tool '{tool_name}' failed on client {i+1}: {e}")+ continue- def is_connected(self) -> bool:- r"""Checks if all the managed servers are connected.+ # If we get here, the tool wasn't found or all calls failed+ if last_error:+ raise MCPToolError(+ f"Tool '{tool_name}' failed on all clients. "+ f"Last error: {last_error}"+ ) from last_error+ else:+ raise MCPToolError(f"Tool '{tool_name}' not found in any client")- Returns:- bool: True if connected, False otherwise.- """- return self._connected+ def call_tool_sync(self, tool_name: str, tool_args: Dict[str, Any]) -> Any:+ r"""Synchronously call a tool."""+ return run_async(self.call_tool)(tool_name, tool_args)- def get_tools(self) -> List[FunctionTool]:- r"""Aggregates all tools from the managed MCP server instances.+ def list_available_tools(self) -> Dict[str, List[str]]:+ r"""List all available tools organized by client.Returns:- List[FunctionTool]: Combined list of all available function tools.+ Dict[str, List[str]]: Dictionary mapping client indices to tool+ names."""- all_tools = []- for server in self.servers:- all_tools.extend(server.get_tools())- return all_tools-- def get_text_tools(self) -> str:- r"""Returns a string containing the descriptions of the tools- in the toolkit.+ available_tools = {}+ for i, client in enumerate(self.clients):+ try:+ tools = client.get_tools()+ tool_names = [tool.func.__name__ for tool in tools]+ available_tools[f"client_{i+1}"] = tool_names+ except Exception as e:+ logger.error(f"Failed to list tools from client {i+1}: {e}")+ available_tools[f"client_{i+1}"] = []- Returns:- str: A string containing the descriptions of the tools- in the toolkit.- """- return "\n".join(server.get_text_tools() for server in self.servers)+ return available_toolsdiff --git a/camel/utils/mcp_client.py b/camel/utils/mcp_client.pynew file mode 100644index 000000000..8c8822873--- /dev/null+++ b/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)diff --git a/docs/mintlify/docs.json b/docs/mintlify/docs.jsonindex 952115311..1a7b4c324 100644--- a/docs/mintlify/docs.json+++ b/docs/mintlify/docs.json@@ -552,6 +552,7 @@"reference/camel.utils.deduplication","reference/camel.utils.filename","reference/camel.utils.mcp",+ "reference/camel.utils.mcp_client","reference/camel.utils.response_format","reference/camel.utils.token_counting","reference/camel.utils.chunker.base",diff --git a/docs/mintlify/reference/camel.toolkits.mcp_toolkit.mdx b/docs/mintlify/reference/camel.toolkits.mcp_toolkit.mdxindex 7e3ecb328..bae11f6d6 100644--- a/docs/mintlify/reference/camel.toolkits.mcp_toolkit.mdx+++ b/docs/mintlify/reference/camel.toolkits.mcp_toolkit.mdx@@ -1,233 +1,138 @@<a id="camel.toolkits.mcp_toolkit"></a>-<a id="camel.toolkits.mcp_toolkit.MCPClient"></a>+<a id="camel.toolkits.mcp_toolkit.MCPConnectionError"></a>-## MCPClient+## MCPConnectionError```python-class MCPClient(BaseToolkit):+class MCPConnectionError(Exception):```-Internal class that provides an abstraction layer to interact with-external tools using the Model Context Protocol (MCP). It supports three-modes of connection:+Raised when MCP connection fails.-1. stdio mode: Connects via standard input/output streams for local-command-line interactions.+<a id="camel.toolkits.mcp_toolkit.MCPToolError"></a>-2. SSE mode (HTTP Server-Sent Events): Connects via HTTP for persistent,-event-based interactions.--3. streamable-http mode: Connects via HTTP for persistent, streamable-interactions.--Connection Lifecycle:-There are three ways to manage the connection lifecycle:--1. Using the async context manager:-```python-async with MCPClient(command_or_url="...") as client:-# Client is connected here-result = await client.some_tool()-# Client is automatically disconnected here-```--2. Using the factory method:-```python-client = await MCPClient.create(command_or_url="...")-# Client is connected here-result = await client.some_tool()-# Don't forget to disconnect when done!-await client.disconnect()-```--3. Using explicit connect/disconnect:-```python-client = MCPClient(command_or_url="...")-await client.connect()-# Client is connected here-result = await client.some_tool()-# Don't forget to disconnect when done!-await client.disconnect()-```--Attributes:-command_or_url (str): URL for SSE mode or command executable for stdio-mode. (default: :obj:`None`)-args (List[str]): List of command-line arguments if stdio mode is used.-(default: :obj:`None`)-env (Dict[str, str]): Environment variables for the stdio mode command.-(default: :obj:`None`)-timeout (Optional[float]): Connection timeout.-(default: :obj:`None`)-headers (Dict[str, str]): Headers for the HTTP request.-(default: :obj:`None`)-mode (Optional[str]): Connection mode. Can be "sse" for Server-Sent-Events, "streamable-http" for streaming HTTP,-or None for stdio mode.-(default: :obj:`None`)-strict (Optional[bool]): Whether to enforce strict mode for the-function call. (default: :obj:`False`)--<a id="camel.toolkits.mcp_toolkit.MCPClient.__init__"></a>--### __init__--```python-def __init__(- self,- command_or_url: str,- args: Optional[List[str]] = None,- env: Optional[Dict[str, str]] = None,- timeout: Optional[float] = None,- headers: Optional[Dict[str, str]] = None,- mode: Optional[str] = None,- strict: Optional[bool] = False-):-```--<a id="camel.toolkits.mcp_toolkit.MCPClient.connect_sync"></a>--### connect_sync+## MCPToolError```python-def connect_sync(self):+class MCPToolError(Exception):```-Synchronously connect to the MCP server.+Raised when MCP tool execution fails.-<a id="camel.toolkits.mcp_toolkit.MCPClient.disconnect_sync"></a>+<a id="camel.toolkits.mcp_toolkit.MCPToolkit"></a>-### disconnect_sync+## MCPToolkit```python-def disconnect_sync(self):+class MCPToolkit(BaseToolkit):```-Synchronously disconnect from the MCP server.+MCPToolkit provides a unified interface for managing multiple+MCP server connections and their tools.-<a id="camel.toolkits.mcp_toolkit.MCPClient.connection_sync"></a>+This class handles the lifecycle of multiple MCP server connections and+offers a centralized configuration mechanism for both local and remote+MCP services. The toolkit manages multiple :obj:`MCPClient` instances and+aggregates their tools into a unified interface compatible with the CAMEL+framework.-### connection_sync+Connection Lifecycle:+There are three ways to manage the connection lifecycle:-```python-def connection_sync(self):-```+1. Using the async context manager (recommended):-Synchronously connect to the MCP server.+.. code-block:: python-<a id="camel.toolkits.mcp_toolkit.MCPClient.list_mcp_tools_sync"></a>+async with MCPToolkit(config_path="config.json") as toolkit:+# Toolkit is connected here+tools = toolkit.get_tools()+# Toolkit is automatically disconnected here-### list_mcp_tools_sync+2. Using the factory method:-```python-def list_mcp_tools_sync(self):-```+.. code-block:: python-Synchronously list the available tools from the connected MCP-server.+toolkit = await MCPToolkit.create(config_path="config.json")+# Toolkit is connected here+tools = toolkit.get_tools()+# Don't forget to disconnect when done!+await toolkit.disconnect()-<a id="camel.toolkits.mcp_toolkit.MCPClient.generate_function_from_mcp_tool"></a>+3. Using explicit connect/disconnect:-### generate_function_from_mcp_tool+.. code-block:: python-```python-def generate_function_from_mcp_tool(self, mcp_tool: 'Tool'):-```+toolkit = MCPToolkit(config_path="config.json")+await toolkit.connect()+# Toolkit is connected here+tools = toolkit.get_tools()+# Don't forget to disconnect when done!+await toolkit.disconnect()-Dynamically generates a Python callable function corresponding to-a given MCP tool.+Note:+Both MCPClient and MCPToolkit now use the same async context manager+pattern for consistent connection management. MCPToolkit automatically+manages multiple MCPClient instances using AsyncExitStack.**Parameters:**-- **mcp_tool** (Tool): The MCP tool definition received from the MCP server.--**Returns:**-- Callable: A dynamically created async Python function that wraps-the MCP tool.--<a id="camel.toolkits.mcp_toolkit.MCPClient.generate_function_from_mcp_tool_sync"></a>--### generate_function_from_mcp_tool_sync--```python-def generate_function_from_mcp_tool_sync(self, mcp_tool: 'Tool'):-```--Synchronously generate a function from an MCP tool.--<a id="camel.toolkits.mcp_toolkit.MCPClient._build_tool_schema"></a>--### _build_tool_schema--```python-def _build_tool_schema(self, mcp_tool: 'Tool'):-```+- **clients** (Optional[List[MCPClient]], optional): List of :obj:`MCPClient` instances to manage. (default: :obj:`None`)+- **config_path** (Optional[str], optional): Path to a JSON configuration file defining MCP servers. The file should contain server configurations in the standard MCP format. (default: :obj:`None`)+- **config_dict** (Optional[Dict[str, Any]], optional): Dictionary containing MCP server configurations in the same format as the config file. This allows for programmatic configuration without file I/O. (default: :obj:`None`)+- **timeout** (Optional[float], optional): Timeout for connection attempts in seconds. This timeout applies to individual client connections. (default: :obj:`None`)+- **Note**: At least one of :obj:`clients`, :obj:`config_path`, or :obj:`config_dict` must be provided. If multiple sources are provided, clients from all sources will be combined. For web servers in the config, you can specify authorization headers using the "headers" field to connect to protected MCP server endpoints. Example configuration: .. code-block:: json `{ "mcpServers": { "filesystem": { "command": "npx", "args": ["-y", "@modelcontextprotocol/server-filesystem", "/path"] }, "protected-server": { "url": "https://example.com/mcp", "timeout": 30, "headers": { "Authorization": "Bearer YOUR_TOKEN", "X-API-Key": "YOUR_API_KEY" } } } }`+- **Attributes**:+- **clients** (List[MCPClient]): List of :obj:`MCPClient` instances being managed by this toolkit.-<a id="camel.toolkits.mcp_toolkit.MCPClient.get_tools"></a>+<a id="camel.toolkits.mcp_toolkit.MCPToolkit.__init__"></a>-### get_tools+### __init__```python-def get_tools(self):+def __init__(+ self,+ clients: Optional[List[MCPClient]] = None,+ config_path: Optional[str] = None,+ config_dict: Optional[Dict[str, Any]] = None,+ timeout: Optional[float] = None+):```-**Returns:**-- List[FunctionTool]: A list of FunctionTool objects-representing the functions in the toolkit.--<a id="camel.toolkits.mcp_toolkit.MCPClient.get_text_tools"></a>+<a id="camel.toolkits.mcp_toolkit.MCPToolkit.is_connected"></a>-### get_text_tools+### is_connected```python-def get_text_tools(self):+def is_connected(self):```**Returns:**- str: A string containing the descriptions of the tools-in the toolkit.+ bool: True if the toolkit is connected to all MCP servers,+False otherwise.-<a id="camel.toolkits.mcp_toolkit.MCPClient.call_tool_sync"></a>+<a id="camel.toolkits.mcp_toolkit.MCPToolkit.connect_sync"></a>-### call_tool_sync+### connect_sync```python-def call_tool_sync(self, tool_name: str, tool_args: Dict[str, Any]):+def connect_sync(self):```-Synchronously call a tool.--<a id="camel.toolkits.mcp_toolkit.MCPClient.session"></a>--### session--```python-def session(self):-```+Synchronously connect to all MCP servers.-<a id="camel.toolkits.mcp_toolkit.MCPClient.create_sync"></a>+<a id="camel.toolkits.mcp_toolkit.MCPToolkit.disconnect_sync"></a>-### create_sync+### disconnect_sync```python-def create_sync(- self,- command_or_url: str,- args: Optional[List[str]] = None,- env: Optional[Dict[str, str]] = None,- timeout: Optional[float] = None,- headers: Optional[Dict[str, str]] = None,- mode: Optional[str] = None-):+def disconnect_sync(self):```-Synchronously create and connect to the MCP server.+Synchronously disconnect from all MCP servers.-<a id="camel.toolkits.mcp_toolkit.MCPClient.__enter__"></a>+<a id="camel.toolkits.mcp_toolkit.MCPToolkit.__enter__"></a>### __enter__@@ -237,7 +142,7 @@ def __enter__(self):Synchronously enter the async context manager.-<a id="camel.toolkits.mcp_toolkit.MCPClient.__exit__"></a>+<a id="camel.toolkits.mcp_toolkit.MCPToolkit.__exit__"></a>### __exit__@@ -252,186 +157,103 @@ def __exit__(Synchronously exit the async context manager.-**Parameters:**--- **exc_type** (Optional[Type[Exception]]): The type of exception that occurred during the execution of the with statement.-- **exc_val** (Optional[Exception]): The exception that occurred during the execution of the with statement.-- **exc_tb** (Optional[TracebackType]): The traceback of the exception that occurred during the execution of the with statement.--**Returns:**-- None--<a id="camel.toolkits.mcp_toolkit.MCPToolkit"></a>--## MCPToolkit--```python-class MCPToolkit(BaseToolkit):-```--MCPToolkit provides a unified interface for managing multiple-MCP server connections and their tools.--This class handles the lifecycle of multiple MCP server connections and-offers a centralized configuration mechanism for both local and remote-MCP services.--Connection Lifecycle:-There are three ways to manage the connection lifecycle:--1. Using the async context manager:-```python-async with MCPToolkit(config_path="config.json") as toolkit:-# Toolkit is connected here-tools = toolkit.get_tools()-# Toolkit is automatically disconnected here-```--2. Using the factory method:-```python-toolkit = await MCPToolkit.create(config_path="config.json")-# Toolkit is connected here-tools = toolkit.get_tools()-# Don't forget to disconnect when done!-await toolkit.disconnect()-```--3. Using explicit connect/disconnect:-```python-toolkit = MCPToolkit(config_path="config.json")-await toolkit.connect()-# Toolkit is connected here-tools = toolkit.get_tools()-# Don't forget to disconnect when done!-await toolkit.disconnect()-```+<a id="camel.toolkits.mcp_toolkit.MCPToolkit.create_sync"></a>-**Parameters:**--- **servers** (Optional[List[MCPClient]]): List of MCPClient instances to manage. (default: :obj:`None`)-- **config_path** (Optional[str]): Path to a JSON configuration file defining MCP servers. (default: :obj:`None`)-- **config_dict** (Optional[Dict[str, Any]]): Dictionary containing MCP server configurations in the same format as the config file. (default: :obj:`None`)-- **strict** (Optional[bool]): Whether to enforce strict mode for the function call. (default: :obj:`False`)-- **Note**: Either `servers`, `config_path`, or `config_dict` must be provided. If multiple are provided, servers from all sources will be combined. For web servers in the config, you can specify authorization headers using the "headers" field to connect to protected MCP server endpoints. Example configuration: .. code-block:: json `{ "mcpServers": { "protected-server": { "url": "https://example.com/mcp", "timeout": 30, "headers": { "Authorization": "Bearer YOUR_TOKEN", "X-API-Key": "YOUR_API_KEY" } } } }`-- **Attributes**:-- **servers** (List[MCPClient]): List of MCPClient instances being managed.--<a id="camel.toolkits.mcp_toolkit.MCPToolkit.__init__"></a>--### __init__+### create_sync```python-def __init__(- self,- servers: Optional[List[MCPClient]] = None,+def create_sync(+ cls,+ clients: Optional[List[MCPClient]] = None,config_path: Optional[str] = None,config_dict: Optional[Dict[str, Any]] = None,- strict: Optional[bool] = False+ timeout: Optional[float] = None):```-<a id="camel.toolkits.mcp_toolkit.MCPToolkit._load_servers_from_config"></a>+Synchronously create and connect to all MCP servers.++<a id="camel.toolkits.mcp_toolkit.MCPToolkit._load_clients_from_config"></a>-### _load_servers_from_config+### _load_clients_from_config```python-def _load_servers_from_config(self, config_path: str, strict: Optional[bool] = False):+def _load_clients_from_config(self, config_path: str):```-Loads MCP server configurations from a JSON file.--**Parameters:**--- **config_path** (str): Path to the JSON configuration file.-- **strict** (bool): Whether to enforce strict mode for the function call. (default: :obj:`False`)--**Returns:**-- List[MCPClient]: List of configured MCPClient instances.+Load clients from configuration file.-<a id="camel.toolkits.mcp_toolkit.MCPToolkit._load_servers_from_dict"></a>+<a id="camel.toolkits.mcp_toolkit.MCPToolkit._load_clients_from_dict"></a>-### _load_servers_from_dict+### _load_clients_from_dict```python-def _load_servers_from_dict(self, config: Dict[str, Any], strict: Optional[bool] = False):+def _load_clients_from_dict(self, config: Dict[str, Any]):```-Loads MCP server configurations from a dictionary.--**Parameters:**--- **config** (Dict[str, Any]): Dictionary containing server configurations.-- **strict** (bool): Whether to enforce strict mode for the function call. (default: :obj:`False`)--**Returns:**-- List[MCPClient]: List of configured MCPClient instances.+Load clients from configuration dictionary.-<a id="camel.toolkits.mcp_toolkit.MCPToolkit.connect_sync"></a>+<a id="camel.toolkits.mcp_toolkit.MCPToolkit._create_client_from_config"></a>-### connect_sync+### _create_client_from_config```python-def connect_sync(self):+def _create_client_from_config(self, name: str, cfg: Dict[str, Any]):```-Synchronously connect to all MCP servers.+Create a single MCP client from configuration.-<a id="camel.toolkits.mcp_toolkit.MCPToolkit.disconnect_sync"></a>+<a id="camel.toolkits.mcp_toolkit.MCPToolkit.get_tools"></a>-### disconnect_sync+### get_tools```python-def disconnect_sync(self):+def get_tools(self):```-Synchronously disconnect from all MCP servers.--<a id="camel.toolkits.mcp_toolkit.MCPToolkit.connection_sync"></a>--### connection_sync+**Returns:**-```python-def connection_sync(self):-```+ List[FunctionTool]: Combined list of all available function tools+from all connected MCP servers. Returns an empty list if no+clients are connected or if no tools are available.-Synchronously connect to all MCP servers.+Note:+This method can be called even when the toolkit is not connected,+but it will log a warning and may return incomplete results.+For best results, ensure the toolkit is connected before calling+this method.-<a id="camel.toolkits.mcp_toolkit.MCPToolkit.is_connected"></a>+<a id="camel.toolkits.mcp_toolkit.MCPToolkit.get_text_tools"></a>-### is_connected+### get_text_tools```python-def is_connected(self):+def get_text_tools(self):```**Returns:**- bool: True if connected, False otherwise.+ str: A string containing the descriptions of all tools.-<a id="camel.toolkits.mcp_toolkit.MCPToolkit.get_tools"></a>+<a id="camel.toolkits.mcp_toolkit.MCPToolkit.call_tool_sync"></a>-### get_tools+### call_tool_sync```python-def get_tools(self):+def call_tool_sync(self, tool_name: str, tool_args: Dict[str, Any]):```-**Returns:**-- List[FunctionTool]: Combined list of all available function tools.+Synchronously call a tool.-<a id="camel.toolkits.mcp_toolkit.MCPToolkit.get_text_tools"></a>+<a id="camel.toolkits.mcp_toolkit.MCPToolkit.list_available_tools"></a>-### get_text_tools+### list_available_tools```python-def get_text_tools(self):+def list_available_tools(self):```**Returns:**- str: A string containing the descriptions of the tools-in the toolkit.+ Dict[str, List[str]]: Dictionary mapping client indices to tool+names.diff --git a/docs/mintlify/reference/camel.utils.mcp_client.mdx b/docs/mintlify/reference/camel.utils.mcp_client.mdxnew file mode 100644index 000000000..055a5e94c--- /dev/null+++ b/docs/mintlify/reference/camel.utils.mcp_client.mdx@@ -0,0 +1,286 @@+<a id="camel.utils.mcp_client"></a>++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.++<a id="camel.utils.mcp_client.TransportType"></a>++## TransportType++```python+class TransportType(str, Enum):+```++Supported transport types.++<a id="camel.utils.mcp_client.ServerConfig"></a>++## ServerConfig++```python+class ServerConfig(BaseModel):+```++<a id="camel.utils.mcp_client.ServerConfig.validate_config"></a>++### validate_config++```python+def validate_config(self):+```++Validate that either command or url is provided.++<a id="camel.utils.mcp_client.ServerConfig.transport_type"></a>++### transport_type++```python+def transport_type(self):+```++Automatically detect transport type based on configuration.++<a id="camel.utils.mcp_client.MCPClient"></a>++## MCPClient++```python+class MCPClient:+```++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.++**Parameters:**++- **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`)++<a id="camel.utils.mcp_client.MCPClient.__init__"></a>++### __init__++```python+def __init__(+ self,+ config: Union[ServerConfig, Dict[str, Any]],+ client_info: Optional[types.Implementation] = None,+ timeout: Optional[float] = 10.0,+ strict: Optional[bool] = False+):+```++<a id="camel.utils.mcp_client.MCPClient.transport_type"></a>++### transport_type++```python+def transport_type(self):+```++Get the detected transport type.++<a id="camel.utils.mcp_client.MCPClient._simplify_connection_error"></a>++### _simplify_connection_error++```python+def _simplify_connection_error(self, error: Exception):+```++Convert complex MCP connection errors to simple, understandable+messages.++<a id="camel.utils.mcp_client.MCPClient.session"></a>++### session++```python+def session(self):+```++Get the current session if connected.++<a id="camel.utils.mcp_client.MCPClient.is_connected"></a>++### is_connected++```python+def is_connected(self):+```++Check if the client is currently connected.++<a id="camel.utils.mcp_client.MCPClient.list_mcp_tools_sync"></a>++### list_mcp_tools_sync++```python+def list_mcp_tools_sync(self):+```++**Returns:**++ ListToolsResult: Result containing available MCP tools.++<a id="camel.utils.mcp_client.MCPClient.generate_function_from_mcp_tool"></a>++### generate_function_from_mcp_tool++```python+def generate_function_from_mcp_tool(self, mcp_tool: types.Tool):+```++Dynamically generates a Python callable function corresponding to+a given MCP tool.++**Parameters:**++- **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.++<a id="camel.utils.mcp_client.MCPClient._build_tool_schema"></a>++### _build_tool_schema++```python+def _build_tool_schema(self, mcp_tool: types.Tool):+```++Build tool schema for OpenAI function calling format.++<a id="camel.utils.mcp_client.MCPClient.get_tools"></a>++### get_tools++```python+def get_tools(self):+```++**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.++<a id="camel.utils.mcp_client.MCPClient.get_text_tools"></a>++### get_text_tools++```python+def get_text_tools(self):+```++**Returns:**++ str: Text description of tools++<a id="camel.utils.mcp_client.MCPClient.call_tool_sync"></a>++### call_tool_sync++```python+def call_tool_sync(self, tool_name: str, arguments: Dict[str, Any]):+```++Synchronously call a tool by name with the provided arguments.++**Parameters:**++- **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.++<a id="camel.utils.mcp_client.create_mcp_client"></a>++## create_mcp_client++```python+def create_mcp_client(config: Union[Dict[str, Any], ServerConfig], **kwargs: Any):+```++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.++**Parameters:**++- **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.++<a id="camel.utils.mcp_client.create_mcp_client_from_config_file"></a>++## create_mcp_client_from_config_file++```python+def create_mcp_client_from_config_file(config_path: Union[str, Path], server_name: str, **kwargs: Any):+```++Create an MCP client from a configuration file.++**Parameters:**++- **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()diff --git a/examples/toolkits/mcp/mcp_arxiv_toolkit/client.py b/examples/toolkits/mcp/mcp_arxiv_toolkit/client.pyindex 8a999226e..6380ffee7 100644--- a/examples/toolkits/mcp/mcp_arxiv_toolkit/client.py+++ b/examples/toolkits/mcp/mcp_arxiv_toolkit/client.py@@ -12,38 +12,49 @@# limitations under the License.# ========= Copyright 2023-2024 @ CAMEL-AI.org. All Rights Reserved. =========import asyncio+import sysfrom mcp.types import CallToolResultfrom camel.toolkits.mcp_toolkit import MCPClient, MCPToolkit-async def run_example():- mcp_toolkit = MCPToolkit(- config_path="examples/mcp_arxiv_toolkit/mcp_servers_config.json"- )+async def run_example_http():+ config = {+ "mcpServers": {+ "arxiv_toolkit": {+ "url": "http://localhost:8000/mcp/",+ "mode": "streamable-http",+ }+ }+ }+ mcp_toolkit = MCPToolkit(config_dict=config, timeout=60)- await mcp_toolkit.connect()+ async with mcp_toolkit:+ # call the server to list the available tools+ mcp_client: MCPClient = mcp_toolkit.clients[0]+ res = await mcp_client.list_mcp_tools()+ if isinstance(res, str):+ raise Exception(res)- # call the server to list the available tools- mcp_client: MCPClient = mcp_toolkit.servers[0]- res = await mcp_client.list_mcp_tools()- if isinstance(res, str):- raise Exception(res)+ # call the server to list the available tools+ mcp_client: MCPClient = mcp_toolkit.clients[0]+ res = await mcp_client.list_mcp_tools()+ if isinstance(res, str):+ raise Exception(res)- tools = [tool.name for tool in res.tools]- print(tools)- """+ tools = [tool.name for tool in res.tools]+ print(tools)+ """===============================================================================['search_papers', 'download_papers']===============================================================================- """-- res1: CallToolResult = await mcp_client.session.call_tool(- "search_papers", {"query": "attention is all you need"}- )- print(res1.content[0].text[:1000])- """+ """+ res1: CallToolResult = await mcp_client.session.call_tool(+ "search_papers", {"query": "attention is all you need"}+ )+ print(res1.content[0].text[:1000])+ """==============================================================================={"title": "Attention Is All You Need But You Don't Need All Of It ForInference of Large Language Models", "published_date": "2024-07-22",@@ -60,10 +71,43 @@ attention layers in a 13B Llama2 model\nresults in a 1.8\\% drop in averageperformance over the OpenLLM benchmark. We\nalso observe that skipping layersexcept the latter layers reduces perform===============================================================================- """+ """+++async def run_example_stdio():+ config = {+ "mcpServers": {+ "arxiv_toolkit": {+ "command": sys.executable,+ "args": [+ "examples/toolkits/mcp/mcp_arxiv_toolkit/arxiv_toolkit_server.py",+ "--mode",+ "stdio",+ ],+ }+ }+ }+ mcp_toolkit = MCPToolkit(config_dict=config, timeout=60)+ async with mcp_toolkit:+ mcp_client: MCPClient = mcp_toolkit.clients[0]+ res = await mcp_client.list_mcp_tools()+ if isinstance(res, str):+ raise Exception(res)++ # call the server to list the available tools+ mcp_client: MCPClient = mcp_toolkit.clients[0]+ res = await mcp_client.list_mcp_tools()+ if isinstance(res, str):+ raise Exception(res)- await mcp_toolkit.disconnect()+ tools = [tool.name for tool in res.tools]+ print(tools)+ res1: CallToolResult = await mcp_client.session.call_tool(+ "search_papers", {"query": "attention is all you need"}+ )+ print(res1.content[0].text[:1000])if __name__ == "__main__":- asyncio.run(run_example())+ asyncio.run(run_example_http())+ asyncio.run(run_example_stdio())diff --git a/examples/toolkits/mcp/mcp_arxiv_toolkit/client_sync.py b/examples/toolkits/mcp/mcp_arxiv_toolkit/client_sync.pyindex 3275fb25b..eb9a1badd 100644--- a/examples/toolkits/mcp/mcp_arxiv_toolkit/client_sync.py+++ b/examples/toolkits/mcp/mcp_arxiv_toolkit/client_sync.py@@ -19,26 +19,30 @@ from camel.toolkits.mcp_toolkit import MCPClient, MCPToolkitdef run_example():mcp_toolkit = MCPToolkit(- config_path="examples/mcp_arxiv_toolkit/mcp_servers_config.json"+ config_dict={+ "mcpServers": {+ "arxiv_toolkit": {+ "url": "http://localhost:8000/mcp/",+ "mode": "streamable-http",+ }+ }+ })- mcp_toolkit.connect_sync()+ with mcp_toolkit:+ # call the server to list the available tools+ mcp_client: MCPClient = mcp_toolkit.clients[0]+ res = mcp_client.list_mcp_tools_sync()+ if isinstance(res, str):+ raise Exception(res)- # call the server to list the available tools- mcp_client: MCPClient = mcp_toolkit.servers[0]- res = mcp_client.list_mcp_tools_sync()- if isinstance(res, str):- raise Exception(res)+ tools = [tool.name for tool in res.tools]+ print(tools)- tools = [tool.name for tool in res]- print(tools)-- res1: CallToolResult = mcp_client.call_tool_sync(- "search_papers", {"query": "attention is all you need"}- )- print(res1.content[0].text[:1000])-- mcp_toolkit.disconnect_sync()+ res1: CallToolResult = mcp_client.call_tool_sync(+ "search_papers", {"query": "attention is all you need"}+ )+ print(res1.content[0].text[:1000])if __name__ == "__main__":diff --git a/examples/toolkits/mcp/mcp_arxiv_toolkit/mcp_servers_config.json b/examples/toolkits/mcp/mcp_arxiv_toolkit/mcp_servers_config.jsondeleted file mode 100644index eeaf67e25..000000000--- a/examples/toolkits/mcp/mcp_arxiv_toolkit/mcp_servers_config.json+++ /dev/null@@ -1,9 +0,0 @@-{- "mcpServers": {- "arxiv_toolkit": {- "url": "http://localhost:8000/mcp/sse",- "timeout": 30,- "mode": "streamable-http"- }- }-}\ No newline at end of filediff --git a/examples/toolkits/mcp/mcp_toolkit.py b/examples/toolkits/mcp/mcp_toolkit.pyindex fd2f15b54..4f0ef234a 100644--- a/examples/toolkits/mcp/mcp_toolkit.py+++ b/examples/toolkits/mcp/mcp_toolkit.py@@ -37,13 +37,47 @@ from camel.agents import ChatAgentfrom camel.models import ModelFactoryfrom camel.toolkits import MCPToolkitfrom camel.types import ModelPlatformType, ModelType+from camel.utils.mcp_client import MCPClient-async def main():+async def mcp_client_example():+ config = {+ "command": "npx",+ "args": ["-y", "@modelcontextprotocol/server-filesystem", "."],+ }+ async with MCPClient(config) as client:+ mcp_tools = await client.list_mcp_tools()+ print("Available MCP tools:", [tool.name for tool in mcp_tools.tools])+ call_tool_result = await client.call_tool(+ "list_directory", {"path": "."}+ )+ print("Directory Contents:")+ for i, item in enumerate(call_tool_result.content[0].text.split('\n')):+ if item.strip():+ print(f" {item}")+ if i >= 4: # Stop after printing 5 items (0-based index)+ break+++'''+===============================================================================+Available MCP tools: ['read_file', 'read_multiple_files', 'write_file',+'edit_file', 'create_directory', 'list_directory', 'directory_tree',+'move_file', 'search_files', 'get_file_info', 'list_allowed_directories']+Directory Contents:+ [DIR] .container+ [FILE] .env+ [DIR] .git+ [DIR] .github+ [FILE] .gitignore+===============================================================================+'''+++async def mcp_toolkit_example():# Use either config path or config dict to initialize the MCP toolkit.# 1. Use config path:config_path = Path(__file__).parent / "mcp_servers_config.json"- mcp_toolkit = MCPToolkit(config_path=str(config_path))# 2. Use config dict:# config_dict = {# "mcpServers": {@@ -61,29 +95,23 @@ async def main():# mcp_toolkit = MCPToolkit(config_dict=config_dict)# Connect to all MCP servers.- await mcp_toolkit.connect()-- sys_msg = "You are a helpful assistant"- model = ModelFactory.create(- model_platform=ModelPlatformType.DEFAULT,- model_type=ModelType.DEFAULT,- )- camel_agent = ChatAgent(- system_message=sys_msg,- model=model,- tools=[*mcp_toolkit.get_tools()],- )- user_msg = "List 5 files in the project, using relative paths"- response = await camel_agent.astep(user_msg)- print(response.msgs[0].content)- print(response.info['tool_calls'])-- # Disconnect from all MCP servers and clean up resources.- await mcp_toolkit.disconnect()+ async with MCPToolkit(config_path=str(config_path)) as mcp_toolkit:+ sys_msg = "You are a helpful assistant"+ model = ModelFactory.create(+ model_platform=ModelPlatformType.DEFAULT,+ model_type=ModelType.DEFAULT,+ )+ camel_agent = ChatAgent(+ system_message=sys_msg,+ model=model,+ tools=[*mcp_toolkit.get_tools()],+ )+ user_msg = "List 5 files in the project, using relative paths"+ response = await camel_agent.astep(user_msg)+ print(response.msgs[0].content)+ print(response.info['tool_calls'])-if __name__ == "__main__":- asyncio.run(main())'''===============================================================================Here are 5 files in the project using relative paths:@@ -95,3 +123,8 @@ Here are 5 files in the project using relative paths:5. `README.md`==============================================================================='''+++if __name__ == "__main__":+ asyncio.run(mcp_client_example())+ asyncio.run(mcp_toolkit_example())diff --git a/test/toolkits/test_mcp_toolkit.py b/test/toolkits/test_mcp_toolkit.pyindex 9d4516759..7da0a2588 100644--- a/test/toolkits/test_mcp_toolkit.py+++ b/test/toolkits/test_mcp_toolkit.py@@ -11,734 +11,574 @@# See the License for the specific language governing permissions and# limitations under the License.# ========= Copyright 2023-2024 @ CAMEL-AI.org. All Rights Reserved. =========+"""+Tests for the refactored MCPToolkit.+"""+import jsonimport tempfile+from contextlib import asynccontextmanagerfrom pathlib import Pathfrom unittest.mock import AsyncMock, MagicMock, patchimport pytest-from camel.toolkits.mcp_toolkit import MCPClient, MCPToolkit+from camel.toolkits.mcp_toolkit import (+ MCPConnectionError,+ MCPToolError,+ MCPToolkit,+)+from camel.utils.mcp_client import MCPClient-class TestMCPClient:- r"""Test MCPClient class."""+class TestMCPToolkit:+ """Test MCPToolkit class."""++ def test_init_with_clients(self):+ """Test MCPToolkit initialization with client instances."""+ mock_client = MagicMock(spec=MCPClient)+ toolkit = MCPToolkit(clients=[mock_client])+ assert len(toolkit.clients) == 1+ assert toolkit.clients[0] == mock_client+ assert not toolkit.is_connected++ def test_init_with_config_dict(self):+ """Test MCPToolkit initialization with config dictionary."""+ config_dict = {+ "mcpServers": {"test_server": {"command": "npx", "args": ["test"]}}+ }- @pytest.mark.asyncio- async def test_init(self):- r"""Test initialization of MCPClient."""- # Test with default parameters- server = MCPClient("test_command")- assert server.command_or_url == "test_command"- assert server.args == []- assert server.env == {}- assert server._mcp_tools == []- assert server.session is None- assert server._is_connected is False-- # Test with custom parameters- server = MCPClient(- "test_url",- args=["--arg1", "--arg2"],- env={"ENV_VAR": "value"},- timeout=30,+ toolkit = MCPToolkit(config_dict=config_dict)+ assert len(toolkit.clients) == 1+ assert toolkit.clients[0].config.command == "npx"++ def test_init_with_config_file(self):+ """Test MCPToolkit initialization with config file."""+ config_data = {+ "mcpServers": {+ "filesystem": {+ "command": "npx",+ "args": [+ "-y",+ "@modelcontextprotocol/server-filesystem",+ "/path",+ ],+ },+ "remote-server": {+ "url": "https://api.example.com/mcp",+ "headers": {"Authorization": "Bearer token"},+ },+ }+ }++ with tempfile.NamedTemporaryFile(+ mode="w", suffix=".json", delete=False+ ) as f:+ json.dump(config_data, f)+ config_path = f.name++ try:+ toolkit = MCPToolkit(config_path=config_path)+ assert len(toolkit.clients) == 2++ # Check first client (filesystem)+ assert toolkit.clients[0].config.command == "npx"+ expected_args = [+ "-y",+ "@modelcontextprotocol/server-filesystem",+ "/path",+ ]+ assert toolkit.clients[0].config.args == expected_args++ # Check second client (remote-server)+ url = "https://api.example.com/mcp"+ assert toolkit.clients[1].config.url == url+ expected_headers = {"Authorization": "Bearer token"}+ assert toolkit.clients[1].config.headers == expected_headers++ finally:+ Path(config_path).unlink()++ def test_init_no_sources_error(self):+ """Test error when no configuration sources provided."""+ expected_msg = (+ "At least one of clients, config_path, or "+ "config_dict must be provided")- assert server.command_or_url == "test_url"- assert server.args == ["--arg1", "--arg2"]- assert server.env == {"ENV_VAR": "value"}- assert server._mcp_tools == []- assert server.session is None- assert server._is_connected is False+ with pytest.raises(ValueError, match=expected_msg):+ MCPToolkit()++ def test_init_invalid_config_dict(self):+ """Test error with invalid config dictionary."""+ config_dict = {"invalid": "config"}++ expected_msg = "No valid MCP clients could be created"+ with pytest.raises(ValueError, match=expected_msg):+ MCPToolkit(config_dict=config_dict)++ def test_init_file_not_found(self):+ """Test error when config file not found."""+ with pytest.raises(FileNotFoundError, match="Config file not found"):+ MCPToolkit(config_path="/nonexistent/config.json")++ def test_init_invalid_json_file(self):+ """Test error with invalid JSON file."""+ with tempfile.NamedTemporaryFile(+ mode="w", suffix=".json", delete=False+ ) as f:+ f.write("invalid json content")+ config_path = f.name++ try:+ with pytest.raises(ValueError, match="Invalid JSON"):+ MCPToolkit(config_path=config_path)+ finally:+ Path(config_path).unlink()++ def test_multiple_sources_combined(self):+ """Test that multiple sources are combined."""+ mock_client = MagicMock(spec=MCPClient)+ config_dict = {+ "mcpServers": {"test_server": {"command": "npx", "args": ["test"]}}+ }++ toolkit = MCPToolkit(clients=[mock_client], config_dict=config_dict)++ assert len(toolkit.clients) == 2+ assert toolkit.clients[0] == mock_client+ assert toolkit.clients[1].config.command == "npx"+++class TestMCPToolkitConnectionManagement:+ """Test connection management in MCPToolkit."""@pytest.mark.asyncio- async def test_connection_http(self):- r"""Test connection with HTTP URL."""- with (- patch("mcp.client.sse.sse_client") as mock_sse_client,- patch("mcp.client.session.ClientSession") as mock_session,- ):- # Setup mocks- mock_read_stream = AsyncMock()- mock_write_stream = AsyncMock()- mock_sse_client.return_value.__aenter__.return_value = (- mock_read_stream,- mock_write_stream,- )+ async def test_connect_success(self):+ """Test successful connection to all clients."""+ # Create mock clients with properly mocked async context managers+ mock_client1 = MagicMock()+ mock_client2 = MagicMock()- mock_session_instance = AsyncMock()- mock_session.return_value.__aenter__.return_value = (- mock_session_instance- )+ # Create proper async context manager mocks+ @asynccontextmanager+ async def mock_connect1():+ yield MagicMock() # Mock session- # Mock list_tools result- list_tools_result = MagicMock()- list_tools_result.tools = ["tool1", "tool2"]- mock_session_instance.list_tools.return_value = list_tools_result+ @asynccontextmanager+ async def mock_connect2():+ yield MagicMock() # Mock session- # Test HTTP connection- server = MCPClient("https://example.com/api")- async with server.connection() as connected_server:- assert connected_server._is_connected is True- assert connected_server._mcp_tools == ["tool1", "tool2"]+ mock_client1.connect = mock_connect1+ mock_client2.connect = mock_connect2+ mock_client1.is_connected.return_value = True+ mock_client2.is_connected.return_value = True- # Verify mocks were called correctly- mock_sse_client.assert_called_once_with(- "https://example.com/api", headers={}, timeout=None- )- mock_session.assert_called_once()- mock_session_instance.initialize.assert_called_once()- mock_session_instance.list_tools.assert_called_once()+ toolkit = MCPToolkit(clients=[mock_client1, mock_client2])++ await toolkit.connect()++ assert toolkit._is_connected+ assert toolkit.is_connected@pytest.mark.asyncio- async def test_connection_stdio(self):- r"""Test connection with stdio command."""- with (- patch("mcp.client.stdio.stdio_client") as mock_stdio_client,- patch("mcp.client.session.ClientSession") as mock_session,- ):- # Setup mocks- mock_read_stream = AsyncMock()- mock_write_stream = AsyncMock()- mock_stdio_client.return_value.__aenter__.return_value = (- mock_read_stream,- mock_write_stream,- )+ async def test_connect_failure_rollback(self):+ """Test rollback when connection fails."""+ # Create mock clients+ mock_client1 = MagicMock()+ mock_client2 = MagicMock()- mock_session_instance = AsyncMock()- mock_session.return_value.__aenter__.return_value = (- mock_session_instance- )+ # Set up the first client as a successful async context manager+ mock_client1.__aenter__.return_value = mock_client1+ mock_client1.__aexit__.return_value = None- # Mock list_tools result- list_tools_result = MagicMock()- list_tools_result.tools = ["tool1", "tool2"]- mock_session_instance.list_tools.return_value = list_tools_result+ # Set up the second client to raise an exception during __aenter__+ mock_client2.__aenter__.side_effect = Exception("Connection failed")- # Test stdio connection- server = MCPClient(- "local_command", args=["--arg1"], env={"ENV_VAR": "value"}- )- async with server.connection() as connected_server:- assert connected_server._is_connected is True- assert connected_server._mcp_tools == ["tool1", "tool2"]+ toolkit = MCPToolkit(clients=[mock_client1, mock_client2])++ expected_msg = "Failed to connect to client 2"+ with pytest.raises(MCPConnectionError, match=expected_msg):+ await toolkit.connect()- # Verify mocks were called correctly- mock_stdio_client.assert_called_once()- mock_session.assert_called_once()- mock_session_instance.initialize.assert_called_once()- mock_session_instance.list_tools.assert_called_once()+ assert not toolkit._is_connected+ # Verify the first client's __aexit__ was called for cleanup+ mock_client1.__aexit__.assert_called_once()@pytest.mark.asyncio- async def test_list_mcp_tools_not_connected(self):- r"""Test list_mcp_tools when not connected."""- server = MCPClient("test_command")- result = await server.list_mcp_tools()- assert isinstance(result, str)- assert "not connected" in result+ async def test_connect_already_connected(self):+ """Test connecting when already connected."""+ mock_client = MagicMock()- @pytest.mark.asyncio- async def test_list_mcp_tools_connected(self):- r"""Test list_mcp_tools when connected."""- server = MCPClient("test_command")- server._session = AsyncMock()+ @asynccontextmanager+ async def mock_connect():+ yield MagicMock() # Mock session++ mock_client.connect = mock_connect- # Mock successful response- mock_result = MagicMock()- server._session.list_tools.return_value = mock_result+ toolkit = MCPToolkit(clients=[mock_client])+ toolkit._is_connected = True- result = await server.list_mcp_tools()- assert result == mock_result- server._session.list_tools.assert_called_once()+ result = await toolkit.connect()- # Mock exception- server._session.list_tools.side_effect = Exception("Test error")- with pytest.raises(Exception) as excinfo:- await server.list_mcp_tools()- assert "Test error" in str(excinfo.value)+ assert result is toolkit@pytest.mark.asyncio- async def test_generate_function_from_mcp_tool(self):- r"""Test generate_function_from_mcp_tool."""- server = MCPClient("test_command")- server._session = AsyncMock()+ async def test_disconnect_success(self):+ """Test successful disconnection from all clients."""+ mock_client1 = MagicMock()+ mock_client1.disconnect = AsyncMock()- # Create mock MCP tool- mock_tool = MagicMock()- mock_tool.name = "test_function"- mock_tool.description = "Test function description"- mock_tool.inputSchema = {- "properties": {- "param1": {"type": "string"},- "param2": {"type": "integer"},- "param3": {"type": "boolean"},- },- "required": ["param1", "param2"],- }+ mock_client2 = MagicMock()+ mock_client2.disconnect = AsyncMock()- # Generate function- func = server.generate_function_from_mcp_tool(mock_tool)-- # Check function attributes- assert func.__name__ == "test_function"- assert func.__doc__ == "Test function description"- assert "param1" in func.__annotations__- assert "param2" in func.__annotations__- assert "param3" in func.__annotations__-- # Mock call_tool response- mock_content = MagicMock()- mock_content.type = "text"- mock_content.text = "Test result"-- mock_result = MagicMock()- mock_result.content = [mock_content]- server._session.call_tool.return_value = mock_result-- # Test function call- result = await func(param1="test", param2=123)- assert result == "Test result"- server._session.call_tool.assert_called_once_with(- "test_function", {"param1": "test", "param2": 123}- )+ toolkit = MCPToolkit(clients=[mock_client1, mock_client2])+ toolkit._is_connected = True- # Test missing required parameter - now returns a message- with patch("camel.toolkits.mcp_toolkit.logger") as mock_logger:- mock_logger.reset_mock()-- result = await func(param1="test")- assert result == "Missing required parameters."- mock_logger.warning.assert_called_once()-- # Test different content types- # Image content- mock_content.type = "image"- mock_content.url = "https://example.com/image.jpg"- result = await func(param1="test", param2=123)- assert "Image available at" in result-- # Image without URL- mock_content.url = None- result = await func(param1="test", param2=123)- assert "Image content received" in result-- # Embedded resource- mock_content.type = "embedded_resource"- mock_content.name = "resource.pdf"- result = await func(param1="test", param2=123)- assert "Embedded resource: resource.pdf" in result-- # Embedded resource without name- mock_content.name = None- result = await func(param1="test", param2=123)- assert "Embedded resource received" in result-- # Unknown content type- mock_content.type = "unknown"- result = await func(param1="test", param2=123)- assert "not fully supported" in result-- # No content- mock_result.content = []- result = await func(param1="test", param2=123)- assert "No data available" in result+ await toolkit.disconnect()- @pytest.mark.asyncio- async def test_build_tool_schema(self):- r"""Test build_tool_schema method."""- server = MCPClient("test_command")- mock_tool = MagicMock()- mock_tool.name = "test_function"- mock_tool.description = "Test function description"- mock_tool.inputSchema = {- "properties": {- "param1": {"type": "string"},- "param2": {"type": "integer"},- },- "required": ["param1", "param2"],- }- schema = server._build_tool_schema(mock_tool)-- target_schema = {- "type": "function",- "function": {- "name": "test_function",- "description": "Test function description",- "strict": False,- "parameters": {- "type": "object",- "properties": {- "param1": {"type": "string"},- "param2": {"type": "integer"},- },- "required": ["param1", "param2"],- "additionalProperties": False,- },- },- }- assert schema == target_schema-- # No description- mock_tool.description = None- schema = server._build_tool_schema(mock_tool)- assert schema == {- "type": "function",- "function": {- "name": "test_function",- "description": "No description provided.",- "strict": False,- "parameters": {- "type": "object",- "properties": {- "param1": {"type": "string"},- "param2": {"type": "integer"},- },- "required": ["param1", "param2"],- "additionalProperties": False,- },- },- }+ assert not toolkit._is_connected@pytest.mark.asyncio- async def test_get_tools(self):- r"""Test get_tools method for MCPClient."""- with patch(- "camel.toolkits.mcp_toolkit.FunctionTool"- ) as mock_function_tool:- server = MCPClient("test_command")-- # Mock tools- mock_tool1 = MagicMock()- mock_tool2 = MagicMock()- server._mcp_tools = [mock_tool1, mock_tool2]-- # Mock generate_function_from_mcp_tool- mock_func1 = AsyncMock()- mock_func2 = AsyncMock()- server.generate_function_from_mcp_tool = MagicMock(- side_effect=[mock_func1, mock_func2]- )-- # Mock FunctionTool- mock_function_tool_instance1 = MagicMock()- mock_function_tool_instance2 = MagicMock()- mock_function_tool.side_effect = [- mock_function_tool_instance1,- mock_function_tool_instance2,- ]+ async def test_disconnect_not_connected(self):+ """Test disconnect when not connected."""+ mock_client = MagicMock()+ mock_client.disconnect = AsyncMock()- # Get tools- tools = server.get_tools()+ toolkit = MCPToolkit(clients=[mock_client])- # Verify results- assert len(tools) == 2- assert tools[0] == mock_function_tool_instance1- assert tools[1] == mock_function_tool_instance2+ await toolkit.disconnect()- # Verify mocks were called correctly- server.generate_function_from_mcp_tool.assert_any_call(mock_tool1)- server.generate_function_from_mcp_tool.assert_any_call(mock_tool2)+ # Should be a no-op when not connected+ assert not toolkit._is_connected@pytest.mark.asyncio- async def test_connect_explicit(self):- r"""Test explicit connect method."""- with (- patch("mcp.client.sse.sse_client") as mock_sse_client,- patch("mcp.client.session.ClientSession") as mock_session,- ):- # Setup mocks- mock_read_stream = AsyncMock()- mock_write_stream = AsyncMock()- mock_sse_client.return_value.__aenter__.return_value = (- mock_read_stream,- mock_write_stream,- )+ async def test_disconnect_with_errors(self):+ """Test disconnect with some clients failing."""+ mock_client1 = MagicMock()+ disconnect_exc = Exception("Disconnect failed")+ mock_client1.disconnect = AsyncMock(side_effect=disconnect_exc)- mock_session_instance = AsyncMock()- mock_session.return_value.__aenter__.return_value = (- mock_session_instance- )+ mock_client2 = MagicMock()+ mock_client2.disconnect = AsyncMock()- # Mock list_tools result- list_tools_result = MagicMock()- list_tools_result.tools = ["tool1", "tool2"]- mock_session_instance.list_tools.return_value = list_tools_result+ toolkit = MCPToolkit(clients=[mock_client1, mock_client2])+ toolkit._is_connected = True- # Test HTTP connection- server = MCPClient("https://example.com/api")- result = await server.connect()+ await toolkit.disconnect()- # Verify results- assert result == server- assert server._is_connected is True- assert server._mcp_tools == ["tool1", "tool2"]- assert server.session is not None+ assert not toolkit._is_connected- # Verify mocks were called correctly- mock_sse_client.assert_called_once_with(- "https://example.com/api", headers={}, timeout=None- )- mock_session.assert_called_once()- mock_session_instance.initialize.assert_called_once()- mock_session_instance.list_tools.assert_called_once()-- # Test connecting when already connected- with patch("camel.toolkits.mcp_toolkit.logger") as mock_logger:- result = await server.connect()- assert result == server- mock_logger.warning.assert_called_once()- # Verify no new connections were made- assert mock_sse_client.call_count == 1+ def test_is_connected_property(self):+ """Test is_connected property."""+ mock_client1 = MagicMock()+ mock_client1.is_connected.return_value = True- @pytest.mark.asyncio- async def test_connect_failure(self):- r"""Test connect method with failure."""- with patch("mcp.client.sse.sse_client") as mock_sse_client:- # Setup mock to raise exception- mock_sse_client.return_value.__aenter__.side_effect = Exception(- "Connection error"- )+ mock_client2 = MagicMock()+ mock_client2.is_connected.return_value = True- # Create server- server = MCPClient("https://example.com/api")+ toolkit = MCPToolkit(clients=[mock_client1, mock_client2])- with pytest.raises(Exception) as excinfo:- await server.connect()+ # Not connected initially+ assert not toolkit.is_connected- assert "Connection error" in str(excinfo.value)+ # Mark as connected+ toolkit._is_connected = True+ assert toolkit.is_connected- assert server._is_connected is False+ # One client disconnected+ mock_client2.is_connected.return_value = False+ assert not toolkit.is_connected@pytest.mark.asyncio- async def test_disconnect_explicit(self):- r"""Test explicit disconnect method."""- # Create server- server = MCPClient("test_command")+ async def test_context_manager(self):+ """Test async context manager."""+ mock_client = MagicMock()- # Setup connected state- server._is_connected = True- # Assign an AsyncMock to _exit_stack to check its aclose method- mock_exit_stack = AsyncMock()- server._exit_stack = mock_exit_stack- server._session = MagicMock()+ @asynccontextmanager+ async def mock_connect():+ yield MagicMock() # Mock session- # Test disconnect- await server.disconnect()+ mock_client.connect = mock_connect+ mock_client.is_connected.return_value = True- # Verify results- assert server._is_connected is False- assert server.session is None- # Assert that aclose was called on the original mock_exit_stack- mock_exit_stack.aclose.assert_called_once()+ toolkit = MCPToolkit(clients=[mock_client])- # Test disconnecting when not connected- server._exit_stack = AsyncMock()- server._exit_stack.aclose = AsyncMock()+ async with toolkit as connected_toolkit:+ assert connected_toolkit is toolkit- await server.disconnect()- # Verify exit stack is still closed even when not connected- server._exit_stack.aclose.assert_not_called()+class TestMCPToolkitFactoryMethods:+ """Test factory methods for MCPToolkit."""@pytest.mark.asyncio- async def test_disconnect_without_connection(self):- r"""Test explicit disconnect method without connection."""- # Create server- server = MCPClient("test_command")+ async def test_create_success(self):+ """Test successful creation with factory method."""+ mock_client = MagicMock()+ mock_client.connect = AsyncMock()+ mock_client.is_connected.return_value = True- # Setup not connected state- server._is_connected = False- # Store the mock session to assert its identity- initial_mock_session = MagicMock()- server._session = initial_mock_session+ # Mock the toolkit creation+ with patch.object(MCPToolkit, '__init__', return_value=None):+ with patch.object(MCPToolkit, 'connect', return_value=None):+ toolkit = MCPToolkit.__new__(MCPToolkit)+ toolkit.clients = [mock_client]+ toolkit._is_connected = False- # Test disconnect- await server.disconnect()+ # Mock the connect method+ async def mock_connect():+ toolkit._is_connected = True+ return toolkit- # Verify results- assert server._is_connected is False- assert server.session is initial_mock_session+ toolkit.connect = mock_connect+ patch_path = 'camel.toolkits.mcp_toolkit.MCPToolkit.__new__'+ with patch(patch_path, return_value=toolkit):+ result = await MCPToolkit.create(clients=[mock_client])-class TestMCPToolkit:- r"""Test MCPToolkit class."""-- def test_init(self):- r"""Test initialization of MCPToolkit."""- # Test with servers list- server1 = MCPClient("test_command1")- server2 = MCPClient("test_command2")- toolkit = MCPToolkit(servers=[server1, server2])-- assert toolkit.servers == [server1, server2]- assert toolkit._connected is False-- # Test with both servers and config_path- with patch("camel.toolkits.mcp_toolkit.logger") as mock_logger:- with patch.object(- MCPToolkit, "_load_servers_from_config", return_value=[]- ):- toolkit = MCPToolkit(- servers=[server1], config_path="dummy_path"- )- assert toolkit.servers == [server1]- mock_logger.warning.assert_called_once()-- def test_init_config_file_not_found(self):- r"""Test from_config with non-existent file."""- with patch("camel.toolkits.mcp_toolkit.logger") as mock_logger:- with tempfile.TemporaryDirectory() as temp_dir:- non_existent_path = Path(temp_dir) / "non_existent.json"-- with pytest.raises(FileNotFoundError):- MCPToolkit(config_path=str(non_existent_path))-- # Verify that a warning was logged- mock_logger.warning.assert_called_once_with(- f"Config file not found: '{non_existent_path}'"- )-- def test_init_config_invalid_json(self):- r"""Test from_config with invalid JSON."""- with tempfile.TemporaryDirectory() as temp_dir:- config_path = Path(temp_dir) / "invalid.json"- config_path.write_text("{invalid json")-- with pytest.raises(json.JSONDecodeError) as excinfo:- MCPToolkit(config_path=str(config_path))-- assert (- "Expecting property name enclosed in double quotes"- in str(excinfo.value)- )-- def test_init_config_valid(self):- r"""Test from_config with valid configuration."""- with tempfile.TemporaryDirectory() as temp_dir:- config_path = Path(temp_dir) / "valid.json"- config_data = {- "mcpServers": {- "server1": {- "command": "test-command",- "args": ["--arg1"],- "env": {"TEST_ENV": "value"},- },- "server2": {"url": "https://test.com/sse"},- }- }- config_path.write_text(json.dumps(config_data))-- toolkit = MCPToolkit(config_path=str(config_path))- assert len(toolkit.servers) == 2-- # Check local server toolkit- assert toolkit.servers[0].command_or_url == "test-command"- assert toolkit.servers[0].args == ["--arg1"]- assert "TEST_ENV" in toolkit.servers[0].env-- # Check web server toolkit- assert toolkit.servers[1].command_or_url == "https://test.com/sse"-- def test_load_servers_from_config_missing_required_fields(self):- r"""Test _load_servers_from_config with missing required fields."""- with patch("camel.toolkits.mcp_toolkit.logger") as mock_logger:- with tempfile.TemporaryDirectory() as temp_dir:- config_path = Path(temp_dir) / "invalid_fields.json"-- # Missing command field- config_data = {"mcpServers": {"server1": {"args": ["--arg1"]}}}- config_path.write_text(json.dumps(config_data))-- mcp_toolkit = MCPToolkit()- servers = mcp_toolkit._load_servers_from_config(- str(config_path)- )- # Should return an empty list and log a warning- assert servers == []- mock_logger.warning.assert_called()-- mock_logger.reset_mock()-- # Missing url field- config_data = {"mcpServers": {"server1": {"timeout": 30}}}- config_path.write_text(json.dumps(config_data))-- servers = mcp_toolkit._load_servers_from_config(- str(config_path)- )- # Should return an empty list and log a warning- assert servers == []- mock_logger.warning.assert_called()-- def test_load_servers_from_config_invalid_structure(self):- r"""Test _load_servers_from_config with invalid structure."""- with patch("camel.toolkits.mcp_toolkit.logger") as mock_logger:- with tempfile.TemporaryDirectory() as temp_dir:- config_path = Path(temp_dir) / "invalid_structure.json"-- # mcpServers is not a dictionary- config_data = {"mcpServers": "not a dictionary"}- config_path.write_text(json.dumps(config_data))-- mcp_toolkit = MCPToolkit()- servers = mcp_toolkit._load_servers_from_config(- str(config_path)- )- # Should return an empty list and log a warning- assert servers == []- mock_logger.warning.assert_called_with(- "'mcpServers' is not a dictionary, skipping..."- )+ assert result is toolkit+ assert toolkit._is_connected@pytest.mark.asyncio- async def test_connection(self):- r"""Test connection context manager."""- # Create mock servers with proper setup- server1 = AsyncMock()- server2 = AsyncMock()+ async def test_create_failure_cleanup(self):+ """Test cleanup on creation failure."""+ mock_client = MagicMock()+ mock_client.disconnect = AsyncMock()++ with patch.object(MCPToolkit, '__init__', return_value=None):+ toolkit = MCPToolkit.__new__(MCPToolkit)+ toolkit.clients = [mock_client]+ toolkit._is_connected = False++ async def failing_connect():+ raise Exception("Connection failed")++ toolkit.connect = failing_connect+ toolkit.disconnect = AsyncMock()++ patch_path = 'camel.toolkits.mcp_toolkit.MCPToolkit.__new__'+ with patch(patch_path, return_value=toolkit):+ expected_msg = "Failed to initialize MCPToolkit"+ with pytest.raises(MCPConnectionError, match=expected_msg):+ await MCPToolkit.create(clients=[mock_client])+++class TestMCPToolkitTools:+ """Test tool management in MCPToolkit."""++ def _create_test_toolkit(self, clients):+ """Helper method to create a toolkit with mock clients."""+ # Mock the parent class initialization to avoid the object.__new__+ # error+ with patch.object(MCPToolkit, '__init__', return_value=None):+ toolkit = MCPToolkit.__new__(MCPToolkit)+ toolkit.clients = clients+ toolkit._is_connected = True+ toolkit._exit_stack = None+ return toolkit++ def test_get_tools(self):+ """Test getting tools from all clients."""+ mock_client1 = MagicMock()+ mock_client2 = MagicMock()++ mock_tool1 = MagicMock()+ mock_tool2 = MagicMock()+ mock_tool3 = MagicMock()++ mock_client1.get_tools.return_value = [mock_tool1, mock_tool2]+ mock_client2.get_tools.return_value = [mock_tool3]+ mock_client1.is_connected.return_value = True+ mock_client2.is_connected.return_value = True++ toolkit = self._create_test_toolkit([mock_client1, mock_client2])++ tools = toolkit.get_tools()++ assert len(tools) == 3+ assert tools == [mock_tool1, mock_tool2, mock_tool3]++ def test_get_tools_not_connected_warning(self):+ """Test warning when getting tools while not connected."""+ mock_client = MagicMock()+ mock_client.get_tools.return_value = []++ toolkit = self._create_test_toolkit([mock_client])+ # Set not connected for this test+ toolkit._is_connected = False++ with patch('camel.toolkits.mcp_toolkit.logger') as mock_logger:+ toolkit.get_tools()++ expected_msg = (+ "MCPToolkit is not connected. "+ "Tools may not be available until connected."+ )+ mock_logger.warning.assert_called_with(expected_msg)++ def test_get_tools_client_error(self):+ """Test handling client errors when getting tools."""+ mock_client1 = MagicMock()+ mock_client2 = MagicMock()++ mock_tool = MagicMock()++ mock_client1.get_tools.side_effect = Exception("Client error")+ mock_client2.get_tools.return_value = [mock_tool]+ mock_client1.is_connected.return_value = True+ mock_client2.is_connected.return_value = True- # Make connect method return the server itself- server1.connect = AsyncMock(return_value=server1)- server2.connect = AsyncMock(return_value=server2)+ toolkit = self._create_test_toolkit([mock_client1, mock_client2])- # Create a proper async context manager for connection- async_cm1 = AsyncMock()- async_cm1.__aenter__.return_value = server1+ with patch('camel.toolkits.mcp_toolkit.logger') as mock_logger:+ tools = toolkit.get_tools()- async_cm2 = AsyncMock()- async_cm2.__aenter__.return_value = server2+ assert len(tools) == 1+ assert tools[0] == mock_tool+ expected_msg = "Failed to get tools from client 1: Client error"+ mock_logger.error.assert_called_with(expected_msg)- # Set up the connection method to return our context manager- server1.connection = MagicMock(return_value=async_cm1)- server2.connection = MagicMock(return_value=async_cm2)+ def test_get_text_tools(self):+ """Test getting text descriptions of tools."""+ mock_client1 = MagicMock()+ mock_client2 = MagicMock()- toolkit = MCPToolkit(servers=[server1, server2])+ mock_client1.get_text_tools.return_value = "Tool 1\nTool 2"+ mock_client2.get_text_tools.return_value = "Tool 3"+ mock_client1.is_connected.return_value = True+ mock_client2.is_connected.return_value = True- # Test connection context manager- async with toolkit.connection() as connected_toolkit:- assert connected_toolkit._connected is True- for server_mock in [server1, server2]:- server_mock.connect.assert_called_once()+ toolkit = self._create_test_toolkit([mock_client1, mock_client2])- # Verify context exit cleans up properly- assert toolkit._connected is False+ text_tools = toolkit.get_text_tools()- def test_is_connected(self):- r"""Test is_connected method."""- toolkit = MCPToolkit(servers=[MCPClient("test_command")])- assert toolkit.is_connected() is False- toolkit._connected = True- assert toolkit.is_connected() is True+ expected = (+ "=== Client 1 Tools ===\nTool 1\nTool 2\n\n"+ "=== Client 2 Tools ===\nTool 3"+ )+ assert text_tools == expected@pytest.mark.asyncio- async def test_get_tools(self):- r"""Test get_tools method."""- server1 = MCPClient("test_command1")- server2 = MCPClient("test_command2")- toolkit = MCPToolkit(servers=[server1, server2])+ async def test_call_tool_success(self):+ """Test successful tool call."""+ mock_client1 = MagicMock()+ mock_client2 = MagicMock()- # Mock get_tools for both serversmock_tool1 = MagicMock()+ mock_tool1.func.__name__ = "tool1"mock_tool2 = MagicMock()- mock_tool3 = MagicMock()+ mock_tool2.func.__name__ = "tool2"- server1.get_tools = MagicMock(return_value=[mock_tool1, mock_tool2])- server2.get_tools = MagicMock(return_value=[mock_tool3])+ mock_client1.get_tools.return_value = [mock_tool1]+ mock_client2.get_tools.return_value = [mock_tool2]+ mock_client2.call_tool = AsyncMock(return_value="tool result")+ mock_client1.is_connected.return_value = True+ mock_client2.is_connected.return_value = True- tools = toolkit.get_tools()+ toolkit = self._create_test_toolkit([mock_client1, mock_client2])- assert len(tools) == 3- assert tools == [mock_tool1, mock_tool2, mock_tool3]- server1.get_tools.assert_called_once()- server2.get_tools.assert_called_once()+ result = await toolkit.call_tool("tool2", {"arg": "value"})++ assert result == "tool result"+ expected_args = ("tool2", {"arg": "value"})+ mock_client2.call_tool.assert_called_once_with(*expected_args)@pytest.mark.asyncio- async def test_connect(self):- r"""Test explicit connect method."""- # Create mock servers- server1 = MCPClient("test_command1")- server2 = MCPClient("test_command2")+ async def test_call_tool_not_connected(self):+ """Test calling tool when not connected."""+ mock_client = MagicMock()- # Mock connect methods- server1.connect = AsyncMock(return_value=server1)- server2.connect = AsyncMock(return_value=server2)+ toolkit = self._create_test_toolkit([mock_client])+ # Set not connected for this test+ toolkit._is_connected = False- # Create toolkit with mock servers- toolkit = MCPToolkit(servers=[server1, server2])+ expected_msg = "MCPToolkit is not connected"+ with pytest.raises(MCPConnectionError, match=expected_msg):+ await toolkit.call_tool("test_tool", {})- # Test connect- result = await toolkit.connect()+ @pytest.mark.asyncio+ async def test_call_tool_not_found(self):+ """Test calling tool that doesn't exist."""+ mock_client = MagicMock()++ mock_tool = MagicMock()+ mock_tool.func.__name__ = "other_tool"+ mock_client.get_tools.return_value = [mock_tool]+ mock_client.is_connected.return_value = True- # Verify results- assert result == toolkit- assert toolkit._connected is True- for server_mock in [server1, server2]:- server_mock.connect.assert_called_once()-- # Test connecting when already connected- with patch("camel.toolkits.mcp_toolkit.logger") as mock_logger:- result = await toolkit.connect()- assert result == toolkit- mock_logger.warning.assert_called_once()- # Verify servers not connected again- assert server1.connect.call_count == 1- assert server2.connect.call_count == 1+ toolkit = self._create_test_toolkit([mock_client])++ expected_msg = "Tool 'nonexistent_tool' not found in any client"+ with pytest.raises(MCPToolError, match=expected_msg):+ await toolkit.call_tool("nonexistent_tool", {})@pytest.mark.asyncio- async def test_connect_failure(self):- r"""Test connect method with failure."""- # Create mock servers- server1 = MCPClient("test_command1")- server2 = MCPClient("test_command2")+ async def test_call_tool_all_clients_fail(self):+ """Test tool call when all clients fail."""+ mock_client1 = MagicMock()+ mock_client2 = MagicMock()- # First server connects successfully, second fails- server1.connect = AsyncMock(return_value=server1)- server2.connect = AsyncMock(side_effect=Exception("Connection error"))+ mock_tool = MagicMock()+ mock_tool.func.__name__ = "test_tool"- # Create toolkit with mock servers- toolkit = MCPToolkit(servers=[server1, server2])+ mock_client1.get_tools.return_value = [mock_tool]+ mock_client2.get_tools.return_value = [mock_tool]- # Test connect with failure - should raise the exception- with pytest.raises(Exception) as excinfo:- await toolkit.connect()+ client1_exc = Exception("Client 1 error")+ client2_exc = Exception("Client 2 error")+ mock_client1.call_tool = AsyncMock(side_effect=client1_exc)+ mock_client2.call_tool = AsyncMock(side_effect=client2_exc)+ mock_client1.is_connected.return_value = True+ mock_client2.is_connected.return_value = True- assert "Connection error" in str(excinfo.value)+ toolkit = self._create_test_toolkit([mock_client1, mock_client2])- # Verify first server was connected- server1.connect.assert_called_once()- # Verify second server was attempted- server2.connect.assert_called_once()+ expected_msg = "Tool 'test_tool' failed on all clients"+ with pytest.raises(MCPToolError, match=expected_msg):+ await toolkit.call_tool("test_tool", {})- @pytest.mark.asyncio- async def test_disconnect(self):- r"""Test explicit disconnect method."""- # Create mock servers- server1 = MCPClient("test_command1")- server2 = MCPClient("test_command2")+ def test_list_available_tools(self):+ """Test listing available tools organized by client."""+ mock_client1 = MagicMock()+ mock_client2 = MagicMock()- # Mock disconnect methods- server1.disconnect = AsyncMock()- server2.disconnect = AsyncMock()+ mock_tool1 = MagicMock()+ mock_tool1.func.__name__ = "tool1"+ mock_tool2 = MagicMock()+ mock_tool2.func.__name__ = "tool2"+ mock_tool3 = MagicMock()+ mock_tool3.func.__name__ = "tool3"- # Create toolkit with mock servers- toolkit = MCPToolkit(servers=[server1, server2])+ mock_client1.get_tools.return_value = [mock_tool1, mock_tool2]+ mock_client2.get_tools.return_value = [mock_tool3]- # Setup connected state- toolkit._connected = True+ toolkit = self._create_test_toolkit([mock_client1, mock_client2])- # Test disconnect- await toolkit.disconnect()+ available_tools = toolkit.list_available_tools()- # Verify results- assert toolkit._connected is False- server1.disconnect.assert_called_once()- server2.disconnect.assert_called_once()+ expected = {"client_1": ["tool1", "tool2"], "client_2": ["tool3"]}+ assert available_tools == expected- # Test disconnecting when not connected- server1.disconnect.reset_mock()- server2.disconnect.reset_mock()+ def test_list_available_tools_with_errors(self):+ """Test listing tools when some clients have errors."""+ mock_client1 = MagicMock()+ mock_client2 = MagicMock()++ mock_tool = MagicMock()+ mock_tool.func.__name__ = "tool1"++ mock_client1.get_tools.side_effect = Exception("Client error")+ mock_client2.get_tools.return_value = [mock_tool]++ toolkit = self._create_test_toolkit([mock_client1, mock_client2])++ with patch('camel.toolkits.mcp_toolkit.logger') as mock_logger:+ available_tools = toolkit.list_available_tools()++ expected = {"client_1": [], "client_2": ["tool1"]}+ assert available_tools == expected+ expected_msg = "Failed to list tools from client 1: Client error"+ mock_logger.error.assert_called_with(expected_msg)- await toolkit.disconnect()- # Verify no actions taken when not connected- server1.disconnect.assert_not_called()- server2.disconnect.assert_not_called()+if __name__ == "__main__":+ pytest.main([__file__])diff --git a/test/utils/test_mcp_client.py b/test/utils/test_mcp_client.pynew file mode 100644index 000000000..7eef9fd4c--- /dev/null+++ b/test/utils/test_mcp_client.py@@ -0,0 +1,525 @@+# ========= 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. =========+"""+Tests for the unified MCP client.+"""++import json+import tempfile+from pathlib import Path+from unittest.mock import MagicMock++import mcp.types as types+import pytest++from camel.utils.mcp_client import (+ MCPClient,+ ServerConfig,+ TransportType,+ create_mcp_client,+ create_mcp_client_from_config_file,+)+++class TestTransportType:+ """Test TransportType enum."""++ def test_transport_type_values(self):+ """Test that TransportType has expected values."""+ assert TransportType.STDIO == "stdio"+ assert TransportType.SSE == "sse"+ assert TransportType.STREAMABLE_HTTP == "streamable_http"+ assert TransportType.WEBSOCKET == "websocket"+++class TestServerConfig:+ """Test ServerConfig validation and transport detection."""++ def test_stdio_config_valid(self):+ """Test valid STDIO configuration."""+ config = ServerConfig(+ command="npx",+ args=["-y", "@modelcontextprotocol/server-filesystem", "/path"],+ )+ assert config.command == "npx"+ assert config.args == [+ "-y",+ "@modelcontextprotocol/server-filesystem",+ "/path",+ ]+ assert config.transport_type == TransportType.STDIO++ def test_http_config_valid(self):+ """Test valid HTTP configuration."""+ config = ServerConfig(+ url="https://api.example.com/mcp",+ headers={"Authorization": "Bearer token"},+ )+ assert config.url == "https://api.example.com/mcp"+ assert config.headers == {"Authorization": "Bearer token"}+ assert config.transport_type == TransportType.STREAMABLE_HTTP++ def test_http_config_prefer_sse(self):+ """Test HTTP configuration with SSE preference."""+ config = ServerConfig(+ url="https://api.example.com/mcp", prefer_sse=True+ )+ assert config.transport_type == TransportType.SSE++ def test_websocket_config_valid(self):+ """Test valid WebSocket configuration."""+ config = ServerConfig(url="ws://localhost:8080/mcp")+ assert config.url == "ws://localhost:8080/mcp"+ assert config.transport_type == TransportType.WEBSOCKET++ def test_websocket_secure_config_valid(self):+ """Test valid secure WebSocket configuration."""+ config = ServerConfig(url="wss://api.example.com/mcp")+ assert config.url == "wss://api.example.com/mcp"+ assert config.transport_type == TransportType.WEBSOCKET++ def test_config_no_command_or_url(self):+ """Test that config without command or url raises ValueError."""+ with pytest.raises(+ ValueError, match="Either 'command'.*or 'url'.*must be provided"+ ):+ ServerConfig()++ def test_config_both_command_and_url(self):+ """Test that config with both command and url raises ValueError."""+ with pytest.raises(+ ValueError, match="Cannot specify both 'command' and 'url'"+ ):+ ServerConfig(command="npx", url="https://api.example.com/mcp")++ def test_unsupported_url_scheme(self):+ """Test that unsupported URL scheme raises ValueError."""+ config = ServerConfig(url="ftp://example.com/mcp")+ with pytest.raises(ValueError, match="Unsupported URL scheme"):+ _ = config.transport_type++ def test_config_defaults(self):+ """Test default configuration values."""+ config = ServerConfig(command="test")+ assert config.timeout == 30.0+ assert config.encoding == "utf-8"+ assert config.sse_read_timeout == 300.0+ assert config.terminate_on_close is True+ assert config.prefer_sse is False++ def test_config_with_optional_stdio_params(self):+ """Test STDIO config with optional parameters."""+ config = ServerConfig(+ command="python",+ args=["server.py"],+ env={"VAR": "value"},+ cwd="/tmp",+ encoding="utf-16",+ )+ assert config.command == "python"+ assert config.args == ["server.py"]+ assert config.env == {"VAR": "value"}+ assert config.cwd == "/tmp"+ assert config.encoding == "utf-16"+++class TestMCPClient:+ """Test MCPClient class."""++ def test_init_with_server_config(self):+ """Test MCPClient initialization with ServerConfig."""+ config = ServerConfig(command="npx", args=["test"])+ client = MCPClient(config)+ assert client.config == config+ assert client.transport_type == TransportType.STDIO+ assert client.session is None+ assert not client.is_connected()++ def test_init_with_dict_config(self):+ """Test MCPClient initialization with dict config."""+ config_dict = {"command": "npx", "args": ["test"]}+ client = MCPClient(config_dict)+ assert isinstance(client.config, ServerConfig)+ assert client.config.command == "npx"+ assert client.config.args == ["test"]++ def test_init_with_client_info(self):+ """Test MCPClient initialization with client info."""+ config = ServerConfig(command="npx", args=["test"])+ client_info = types.Implementation(name="test-client", version="1.0.0")+ client = MCPClient(config, client_info=client_info)+ assert client.client_info == client_info++ def test_init_with_invalid_config(self):+ """Test MCPClient initialization with invalid config."""+ with pytest.raises(ValueError):+ MCPClient({}) # No command or url++ def test_transport_type_property(self):+ """Test that transport_type property works correctly."""+ # STDIO+ client1 = MCPClient({"command": "test"})+ assert client1.transport_type == TransportType.STDIO++ # HTTP+ client2 = MCPClient({"url": "https://example.com"})+ assert client2.transport_type == TransportType.STREAMABLE_HTTP++ # WebSocket+ client3 = MCPClient({"url": "ws://example.com"})+ assert client3.transport_type == TransportType.WEBSOCKET++ # SSE+ client4 = MCPClient({"url": "https://example.com", "prefer_sse": True})+ assert client4.transport_type == TransportType.SSE++ def test_session_properties(self):+ """Test session property and is_connected method."""+ config = ServerConfig(command="test")+ client = MCPClient(config)++ # Initially not connected+ assert client.session is None+ assert not client.is_connected()++ # Simulate connection by setting session+ mock_session = MagicMock()+ client._session = mock_session++ assert client.session == mock_session+ assert client.is_connected()++ # Clear session+ client._session = None+ assert client.session is None+ assert not client.is_connected()+++class TestCreateMCPClient:+ """Test create_mcp_client factory function."""++ def test_create_from_dict(self):+ """Test creating client from dict config."""+ config_dict = {"command": "npx", "args": ["test"]}+ client = create_mcp_client(config_dict)+ assert isinstance(client, MCPClient)+ assert client.config.command == "npx"+ assert client.config.args == ["test"]++ def test_create_from_server_config(self):+ """Test creating client from ServerConfig object."""+ config = ServerConfig(command="npx", args=["test"])+ client = create_mcp_client(config)+ assert isinstance(client, MCPClient)+ assert client.config == config++ def test_create_with_client_info(self):+ """Test creating client with client_info parameter."""+ config_dict = {"command": "npx", "args": ["test"]}+ client_info = types.Implementation(name="test", version="1.0")+ client = create_mcp_client(config_dict, client_info=client_info)+ assert client.client_info == client_info+++class TestCreateMCPClientFromConfigFile:+ """Test create_mcp_client_from_config_file function."""++ def test_create_from_config_file(self):+ """Test creating client from config file."""+ config_data = {+ "mcpServers": {+ "filesystem": {+ "command": "npx",+ "args": [+ "-y",+ "@modelcontextprotocol/server-filesystem",+ "/path",+ ],+ },+ "remote-server": {+ "url": "https://api.example.com/mcp",+ "headers": {"Authorization": "Bearer token"},+ },+ }+ }++ with tempfile.NamedTemporaryFile(+ mode="w", suffix=".json", delete=False+ ) as f:+ json.dump(config_data, f)+ config_path = f.name++ try:+ client = create_mcp_client_from_config_file(+ config_path, "filesystem"+ )+ assert isinstance(client, MCPClient)+ assert client.config.command == "npx"+ assert client.config.args == [+ "-y",+ "@modelcontextprotocol/server-filesystem",+ "/path",+ ]+ assert client.transport_type == TransportType.STDIO+ finally:+ Path(config_path).unlink()++ def test_create_from_config_file_http_server(self):+ """Test creating HTTP client from config file."""+ config_data = {+ "mcpServers": {+ "remote-server": {+ "url": "https://api.example.com/mcp",+ "headers": {"Authorization": "Bearer token"},+ }+ }+ }++ with tempfile.NamedTemporaryFile(+ mode="w", suffix=".json", delete=False+ ) as f:+ json.dump(config_data, f)+ config_path = f.name++ try:+ client = create_mcp_client_from_config_file(+ config_path, "remote-server"+ )+ assert isinstance(client, MCPClient)+ assert client.config.url == "https://api.example.com/mcp"+ assert client.config.headers == {"Authorization": "Bearer token"}+ assert client.transport_type == TransportType.STREAMABLE_HTTP+ finally:+ Path(config_path).unlink()++ def test_create_from_config_file_server_not_found(self):+ """Test error when server not found in config file."""+ config_data = {+ "mcpServers": {"filesystem": {"command": "npx", "args": ["test"]}}+ }++ with tempfile.NamedTemporaryFile(+ mode="w", suffix=".json", delete=False+ ) as f:+ json.dump(config_data, f)+ config_path = f.name++ try:+ with pytest.raises(+ ValueError, match="Server 'nonexistent' not found"+ ):+ create_mcp_client_from_config_file(config_path, "nonexistent")+ finally:+ Path(config_path).unlink()++ def test_create_from_config_file_no_mcp_servers(self):+ """Test config file without mcpServers section."""+ config_data = {"other": "data"}++ with tempfile.NamedTemporaryFile(+ mode="w", suffix=".json", delete=False+ ) as f:+ json.dump(config_data, f)+ config_path = f.name++ try:+ with pytest.raises(ValueError, match="Server 'test' not found"):+ create_mcp_client_from_config_file(config_path, "test")+ finally:+ Path(config_path).unlink()++ def test_create_from_config_file_with_kwargs(self):+ """Test creating client from config file with additional kwargs."""+ config_data = {+ "mcpServers": {"test": {"command": "npx", "args": ["test"]}}+ }++ with tempfile.NamedTemporaryFile(+ mode="w", suffix=".json", delete=False+ ) as f:+ json.dump(config_data, f)+ config_path = f.name++ try:+ client_info = types.Implementation(name="test", version="1.0")+ client = create_mcp_client_from_config_file(+ config_path, "test", client_info=client_info+ )+ assert client.client_info == client_info+ finally:+ Path(config_path).unlink()++ def test_create_from_config_file_invalid_json(self):+ """Test creating client from invalid JSON file."""+ with tempfile.NamedTemporaryFile(+ mode="w", suffix=".json", delete=False+ ) as f:+ f.write("invalid json content")+ config_path = f.name++ try:+ with pytest.raises(json.JSONDecodeError):+ create_mcp_client_from_config_file(config_path, "test")+ finally:+ Path(config_path).unlink()+++class TestIntegration:+ """Integration tests for the MCP client."""++ def test_stdio_server_configuration(self):+ """Test complete STDIO server configuration."""+ client = create_mcp_client(+ {+ "command": "python",+ "args": ["-m", "server"],+ "env": {"DEBUG": "1"},+ "cwd": "/tmp",+ "timeout": 60.0,+ "encoding": "utf-8",+ }+ )++ assert client.transport_type == TransportType.STDIO+ assert client.config.command == "python"+ assert client.config.args == ["-m", "server"]+ assert client.config.env == {"DEBUG": "1"}+ assert client.config.cwd == "/tmp"+ assert client.config.timeout == 60.0+ assert client.config.encoding == "utf-8"++ def test_http_server_configuration(self):+ """Test complete HTTP server configuration."""+ client = create_mcp_client(+ {+ "url": "https://api.example.com/mcp",+ "headers": {+ "Authorization": "Bearer token",+ "User-Agent": "test-client/1.0",+ },+ "timeout": 45.0,+ "sse_read_timeout": 600.0,+ "terminate_on_close": False,+ }+ )++ assert client.transport_type == TransportType.STREAMABLE_HTTP+ assert client.config.url == "https://api.example.com/mcp"+ assert client.config.headers["Authorization"] == "Bearer token"+ assert client.config.headers["User-Agent"] == "test-client/1.0"+ assert client.config.timeout == 45.0+ assert client.config.sse_read_timeout == 600.0+ assert client.config.terminate_on_close is False++ def test_websocket_server_configuration(self):+ """Test complete WebSocket server configuration."""+ client = create_mcp_client(+ {"url": "wss://api.example.com/mcp", "timeout": 30.0}+ )++ assert client.transport_type == TransportType.WEBSOCKET+ assert client.config.url == "wss://api.example.com/mcp"+ assert client.config.timeout == 30.0+++class TestEdgeCases:+ """Test edge cases and error conditions."""++ def test_config_with_path_object(self):+ """Test config with Path object for cwd."""+ config = ServerConfig(command="python", cwd=Path("/tmp"))+ assert config.cwd == Path("/tmp")+ assert config.transport_type == TransportType.STDIO++ def test_config_with_empty_headers(self):+ """Test config with empty headers dict."""+ config = ServerConfig(url="https://api.example.com/mcp", headers={})+ assert config.headers == {}+ assert config.transport_type == TransportType.STREAMABLE_HTTP++ def test_config_edge_case_url_schemes(self):+ """Test various URL scheme edge cases."""+ # Test uppercase schemes+ config1 = ServerConfig(url="HTTP://api.example.com/mcp")+ # Note: This will actually fail because startswith() is case-sensitive+ # This is expected behavior - URLs should use lowercase schemes+ with pytest.raises(ValueError, match="Unsupported URL scheme"):+ _ = config1.transport_type++ # Test URL with port+ config2 = ServerConfig(url="https://api.example.com:8443/mcp")+ assert config2.transport_type == TransportType.STREAMABLE_HTTP++ # Test WebSocket with port+ config3 = ServerConfig(url="ws://localhost:8080/mcp")+ assert config3.transport_type == TransportType.WEBSOCKET++ def test_client_session_property_when_not_connected(self):+ """Test session property when not connected."""+ config = ServerConfig(command="test")+ client = MCPClient(config)++ assert client.session is None+ assert not client.is_connected()++ def test_invalid_transport_detection(self):+ """Test error conditions in transport type detection."""+ # Test missing command and URL - this should be caught by validation+ with pytest.raises(ValueError):+ ServerConfig()++ def test_config_validation_edge_cases(self):+ """Test additional config validation edge cases."""+ # Test that we can't have both command and URL+ with pytest.raises(ValueError, match="Cannot specify both"):+ ServerConfig(command="test", url="https://example.com")++ # Test empty command string - this should fail validation since empty string is falsy # noqa: E501+ with pytest.raises(+ ValueError, match="Either 'command'.*or 'url'.*must be provided"+ ):+ ServerConfig(command="")++ # Test empty URL string - this should also fail validation+ with pytest.raises(+ ValueError, match="Either 'command'.*or 'url'.*must be provided"+ ):+ ServerConfig(url="")++ def test_client_initialization_variations(self):+ """Test different ways to initialize the client."""+ # Test with minimal config+ client1 = MCPClient({"command": "test"})+ assert client1.config.command == "test"++ # Test with comprehensive config+ client2 = MCPClient(+ {+ "url": "wss://api.example.com/mcp",+ "timeout": 120.0,+ "sse_read_timeout": 600.0,+ }+ )+ assert client2.config.url == "wss://api.example.com/mcp"+ assert client2.config.timeout == 120.0++ # Test with client_info+ client_info = types.Implementation(name="test", version="2.0")+ client3 = MCPClient({"command": "test"}, client_info=client_info)+ assert client3.client_info.name == "test"+ assert client3.client_info.version == "2.0"+++if __name__ == "__main__":+ pytest.main([__file__])diff --git a/test/utils/test_mcp_server.py b/test/utils/test_mcp_server.pyindex 6f79868a3..26e0b8e95 100644--- a/test/utils/test_mcp_server.py+++ b/test/utils/test_mcp_server.py@@ -13,7 +13,7 @@# ========= Copyright 2023-2024 @ CAMEL-AI.org. All Rights Reserved. =========import asyncioimport sys-from typing import TYPE_CHECKING, Literal+from typing import Literalimport pytestfrom mcp.server import FastMCP@@ -21,9 +21,6 @@ from mcp.server import FastMCPfrom camel.toolkits.mcp_toolkit import MCPClientfrom camel.utils import MCPServer-if TYPE_CHECKING:- from mcp import ClientSession-@MCPServer(server_name="TextProcessorForMCP",@@ -94,31 +91,28 @@ def test_tool_schema():@pytest.mark.asyncioasync def test_async_word_count():processor = TextProcessorForMCP()- server = MCPClient(- command_or_url=sys.executable,- args=[__file__, "--server"],- )- await server.connect()- session: "ClientSession" = server._session-- text = "hello world"-- result = await session.call_tool(- name="reverse_text",- arguments={"text": text},- )- assert len(result.content) == 1- assert result.content[0].text == processor.reverse_text(text)-- result = await session.call_tool(- name="async_word_count",- arguments={"text": text},- )- assert len(result.content) == 1- assert int(result.content[0].text) == await processor.async_word_count(- text- )- await server.disconnect()+ async with MCPClient(+ config={+ "command": sys.executable,+ "args": [__file__, "--server"],+ }+ ) as client:+ text = "hello world"+ result = await client.call_tool(+ tool_name="reverse_text",+ arguments={"text": text},+ )+ assert len(result.content) == 1+ assert result.content[0].text == processor.reverse_text(text)++ result = await client.call_tool(+ tool_name="async_word_count",+ arguments={"text": text},+ )+ assert len(result.content) == 1+ assert int(result.content[0].text) == await processor.async_word_count(+ text+ )if __name__ == "__main__":