mcp-use 1.1.4__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/client.py

@@ -214,7 +214,7 @@ class MCPClient:
 
         try:
             # Disconnect from the session
-            logger.info(f"Closing session for server '{server_name}'")
+            logger.debug(f"Closing session for server '{server_name}'")
             await session.disconnect()
         except Exception as e:
             logger.error(f"Error closing session for server '{server_name}': {e}")
@@ -237,7 +237,7 @@ class MCPClient:
 
         for server_name in server_names:
             try:
-                logger.info(f"Closing session for server '{server_name}'")
+                logger.debug(f"Closing session for server '{server_name}'")
                 await self.close_session(server_name)
             except Exception as e:
                 error_msg = f"Failed to close session for server '{server_name}': {e}"
@@ -248,4 +248,4 @@ class MCPClient:
         if errors:
             logger.error(f"Encountered {len(errors)} errors while closing sessions")
         else:
-            logger.info("All sessions closed successfully")
+            logger.debug("All sessions closed successfully")

mcp_use/connectors/base.py

@@ -39,10 +39,10 @@ class BaseConnector(ABC):
             logger.debug("Not connected to MCP implementation")
             return
 
-        logger.info("Disconnecting from MCP implementation")
+        logger.debug("Disconnecting from MCP implementation")
         await self._cleanup_resources()
         self._connected = False
-        logger.info("Disconnected from MCP implementation")
+        logger.debug("Disconnected from MCP implementation")
 
     async def _cleanup_resources(self) -> None:
         """Clean up all resources associated with this connector."""
@@ -83,7 +83,7 @@ class BaseConnector(ABC):
         if not self.client:
             raise RuntimeError("MCP client is not connected")
 
-        logger.info("Initializing MCP session")
+        logger.debug("Initializing MCP session")
 
         # Initialize the session
         result = await self.client.initialize()
@@ -92,7 +92,7 @@ class BaseConnector(ABC):
         tools_result = await self.client.list_tools()
         self._tools = tools_result.tools
 
-        logger.info(f"MCP session initialized with {len(self._tools)} tools")
+        logger.debug(f"MCP session initialized with {len(self._tools)} tools")
 
         return result
 
@@ -110,6 +110,7 @@ class BaseConnector(ABC):
 
         logger.debug(f"Calling tool '{name}' with arguments: {arguments}")
         result = await self.client.call_tool(name, arguments)
+        logger.debug(f"Tool '{name}' called with result: {result}")
         return result
 
     async def list_resources(self) -> list[dict[str, Any]]:

mcp_use/connectors/http.py

@@ -51,7 +51,7 @@ class HttpConnector(BaseConnector):
             logger.debug("Already connected to MCP implementation")
             return
 
-        logger.info(f"Connecting to MCP implementation via HTTP/SSE: {self.base_url}")
+        logger.debug(f"Connecting to MCP implementation via HTTP/SSE: {self.base_url}")
         try:
             # Create the SSE connection URL
             sse_url = f"{self.base_url}"
@@ -68,7 +68,7 @@ class HttpConnector(BaseConnector):
 
             # Mark as connected
             self._connected = True
-            logger.info(
+            logger.debug(
                 f"Successfully connected to MCP implementation via HTTP/SSE: {self.base_url}"
             )
 

mcp_use/connectors/stdio.py

@@ -49,7 +49,7 @@ class StdioConnector(BaseConnector):
             logger.debug("Already connected to MCP implementation")
             return
 
-        logger.info(f"Connecting to MCP implementation: {self.command}")
+        logger.debug(f"Connecting to MCP implementation: {self.command}")
         try:
             # Create server parameters
             server_params = StdioServerParameters(
@@ -66,7 +66,7 @@ class StdioConnector(BaseConnector):
 
             # Mark as connected
             self._connected = True
-            logger.info(f"Successfully connected to MCP implementation: {self.command}")
+            logger.debug(f"Successfully connected to MCP implementation: {self.command}")
 
         except Exception as e:
             logger.error(f"Failed to connect to MCP implementation: {e}")

mcp_use/connectors/websocket.py

@@ -57,7 +57,7 @@ class WebSocketConnector(BaseConnector):
             logger.debug("Already connected to MCP implementation")
             return
 
-        logger.info(f"Connecting to MCP implementation via WebSocket: {self.url}")
+        logger.debug(f"Connecting to MCP implementation via WebSocket: {self.url}")
         try:
             # Create and start the connection manager
             self._connection_manager = WebSocketConnectionManager(self.url, self.headers)
@@ -70,7 +70,7 @@ class WebSocketConnector(BaseConnector):
 
             # Mark as connected
             self._connected = True
-            logger.info(f"Successfully connected to MCP implementation via WebSocket: {self.url}")
+            logger.debug(f"Successfully connected to MCP implementation via WebSocket: {self.url}")
 
         except Exception as e:
             logger.error(f"Failed to connect to MCP implementation via WebSocket: {e}")
@@ -117,10 +117,10 @@ class WebSocketConnector(BaseConnector):
             logger.debug("Not connected to MCP implementation")
             return
 
-        logger.info("Disconnecting from MCP implementation")
+        logger.debug("Disconnecting from MCP implementation")
         await self._cleanup_resources()
         self._connected = False
-        logger.info("Disconnected from MCP implementation")
+        logger.debug("Disconnected from MCP implementation")
 
     async def _cleanup_resources(self) -> None:
         """Clean up all resources associated with this connector."""
@@ -199,14 +199,14 @@ class WebSocketConnector(BaseConnector):
 
     async def initialize(self) -> dict[str, Any]:
         """Initialize the MCP session and return session information."""
-        logger.info("Initializing MCP session")
+        logger.debug("Initializing MCP session")
         result = await self._send_request("initialize")
 
         # Get available tools
         tools_result = await self.list_tools()
         self._tools = [Tool(**tool) for tool in tools_result]
 
-        logger.info(f"MCP session initialized with {len(self._tools)} tools")
+        logger.debug(f"MCP session initialized with {len(self._tools)} tools")
         return result
 
     async def list_tools(self) -> list[dict[str, Any]]:

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()