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: add pulse mcp search toolkits (#2278)

Xiaotian Jinebc65d800b1f
diff --git a/camel/toolkits/__init__.py b/camel/toolkits/__init__.py
index e96cfbe8b..080e527e7 100644
--- a/camel/toolkits/__init__.py
+++ b/camel/toolkits/__init__.py
@@ -68,6 +68,7 @@ from .pyautogui_toolkit import PyAutoGUIToolkit
from .openai_agent_toolkit import OpenAIAgentToolkit
from .searxng_toolkit import SearxNGToolkit
from .jina_reranker_toolkit import JinaRerankerToolkit
+from .pulse_mcp_search_toolkit import PulseMCPSearchToolkit
from .klavis_toolkit import KlavisToolkit
from .aci_toolkit import ACIToolkit
@@ -126,6 +127,7 @@ __all__ = [
'OpenAIAgentToolkit',
'SearxNGToolkit',
'JinaRerankerToolkit',
+ 'PulseMCPSearchToolkit',
'KlavisToolkit',
'ACIToolkit',
]
diff --git a/camel/toolkits/pulse_mcp_search_toolkit.py b/camel/toolkits/pulse_mcp_search_toolkit.py
new file mode 100644
index 000000000..b1275a8a3
--- /dev/null
+++ b/camel/toolkits/pulse_mcp_search_toolkit.py
@@ -0,0 +1,132 @@
+# ========= 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, Dict, List, Optional
+
+import requests
+
+from camel.toolkits.base import BaseToolkit
+from camel.toolkits.function_tool import FunctionTool
+from camel.utils import MCPServer
+
+
+@MCPServer()
+class PulseMCPSearchToolkit(BaseToolkit):
+ r"""A toolkit for searching MCP servers using the PulseMCP API."""
+
+ def __init__(self, timeout: Optional[float] = None):
+ super().__init__(timeout=timeout)
+ self.api_base_url = "https://api.pulsemcp.com/v0beta"
+
+ def search_mcp_servers(
+ self,
+ query: Optional[str] = None,
+ top_k: Optional[int] = 5,
+ package_registry: Optional[str] = None,
+ count_per_page: int = 5000,
+ offset: int = 0,
+ ) -> Dict[str, Any]:
+ r"""Search for MCP servers using the PulseMCP API.
+
+ Args:
+ query (Optional[str]): The query to search for.
+ (default: :obj:`None`)
+ top_k (Optional[int]): After sorting, return only the top_k
+ servers. (default: :obj:`5`)
+ package_registry (Optional[str]): The package registry to search
+ for. (default: :obj:`None`)
+ count_per_page (int): The number of servers to return per page.
+ (default: :obj:`5000`)
+ offset (int): The offset to start the search from.
+ (default: :obj:`0`)
+
+ Returns:
+ Dict[str, Any]: A dictionary containing the search results or
+ an error message.
+ """
+ params: Dict[str, Any] = {
+ "count_per_page": min(count_per_page, 5000),
+ "offset": offset,
+ }
+ if query:
+ params["query"] = query
+
+ response = requests.get(f"{self.api_base_url}/servers", params=params)
+
+ if response.status_code != 200:
+ error_msg = f"Error searching MCP servers: {response.status_code}"
+ if response.text:
+ try:
+ error_info = response.json()
+ if "error" in error_info:
+ msg = error_info['error'].get('message', '')
+ error_msg = f"{error_msg} - {msg}"
+ except Exception:
+ error_msg = f"{error_msg} - {response.text}"
+ return {"error": error_msg}
+
+ data = response.json()
+ servers = data.get("servers", [])
+
+ if package_registry:
+ package_registry_lower = package_registry.lower()
+ servers = [
+ server
+ for server in servers
+ if isinstance(server.get("package_registry"), str)
+ and server.get("package_registry").lower()
+ == package_registry_lower
+ ]
+
+ if query:
+ query_lower = query.lower()
+ # Helper function to calculate score
+ # 1. With name +5
+ # 2. With description +3
+ # 3. With stars +1
+
+ def score(server: Dict[str, Any]) -> float:
+ name = server.get("name", "").lower()
+ desc = server.get("short_description", "").lower()
+ stars = server.get("github_stars", 0) or 0
+ score: float = 0.0
+ if query_lower in name:
+ score += 5
+ if query_lower in desc:
+ score += 3
+ score += stars / 1000
+ return score
+
+ servers = sorted(servers, key=score, reverse=True)
+ else:
+ servers = sorted(
+ servers,
+ key=lambda x: x.get("github_stars", 0) or 0,
+ reverse=True,
+ )
+
+ if top_k is not None:
+ servers = servers[:top_k]
+
+ return {"servers": servers}
+
+ def get_tools(self) -> List[FunctionTool]:
+ r"""Returns a list of FunctionTool objects representing the
+ functions in the toolkit.
+
+ Returns:
+ List[FunctionTool]: A list of FunctionTool objects.
+ """
+ return [
+ FunctionTool(self.search_mcp_servers),
+ ]
diff --git a/examples/toolkits/mcp/mcp_search_toolkit.py b/examples/toolkits/mcp/mcp_search_toolkit.py
new file mode 100644
index 000000000..5dc9ed76d
--- /dev/null
+++ b/examples/toolkits/mcp/mcp_search_toolkit.py
@@ -0,0 +1,167 @@
+# ========= 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 json
+
+from camel.agents import ChatAgent
+from camel.models import ModelFactory
+from camel.toolkits import PulseMCPSearchToolkit
+from camel.types import ModelPlatformType, ModelType
+
+# Create an instance of the MCP search toolkit
+search_toolkit = PulseMCPSearchToolkit()
+
+# Example 1: Search for MCP servers with a specific query
+print("Example 1: Search for MCP servers related to 'github'")
+search_results = search_toolkit.search_mcp_servers(
+ query="github",
+ top_k=4, # Limit to 4 results for brevity
+)
+print(json.dumps(search_results, indent=2))
+"""
+===============================================================================
+Example 1: Search for MCP servers related to 'github'
+{
+ "servers": [
+ {
+ "name": "GitHub",
+ "url": "https://www.pulsemcp.com/servers/modelcontextprotocol-github",
+ "external_url": null,
+ "short_description": "Manage repositories, issues, and search code via GitHub API.",
+ "source_code_url": "https://github.com/modelcontextprotocol/servers/tree/HEAD/src/github",
+ "github_stars": 41847,
+ "package_registry": "npm",
+ "package_name": "@modelcontextprotocol/server-github",
+ "package_download_count": 710829,
+ "EXPERIMENTAL_ai_generated_description": "This GitHub MCP server, developed by Anthropic, provides AI assistants with comprehensive access to GitHub's API functionality. It enables operations like file management, repository creation, issue tracking, and advanced code search across GitHub. Built in TypeScript, the implementation handles authentication, request formatting, and exposes GitHub's features through a standardized MCP interface. By bridging AI models and GitHub's development platform, this server allows AI systems to interact with code repositories, manage projects, and analyze development workflows. It is particularly useful for AI assistants supporting software development teams in tasks like code review, project management, and collaborative coding on GitHub."
+ },
+ {
+ "name": "GitHub",
+ "url": "https://www.pulsemcp.com/servers/github",
+ "external_url": "https://github.blog/changelog/2025-04-04-github-mcp-server-public-preview/",
+ "short_description": "Integration with GitHub Issues, Pull Requests, and more.",
+ "source_code_url": "https://github.com/github/github-mcp-server",
+ "github_stars": 12571,
+ "package_registry": null,
+ "package_name": null,
+ "package_download_count": null,
+ "EXPERIMENTAL_ai_generated_description": "A Model Context Protocol (MCP) server for GitHub that enables AI assistants to access GitHub repositories, issues, pull requests, and other GitHub data."
+ },
+ {
+ "name": "Pipedream",
+ "url": "https://www.pulsemcp.com/servers/pipedream",
+ "external_url": "https://mcp.pipedream.com/",
+ "short_description": "Access hosted MCP servers or deploy your own for 2,500+ APIs like Slack, GitHub, Notion, Google Drive, and more, all with built-in auth and 10k tools.",
+ "source_code_url": "https://github.com/pipedreamhq/pipedream/tree/HEAD/modelcontextprotocol",
+ "github_stars": 9646,
+ "package_registry": "npm",
+ "package_name": "@pipedream/mcp",
+ "package_download_count": 2303,
+ "EXPERIMENTAL_ai_generated_description": "Pipedream's MCP server lets you:\n- Run the servers locally with npx @pipedream/mcp\n- Host the servers yourself to use them within your app or company\n\nSome of the key features include the ability to:\n- Run your own MCP server for over 2,500 apps\n- Manage servers for your users, in your own app.\n- Connect accounts, configure params, and make API requests, all via tools\n- Fully-managed OAuth and credential storage "
+ },
+ {
+ "name": "GitMCP (GitHub to MCP)",
+ "url": "https://www.pulsemcp.com/servers/idosal-git-mcp",
+ "external_url": "https://gitmcp.io/",
+ "short_description": "GitMCP is a free, open-source, remote Model Context Protocol (MCP) server that transforms any GitHub project (repositories or GitHub pages) into a documentation hub. It allows AI tools like Cursor to access up-to-date documentation and code, ending hallucinations seamlessly.",
+ "source_code_url": "https://github.com/idosal/git-mcp",
+ "github_stars": 1864,
+ "package_registry": null,
+ "package_name": null,
+ "package_download_count": null,
+ "EXPERIMENTAL_ai_generated_description": "Transforms any GitHub project (repositories or GitHub pages) into a documentation hub. It allows AI tools like Cursor to access up-to-date documentation and code, ending hallucinations seamlessly."
+ }
+ ]
+}
+===============================================================================
+""" # noqa: E501
+
+# Example 2: Search for MCP servers restricted to a specific package registry
+print(
+ "Example 2: Search for MCP servers restricted to a specific package registry" # noqa: E501
+)
+search_results = search_toolkit.search_mcp_servers(
+ query="Slack",
+ package_registry="npm", # Only search for servers registered in npm
+ top_k=1,
+)
+print(json.dumps(search_results, indent=2))
+"""
+===============================================================================
+Example 2: Search for MCP servers restricted to a specific package registry
+{
+ "servers": [
+ {
+ "name": "Slack",
+ "url": "https://www.pulsemcp.com/servers/slack",
+ "external_url": null,
+ "short_description": "Send messages, manage channels, and access workspace history.",
+ "source_code_url": "https://github.com/modelcontextprotocol/servers/tree/HEAD/src/slack",
+ "github_stars": 41847,
+ "package_registry": "npm",
+ "package_name": "@modelcontextprotocol/server-slack",
+ "package_download_count": 188989,
+ "EXPERIMENTAL_ai_generated_description": "This Slack MCP Server, developed by the Anthropic team, provides a robust interface for language models to interact with Slack workspaces. It enables AI agents to perform a wide range of Slack-specific tasks including listing channels, posting messages, replying to threads, adding reactions, retrieving channel history, and accessing user information. The implementation distinguishes itself by offering comprehensive Slack API integration, making it ideal for AI-driven workplace communication and automation. By leveraging Slack's Bot User OAuth Tokens, it ensures secure and authorized access to workspace data. This tool is particularly powerful for AI assistants designed to enhance team collaboration, automate routine communication tasks, and provide intelligent insights from Slack conversations."
+ }
+ ]
+}
+===============================================================================
+""" # noqa: E501
+
+# Example 3: Search for MCP servers using a chat agent
+model = ModelFactory.create(
+ model_platform=ModelPlatformType.ANTHROPIC,
+ model_type=ModelType.CLAUDE_3_7_SONNET,
+)
+
+agent = ChatAgent(
+ model=model,
+ system_message="You are a helpful assistant that can search for MCP servers.", # noqa: E501
+ tools=search_toolkit.get_tools(),
+)
+
+response = agent.step("Search for MCP servers related to 'SQL'")
+print(response.msg.content)
+"""
+===============================================================================
+I've searched for MCP servers related to SQL and found 5 relevant results:
+
+1. SQLite Server
+- Allows querying and analyzing SQLite databases directly
+- Available on PyPI as 'mcp-server-sqlite'
+- Features tools for database operations and schema inspection
+
+2. PostgreSQL Server
+- Provides read-only access to Postgres databases
+- Available on npm as '@modelcontextprotocol/server-postgres'
+- Focuses on database schema inspection and SQL query execution
+
+3. MySQL Server
+- Enables exploring schemas and executing read-only SQL queries on MySQL databases
+- Available on PyPI as 'mysql-mcp-server'
+- Offers secure database interaction capabilities
+
+4. Read MySQL Server
+- Provides secure read-only MySQL database access
+- Available on npm as '@benborla29/mcp-server-mysql'
+- Built in TypeScript with focus on security through read-only transactions
+
+5. SQL Alchemy Server
+- Integrates with multiple SQL database engines using SQLAlchemy
+- Supports PostgreSQL, MySQL, MariaDB, SQLite, and other SQLAlchemy-compatible databases
+- Offers tools for database exploration and query assistance
+
+Each server provides specific functionality for interacting with different types of SQL databases, with varying features and security measures. Would you like more specific information about any of these servers?
+===============================================================================
+""" # noqa: E501
diff --git a/test/services/test_agent_mcp_server.py b/test/services/test_agent_mcp_server.py
index 5c4a4a564..94b78e60c 100644
--- a/test/services/test_agent_mcp_server.py
+++ b/test/services/test_agent_mcp_server.py
@@ -14,6 +14,7 @@
from unittest.mock import AsyncMock, Mock, patch
import pytest
+from mcp.server.fastmcp import Context
from camel.messages import BaseMessage
from camel.responses import ChatAgentResponse
@@ -45,6 +46,13 @@ def mock_agent():
return agent
+def mock_context():
+ context = Mock(spec=Context)
+ context.info = Mock()
+ return context
+
+
@pytest.fixture
def mock_message():
message = Mock(spec=BaseMessage)
@@ -65,10 +73,10 @@ def mock_response(mock_message):
@pytest.mark.asyncio
-async def test_step_success(mock_agent, mock_response):
+async def test_step_success(mock_agent, mock_response, mock_context):
with patch.dict(agents_dict, {"test": mock_agent}):
mock_agent.astep.return_value = mock_response
- result = await step("test", "Hello")
+ result = await step("test", "Hello", mock_context)
assert result["status"] == "success"
assert len(result["messages"]) == 1
@@ -77,10 +85,11 @@ async def test_step_success(mock_agent, mock_response):
assert result["info"] == {}
mock_agent.astep.assert_called_once_with("Hello", None)
+ mock_context.info.assert_called_once()
@pytest.mark.asyncio
-async def test_step_with_format(mock_agent, mock_response):
+async def test_step_with_format(mock_agent, mock_response, mock_context):
response_format = {
"type": "object",
"properties": {"answer": {"type": "string"}},
@@ -88,37 +97,40 @@ async def test_step_with_format(mock_agent, mock_response):
with patch.dict(agents_dict, {"test": mock_agent}):
mock_agent.astep.return_value = mock_response
- result = await step("test", "Hello", response_format)
+ result = await step("test", "Hello", mock_context, response_format)
assert result["status"] == "success"
mock_agent.astep.assert_called_once()
+ mock_context.info.assert_called_once()
@pytest.mark.asyncio
-async def test_step_agent_not_found():
+async def test_step_agent_not_found(mock_context):
# Ensure agents_dict is empty
with patch.dict(agents_dict, {}, clear=True):
- result = await step("nonexistent", "Hello")
+ result = await step("nonexistent", "Hello", mock_context)
assert result["status"] == "error"
assert "not found" in result["message"]
-def test_reset(mock_agent):
+def test_reset(mock_agent, mock_context):
with patch.dict(agents_dict, {"test": mock_agent}):
- result = reset()
+ result = reset(mock_context)
assert result["status"] == "success"
assert "successfully" in result["message"]
mock_agent.reset.assert_called_once()
+ mock_context.info.assert_called_once()
-def test_set_output_language(mock_agent):
+def test_set_output_language(mock_agent, mock_context):
with patch.dict(agents_dict, {"test": mock_agent}):
- result = set_output_language("fr")
+ result = set_output_language("fr", mock_context)
assert result["status"] == "success"
assert "fr" in result["message"]
assert mock_agent.output_language == "fr"
+ mock_context.info.assert_called_once()
def test_get_agents_info():