Skip to content

armgit / camel

Public Imported from GitHub
0

🐫 CAMEL: The first and the best multi-agent framework. Finding the Scaling Law of Agents. https://www.camel-ai.org

feat: integrate MCP client as a Toolkit (#1755)

koch30924582aa909a4e
diff --git a/camel/toolkits/__init__.py b/camel/toolkits/__init__.py
index 393d12b23..c56aa7c6b 100644
--- a/camel/toolkits/__init__.py
+++ b/camel/toolkits/__init__.py
@@ -54,6 +54,7 @@ from .audio_analysis_toolkit import AudioAnalysisToolkit
from .excel_toolkit import ExcelToolkit
from .video_analysis_toolkit import VideoAnalysisToolkit
from .image_analysis_toolkit import ImageAnalysisToolkit
+from .mcp_toolkit import MCPToolkit
from .web_toolkit import WebToolkit
from .terminal_toolkit import TerminalToolkit
@@ -94,6 +95,7 @@ __all__ = [
'ZapierToolkit',
'SymPyToolkit',
'MinerUToolkit',
+ 'MCPToolkit',
'AudioAnalysisToolkit',
'ExcelToolkit',
'VideoAnalysisToolkit',
diff --git a/camel/toolkits/mcp_toolkit.py b/camel/toolkits/mcp_toolkit.py
new file mode 100644
index 000000000..af03a37a0
--- /dev/null
+++ b/camel/toolkits/mcp_toolkit.py
@@ -0,0 +1,251 @@
+# ========= 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. =========
+import inspect
+from contextlib import AsyncExitStack, asynccontextmanager
+from typing import (
+ TYPE_CHECKING,
+ Any,
+ Callable,
+ Dict,
+ List,
+ Optional,
+ Set,
+ Union,
+)
+from urllib.parse import urlparse
+
+if TYPE_CHECKING:
+ from mcp import ListToolsResult, Tool
+
+from camel.toolkits import BaseToolkit, FunctionTool
+
+
+class MCPToolkit(BaseToolkit):
+ r"""MCPToolkit provides an abstraction layer to interact with external
+ tools using the Model Context Protocol (MCP). It supports two modes of
+ connection:
+
+ 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.
+
+ 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'`)
+ """
+
+ def __init__(
+ self,
+ command_or_url: str,
+ args: Optional[List[str]] = None,
+ env: Optional[Dict[str, str]] = None,
+ timeout: Optional[float] = None,
+ ):
+ from mcp import Tool
+ from mcp.client.session import ClientSession
+
+ super().__init__(timeout=timeout)
+
+ self.command_or_url = command_or_url
+ self.args = args or []
+ self.env = env or {}
+
+ self._mcp_tools: List[Tool] = []
+ self._session: Optional['ClientSession'] = None
+ self._exit_stack = AsyncExitStack()
+ self._is_connected = False
+
+ @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`.
+
+ Yields:
+ MCPToolkit: Instance with active connection ready for tool
+ interaction.
+ """
+ from mcp.client.session import ClientSession
+ from mcp.client.sse import sse_client
+ from mcp.client.stdio import StdioServerParameters, stdio_client
+
+ try:
+ if urlparse(self.command_or_url).scheme in ("http", "https"):
+ (
+ read_stream,
+ write_stream,
+ ) = await self._exit_stack.enter_async_context(
+ sse_client(self.command_or_url)
+ )
+ else:
+ server_parameters = StdioServerParameters(
+ command=self.command_or_url, args=self.args, env=self.env
+ )
+ (
+ read_stream,
+ write_stream,
+ ) = await self._exit_stack.enter_async_context(
+ stdio_client(server_parameters)
+ )
+
+ self._session = await self._exit_stack.enter_async_context(
+ ClientSession(read_stream, write_stream)
+ )
+ await self._session.initialize()
+ list_tools_result = await self.list_mcp_tools()
+ self._mcp_tools = list_tools_result.tools
+ self._is_connected = True
+ yield self
+
+ finally:
+ self._is_connected = False
+ await self._exit_stack.aclose()
+ self._session = None
+
+ async def list_mcp_tools(self) -> Union[str, "ListToolsResult"]:
+ 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:
+ return f"Failed to list MCP tools: {e!s}"
+
+ def generate_function_from_mcp_tool(self, mcp_tool: "Tool") -> Callable:
+ r"""Dynamically generates a Python callable function corresponding to
+ a given MCP tool.
+
+ Args:
+ 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.
+ """
+ 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):
+ 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:
+ raise ValueError(
+ f"Missing required parameters: {missing_params}"
+ )
+
+ result: CallToolResult = await self._session.call_tool(
+ func_name, kwargs
+ )
+
+ if not result.content:
+ return "No data available for this request."
+
+ # Handle different content types
+ 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."
+
+ 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 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.
+
+ Returns:
+ List[FunctionTool]: A list of FunctionTool objects
+ representing the functions in the toolkit.
+ """
+ return [
+ FunctionTool(self.generate_function_from_mcp_tool(mcp_tool))
+ for mcp_tool in self._mcp_tools
+ ]
diff --git a/examples/toolkits/mcp/mcp_server.py b/examples/toolkits/mcp/mcp_server.py
new file mode 100755
index 000000000..7f02d5741
--- /dev/null
+++ b/examples/toolkits/mcp/mcp_server.py
@@ -0,0 +1,136 @@
+# ========= 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. =========
+from typing import Any
+
+import httpx
+from mcp.server.fastmcp import FastMCP
+
+mcp = FastMCP("weather")
+
+NWS_API_BASE = "https://api.weather.gov"
+USER_AGENT = "weather-app/1.0"
+
+
+async def make_nws_request(url: str) -> dict[str, Any] | None:
+ r"""Make a request to the NWS API with proper error handling."""
+ headers = {"User-Agent": USER_AGENT, "Accept": "application/geo+json"}
+ async with httpx.AsyncClient() as client:
+ try:
+ response = await client.get(url, headers=headers, timeout=30.0)
+ response.raise_for_status()
+ return response.json()
+ except Exception:
+ return None
+
+
+def format_alert(feature: dict) -> str:
+ r"""Format an alert feature into a readable string."""
+ props = feature["properties"]
+ return f"""
+Event: {props.get('event', 'Unknown')}
+Area: {props.get('areaDesc', 'Unknown')}
+Severity: {props.get('severity', 'Unknown')}
+Description: {props.get('description', 'No description available')}
+Instructions: {props.get('instruction', 'No specific instructions provided')}
+"""
+
+
+async def get_alerts(state: str) -> str:
+ r"""Get weather alerts for a US state.
+
+ Args:
+ state: Two-letter US state code (e.g. CA, NY)
+ """
+ url = f"{NWS_API_BASE}/alerts/active/area/{state}"
+ data = await make_nws_request(url)
+
+ if not data or "features" not in data:
+ return "Unable to fetch alerts or no alerts found."
+
+ if not data["features"]:
+ return "No active alerts for this state."
+
+ alerts = [format_alert(feature) for feature in data["features"]]
+ return "\n---\n".join(alerts)
+
+
+async def get_forecast(latitude: float, longitude: float) -> str:
+ r"""Get weather forecast for a location.
+
+ Args:
+ latitude: Latitude of the location
+ longitude: Longitude of the location
+ """
+ # First get the forecast grid endpoint
+ points_url = f"{NWS_API_BASE}/points/{latitude},{longitude}"
+ points_data = await make_nws_request(points_url)
+
+ if not points_data:
+ return "Unable to fetch forecast data for this location."
+
+ # Get the forecast URL from the points response
+ forecast_url = points_data["properties"]["forecast"]
+ forecast_data = await make_nws_request(forecast_url)
+
+ if not forecast_data:
+ return "Unable to fetch detailed forecast."
+
+ # Format the periods into a readable forecast
+ periods = forecast_data["properties"]["periods"]
+ forecasts = []
+ for period in periods[:5]: # Only show next 5 periods
+ forecast = f"""
+{period['name']}:
+Temperature: {period['temperature']}°{period['temperatureUnit']}
+Wind: {period['windSpeed']} {period['windDirection']}
+Forecast: {period['detailedForecast']}
+"""
+ forecasts.append(forecast)
+
+ return "\n---\n".join(forecasts)
+
+
+def main(transport: str = "stdio"):
+ r"""Weather MCP Server
+
+ This server provides weather-related functionalities implemented via the Model Context Protocol (MCP).
+ It demonstrates how to establish interactions between AI models and external tools using MCP.
+
+ The server supports two modes of operation:
+
+ 1. stdio mode (default):
+
+ - Communicates with clients via standard input/output streams, ideal for local command-line usage.
+
+ - Example usage: python mcp_server.py [--transport stdio]
+
+ 2. SSE mode (Server-Sent Events):
+
+ - Communicates with clients over HTTP using server-sent events, suitable for persistent network connections.
+
+ - Runs by default at http://127.0.0.1:8000.
+
+ - Example usage: python mcp_server.py --transport sse
+ """ # noqa: E501
+ if transport == 'stdio':
+ mcp.run(transport='stdio')
+ elif transport == 'sse':
+ mcp.run(transport='sse')
+
+
+if __name__ == "__main__":
+ # Hardcoded to use stdio transport mode
+ main("stdio")
diff --git a/examples/toolkits/mcp/mcp_toolkit.py b/examples/toolkits/mcp/mcp_toolkit.py
new file mode 100644
index 000000000..107226822
--- /dev/null
+++ b/examples/toolkits/mcp/mcp_toolkit.py
@@ -0,0 +1,108 @@
+# ========= 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. =========
+import asyncio
+import sys
+from pathlib import Path
+
+from camel.agents import ChatAgent
+from camel.configs.openai_config import ChatGPTConfig
+from camel.models import ModelFactory
+from camel.toolkits import MCPToolkit
+from camel.types import ModelPlatformType, ModelType
+
+
+async def main(server_transport: str = "stdio"):
+ if server_transport == "stdio":
+ mcp_toolkit = MCPToolkit(
+ command_or_url=sys.executable,
+ args=[str(Path(__file__).parent / "mcp_server.py")],
+ )
+ else:
+ # SSE mode, Must run the server first
+ mcp_toolkit = MCPToolkit("http://127.0.0.1:8000/sse")
+
+ async with mcp_toolkit.connection() as toolkit:
+ tools = toolkit.get_tools()
+
+ # Define system message
+ sys_msg = "You are a helpful assistant"
+ model_config_dict = ChatGPTConfig(
+ temperature=0.0,
+ ).as_dict()
+
+ model = ModelFactory.create(
+ model_platform=ModelPlatformType.DEFAULT,
+ model_type=ModelType.DEFAULT,
+ model_config_dict=model_config_dict,
+ )
+
+ # Set agent
+ camel_agent = ChatAgent(
+ system_message=sys_msg,
+ model=model,
+ tools=tools,
+ )
+ camel_agent.reset()
+
+ # Define a user message
+ usr_msg = "How is the weather in Chicago today?"
+
+ # Get response information
+ response = await camel_agent.astep(usr_msg)
+ print(str(response.info['tool_calls']))
+ """
+ =======================================================================
+ [ToolCallingRecord(tool_name='get_forecast', args={'latitude': 41.
+ 8781, 'longitude': -87.6298}, result='\nThis Afternoon:\nTemperature:
+ 65°F\nWind: 15 mph SW\nForecast: Sunny, with a high near 65. Southwest
+ wind around 15 mph, with gusts as high as 25 mph.
+ \n\n---\n\nTonight:\nTemperature: 45°F\nWind: 10 to 15 mph
+ SW\nForecast: Mostly clear. Low around 45, with temperatures rising to
+ around 51 overnight. Southwest wind 10 to 15 mph, with gusts as high
+ as 30 mph.\n\n---\n\nTuesday:\nTemperature: 46°F\nWind: 10 to 20 mph
+ NW\nForecast: Mostly sunny. High near 46, with temperatures falling
+ to around 36 in the afternoon. Northwest wind 10 to 20 mph, with
+ gusts as high as 35 mph.\n\n---\n\nTuesday Night:\nTemperature: 36°
+ F\nWind: 10 to 20 mph ENE\nForecast: Partly cloudy, with a low around
+ 36. East northeast wind 10 to 20 mph.
+ \n\n---\n\nWednesday:\nTemperature: 46°F\nWind: 5 to 15 mph
+ E\nForecast: Mostly sunny, with a high near 46. East wind 5 to 15 mph.
+ \n', tool_call_id='call_DJjGYAzqlzb5ojirRAuKZmtk')]
+ =======================================================================
+ """
+
+ usr_msg = "Please get the latest 3 weather alerts for California."
+
+ # Get response information
+ response = await camel_agent.astep(usr_msg)
+ print(str(response.info['tool_calls']))
+ """
+ =======================================================================
+ [ToolCallingRecord(tool_name='get_alerts', args={'state': 'CA'}, result
+ ='\nEvent: Wind Advisory\nArea: Central Siskiyou County\nSeverity:
+ Moderate\nDescription: * WHAT...South winds 20 to 30 mph with gusts up
+ to 50 mph expected.\n\n* WHERE...Portions of central Siskiyou County.
+ This includes\nInterstate 5 from Weed to Grenada and portions of
+ Highway 97.\n\n* WHEN...Until 5 PM PDT this afternoon.\n\n* IMPACTS...
+ Gusty winds will blow around unsecured objects. Tree\nlimbs could be
+ blown down and a few power outages may result.\nInstructions: Winds
+ this strong can make driving difficult, especially for high\nprofile
+ vehicles. Use extra caution.\n\nSecure outdoor objects.\n',
+ tool_call_id='call_JRDYuTjOjYrymXeFiWxcHZ5d')]
+ =======================================================================
+ """
+
+
+if __name__ == "__main__":
+ asyncio.run(main())
diff --git a/pyproject.toml b/pyproject.toml
index f3abff150..ec3f966b5 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -148,6 +148,8 @@ dev_tools = [
"e2b-code-interpreter>=1.0.3,<2",
"tree-sitter-python>=0.23.6,<0.24",
"tree-sitter>=0.23.2,<0.24",
+ "typer>=0.15.2",
+ "mcp>=1.3.0",
]
model_platforms = [
"litellm>=1.38.1,<2",
@@ -273,6 +275,8 @@ all = [
"scenedetect>=0.6.5.2",
"playwright>=1.50.0",
"html2text>=2024.2.26",
+ "mcp>=1.3.0",
+ "typer>=0.15.2",
]
[project.urls]
@@ -444,5 +448,7 @@ module = [
"scenedetect",
"playwright",
"html2text",
+ "mcp",
+ "typer",
]
ignore_missing_imports = true
diff --git a/test/toolkits/test_mcp_toolkit.py b/test/toolkits/test_mcp_toolkit.py
new file mode 100644
index 000000000..0424a2c55
--- /dev/null
+++ b/test/toolkits/test_mcp_toolkit.py
@@ -0,0 +1,280 @@
+# ========= 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. =========
+from unittest.mock import AsyncMock, MagicMock, patch
+
+import pytest
+
+from camel.toolkits.mcp_toolkit import MCPToolkit
+
+
+async def test_init():
+ r"""Test initialization of MCPToolkit."""
+ # Test with default parameters
+ toolkit = MCPToolkit("test_command")
+ assert toolkit.command_or_url == "test_command"
+ assert toolkit.args == []
+ assert toolkit.env == {}
+ assert toolkit._mcp_tools == []
+ assert toolkit._session is None
+ assert toolkit._is_connected is False
+
+ # Test with custom parameters
+ toolkit = MCPToolkit(
+ "test_url",
+ args=["--arg1", "--arg2"],
+ env={"ENV_VAR": "value"},
+ timeout=30,
+ )
+ assert toolkit.command_or_url == "test_url"
+ assert toolkit.args == ["--arg1", "--arg2"]
+ assert toolkit.env == {"ENV_VAR": "value"}
+ assert toolkit._mcp_tools == []
+ assert toolkit._session is None
+ assert toolkit._is_connected is False
+
+
+async def test_connection_http():
+ 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,
+ )
+
+ mock_session_instance = AsyncMock()
+ mock_session.return_value.__aenter__.return_value = (
+ mock_session_instance
+ )
+
+ # Mock list_tools result
+ list_tools_result = MagicMock()
+ list_tools_result.tools = ["tool1", "tool2"]
+ mock_session_instance.list_tools.return_value = list_tools_result
+
+ # Test HTTP connection
+ toolkit = MCPToolkit("https://example.com/api")
+ async with toolkit.connection() as connected_toolkit:
+ assert connected_toolkit._is_connected is True
+ assert connected_toolkit._mcp_tools == ["tool1", "tool2"]
+
+ # Verify mocks were called correctly
+ mock_sse_client.assert_called_once_with("https://example.com/api")
+ mock_session.assert_called_once()
+ mock_session_instance.initialize.assert_called_once()
+ mock_session_instance.list_tools.assert_called_once()
+
+
+async def test_connection_stdio():
+ 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,
+ )
+
+ mock_session_instance = AsyncMock()
+ mock_session.return_value.__aenter__.return_value = (
+ mock_session_instance
+ )
+
+ # Mock list_tools result
+ list_tools_result = MagicMock()
+ list_tools_result.tools = ["tool1", "tool2"]
+ mock_session_instance.list_tools.return_value = list_tools_result
+
+ # Test stdio connection
+ toolkit = MCPToolkit(
+ "local_command", args=["--arg1"], env={"ENV_VAR": "value"}
+ )
+ async with toolkit.connection() as connected_toolkit:
+ assert connected_toolkit._is_connected is True
+ assert connected_toolkit._mcp_tools == ["tool1", "tool2"]
+
+ # 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()
+
+
+async def test_list_mcp_tools_not_connected():
+ r"""Test list_mcp_tools when not connected."""
+ toolkit = MCPToolkit("test_command")
+ result = await toolkit.list_mcp_tools()
+ assert isinstance(result, str)
+ assert "not connected" in result
+
+
+async def test_list_mcp_tools_connected():
+ r"""Test list_mcp_tools when connected."""
+ toolkit = MCPToolkit("test_command")
+ toolkit._session = AsyncMock()
+
+ # Mock successful response
+ mock_result = MagicMock()
+ toolkit._session.list_tools.return_value = mock_result
+
+ result = await toolkit.list_mcp_tools()
+ assert result == mock_result
+ toolkit._session.list_tools.assert_called_once()
+
+ # Mock exception
+ toolkit._session.list_tools.side_effect = Exception("Test error")
+ result = await toolkit.list_mcp_tools()
+ assert isinstance(result, str)
+ assert "Failed to list MCP tools" in result
+
+
+async def test_generate_function_from_mcp_tool():
+ r"""Test generate_function_from_mcp_tool."""
+ toolkit = MCPToolkit("test_command")
+ toolkit._session = 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"],
+ }
+
+ # Generate function
+ func = toolkit.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]
+ toolkit._session.call_tool.return_value = mock_result
+
+ # Test function call
+ result = await func(param1="test", param2=123)
+ assert result == "Test result"
+ toolkit._session.call_tool.assert_called_once_with(
+ "test_function", {"param1": "test", "param2": 123}
+ )
+
+ # Test missing required parameter
+ with pytest.raises(ValueError) as excinfo:
+ await func(param1="test")
+ assert "Missing required parameters" in str(excinfo.value)
+
+ # 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
+
+
+async def test_get_tools():
+ r"""Test get_tools method."""
+ with patch(
+ "camel.toolkits.mcp_toolkit.FunctionTool"
+ ) as mock_function_tool:
+ toolkit = MCPToolkit("test_command")
+
+ # Mock tools
+ mock_tool1 = MagicMock()
+ mock_tool2 = MagicMock()
+ toolkit._mcp_tools = [mock_tool1, mock_tool2]
+
+ # Mock generate_function_from_mcp_tool
+ mock_func1 = AsyncMock()
+ mock_func2 = AsyncMock()
+ toolkit.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,
+ ]
+
+ # Get tools
+ tools = toolkit.get_tools()
+
+ # Verify results
+ assert len(tools) == 2
+ assert tools[0] == mock_function_tool_instance1
+ assert tools[1] == mock_function_tool_instance2
+
+ # Verify mocks were called correctly
+ toolkit.generate_function_from_mcp_tool.assert_any_call(mock_tool1)
+ toolkit.generate_function_from_mcp_tool.assert_any_call(mock_tool2)
+ mock_function_tool.assert_any_call(mock_func1)
+ mock_function_tool.assert_any_call(mock_func2)
diff --git a/uv.lock b/uv.lock
index aaf2107c6..0518b8dd4 100644
--- a/uv.lock
+++ b/uv.lock
@@ -564,6 +564,7 @@ all = [
{ name = "jupyter-client" },
{ name = "linkup-sdk" },
{ name = "litellm" },
+ { name = "mcp" },
{ name = "mistralai" },
{ name = "mock" },
{ name = "mypy" },
@@ -614,6 +615,7 @@ all = [
{ name = "transformers" },
{ name = "tree-sitter" },
{ name = "tree-sitter-python" },
+ { name = "typer" },
{ name = "types-colorama" },
{ name = "types-mock" },
{ name = "types-pyyaml" },
@@ -668,8 +670,10 @@ dev-tools = [
{ name = "e2b-code-interpreter" },
{ name = "ipykernel" },
{ name = "jupyter-client" },
+ { name = "mcp" },
{ name = "tree-sitter" },
{ name = "tree-sitter-python" },
+ { name = "typer" },
]
docs = [
{ name = "docutils" },
@@ -845,6 +849,8 @@ requires-dist = [
{ name = "linkup-sdk", marker = "extra == 'web-tools'", specifier = ">=0.2.1,<0.3" },
{ name = "litellm", marker = "extra == 'all'", specifier = ">=1.38.1,<2" },
{ name = "litellm", marker = "extra == 'model-platforms'", specifier = ">=1.38.1,<2" },
+ { name = "mcp", marker = "extra == 'all'", specifier = ">=1.3.0" },
+ { name = "mcp", marker = "extra == 'dev-tools'", specifier = ">=1.3.0" },
{ name = "mistralai", marker = "extra == 'all'", specifier = ">=1.1.0,<2" },
{ name = "mistralai", marker = "extra == 'model-platforms'", specifier = ">=1.1.0,<2" },
{ name = "mock", marker = "extra == 'all'", specifier = ">=5,<6" },
@@ -966,6 +972,8 @@ requires-dist = [
{ name = "tree-sitter", marker = "extra == 'dev-tools'", specifier = ">=0.23.2,<0.24" },
{ name = "tree-sitter-python", marker = "extra == 'all'", specifier = ">=0.23.6,<0.24" },
{ name = "tree-sitter-python", marker = "extra == 'dev-tools'", specifier = ">=0.23.6,<0.24" },
+ { name = "typer", marker = "extra == 'all'", specifier = ">=0.15.2" },
+ { name = "typer", marker = "extra == 'dev-tools'", specifier = ">=0.15.2" },
{ name = "types-colorama", marker = "extra == 'all'", specifier = ">=0.4.15,<0.5" },
{ name = "types-colorama", marker = "extra == 'dev'", specifier = ">=0.4.15,<0.5" },
{ name = "types-mock", marker = "extra == 'all'", specifier = ">=5.1.0,<6" },
@@ -3152,6 +3160,25 @@ wheels = [
{ url = "https://files.pythonhosted.org/packages/8f/8e/9ad090d3553c280a8060fbf6e24dc1c0c29704ee7d1c372f0c174aa59285/matplotlib_inline-0.1.7-py3-none-any.whl", hash = "sha256:df192d39a4ff8f21b1895d72e6a13f5fcc5099f00fa84384e0ea28c2cc0653ca", size = 9899 },
]
+[[package]]
+name = "mcp"
+version = "1.3.0"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+ { name = "anyio" },
+ { name = "httpx" },
+ { name = "httpx-sse" },
+ { name = "pydantic" },
+ { name = "pydantic-settings" },
+ { name = "sse-starlette" },
+ { name = "starlette" },
+ { name = "uvicorn" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/6b/b6/81e5f2490290351fc97bf46c24ff935128cb7d34d68e3987b522f26f7ada/mcp-1.3.0.tar.gz", hash = "sha256:f409ae4482ce9d53e7ac03f3f7808bcab735bdfc0fba937453782efb43882d45", size = 150235 }
+wheels = [
+ { url = "https://files.pythonhosted.org/packages/d0/d2/a9e87b506b2094f5aa9becc1af5178842701b27217fa43877353da2577e3/mcp-1.3.0-py3-none-any.whl", hash = "sha256:2829d67ce339a249f803f22eba5e90385eafcac45c94b00cab6cef7e8f217211", size = 70672 },
+]
+
[[package]]
name = "mdit-py-plugins"
version = "0.4.2"
@@ -4565,6 +4592,19 @@ wheels = [
{ url = "https://files.pythonhosted.org/packages/a9/f9/b6bcaf874f410564a78908739c80861a171788ef4d4f76f5009656672dfe/pydantic_core-2.23.4-pp310-pypy310_pp73-win_amd64.whl", hash = "sha256:9a5bce9d23aac8f0cf0836ecfc033896aa8443b501c58d0602dbfd5bd5b37753", size = 1920344 },
]
+[[package]]
+name = "pydantic-settings"
+version = "2.8.1"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+ { name = "pydantic" },
+ { name = "python-dotenv" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/88/82/c79424d7d8c29b994fb01d277da57b0a9b09cc03c3ff875f9bd8a86b2145/pydantic_settings-2.8.1.tar.gz", hash = "sha256:d5c663dfbe9db9d5e1c646b2e161da12f0d734d422ee56f567d0ea2cee4e8585", size = 83550 }
+wheels = [
+ { url = "https://files.pythonhosted.org/packages/0b/53/a64f03044927dc47aafe029c42a5b7aabc38dfb813475e0e1bf71c4a59d0/pydantic_settings-2.8.1-py3-none-any.whl", hash = "sha256:81942d5ac3d905f7f3ee1a70df5dfb62d5569c12f51a5a647defc1c3d9ee2e9c", size = 30839 },
+]
+
[[package]]
name = "pydata-sphinx-theme"
version = "0.15.4"
@@ -5240,6 +5280,20 @@ wheels = [
{ url = "https://files.pythonhosted.org/packages/7b/44/4e421b96b67b2daff264473f7465db72fbdf36a07e05494f50300cc7b0c6/rfc3339_validator-0.1.4-py2.py3-none-any.whl", hash = "sha256:24f6ec1eda14ef823da9e36ec7113124b39c04d50a4d3d3a3c2859577e7791fa", size = 3490 },
]
+[[package]]
+name = "rich"
+version = "13.9.4"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+ { name = "markdown-it-py" },
+ { name = "pygments" },
+ { name = "typing-extensions", marker = "python_full_version < '3.11'" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/ab/3a/0316b28d0761c6734d6bc14e770d85506c986c85ffb239e688eeaab2c2bc/rich-13.9.4.tar.gz", hash = "sha256:439594978a49a09530cff7ebc4b5c7103ef57baf48d5ea3184f21d9a2befa098", size = 223149 }
+wheels = [
+ { url = "https://files.pythonhosted.org/packages/19/71/39c7c0d87f8d4e6c020a393182060eaefeeae6c01dab6a84ec346f2567df/rich-13.9.4-py3-none-any.whl", hash = "sha256:6049d5e6ec054bf2779ab3358186963bac2ea89175919d699e378b99738c2a90", size = 242424 },
+]
+
[[package]]
name = "rouge"
version = "1.0.1"
@@ -5618,6 +5672,15 @@ version = "1.0.0"
source = { registry = "https://pypi.org/simple" }
sdist = { url = "https://files.pythonhosted.org/packages/9e/bd/3704a8c3e0942d711c1299ebf7b9091930adae6675d7c8f476a7ce48653c/sgmllib3k-1.0.0.tar.gz", hash = "sha256:7868fb1c8bfa764c1ac563d3cf369c381d1325d36124933a726f29fcdaa812e9", size = 5750 }
+[[package]]
+name = "shellingham"
+version = "1.5.4"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/58/15/8b3609fd3830ef7b27b655beb4b4e9c62313a4e8da8c676e142cc210d58e/shellingham-1.5.4.tar.gz", hash = "sha256:8dbca0739d487e5bd35ab3ca4b36e11c4078f3a234bfce294b0a0291363404de", size = 10310 }
+wheels = [
+ { url = "https://files.pythonhosted.org/packages/e0/f9/0595336914c5619e5f28a1fb793285925a8cd4b432c9da0a987836c7f822/shellingham-1.5.4-py2.py3-none-any.whl", hash = "sha256:7ecfff8f2fd72616f7481040475a65b2bf8af90a56c89140852d1120324e8686", size = 9755 },
+]
+
[[package]]
name = "six"
version = "1.17.0"
@@ -5925,6 +5988,19 @@ wheels = [
{ url = "https://files.pythonhosted.org/packages/6b/ed/8bc1d54387434f4c1b99a54721691444e9e249bb728a0da47b3150c756d6/sqlglotrs-0.3.0-cp312-none-win_amd64.whl", hash = "sha256:b9f308732f12331f06c53fcb1d7c2b135a43aa22486b4c88c26d42710f329448", size = 190557 },
]
+[[package]]
+name = "sse-starlette"
+version = "2.2.1"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+ { name = "anyio" },
+ { name = "starlette" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/71/a4/80d2a11af59fe75b48230846989e93979c892d3a20016b42bb44edb9e398/sse_starlette-2.2.1.tar.gz", hash = "sha256:54470d5f19274aeed6b2d473430b08b4b379ea851d953b11d7f1c4a2c118b419", size = 17376 }
+wheels = [
+ { url = "https://files.pythonhosted.org/packages/d9/e0/5b8bd393f27f4a62461c5cf2479c75a2cc2ffa330976f9f00f5f6e4f50eb/sse_starlette-2.2.1-py3-none-any.whl", hash = "sha256:6410a3d3ba0c89e7675d4c273a301d64649c03a5ef1ca101f10b47f895fd0e99", size = 10120 },
+]
+
[[package]]
name = "stack-data"
version = "0.6.3"
@@ -6356,6 +6432,21 @@ wheels = [
{ url = "https://files.pythonhosted.org/packages/fe/7b/7757205dee3628f75e7991021d15cd1bd0c9b044ca9affe99b50879fc0e1/triton-3.0.0-1-cp312-cp312-manylinux2014_x86_64.manylinux_2_17_x86_64.whl", hash = "sha256:34e509deb77f1c067d8640725ef00c5cbfcb2052a1a3cb6a6d343841f92624eb", size = 209464695 },
]
+[[package]]
+name = "typer"
+version = "0.15.2"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+ { name = "click" },
+ { name = "rich" },
+ { name = "shellingham" },
+ { name = "typing-extensions" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/8b/6f/3991f0f1c7fcb2df31aef28e0594d8d54b05393a0e4e34c65e475c2a5d41/typer-0.15.2.tar.gz", hash = "sha256:ab2fab47533a813c49fe1f16b1a370fd5819099c00b119e0633df65f22144ba5", size = 100711 }
+wheels = [
+ { url = "https://files.pythonhosted.org/packages/7f/fc/5b29fea8cee020515ca82cc68e3b8e1e34bb19a3535ad854cac9257b414c/typer-0.15.2-py3-none-any.whl", hash = "sha256:46a499c6107d645a9c13f7ee46c5d5096cae6f5fc57dd11eccbbb9ae3e44ddfc", size = 45061 },
+]
+
[[package]]
name = "types-colorama"
version = "0.4.15.20240311"