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

mcp_use/agents/prompts/system_prompt_builder.py

@@ -0,0 +1,105 @@
+from langchain.schema import SystemMessage
+from langchain_core.tools import BaseTool
+
+
+def generate_tool_descriptions(
+    tools: list[BaseTool], disallowed_tools: list[str] | None = None
+) -> list[str]:
+    """
+    Generates a list of formatted tool descriptions, excluding disallowed tools.
+
+    Args:
+        tools: The list of available BaseTool objects.
+        disallowed_tools: A list of tool names to exclude.
+
+    Returns:
+        A list of strings, each describing a tool in the format "- tool_name: description".
+    """
+    disallowed_set = set(disallowed_tools or [])
+    tool_descriptions_list = []
+    for tool in tools:
+        if tool.name in disallowed_set:
+            continue
+        # Escape curly braces for formatting
+        escaped_desc = tool.description.replace("{", "{{").replace("}", "}}")
+        description = f"- {tool.name}: {escaped_desc}"
+        tool_descriptions_list.append(description)
+    return tool_descriptions_list
+
+
+def build_system_prompt_content(
+    template: str, tool_description_lines: list[str], additional_instructions: str | None = None
+) -> str:
+    """
+    Builds the final system prompt string using a template, tool descriptions,
+    and optional additional instructions.
+
+    Args:
+        template: The system prompt template string (must contain '{tool_descriptions}').
+        tool_description_lines: A list of formatted tool description strings.
+        additional_instructions: Optional extra instructions to append.
+
+    Returns:
+        The fully formatted system prompt content string.
+    """
+    tool_descriptions_block = "\n".join(tool_description_lines)
+    # Add a check for missing placeholder to prevent errors
+    if "{tool_descriptions}" not in template:
+        # Handle this case: maybe append descriptions at the end or raise an error
+        # For now, let's append if placeholder is missing
+        print("Warning: '{tool_descriptions}' placeholder not found in template.")
+        system_prompt_content = template + "\n\nAvailable tools:\n" + tool_descriptions_block
+    else:
+        system_prompt_content = template.format(tool_descriptions=tool_descriptions_block)
+
+    if additional_instructions:
+        system_prompt_content += f"\n\n{additional_instructions}"
+
+    return system_prompt_content
+
+
+def create_system_message(
+    tools: list[BaseTool],
+    system_prompt_template: str,
+    server_manager_template: str,
+    use_server_manager: bool,
+    disallowed_tools: list[str] | None = None,
+    user_provided_prompt: str | None = None,
+    additional_instructions: str | None = None,
+) -> SystemMessage:
+    """
+    Creates the final SystemMessage object for the agent.
+
+    Handles selecting the correct template, generating tool descriptions,
+    and incorporating user overrides and additional instructions.
+
+    Args:
+        tools: List of available tools.
+        system_prompt_template: The default system prompt template.
+        server_manager_template: The template to use when server manager is active.
+        use_server_manager: Flag indicating if server manager mode is enabled.
+        disallowed_tools: List of tool names to exclude.
+        user_provided_prompt: A complete system prompt provided by the user, overriding templates.
+        additional_instructions: Extra instructions to append to the template-based prompt.
+
+    Returns:
+        A SystemMessage object containing the final prompt content.
+    """
+    # If a complete user prompt is given, use it directly
+    if user_provided_prompt:
+        return SystemMessage(content=user_provided_prompt)
+
+    # Select the appropriate template
+    template_to_use = server_manager_template if use_server_manager else system_prompt_template
+
+    # Generate tool descriptions
+    tool_description_lines = generate_tool_descriptions(tools, disallowed_tools)
+
+    # Build the final prompt content
+    final_prompt_content = build_system_prompt_content(
+        template=template_to_use,
+        tool_description_lines=tool_description_lines,
+        additional_instructions=additional_instructions,
+    )
+
+    return SystemMessage(content=final_prompt_content)

mcp_use/agents/prompts/templates.py

@@ -0,0 +1,43 @@
+# mcp_use/agents/prompts/templates.py
+
+DEFAULT_SYSTEM_PROMPT_TEMPLATE = """You are a helpful AI assistant.
+You have access to the following tools:
+
+{tool_descriptions}
+
+Use the following format:
+
+Question: the input question you must answer
+Thought: you should always think about what to do
+Action: the action to take, should be one of the available tools
+Action Input: the input to the action
+Observation: the result of the action
+... (this Thought/Action/Action Input/Observation can repeat N times)
+Thought: I now know the final answer
+Final Answer: the final answer to the original input question"""
+
+
+SERVER_MANAGER_SYSTEM_PROMPT_TEMPLATE = """You are a helpful assistant designed to interact with MCP
+ (Model Context Protocol) servers. You can manage connections to different servers and use the tools
+ provided by the currently active server.
+
+Important: The available tools change depending on which server is active.
+If a request requires tools not listed below (e.g., file operations, web browsing,
+ image manipulation), you MUST first connect to the appropriate server using
+ 'connect_to_mcp_server'.
+Use 'list_mcp_servers' to find the relevant server if you are unsure.
+Only after successfully connecting and seeing the new tools listed in
+the response should you attempt to use those server-specific tools.
+Before attempting a task that requires specific tools, you should
+ensure you are connected to the correct server and aware of its
+available tools. If unsure, use 'list_mcp_servers' to see options
+or 'get_active_mcp_server' to check the current connection.
+
+When you connect to a server using 'connect_to_mcp_server',
+ you will be informed about the new tools that become available.
+You can then use these server-specific tools in subsequent steps.
+
+Here are the tools *currently* available to you (this list includes server management tools and will
+ change when you connect to a server):
+{tool_descriptions}
+"""

mcp_use/agents/server_manager.py

@@ -0,0 +1,280 @@
+from langchain_core.tools import BaseTool, StructuredTool
+from pydantic import BaseModel, Field
+
+from mcp_use.client import MCPClient
+from mcp_use.logging import logger
+
+from ..adapters.langchain_adapter import LangChainAdapter
+
+
+class ServerActionInput(BaseModel):
+    """Base input for server-related actions"""
+
+    server_name: str = Field(description="The name of the MCP server")
+
+
+class DisconnectServerInput(BaseModel):
+    """Empty input for disconnecting from the current server"""
+
+    pass
+
+
+class ListServersInput(BaseModel):
+    """Empty input for listing available servers"""
+
+    pass
+
+
+class CurrentServerInput(BaseModel):
+    """Empty input for checking current server"""
+
+    pass
+
+
+class ServerManager:
+    """Manages MCP servers and provides tools for server selection and management.
+
+    This class allows an agent to discover and select which MCP server to use,
+    dynamically activating the tools for the selected server.
+    """
+
+    def __init__(self, client: MCPClient, adapter: LangChainAdapter) -> None:
+        """Initialize the server manager.
+
+        Args:
+            client: The MCPClient instance managing server connections
+            adapter: The LangChainAdapter for converting MCP tools to LangChain tools
+        """
+        self.client = client
+        self.adapter = adapter
+        self.active_server: str | None = None
+        self.initialized_servers: dict[str, bool] = {}
+        self._server_tools: dict[str, list[BaseTool]] = {}
+
+    async def initialize(self) -> None:
+        """Initialize the server manager and prepare server management tools."""
+        # Make sure we have server configurations
+        if not self.client.get_server_names():
+            logger.warning("No MCP servers defined in client configuration")
+
+    async def get_server_management_tools(self) -> list[BaseTool]:
+        """Get tools for managing server connections.
+
+        Returns:
+            List of LangChain tools for server management
+        """
+        # Create structured tools for server management with direct parameter passing
+        list_servers_tool = StructuredTool.from_function(
+            coroutine=self.list_servers,
+            name="list_mcp_servers",
+            description="Lists all available MCP (Model Context Protocol) servers that can be "
+            "connected to, along with the tools available on each server. "
+            "Use this tool to discover servers and see what functionalities they offer.",
+            args_schema=ListServersInput,
+        )
+
+        connect_server_tool = StructuredTool.from_function(
+            coroutine=self.connect_to_server,
+            name="connect_to_mcp_server",
+            description="Connect to a specific MCP (Model Context Protocol) server to use its "
+            "tools. Use this tool to connect to a specific server and use its tools.",
+            args_schema=ServerActionInput,
+        )
+
+        get_active_server_tool = StructuredTool.from_function(
+            coroutine=self.get_active_server,
+            name="get_active_mcp_server",
+            description="Get the currently active MCP (Model Context Protocol) server",
+            args_schema=CurrentServerInput,
+        )
+
+        disconnect_server_tool = StructuredTool.from_function(
+            func=None,
+            coroutine=self.disconnect_from_server,
+            name="disconnect_from_mcp_server",
+            description="Disconnect from the currently active MCP (Model Context Protocol) server",
+            args_schema=DisconnectServerInput,
+        )
+
+        return [
+            list_servers_tool,
+            connect_server_tool,
+            get_active_server_tool,
+            disconnect_server_tool,
+        ]
+
+    async def list_servers(self) -> str:
+        """List all available MCP servers along with their available tools.
+
+        Returns:
+            String listing all available servers and their tools.
+        """
+        servers = self.client.get_server_names()
+        if not servers:
+            return "No MCP servers are currently defined."
+
+        result = "Available MCP servers:\n"
+        for i, server_name in enumerate(servers):
+            active_marker = " (ACTIVE)" if server_name == self.active_server else ""
+            result += f"{i + 1}. {server_name}{active_marker}\n"
+
+            tools: list[BaseTool] = []
+            try:
+                # Check cache first
+                if server_name in self._server_tools:
+                    tools = self._server_tools[server_name]
+                else:
+                    # Attempt to get/create session without setting active
+                    session = None
+                    try:
+                        session = self.client.get_session(server_name)
+                        logger.debug(
+                            f"Using existing session for server '{server_name}' to list tools."
+                        )
+                    except ValueError:
+                        try:
+                            # Only create session if needed, don't set active
+                            session = await self.client.create_session(server_name)
+                            logger.debug(f"Temporarily created session for server '{server_name}'")
+                        except Exception:
+                            logger.warning(f"Could not create session for server '{server_name}'")
+
+                    # Fetch tools if session is available
+                    if session:
+                        try:
+                            connector = session.connector
+                            fetched_tools = await self.adapter.create_langchain_tools([connector])
+                            self._server_tools[server_name] = fetched_tools  # Cache tools
+                            self.initialized_servers[server_name] = True  # Mark as initialized
+                            tools = fetched_tools
+                            logger.debug(f"Fetched {len(tools)} tools for server '{server_name}'.")
+                        except Exception as e:
+                            logger.warning(f"Could not fetch tools for server '{server_name}': {e}")
+                            # Keep tools as empty list if fetching failed
+
+                # Append tool names to the result string
+                if tools:
+                    tool_names = ", ".join([tool.name for tool in tools])
+                    result += f"   Tools: {tool_names}\n"
+                else:
+                    result += "   Tools: (Could not retrieve or none available)\n"
+
+            except Exception as e:
+                logger.error(f"Unexpected error listing tools for server '{server_name}': {e}")
+                result += "   Tools: (Error retrieving tools)\n"
+
+        return result
+
+    async def connect_to_server(self, server_name: str) -> str:
+        """Connect to a specific MCP server.
+
+        Args:
+            server_name: The name of the server to connect to
+
+        Returns:
+            Status message about the connection
+        """
+        # Check if server exists
+        servers = self.client.get_server_names()
+        if server_name not in servers:
+            available = ", ".join(servers) if servers else "none"
+            return f"Server '{server_name}' not found. Available servers: {available}"
+
+        # If we're already connected to this server, just return
+        if self.active_server == server_name:
+            return f"Already connected to MCP server '{server_name}'"
+
+        try:
+            # Create or get session for this server
+            try:
+                session = self.client.get_session(server_name)
+                logger.debug(f"Using existing session for server '{server_name}'")
+            except ValueError:
+                logger.debug(f"Creating new session for server '{server_name}'")
+                session = await self.client.create_session(server_name)
+
+            # Set as active server
+            self.active_server = server_name
+
+            # Initialize server tools if not already initialized
+            if server_name not in self._server_tools:
+                connector = session.connector
+                self._server_tools[server_name] = await self.adapter.create_langchain_tools(
+                    [connector]
+                )
+                self.initialized_servers[server_name] = True
+
+            server_tools = self._server_tools.get(server_name, [])
+            num_tools = len(server_tools)
+
+            tool_descriptions = "\nAvailable tools for this server:\n"
+            for i, tool in enumerate(server_tools):
+                tool_descriptions += f"{i + 1}. {tool.name}: {tool.description}\n"
+
+            return (
+                f"Connected to MCP server '{server_name}'. "
+                f"{num_tools} tools are now available."
+                f"{tool_descriptions}"
+            )
+
+        except Exception as e:
+            logger.error(f"Error connecting to server '{server_name}': {e}")
+            return f"Failed to connect to server '{server_name}': {str(e)}"
+
+    async def get_active_server(self) -> str:
+        """Get the currently active MCP server.
+
+        Returns:
+            Name of the active server or message if none is active
+        """
+        if not self.active_server:
+            return (
+                "No MCP server is currently active. "
+                "Use connect_to_mcp_server to connect to a server."
+            )
+        return f"Currently active MCP server: {self.active_server}"
+
+    async def disconnect_from_server(self) -> str:
+        """Disconnect from the currently active MCP server.
+
+        Returns:
+            Status message about the disconnection
+        """
+
+        if not self.active_server:
+            return "No MCP server is currently active, so there's nothing to disconnect from."
+
+        server_name = self.active_server
+        try:
+            # Clear the active server
+            self.active_server = None
+
+            # Note: We're not actually closing the session here, just 'deactivating'
+            # This way we keep the session cache without requiring reconnection if needed again
+            # TODO: consider closing the sessions
+
+            return f"Successfully disconnected from MCP server '{server_name}'."
+        except Exception as e:
+            logger.error(f"Error disconnecting from server '{server_name}': {e}")
+            return f"Failed to disconnect from server '{server_name}': {str(e)}"
+
+    async def get_active_server_tools(self) -> list[BaseTool]:
+        """Get the tools for the currently active server.
+
+        Returns:
+            List of LangChain tools for the active server or empty list if no active server
+        """
+        if not self.active_server:
+            return []
+
+        return self._server_tools.get(self.active_server, [])
+
+    async def get_all_tools(self) -> list[BaseTool]:
+        """Get all tools - both server management tools and tools for the active server.
+
+        Returns:
+            Combined list of server management tools and active server tools
+        """
+        management_tools = await self.get_server_management_tools()
+        active_server_tools = await self.get_active_server_tools()
+        return management_tools + active_server_tools

mcp_use/logging.py

@@ -9,6 +9,11 @@ import logging
 import os
 import sys
 
+from langchain.globals import set_debug as langchain_set_debug
+
+# Global debug flag - can be set programmatically or from environment
+MCP_USE_DEBUG = False
+
 
 class Logger:
     """Centralized logger for mcp_use.
@@ -45,7 +50,7 @@ class Logger:
     @classmethod
     def configure(
         cls,
-        level: int | str = logging.INFO,
+        level: int | str = None,
         format_str: str | None = None,
         log_to_console: bool = True,
         log_to_file: str | None = None,
@@ -53,16 +58,26 @@ class Logger:
         """Configure the root mcp_use logger.
 
         Args:
-            level: Log level (default: INFO)
+            level: Log level (default: DEBUG if MCP_USE_DEBUG is 2,
+            INFO if MCP_USE_DEBUG is 1,
+            otherwise WARNING)
             format_str: Log format string (default: DEFAULT_FORMAT)
             log_to_console: Whether to log to console (default: True)
             log_to_file: Path to log file (default: None)
         """
         root_logger = cls.get_logger()
 
-        # Set level
-        if isinstance(level, str):
+        # Set level based on debug settings if not explicitly provided
+        if level is None:
+            if MCP_USE_DEBUG == 2:
+                level = logging.DEBUG
+            elif MCP_USE_DEBUG == 1:
+                level = logging.INFO
+            else:
+                level = logging.WARNING
+        elif isinstance(level, str):
             level = getattr(logging, level.upper())
+
         root_logger.setLevel(level)
 
         # Clear existing handlers
@@ -89,6 +104,38 @@ class Logger:
             file_handler.setFormatter(formatter)
             root_logger.addHandler(file_handler)
 
+    @classmethod
+    def set_debug(cls, debug_level: int = 2) -> None:
+        """Set the debug flag and update the log level accordingly.
+
+        Args:
+            debug_level: Debug level (0=off, 1=info, 2=debug)
+        """
+        global MCP_USE_DEBUG
+        MCP_USE_DEBUG = debug_level
+
+        # Update log level for existing loggers
+        if debug_level == 2:
+            for logger in cls._loggers.values():
+                logger.setLevel(logging.DEBUG)
+                langchain_set_debug(True)
+        elif debug_level == 1:
+            for logger in cls._loggers.values():
+                logger.setLevel(logging.INFO)
+                langchain_set_debug(False)
+        else:
+            # Reset to default (WARNING)
+            for logger in cls._loggers.values():
+                logger.setLevel(logging.WARNING)
+                langchain_set_debug(False)
+
+
+# Check environment variable for debug flag
+debug_env = os.environ.get("DEBUG", "").lower()
+if debug_env == "2":
+    MCP_USE_DEBUG = 2
+elif debug_env == "1":
+    MCP_USE_DEBUG = 1
 
 # Configure default logger
 Logger.configure()

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mcp-use
-Version: 1.1.5
+Version: 1.2.5
 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,6 +66,7 @@ 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 |
 
@@ -388,7 +390,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 +416,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 +451,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 +503,63 @@ 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 +568,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.