mcp-use 1.1.5__py3-none-any.whl → 1.2.6__py3-none-any.whl

{mcp_use-1.1.5.dist-info → mcp_use-1.2.6.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mcp-use
-Version: 1.1.5
+Version: 1.2.6
 Summary: MCP Library for LLMs
 Author-email: Pietro Zullo <pietro.zullo@gmail.com>
 License: MIT
@@ -41,9 +41,9 @@ Description-Content-Type: text/markdown
   <img alt="" src="./static/image.jpg"  width="full">
 </picture>
 
-<h1 align="center">Open Source MCP CLient Library </h1>
+<h1 align="center">Unified MCP Client Library </h1>
 
-[![](https://img.shields.io/pypi/dd/mcp_use.svg)](https://pypi.org/project/mcp_use/)
+[![](https://img.shields.io/pypi/dw/mcp_use.svg)](https://pypi.org/project/mcp_use/)
 [![PyPI Downloads](https://img.shields.io/pypi/dm/mcp_use.svg)](https://pypi.org/project/mcp_use/)
 [![PyPI Version](https://img.shields.io/pypi/v/mcp_use.svg)](https://pypi.org/project/mcp_use/)
 [![Python Versions](https://img.shields.io/pypi/pyversions/mcp_use.svg)](https://pypi.org/project/mcp_use/)
@@ -51,8 +51,9 @@ Description-Content-Type: text/markdown
 [![License](https://img.shields.io/github/license/pietrozullo/mcp-use)](https://github.com/pietrozullo/mcp-use/blob/main/LICENSE)
 [![Code style: Ruff](https://img.shields.io/badge/code%20style-ruff-000000.svg)](https://github.com/astral-sh/ruff)
 [![GitHub stars](https://img.shields.io/github/stars/pietrozullo/mcp-use?style=social)](https://github.com/pietrozullo/mcp-use/stargazers)
+[![Twitter Follow](https://img.shields.io/twitter/follow/Pietro?style=social)](https://x.com/pietrozullo)
 
-🌐 MCP-Use is the open source way to connect any LLM to MCP tools and build custom agents that have tool access, without using closed source or application clients.
+🌐 MCP-Use is the open source way to connect **any LLM to any MCP server** and build custom agents that have tool access, without using closed source or application clients.
 
 💡 Let developers easily connect any LLM to tools like web browsing, file operations, and more.
 
@@ -65,8 +66,10 @@ Description-Content-Type: text/markdown
 | 🔄 **Ease of use** | Create your first MCP capable agent you need only 6 lines of code |
 | 🤖 **LLM Flexibility** | Works with any langchain supported LLM that supports tool calling (OpenAI, Anthropic, Groq, LLama etc.) |
 | 🌐 **HTTP Support** | Direct connection to MCP servers running on specific HTTP ports |
+| ⚙️ **Dynamic Server Selection** | Agents can dynamically choose the most appropriate MCP server for a given task from the available pool |
 | 🧩 **Multi-Server Support** | Use multiple MCP servers simultaneously in a single agent |
 | 🛡️ **Tool Restrictions** | Restrict potentially dangerous tools like file system or network access |
+| 🔧 **Custom Agents** | Build your own agents with any framework using the LangChain adapter or create new adapters |
 
 
 # Quick start
@@ -388,7 +391,7 @@ This example demonstrates how to connect to an MCP server running on a specific
 
 # Multi-Server Support
 
-MCP-Use supports working with multiple MCP servers simultaneously, allowing you to combine tools from different servers in a single agent. This is useful for complex tasks that require multiple capabilities, such as web browsing combined with file operations or 3D modeling.
+MCP-Use allows configuring and connecting to multiple MCP servers simultaneously using the `MCPClient`. This enables complex workflows that require tools from different servers, such as web browsing combined with file operations or 3D modeling.
 
 ## Configuration
 
@@ -414,7 +417,28 @@ You can configure multiple servers in your configuration file:
 
 ## Usage
 
-The `MCPClient` class provides several methods for managing multiple servers:
+The `MCPClient` class provides methods for managing connections to multiple servers. When creating an `MCPAgent`, you can provide an `MCPClient` configured with multiple servers.
+
+By default, the agent will have access to tools from all configured servers. If you need to target a specific server for a particular task, you can specify the `server_name` when calling the `agent.run()` method.
+
+```python
+# Example: Manually selecting a server for a specific task
+result = await agent.run(
+    "Search for Airbnb listings in Barcelona",
+    server_name="airbnb" # Explicitly use the airbnb server
+)
+
+result_google = await agent.run(
+    "Find restaurants near the first result using Google Search",
+    server_name="playwright" # Explicitly use the playwright server
+)
+```
+
+## Dynamic Server Selection (Server Manager)
+
+For enhanced efficiency and to reduce potential agent confusion when dealing with many tools from different servers, you can enable the Server Manager by setting `use_server_manager=True` during `MCPAgent` initialization.
+
+When enabled, the agent intelligently selects the correct MCP server based on the tool chosen by the LLM for a specific step. This minimizes unnecessary connections and ensures the agent uses the appropriate tools for the task.
 
 ```python
 import asyncio
@@ -428,7 +452,8 @@ async def main():
     # Create agent with the client
     agent = MCPAgent(
         llm=ChatAnthropic(model="claude-3-5-sonnet-20240620"),
-        client=client
+        client=client,
+        use_server_manager=True  # Enable the Server Manager
     )
 
     try:
@@ -479,6 +504,98 @@ if __name__ == "__main__":
     asyncio.run(main())
 ```
 
+# Build a Custom Agent:
+
+You can also build your own custom agent using the LangChain adapter:
+
+```python
+import asyncio
+from langchain_openai import ChatOpenAI
+from mcp_use.client import MCPClient
+from mcp_use.adapters.langchain_adapter import LangChainAdapter
+from dotenv import load_dotenv
+
+load_dotenv()
+
+
+async def main():
+    # Initialize MCP client
+    client = MCPClient.from_config_file("examples/browser_mcp.json")
+    llm = ChatOpenAI(model="gpt-4o")
+
+    # Create adapter instance
+    adapter = LangChainAdapter()
+    # Get LangChain tools with a single line
+    tools = await adapter.create_tools(client)
+
+    # Create a custom LangChain agent
+    llm_with_tools = llm.bind_tools(tools)
+    result = await llm_with_tools.ainvoke("What tools do you have avilable ? ")
+    print(result)
+
+
+if __name__ == "__main__":
+    asyncio.run(main())
+
+
+```
+
+# Debugging
+
+MCP-Use provides a built-in debug mode that increases log verbosity and helps diagnose issues in your agent implementation.
+
+## Enabling Debug Mode
+
+There are two primary ways to enable debug mode:
+
+### 1. Environment Variable (Recommended for One-off Runs)
+
+Run your script with the `DEBUG` environment variable set to the desired level:
+
+```bash
+# Level 1: Show INFO level messages
+DEBUG=1 python3.11 examples/browser_use.py
+
+# Level 2: Show DEBUG level messages (full verbose output)
+DEBUG=2 python3.11 examples/browser_use.py
+```
+
+This sets the debug level only for the duration of that specific Python process.
+
+Alternatively you can set the following environment variable to the desired logging level:
+
+```bash
+export MCP_USE_DEBUG=1 # or 2
+```
+
+### 2. Setting the Debug Flag Programmatically
+
+You can set the global debug flag directly in your code:
+
+```python
+import mcp_use
+
+mcp_use.set_debug(1)  # INFO level
+# or
+mcp_use.set_debug(2)  # DEBUG level (full verbose output)
+```
+
+### 3. Agent-Specific Verbosity
+
+If you only want to see debug information from the agent without enabling full debug logging, you can set the `verbose` parameter when creating an MCPAgent:
+
+```python
+# Create agent with increased verbosity
+agent = MCPAgent(
+    llm=your_llm,
+    client=your_client,
+    verbose=True  # Only shows debug messages from the agent
+)
+```
+
+This is useful when you only need to see the agent's steps and decision-making process without all the low-level debug information from other components.
+
+
 # Roadmap
 
 <ul>
@@ -487,6 +604,10 @@ if __name__ == "__main__":
 <li>[ ] ... </li>
 </ul>
 
+## Star History
+
+[![Star History Chart](https://api.star-history.com/svg?repos=pietrozullo/mcp-use&type=Date)](https://www.star-history.com/#pietrozullo/mcp-use&Date)
+
 # Contributing
 
 We love contributions! Feel free to open issues for bugs or feature requests.

{mcp_use-1.1.5.dist-info → mcp_use-1.2.6.dist-info}/RECORD

@@ -1,13 +1,17 @@
-mcp_use/__init__.py,sha256=PSoxLAu1GPjfIDPcZiJyI3k66MMS3lcfx5kERUgFb1o,723
+mcp_use/__init__.py,sha256=FikKagS6u8mugJOeslN3xfSA-tBLhjOywZSEcQ-y23g,1006
 mcp_use/client.py,sha256=RoOOpCzMCjpqkkyAIEDOVc6Sn_HsET1rbn_J_J778q4,8278
 mcp_use/config.py,sha256=O9V4pa-shZ2mPokRTrd7KZQ2GpuTcYBGUslefl1fosw,1653
-mcp_use/logging.py,sha256=2-hSB7ZWcHEx_OFHNg8GIbSGCZx3MW4mZGGWxi2Ew3E,2690
+mcp_use/logging.py,sha256=UhQdMx0H0q08-ZPjY_hAJVErkEUAkU1oahHqwdfdK_U,4274
 mcp_use/session.py,sha256=Z4EZTUnQUX0QyGMzkJIrMRTX4SDk6qQUoBld408LIJE,3449
-mcp_use/agents/__init__.py,sha256=ukchMTqCOID6ikvLmJ-6sldWTVFIzztGQo4BX6QeQr8,312
+mcp_use/adapters/__init__.py,sha256=-xCrgPThuX7x0PHGFDdjb7M-mgw6QV3sKu5PM7ShnRg,275
+mcp_use/adapters/base.py,sha256=ixLHXp8FWdyZPx7Kh6s-4jEVs3qT4DWrApSLXfqzNws,6141
+mcp_use/adapters/langchain_adapter.py,sha256=mbOkWHMgHJJNJYFXYLCk3JjIT0CRW_iiu5eZtxsWEmk,6309
+mcp_use/agents/__init__.py,sha256=7QCfjE9WA50r-W8CS7IzUZMuhLgm8xSuKH1kYWdFU64,324
 mcp_use/agents/base.py,sha256=bfuldi_89AbSbNc8KeTiCArRT9V62CNxHOWYkLHWjyA,1605
-mcp_use/agents/langchain_agent.py,sha256=7gHTxZ5kIfHy0qRDMTGKiek0OOlU-7yLd8ruoJPzTyY,10168
-mcp_use/agents/mcpagent.py,sha256=5n0FbLrx30dc1afH75UW2s_R0p3nSssE2BrXYNfbygo,14190
-mcp_use/agents/prompts/default.py,sha256=tnwt9vOiVBhdpu-lIHhwEJo3rvE6EobPfUgS9JURBzg,941
+mcp_use/agents/mcpagent.py,sha256=kSNqmF728LrEYfzfvW8h8llqC877vJLcn-DJodYVucU,23988
+mcp_use/agents/server_manager.py,sha256=ShmjrvDtmU7dJtfVlw_srC3t5f_B-QtifzIiV4mfsRA,11315
+mcp_use/agents/prompts/system_prompt_builder.py,sha256=GH5Pvl49IBpKpZA9YTI83xMsdYSkRN_hw4LFHkKtxbg,4122
+mcp_use/agents/prompts/templates.py,sha256=AZKrGWuI516C-PmyOPvxDBibNdqJtN24sOHTGR06bi4,1933
 mcp_use/connectors/__init__.py,sha256=jnd-7pPPJMb0UNJ6aD9lInj5Tlamc8lA_mFyG8RWJpo,385
 mcp_use/connectors/base.py,sha256=5TcXB-I5zrwPtedB6dShceNucsK3wHBeGC2yDVq8X48,4885
 mcp_use/connectors/http.py,sha256=2ZG5JxcK1WZ4jkTfTir6bEQLMxXBTPHyi0s42RHGeFs,2837
@@ -18,7 +22,7 @@ mcp_use/task_managers/base.py,sha256=ksNdxTwq8N-zqymxVoKGnWXq9iqkLYC61uB91o6Mh-4
 mcp_use/task_managers/sse.py,sha256=WysmjwqRI3meXMZY_F4y9tSBMvSiUZfTJQfitM5l6jQ,2529
 mcp_use/task_managers/stdio.py,sha256=DEISpXv4mo3d5a-WT8lkWbrXJwUh7QW0nMT_IM3fHGg,2269
 mcp_use/task_managers/websocket.py,sha256=ZbCqdGgzCRtsXzRGFws-f2OzH8cPAkN4sJNDwEpRmCc,1915
-mcp_use-1.1.5.dist-info/METADATA,sha256=A-VlMFyFTy0oSs8RpWCEd7cfuo6ObqQrc4O4QdRf67Q,14004
-mcp_use-1.1.5.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
-mcp_use-1.1.5.dist-info/licenses/LICENSE,sha256=7Pw7dbwJSBw8zH-WE03JnR5uXvitRtaGTP9QWPcexcs,1068
-mcp_use-1.1.5.dist-info/RECORD,,
+mcp_use-1.2.6.dist-info/METADATA,sha256=wGaSC2X6TKK2-WUqmr7qupD_oc1l0IK_1Xrn09iLKiE,18156
+mcp_use-1.2.6.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+mcp_use-1.2.6.dist-info/licenses/LICENSE,sha256=7Pw7dbwJSBw8zH-WE03JnR5uXvitRtaGTP9QWPcexcs,1068
+mcp_use-1.2.6.dist-info/RECORD,,

mcp_use/agents/langchain_agent.py

@@ -1,267 +0,0 @@
-"""
-LangChain agent implementation for MCP tools with customizable system message.
-
-This module provides a LangChain agent implementation that can use MCP tools
-through a unified interface, with support for customizable system messages.
-"""
-
-from typing import Any, NoReturn
-
-from jsonschema_pydantic import jsonschema_to_pydantic
-from langchain.agents import AgentExecutor, create_tool_calling_agent
-from langchain.prompts import ChatPromptTemplate, MessagesPlaceholder
-from langchain.schema.language_model import BaseLanguageModel
-from langchain_core.tools import BaseTool, ToolException
-from mcp.types import CallToolResult, EmbeddedResource, ImageContent, TextContent
-from pydantic import BaseModel
-
-from ..connectors.base import BaseConnector
-from ..logging import logger
-
-
-def _parse_mcp_tool_result(tool_result: CallToolResult) -> str:
-    """Parse the content of a CallToolResult into a string.
-
-    Args:
-        tool_result: The result object from calling an MCP tool.
-
-    Returns:
-        A string representation of the tool result content.
-
-    Raises:
-        ToolException: If the tool execution failed, returned no content,
-                       or contained unexpected content types.
-    """
-    if tool_result.isError:
-        raise ToolException(f"Tool execution failed: {tool_result.content}")
-
-    if not tool_result.content:
-        raise ToolException("Tool execution returned no content")
-
-    decoded_result = ""
-    for item in tool_result.content:
-        match item.type:
-            case "text":
-                item: TextContent
-                decoded_result += item.text
-            case "image":
-                item: ImageContent
-                decoded_result += item.data  # Assuming data is string-like or base64
-            case "resource":
-                resource: EmbeddedResource = item.resource
-                if hasattr(resource, "text"):
-                    decoded_result += resource.text
-                elif hasattr(resource, "blob"):
-                    # Assuming blob needs decoding or specific handling; adjust as needed
-                    decoded_result += (
-                        resource.blob.decode()
-                        if isinstance(resource.blob, bytes)
-                        else str(resource.blob)
-                    )
-                else:
-                    raise ToolException(f"Unexpected resource type: {resource.type}")
-            case _:
-                raise ToolException(f"Unexpected content type: {item.type}")
-
-    return decoded_result
-
-
-class LangChainAgent:
-    """LangChain agent that can use MCP tools.
-
-    This agent uses LangChain's agent framework to interact with MCP tools
-    through a unified interface.
-    """
-
-    # Default system message if none is provided
-    DEFAULT_SYSTEM_MESSAGE = "You are a helpful AI assistant that can use tools to help users."
-
-    def __init__(
-        self,
-        connectors: list[BaseConnector],
-        llm: BaseLanguageModel,
-        max_steps: int = 5,
-        system_message: str | None = None,
-        disallowed_tools: list[str] | None = None,
-    ) -> None:
-        """Initialize a new LangChain agent.
-
-        Args:
-            connector: The MCP connector to use.
-            llm: The LangChain LLM to use.
-            max_steps: The maximum number of steps to take.
-            system_message: Optional custom system message to use.
-            disallowed_tools: List of tool names that should not be available to the agent.
-        """
-        self.connectors = connectors
-        self.llm = llm
-        self.max_steps = max_steps
-        self.system_message = system_message or self.DEFAULT_SYSTEM_MESSAGE
-        self.disallowed_tools = disallowed_tools or []
-        self.tools: list[BaseTool] = []
-        self.agent: AgentExecutor | None = None
-
-    def set_system_message(self, message: str) -> None:
-        """Set a new system message and recreate the agent.
-
-        Args:
-            message: The new system message.
-        """
-        self.system_message = message
-
-        # Recreate the agent with the new system message if it exists
-        if self.agent and self.tools:
-            self.agent = self._create_agent()
-            logger.debug("Agent recreated with new system message")
-
-    async def initialize(self) -> None:
-        """Initialize the agent and its tools."""
-        self.tools = await self._create_langchain_tools()
-        self.agent = self._create_agent()
-
-    def fix_schema(self, schema: dict) -> dict:
-        """Convert JSON Schema 'type': ['string', 'null'] to 'anyOf' format.
-
-        Args:
-            schema: The JSON schema to fix.
-
-        Returns:
-            The fixed JSON schema.
-        """
-        if isinstance(schema, dict):
-            if "type" in schema and isinstance(schema["type"], list):
-                schema["anyOf"] = [{"type": t} for t in schema["type"]]
-                del schema["type"]  # Remove 'type' and standardize to 'anyOf'
-            for key, value in schema.items():
-                schema[key] = self.fix_schema(value)  # Apply recursively
-        return schema
-
-    async def _create_langchain_tools(self) -> list[BaseTool]:
-        """Create LangChain tools from MCP tools.
-
-        Returns:
-            A list of LangChain tools that wrap MCP tools.
-        """
-        tools = []
-        for connector in self.connectors:
-            local_connector = connector  # Capture for closure
-            for tool in connector.tools:
-                # Skip disallowed tools
-                if tool.name in self.disallowed_tools:
-                    continue
-
-                class McpToLangChainAdapter(BaseTool):
-                    name: str = tool.name or "NO NAME"
-                    description: str = tool.description or ""
-                    # Convert JSON schema to Pydantic model for argument validation
-                    args_schema: type[BaseModel] = jsonschema_to_pydantic(
-                        self.fix_schema(tool.inputSchema)  # Apply schema conversion
-                    )
-                    connector: BaseConnector = local_connector
-                    handle_tool_error: bool = True
-
-                    def _run(self, **kwargs: Any) -> NoReturn:
-                        """Synchronous run method that always raises an error.
-
-                        Raises:
-                            NotImplementedError: Always raises this error because MCP tools
-                                only support async operations.
-                        """
-                        raise NotImplementedError("MCP tools only support async operations")
-
-                    async def _arun(self, **kwargs: Any) -> Any:
-                        """Asynchronously execute the tool with given arguments.
-
-                        Args:
-                            kwargs: The arguments to pass to the tool.
-
-                        Returns:
-                            The result of the tool execution.
-
-                        Raises:
-                            ToolException: If tool execution fails.
-                        """
-                        logger.debug(f'MCP tool: "{self.name}" received input: {kwargs}')
-
-                        try:
-                            tool_result: CallToolResult = await self.connector.call_tool(
-                                self.name, kwargs
-                            )
-                            try:
-                                # Use the helper function to parse the result
-                                return _parse_mcp_tool_result(tool_result)
-                            except Exception as e:
-                                # Log the exception for debugging
-                                logger.error(f"Error parsing tool result: {e}")
-                                # Shortened line:
-                                return (
-                                    f"Error parsing result: {e!s};"
-                                    f" Raw content: {tool_result.content!r}"
-                                )
-
-                        except Exception as e:
-                            if self.handle_tool_error:
-                                return f"Error executing MCP tool: {str(e)}"
-                            raise
-
-                tools.append(McpToLangChainAdapter())
-
-        # Log available tools for debugging
-        logger.debug(f"Available tools: {[tool.name for tool in tools]}")
-        return tools
-
-    def _create_agent(self) -> AgentExecutor:
-        """Create the LangChain agent with the configured system message.
-
-        Returns:
-            An initialized AgentExecutor.
-        """
-        prompt = ChatPromptTemplate.from_messages(
-            [
-                (
-                    "system",
-                    self.system_message,
-                ),
-                MessagesPlaceholder(variable_name="chat_history"),
-                ("human", "{input}"),
-                MessagesPlaceholder(variable_name="agent_scratchpad"),
-            ]
-        )
-        agent = create_tool_calling_agent(llm=self.llm, tools=self.tools, prompt=prompt)
-        return AgentExecutor(
-            agent=agent, tools=self.tools, max_iterations=self.max_steps, verbose=False
-        )
-
-    async def run(
-        self,
-        query: str,
-        max_steps: int | None = None,
-        chat_history: list | None = None,
-    ) -> str:
-        """Run the agent on a query.
-
-        Args:
-            query: The query to run.
-            max_steps: Optional maximum number of steps to take.
-            chat_history: Optional chat history.
-
-        Returns:
-            The result of running the query.
-
-        Raises:
-            RuntimeError: If the MCP client is not initialized.
-        """
-        if not self.agent:
-            raise RuntimeError("MCP client is not initialized")
-
-        if max_steps is not None:
-            self.agent.max_iterations = max_steps
-
-        # Initialize empty chat history if none provided
-        if chat_history is None:
-            chat_history = []
-
-        # Invoke with all required variables
-        result = await self.agent.ainvoke({"input": query, "chat_history": chat_history})
-
-        return result["output"]

mcp_use/agents/prompts/default.py

@@ -1,22 +0,0 @@
-DEFAULT_SYSTEM_PROMPT_TEMPLATE = """You are an assistant with access to these tools:
-
-{tool_descriptions}
-
-Proactively use these tools to:
-- Retrieve and analyze information relevant to user requests
-- Process and transform data in various formats
-- Perform computations and generate insights
-- Execute multi-step workflows by combining tools as needed
-- Interact with external systems when authorized
-
-When appropriate, use available tools rather than relying on your built-in knowledge alone.
-Your tools enable you to perform tasks that would otherwise be beyond your capabilities.
-
-For optimal assistance:
-1. Identify when a tool can help address the user's request
-2. Select the most appropriate tool(s) for the task
-3. Apply tools in the correct sequence when multiple tools are needed
-4. Clearly communicate your process and findings
-
-Remember that you have real capabilities through your tools - use them confidently when needed.
-"""