mcp-use 1.3.8__py3-none-any.whl → 1.3.10__py3-none-any.whl

mcp_use/connectors/base.py

@@ -5,14 +5,27 @@ This module provides the base connector interface that all MCP connectors
 must implement.
 """
 
+import warnings
 from abc import ABC, abstractmethod
 from datetime import timedelta
 from typing import Any
 
 from mcp import ClientSession, Implementation
-from mcp.client.session import ElicitationFnT, SamplingFnT
+from mcp.client.session import ElicitationFnT, LoggingFnT, MessageHandlerFnT, SamplingFnT
 from mcp.shared.exceptions import McpError
-from mcp.types import CallToolResult, GetPromptResult, Prompt, ReadResourceResult, Resource, Tool
+from mcp.types import (
+    CallToolResult,
+    GetPromptResult,
+    Prompt,
+    PromptListChangedNotification,
+    ReadResourceResult,
+    Resource,
+    ResourceListChangedNotification,
+    ServerCapabilities,
+    ServerNotification,
+    Tool,
+    ToolListChangedNotification,
+)
 from pydantic import AnyUrl
 
 import mcp_use
@@ -31,6 +44,8 @@ class BaseConnector(ABC):
         self,
         sampling_callback: SamplingFnT | None = None,
         elicitation_callback: ElicitationFnT | None = None,
+        message_handler: MessageHandlerFnT | None = None,
+        logging_callback: LoggingFnT | None = None,
     ):
         """Initialize base connector with common attributes."""
         self.client_session: ClientSession | None = None
@@ -43,6 +58,9 @@ class BaseConnector(ABC):
         self.auto_reconnect = True  # Whether to automatically reconnect on connection loss (not configurable for now)
         self.sampling_callback = sampling_callback
         self.elicitation_callback = elicitation_callback
+        self.message_handler = message_handler
+        self.logging_callback = logging_callback
+        self.capabilities: ServerCapabilities | None = None
 
     @property
     def client_info(self) -> Implementation:
@@ -53,6 +71,20 @@ class BaseConnector(ABC):
             url="https://github.com/mcp-use/mcp-use",
         )
 
+    async def _internal_message_handler(self, message: Any) -> None:
+        """Wrap the user-provided message handler."""
+        if isinstance(message, ServerNotification):
+            if isinstance(message.root, ToolListChangedNotification):
+                logger.debug("Received tool list changed notification")
+            elif isinstance(message.root, ResourceListChangedNotification):
+                logger.debug("Received resource list changed notification")
+            elif isinstance(message.root, PromptListChangedNotification):
+                logger.debug("Received prompt list changed notification")
+
+        # Call the user's handler
+        if self.message_handler:
+            await self.message_handler(message)
+
     @abstractmethod
     async def connect(self) -> None:
         """Establish a connection to the MCP implementation."""
@@ -125,37 +157,37 @@ class BaseConnector(ABC):
         result = await self.client_session.initialize()
         self._initialized = True  # Mark as initialized
 
-        server_capabilities = result.capabilities
+        self.capabilities = result.capabilities
 
-        if server_capabilities.tools:
+        if self.capabilities.tools:
             # Get available tools directly from client session
             try:
                 tools_result = await self.client_session.list_tools()
                 self._tools = tools_result.tools if tools_result else []
             except Exception as e:
-                logger.error(f"Error listing tools: {e}")
+                logger.error(f"Error listing tools for connector {self.public_identifier}: {e}")
                 self._tools = []
         else:
             self._tools = []
 
-        if server_capabilities.resources:
+        if self.capabilities.resources:
             # Get available resources directly from client session
             try:
                 resources_result = await self.client_session.list_resources()
                 self._resources = resources_result.resources if resources_result else []
             except Exception as e:
-                logger.error(f"Error listing resources: {e}")
+                logger.error(f"Error listing resources for connector {self.public_identifier}: {e}")
                 self._resources = []
         else:
             self._resources = []
 
-        if server_capabilities.prompts:
+        if self.capabilities.prompts:
             # Get available prompts directly from client session
             try:
                 prompts_result = await self.client_session.list_prompts()
                 self._prompts = prompts_result.prompts if prompts_result else []
             except Exception as e:
-                logger.error(f"Error listing prompts: {e}")
+                logger.error(f"Error listing prompts for connector {self.public_identifier}: {e}")
                 self._prompts = []
         else:
             self._prompts = []
@@ -170,21 +202,57 @@ class BaseConnector(ABC):
 
     @property
     def tools(self) -> list[Tool]:
-        """Get the list of available tools."""
+        """Get the list of available tools.
+
+        .. deprecated::
+            This property is deprecated because it may return stale data when the server
+            sends list change notifications. Use `await list_tools()` instead to ensure
+            you always get the latest data.
+        """
+        warnings.warn(
+            "The 'tools' property is deprecated and may return stale data. "
+            "Use 'await list_tools()' instead to ensure fresh data.",
+            DeprecationWarning,
+            stacklevel=2,
+        )
         if self._tools is None:
             raise RuntimeError("MCP client is not initialized")
         return self._tools
 
     @property
     def resources(self) -> list[Resource]:
-        """Get the list of available resources."""
+        """Get the list of available resources.
+
+        .. deprecated::
+            This property is deprecated because it may return stale data when the server
+            sends list change notifications. Use `await list_resources()` instead to ensure
+            you always get the latest data.
+        """
+        warnings.warn(
+            "The 'resources' property is deprecated and may return stale data. "
+            "Use 'await list_resources()' instead to ensure fresh data.",
+            DeprecationWarning,
+            stacklevel=2,
+        )
         if self._resources is None:
             raise RuntimeError("MCP client is not initialized")
         return self._resources
 
     @property
     def prompts(self) -> list[Prompt]:
-        """Get the list of available prompts."""
+        """Get the list of available prompts.
+
+        .. deprecated::
+            This property is deprecated because it may return stale data when the server
+            sends list change notifications. Use `await list_prompts()' instead to ensure
+            you always get the latest data.
+        """
+        warnings.warn(
+            "The 'prompts' property is deprecated and may return stale data. "
+            "Use 'await list_prompts()' instead to ensure fresh data.",
+            DeprecationWarning,
+            stacklevel=2,
+        )
         if self._prompts is None:
             raise RuntimeError("MCP client is not initialized")
         return self._prompts
@@ -303,28 +371,39 @@ class BaseConnector(ABC):
     async def list_tools(self) -> list[Tool]:
         """List all available tools from the MCP implementation."""
 
+        if self.capabilities and not self.capabilities.tools:
+            logger.debug(f"Server {self.public_identifier} does not support tools")
+            return []
+
         # Ensure we're connected
         await self._ensure_connected()
 
         logger.debug("Listing tools")
         try:
             result = await self.client_session.list_tools()
+            self._tools = result.tools
             return result.tools
         except McpError as e:
-            logger.error(f"Error listing tools: {e}")
+            logger.error(f"Error listing tools for connector {self.public_identifier}: {e}")
             return []
 
     async def list_resources(self) -> list[Resource]:
         """List all available resources from the MCP implementation."""
+
+        if self.capabilities and not self.capabilities.resources:
+            logger.debug(f"Server {self.public_identifier} does not support resources")
+            return []
+
         # Ensure we're connected
         await self._ensure_connected()
 
         logger.debug("Listing resources")
         try:
             result = await self.client_session.list_resources()
+            self._resources = result.resources
             return result.resources
         except McpError as e:
-            logger.error(f"Error listing resources: {e}")
+            logger.warning(f"Error listing resources for connector {self.public_identifier}: {e}")
             return []
 
     async def read_resource(self, uri: AnyUrl) -> ReadResourceResult:
@@ -337,14 +416,20 @@ class BaseConnector(ABC):
 
     async def list_prompts(self) -> list[Prompt]:
         """List all available prompts from the MCP implementation."""
+
+        if self.capabilities and not self.capabilities.prompts:
+            logger.debug(f"Server {self.public_identifier} does not support prompts")
+            return []
+
         await self._ensure_connected()
 
         logger.debug("Listing prompts")
         try:
             result = await self.client_session.list_prompts()
+            self._prompts = result.prompts
             return result.prompts
         except McpError as e:
-            logger.error(f"Error listing prompts: {e}")
+            logger.error(f"Error listing prompts for connector {self.public_identifier}: {e}")
             return []
 
     async def get_prompt(self, name: str, arguments: dict[str, Any] | None = None) -> GetPromptResult:

mcp_use/connectors/http.py

@@ -7,7 +7,7 @@ through HTTP APIs with SSE or Streamable HTTP for transport.
 
 import httpx
 from mcp import ClientSession
-from mcp.client.session import ElicitationFnT, SamplingFnT
+from mcp.client.session import ElicitationFnT, LoggingFnT, MessageHandlerFnT, SamplingFnT
 
 from ..logging import logger
 from ..task_managers import SseConnectionManager, StreamableHttpConnectionManager
@@ -30,6 +30,8 @@ class HttpConnector(BaseConnector):
         sse_read_timeout: float = 60 * 5,
         sampling_callback: SamplingFnT | None = None,
         elicitation_callback: ElicitationFnT | None = None,
+        message_handler: MessageHandlerFnT | None = None,
+        logging_callback: LoggingFnT | None = None,
     ):
         """Initialize a new HTTP connector.
 
@@ -42,7 +44,12 @@ class HttpConnector(BaseConnector):
             sampling_callback: Optional sampling callback.
             elicitation_callback: Optional elicitation callback.
         """
-        super().__init__(sampling_callback=sampling_callback, elicitation_callback=elicitation_callback)
+        super().__init__(
+            sampling_callback=sampling_callback,
+            elicitation_callback=elicitation_callback,
+            message_handler=message_handler,
+            logging_callback=logging_callback,
+        )
         self.base_url = base_url.rstrip("/")
         self.auth_token = auth_token
         self.headers = headers or {}
@@ -78,6 +85,8 @@ class HttpConnector(BaseConnector):
                 write_stream,
                 sampling_callback=self.sampling_callback,
                 elicitation_callback=self.elicitation_callback,
+                message_handler=self._internal_message_handler,
+                logging_callback=self.logging_callback,
                 client_info=self.client_info,
             )
             await test_client.__aenter__()
@@ -162,6 +171,8 @@ class HttpConnector(BaseConnector):
                         write_stream,
                         sampling_callback=self.sampling_callback,
                         elicitation_callback=self.elicitation_callback,
+                        message_handler=self._internal_message_handler,
+                        logging_callback=self.logging_callback,
                         client_info=self.client_info,
                     )
                     await self.client_session.__aenter__()

mcp_use/connectors/sandbox.py

@@ -12,7 +12,7 @@ import time
 
 import aiohttp
 from mcp import ClientSession
-from mcp.client.session import ElicitationFnT, SamplingFnT
+from mcp.client.session import ElicitationFnT, LoggingFnT, MessageHandlerFnT, SamplingFnT
 
 from ..logging import logger
 from ..task_managers import SseConnectionManager
@@ -20,10 +20,7 @@ from ..task_managers import SseConnectionManager
 # Import E2B SDK components (optional dependency)
 try:
     logger.debug("Attempting to import e2b_code_interpreter...")
-    from e2b_code_interpreter import (
-        CommandHandle,
-        Sandbox,
-    )
+    from e2b_code_interpreter import CommandHandle, Sandbox
 
     logger.debug("Successfully imported e2b_code_interpreter")
 except ImportError as e:
@@ -53,6 +50,8 @@ class SandboxConnector(BaseConnector):
         sse_read_timeout: float = 60 * 5,
         sampling_callback: SamplingFnT | None = None,
         elicitation_callback: ElicitationFnT | None = None,
+        message_handler: MessageHandlerFnT | None = None,
+        logging_callback: LoggingFnT | None = None,
     ):
         """Initialize a new sandbox connector.
 
@@ -67,7 +66,12 @@ class SandboxConnector(BaseConnector):
             sampling_callback: Optional sampling callback.
             elicitation_callback: Optional elicitation callback.
         """
-        super().__init__(sampling_callback=sampling_callback, elicitation_callback=elicitation_callback)
+        super().__init__(
+            sampling_callback=sampling_callback,
+            elicitation_callback=elicitation_callback,
+            message_handler=message_handler,
+            logging_callback=logging_callback,
+        )
         if Sandbox is None:
             raise ImportError(
                 "E2B SDK (e2b-code-interpreter) not found. Please install it with "
@@ -227,6 +231,8 @@ class SandboxConnector(BaseConnector):
                 write_stream,
                 sampling_callback=self.sampling_callback,
                 elicitation_callback=self.elicitation_callback,
+                message_handler=self._internal_message_handler,
+                logging_callback=self.logging_callback,
                 client_info=self.client_info,
             )
             await self.client_session.__aenter__()

mcp_use/connectors/stdio.py

@@ -8,7 +8,7 @@ through the standard input/output streams.
 import sys
 
 from mcp import ClientSession, StdioServerParameters
-from mcp.client.session import ElicitationFnT, SamplingFnT
+from mcp.client.session import ElicitationFnT, LoggingFnT, MessageHandlerFnT, SamplingFnT
 
 from ..logging import logger
 from ..task_managers import StdioConnectionManager
@@ -31,6 +31,8 @@ class StdioConnector(BaseConnector):
         errlog=sys.stderr,
         sampling_callback: SamplingFnT | None = None,
         elicitation_callback: ElicitationFnT | None = None,
+        message_handler: MessageHandlerFnT | None = None,
+        logging_callback: LoggingFnT | None = None,
     ):
         """Initialize a new stdio connector.
 
@@ -42,7 +44,12 @@ class StdioConnector(BaseConnector):
             sampling_callback: Optional callback to sample the client.
             elicitation_callback: Optional callback to elicit the client.
         """
-        super().__init__(sampling_callback=sampling_callback, elicitation_callback=elicitation_callback)
+        super().__init__(
+            sampling_callback=sampling_callback,
+            elicitation_callback=elicitation_callback,
+            message_handler=message_handler,
+            logging_callback=logging_callback,
+        )
         self.command = command
         self.args = args or []  # Ensure args is never None
         self.env = env
@@ -69,6 +76,8 @@ class StdioConnector(BaseConnector):
                 write_stream,
                 sampling_callback=self.sampling_callback,
                 elicitation_callback=self.elicitation_callback,
+                message_handler=self._internal_message_handler,
+                logging_callback=self.logging_callback,
                 client_info=self.client_info,
             )
             await self.client_session.__aenter__()

mcp_use/errors/__init__.py

@@ -0,0 +1 @@
+

mcp_use/errors/error_formatting.py

@@ -0,0 +1,29 @@
+import traceback
+
+from ..logging import logger
+
+retryable_exceptions = (TimeoutError, ConnectionError)  # We can add more exceptions here
+
+
+def format_error(error: Exception, **context) -> dict:
+    """
+    Formats an exception into a structured format that can be understood by LLMs.
+
+    Args:
+        error: The exception to format.
+        **context: Additional context to include in the formatted error.
+
+    Returns:
+        A dictionary containing the formatted error.
+    """
+    formatted_context = {
+        "error": type(error).__name__,
+        "details": str(error),
+        "isRetryable": isinstance(error, retryable_exceptions),
+        "stack": traceback.format_exc(),
+        "code": getattr(error, "code", "UNKNOWN"),
+    }
+    formatted_context.update(context)
+
+    logger.error(f"Structured error: {formatted_context}")  # For observability (maybe remove later)
+    return formatted_context

mcp_use/logging.py

@@ -80,6 +80,9 @@ class Logger:
 
         root_logger.setLevel(level)
 
+        # Set propagate to True to ensure child loggers inherit settings
+        root_logger.propagate = True
+
         # Clear existing handlers
         for handler in root_logger.handlers[:]:
             root_logger.removeHandler(handler)
@@ -91,6 +94,7 @@ class Logger:
         if log_to_console:
             console_handler = logging.StreamHandler(sys.stdout)
             console_handler.setFormatter(formatter)
+            console_handler.setLevel(level)  # Ensure handler respects the level
             root_logger.addHandler(console_handler)
 
         # Add file handler if requested
@@ -102,6 +106,7 @@ class Logger:
 
             file_handler = logging.FileHandler(log_to_file)
             file_handler.setFormatter(formatter)
+            file_handler.setLevel(level)  # Ensure handler respects the level
             root_logger.addHandler(file_handler)
 
     @classmethod
@@ -114,24 +119,34 @@ class Logger:
         global MCP_USE_DEBUG
         MCP_USE_DEBUG = debug_level
 
-        # Update log level for existing loggers
+        # Determine the target level
         if debug_level == 2:
-            for logger in cls._loggers.values():
-                logger.setLevel(logging.DEBUG)
-                langchain_set_debug(True)
+            target_level = logging.DEBUG
+            langchain_set_debug(True)
         elif debug_level == 1:
-            for logger in cls._loggers.values():
-                logger.setLevel(logging.INFO)
-                langchain_set_debug(False)
+            target_level = 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)
+            target_level = logging.WARNING
+            langchain_set_debug(False)
+
+        # Update log level for existing loggers in our registry
+        for logger in cls._loggers.values():
+            logger.setLevel(target_level)
+            # Also update handler levels
+            for handler in logger.handlers:
+                handler.setLevel(target_level)
+
+        # Also update all mcp_use child loggers that might exist
+        # This ensures loggers created with logging.getLogger() are also updated
+        base_logger = logging.getLogger("mcp_use")
+        base_logger.setLevel(target_level)
+        for handler in base_logger.handlers:
+            handler.setLevel(target_level)
 
 
 # Check environment variable for debug flag
-debug_env = os.environ.get("DEBUG", "").lower()
+debug_env = os.environ.get("MCP_USE_DEBUG", "").lower() or os.environ.get("DEBUG", "").lower()
 if debug_env == "2":
     MCP_USE_DEBUG = 2
 elif debug_env == "1":

mcp_use/managers/base.py

@@ -0,0 +1,36 @@
+from abc import ABC, abstractmethod
+
+from langchain_core.tools import BaseTool
+
+
+class BaseServerManager(ABC):
+    """Abstract base class for server managers.
+
+    This class defines the interface for server managers that can be used with MCPAgent.
+    Custom server managers should inherit from this class and implement the required methods.
+    """
+
+    @abstractmethod
+    async def initialize(self) -> None:
+        """Initialize the server manager."""
+        raise NotImplementedError
+
+    @property
+    @abstractmethod
+    def tools(self) -> list[BaseTool]:
+        """Get all server management tools and tools from the active server.
+
+        Returns:
+            list of LangChain tools for server management plus tools from active server
+        """
+        raise NotImplementedError
+
+    @abstractmethod
+    def has_tool_changes(self, current_tool_names: set[str]) -> bool:
+        """Check if the available tools have changed.
+        Args:
+            current_tool_names: Set of currently known tool names
+        Returns:
+            True if tools have changed, False otherwise
+        """
+        raise NotImplementedError

mcp_use/managers/server_manager.py

@@ -4,16 +4,11 @@ from mcp_use.client import MCPClient
 from mcp_use.logging import logger
 
 from ..adapters.base import BaseAdapter
-from .tools import (
-    ConnectServerTool,
-    DisconnectServerTool,
-    GetActiveServerTool,
-    ListServersTool,
-    SearchToolsTool,
-)
+from .base import BaseServerManager
+from .tools import ConnectServerTool, DisconnectServerTool, GetActiveServerTool, ListServersTool, SearchToolsTool
 
 
-class ServerManager:
+class ServerManager(BaseServerManager):
     """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,

mcp_use/managers/tools/connect_server.py

@@ -2,6 +2,7 @@ from typing import ClassVar
 
 from pydantic import BaseModel, Field
 
+from mcp_use.errors.error_formatting import format_error
 from mcp_use.logging import logger
 
 from .base_tool import MCPServerTool
@@ -62,7 +63,7 @@ class ConnectServerTool(MCPServerTool):
 
         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)}"
+            return format_error(e, server_name=server_name)
 
     def _run(self, server_name: str) -> str:
         """Synchronous version that raises a NotImplementedError - use _arun instead."""

mcp_use/managers/tools/disconnect_server.py

@@ -2,6 +2,7 @@ from typing import ClassVar
 
 from pydantic import BaseModel
 
+from mcp_use.errors.error_formatting import format_error
 from mcp_use.logging import logger
 
 from .base_tool import MCPServerTool
@@ -36,7 +37,7 @@ class DisconnectServerTool(MCPServerTool):
             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)}"
+            return format_error(e, server_name=server_name)
 
     async def _arun(self, **kwargs) -> str:
         """Async implementation of _run."""

mcp_use/managers/tools/list_servers_tool.py

@@ -2,6 +2,7 @@ from typing import ClassVar
 
 from pydantic import BaseModel
 
+from mcp_use.errors.error_formatting import format_error
 from mcp_use.logging import logger
 
 from .base_tool import MCPServerTool
@@ -44,6 +45,7 @@ class ListServersTool(MCPServerTool):
                     result += f"   {tool_count} tools available for this server\n"
             except Exception as e:
                 logger.error(f"Unexpected error listing tools for server '{server_name}': {e}")
+                return format_error(e, server=server_name, operation="list_tools")
 
         return result
 

mcp_use/observability/__init__.py

@@ -4,5 +4,6 @@ from dotenv import load_dotenv
 load_dotenv()
 
 from . import laminar, langfuse  # noqa
+from .callbacks_manager import ObservabilityManager, get_default_manager, create_manager  # noqa
 
-__all__ = ["laminar", "langfuse"]
+__all__ = ["laminar", "langfuse", "ObservabilityManager", "get_default_manager", "create_manager"]