mcp-use 1.3.0__py3-none-any.whl → 1.3.2__py3-none-any.whl

mcp_use/managers/tools/search_tools.py

@@ -48,36 +48,12 @@ class SearchToolsTool(MCPServerTool):
         results = await self._search_tool.search_tools(
             query, top_k=top_k, active_server=self.server_manager.active_server
         )
-        return self.format_search_results(results)
+        return results
 
     def _run(self, query: str, top_k: int = 100) -> str:
         """Synchronous version that raises a NotImplementedError - use _arun instead."""
         raise NotImplementedError("SearchToolsTool requires async execution. Use _arun instead.")
 
-    def format_search_results(self, results: list[tuple[BaseTool, str, float]]) -> str:
-        """Format search results in a consistent format."""
-
-        # Only show top_k results
-        results = results
-
-        formatted_output = "Search results\n\n"
-
-        for i, (tool, server_name, score) in enumerate(results):
-            # Format score as percentage
-            if i < 5:
-                score_pct = f"{score * 100:.1f}%"
-                logger.info(f"{i}: {tool.name} ({score_pct} match)")
-            formatted_output += f"[{i + 1}] Tool: {tool.name} ({score_pct} match)\n"
-            formatted_output += f"    Server: {server_name}\n"
-            formatted_output += f"    Description: {tool.description}\n\n"
-
-        # Add footer with information about how to use the results
-        formatted_output += (
-            "\nTo use a tool, connect to the appropriate server first, then invoke the tool."
-        )
-
-        return formatted_output
-
 
 class ToolSearchEngine:
     """
@@ -115,13 +91,18 @@ class ToolSearchEngine:
 
         try:
             from fastembed import TextEmbedding  # optional dependency install with [search]
-        except ImportError:
+        except ImportError as exc:
             logger.error(
                 "The 'fastembed' library is not installed. "
                 "To use the search functionality, please install it by running: "
                 "pip install mcp-use[search]"
             )
-            return False
+            raise ImportError(
+                "The 'fastembed' library is not installed. "
+                "To use the server_manager functionality, please install it by running: "
+                "pip install mcp-use[search] "
+                "or disable the server_manager by setting use_server_manager=False in the MCPAgent constructor."
+            ) from exc
 
         try:
             self.model = TextEmbedding(model_name="BAAI/bge-small-en-v1.5")
@@ -282,11 +263,7 @@ class ToolSearchEngine:
                 )
 
         # If the server manager has an active server but it wasn't provided, use it
-        if (
-            active_server is None
-            and self.server_manager
-            and hasattr(self.server_manager, "active_server")
-        ):
+        if active_server is None and self.server_manager and hasattr(self.server_manager, "active_server"):
             active_server = self.server_manager.active_server
 
         results = self.search(query, top_k=top_k)
@@ -303,11 +280,27 @@ class ToolSearchEngine:
             marked_results = []
             for tool, server_name, score in results:
                 # If this is the active server, add "(ACTIVE)" marker
-                display_server = (
-                    f"{server_name} (ACTIVE)" if server_name == active_server else server_name
-                )
+                display_server = f"{server_name} (ACTIVE)" if server_name == active_server else server_name
                 marked_results.append((tool, display_server, score))
             results = marked_results
 
         # Format and return the results
-        return results
+        return self._format_search_results(results)
+
+    def _format_search_results(self, results: list[tuple[BaseTool, str, float]]) -> str:
+        """Format search results in a consistent format."""
+        formatted_output = "Search results\n\n"
+
+        for i, (tool, server_name, score) in enumerate(results):
+            # Format score as percentage
+            score_pct = f"{score * 100:.1f}%"
+            if i < 5:
+                logger.info(f"{i}: {tool.name} ({score_pct} match)")
+            formatted_output += f"[{i + 1}] Tool: {tool.name} ({score_pct} match)\n"
+            formatted_output += f"    Server: {server_name}\n"
+            formatted_output += f"    Description: {tool.description}\n\n"
+
+        # Add footer with information about how to use the results
+        formatted_output += "\nTo use a tool, connect to the appropriate server first, then invoke the tool."
+
+        return formatted_output

mcp_use/managers/tools/use_tool.py

@@ -30,9 +30,7 @@ class UseToolFromServerTool(MCPServerTool):
     )
     args_schema: ClassVar[type[BaseModel]] = UseToolInput
 
-    async def _arun(
-        self, server_name: str, tool_name: str, tool_input: dict[str, Any] | str
-    ) -> str:
+    async def _arun(self, server_name: str, tool_name: str, tool_input: dict[str, Any] | str) -> str:
         """Execute a tool from a specific server."""
         # Check if server exists
         servers = self.server_manager.client.get_server_names()
@@ -78,20 +76,14 @@ class UseToolFromServerTool(MCPServerTool):
 
         if not target_tool:
             tool_names = [t.name for t in server_tools]
-            return (
-                f"Tool '{tool_name}' not found on server '{server_name}'. "
-                f"Available tools: {', '.join(tool_names)}"
-            )
+            return f"Tool '{tool_name}' not found on server '{server_name}'. Available tools: {', '.join(tool_names)}"
 
         # Execute the tool with the provided input
         try:
             # Parse the input based on target tool's schema
             structured_input = self._parse_tool_input(target_tool, tool_input)
             if structured_input is None:
-                return (
-                    f"Could not parse input for tool '{tool_name}'."
-                    " Please check the input format and try again."
-                )
+                return f"Could not parse input for tool '{tool_name}'. Please check the input format and try again."
 
             # Store the previous active server
             previous_active = self.server_manager.active_server
@@ -100,10 +92,7 @@ class UseToolFromServerTool(MCPServerTool):
             self.server_manager.active_server = server_name
 
             # Execute the tool
-            logger.info(
-                f"Executing tool '{tool_name}' on server '{server_name}'"
-                "with input: {structured_input}"
-            )
+            logger.info(f"Executing tool '{tool_name}' on server '{server_name}'with input: {{structured_input}}")
             result = await target_tool._arun(**structured_input)
 
             # Restore the previous active server
@@ -162,6 +151,4 @@ class UseToolFromServerTool(MCPServerTool):
 
     def _run(self, server_name: str, tool_name: str, tool_input: dict[str, Any] | str) -> str:
         """Synchronous version that raises a NotImplementedError."""
-        raise NotImplementedError(
-            "UseToolFromServerTool requires async execution. Use _arun instead."
-        )
+        raise NotImplementedError("UseToolFromServerTool requires async execution. Use _arun instead.")

mcp_use/observability/__init__.py

@@ -0,0 +1,8 @@
+from dotenv import load_dotenv
+
+# Load environment variables once for all observability modules
+load_dotenv()
+
+from . import laminar, langfuse  # noqa
+
+__all__ = ["laminar", "langfuse"]

mcp_use/observability/laminar.py

@@ -0,0 +1,21 @@
+import logging
+import os
+
+logger = logging.getLogger(__name__)
+
+# Check if Laminar is disabled via environment variable
+_laminar_disabled = os.getenv("MCP_USE_LAMINAR", "").lower() == "false"
+
+# Only initialize if not disabled and API key is present
+if _laminar_disabled:
+    logger.debug("Laminar tracing disabled via MCP_USE_LAMINAR environment variable")
+elif not os.getenv("LAMINAR_PROJECT_API_KEY"):
+    logger.debug("Laminar API key not found - tracing disabled. Set LAMINAR_PROJECT_API_KEY to enable")
+else:
+    try:
+        from lmnr import Laminar
+
+        Laminar.initialize(project_api_key=os.getenv("LAMINAR_PROJECT_API_KEY"))
+        logger.debug("Laminar observability initialized successfully")
+    except ImportError:
+        logger.debug("Laminar package not installed - tracing disabled. Install with: pip install lmnr")

mcp_use/observability/langfuse.py

@@ -0,0 +1,35 @@
+import logging
+import os
+
+logger = logging.getLogger(__name__)
+
+# Check if Langfuse is disabled via environment variable
+_langfuse_disabled = os.getenv("MCP_USE_LANGFUSE", "").lower() == "false"
+
+# Only initialize if not disabled and required keys are present
+if _langfuse_disabled:
+    logger.debug("Langfuse tracing disabled via MCP_USE_LANGFUSE environment variable")
+    langfuse = None
+    langfuse_handler = None
+elif not os.getenv("LANGFUSE_PUBLIC_KEY") or not os.getenv("LANGFUSE_SECRET_KEY"):
+    logger.debug(
+        "Langfuse API keys not found - tracing disabled. Set LANGFUSE_PUBLIC_KEY and LANGFUSE_SECRET_KEY to enable"
+    )
+    langfuse = None
+    langfuse_handler = None
+else:
+    try:
+        from langfuse import Langfuse
+        from langfuse.langchain import CallbackHandler
+
+        langfuse = Langfuse(
+            public_key=os.getenv("LANGFUSE_PUBLIC_KEY"),
+            secret_key=os.getenv("LANGFUSE_SECRET_KEY"),
+            host=os.getenv("LANGFUSE_HOST", "https://cloud.langfuse.com"),
+        )
+        langfuse_handler = CallbackHandler()
+        logger.debug("Langfuse observability initialized successfully")
+    except ImportError:
+        logger.debug("Langfuse package not installed - tracing disabled. Install with: pip install langfuse")
+        langfuse = None
+        langfuse_handler = None

mcp_use/session.py

@@ -7,8 +7,6 @@ which handles authentication, initialization, and tool discovery.
 
 from typing import Any
 
-from mcp.types import Tool
-
 from .connectors.base import BaseConnector
 
 
@@ -32,7 +30,6 @@ class MCPSession:
         """
         self.connector = connector
         self.session_info: dict[str, Any] | None = None
-        self.tools: list[Tool] = []
         self.auto_connect = auto_connect
 
     async def __aenter__(self) -> "MCPSession":
@@ -84,4 +81,4 @@ class MCPSession:
         Returns:
             True if the connector is connected, False otherwise.
         """
-        return hasattr(self.connector, "client") and self.connector.client is not None
+        return self.connector.is_connected

mcp_use/task_managers/__init__.py

@@ -8,12 +8,13 @@ through different transport mechanisms.
 from .base import ConnectionManager
 from .sse import SseConnectionManager
 from .stdio import StdioConnectionManager
+from .streamable_http import StreamableHttpConnectionManager
 from .websocket import WebSocketConnectionManager
 
 __all__ = [
     "ConnectionManager",
-    "HttpConnectionManager",
     "StdioConnectionManager",
     "WebSocketConnectionManager",
     "SseConnectionManager",
+    "StreamableHttpConnectionManager",
 ]

mcp_use/task_managers/base.py

@@ -70,9 +70,7 @@ class ConnectionManager(Generic[T], ABC):
         self._exception = None
 
         # Create a task to establish and maintain the connection
-        self._task = asyncio.create_task(
-            self._connection_task(), name=f"{self.__class__.__name__}_task"
-        )
+        self._task = asyncio.create_task(self._connection_task(), name=f"{self.__class__.__name__}_task")
 
         # Wait for the connection to be ready or fail
         await self._ready_event.wait()
@@ -105,6 +103,14 @@ class ConnectionManager(Generic[T], ABC):
         await self._done_event.wait()
         logger.debug(f"{self.__class__.__name__} task completed")
 
+    def get_streams(self) -> T | None:
+        """Get the current connection streams.
+
+        Returns:
+            The current connection (typically a tuple of read_stream, write_stream) or None if not connected.
+        """
+        return self._connection
+
     async def _connection_task(self) -> None:
         """Run the connection task.
 
@@ -137,7 +143,7 @@ class ConnectionManager(Generic[T], ABC):
             self._ready_event.set()
 
         finally:
-            # Close the connection if it was establishedSUPABASE_URL
+            # Close the connection if it was established
             if self._connection is not None:
                 try:
                     await self._close_connection()

mcp_use/task_managers/streamable_http.py

@@ -0,0 +1,81 @@
+"""
+Streamable HTTP connection management for MCP implementations.
+
+This module provides a connection manager for streamable HTTP-based MCP connections
+that ensures proper task isolation and resource cleanup.
+"""
+
+from datetime import timedelta
+from typing import Any
+
+from mcp.client.streamable_http import streamablehttp_client
+
+from ..logging import logger
+from .base import ConnectionManager
+
+
+class StreamableHttpConnectionManager(ConnectionManager[tuple[Any, Any]]):
+    """Connection manager for streamable HTTP-based MCP connections.
+
+    This class handles the proper task isolation for HTTP streaming connections
+    to prevent the "cancel scope in different task" error. It runs the http_stream_client
+    in a dedicated task and manages its lifecycle.
+    """
+
+    def __init__(
+        self,
+        url: str,
+        headers: dict[str, str] | None = None,
+        timeout: float = 5,
+        read_timeout: float = 60 * 5,
+    ):
+        """Initialize a new streamable HTTP connection manager.
+
+        Args:
+            url: The HTTP endpoint URL
+            headers: Optional HTTP headers
+            timeout: Timeout for HTTP operations in seconds
+            read_timeout: Timeout for HTTP read operations in seconds
+        """
+        super().__init__()
+        self.url = url
+        self.headers = headers or {}
+        self.timeout = timedelta(seconds=timeout)
+        self.read_timeout = timedelta(seconds=read_timeout)
+        self._http_ctx = None
+
+    async def _establish_connection(self) -> tuple[Any, Any]:
+        """Establish a streamable HTTP connection.
+
+        Returns:
+            A tuple of (read_stream, write_stream)
+
+        Raises:
+            Exception: If connection cannot be established.
+        """
+        # Create the context manager
+        self._http_ctx = streamablehttp_client(
+            url=self.url,
+            headers=self.headers,
+            timeout=self.timeout,
+            sse_read_timeout=self.read_timeout,
+        )
+
+        # Enter the context manager. Ignoring the session id callback
+        read_stream, write_stream, _ = await self._http_ctx.__aenter__()
+
+        # Return the streams
+        return (read_stream, write_stream)
+
+    async def _close_connection(self) -> None:
+        """Close the streamable HTTP connection."""
+
+        if self._http_ctx:
+            # Exit the context manager
+            try:
+                await self._http_ctx.__aexit__(None, None, None)
+            except Exception as e:
+                # Only log if it's not a normal connection termination
+                logger.debug(f"Streamable HTTP context cleanup: {e}")
+            finally:
+                self._http_ctx = None

mcp_use/task_managers/websocket.py

@@ -22,14 +22,17 @@ class WebSocketConnectionManager(ConnectionManager[tuple[Any, Any]]):
     def __init__(
         self,
         url: str,
+        headers: dict[str, str] | None = None,
     ):
         """Initialize a new WebSocket connection manager.
 
         Args:
             url: The WebSocket URL to connect to
+            headers: Optional HTTP headers
         """
         super().__init__()
         self.url = url
+        self.headers = headers or {}
 
     async def _establish_connection(self) -> tuple[Any, Any]:
         """Establish a WebSocket connection.
@@ -42,6 +45,8 @@ class WebSocketConnectionManager(ConnectionManager[tuple[Any, Any]]):
         """
         logger.debug(f"Connecting to WebSocket: {self.url}")
         # Create the context manager
+        # Note: The current MCP websocket_client implementation doesn't support headers
+        # If headers need to be passed, this would need to be updated when MCP supports it
         self._ws_ctx = websocket_client(self.url)
 
         # Enter the context manager

mcp_use/telemetry/events.py

@@ -0,0 +1,93 @@
+from abc import ABC, abstractmethod
+from dataclasses import dataclass
+from typing import Any
+
+
+class BaseTelemetryEvent(ABC):
+    """Base class for all telemetry events"""
+
+    @property
+    @abstractmethod
+    def name(self) -> str:
+        """Event name for tracking"""
+        pass
+
+    @property
+    @abstractmethod
+    def properties(self) -> dict[str, Any]:
+        """Event properties to send with the event"""
+        pass
+
+
+@dataclass
+class MCPAgentExecutionEvent(BaseTelemetryEvent):
+    """Comprehensive event for tracking complete MCP agent execution"""
+
+    # Execution method and context
+    execution_method: str  # "run" or "astream"
+    query: str  # The actual user query
+    success: bool
+
+    # Agent configuration
+    model_provider: str
+    model_name: str
+    server_count: int
+    server_identifiers: list[dict[str, str]]
+    total_tools_available: int
+    tools_available_names: list[str]
+    max_steps_configured: int
+    memory_enabled: bool
+    use_server_manager: bool
+
+    # Execution PARAMETERS
+    max_steps_used: int | None
+    manage_connector: bool
+    external_history_used: bool
+
+    # Execution results
+    steps_taken: int | None = None
+    tools_used_count: int | None = None
+    tools_used_names: list[str] | None = None
+    response: str | None = None  # The actual response
+    execution_time_ms: int | None = None
+    error_type: str | None = None
+
+    # Context
+    conversation_history_length: int | None = None
+
+    @property
+    def name(self) -> str:
+        return "mcp_agent_execution"
+
+    @property
+    def properties(self) -> dict[str, Any]:
+        return {
+            # Core execution info
+            "execution_method": self.execution_method,
+            "query": self.query,
+            "query_length": len(self.query),
+            "success": self.success,
+            # Agent configuration
+            "model_provider": self.model_provider,
+            "model_name": self.model_name,
+            "server_count": self.server_count,
+            "server_identifiers": self.server_identifiers,
+            "total_tools_available": self.total_tools_available,
+            "tools_available_names": self.tools_available_names,
+            "max_steps_configured": self.max_steps_configured,
+            "memory_enabled": self.memory_enabled,
+            "use_server_manager": self.use_server_manager,
+            # Execution parameters (always include, even if None)
+            "max_steps_used": self.max_steps_used,
+            "manage_connector": self.manage_connector,
+            "external_history_used": self.external_history_used,
+            # Execution results (always include, even if None)
+            "steps_taken": self.steps_taken,
+            "tools_used_count": self.tools_used_count,
+            "tools_used_names": self.tools_used_names,
+            "response": self.response,
+            "response_length": len(self.response) if self.response else None,
+            "execution_time_ms": self.execution_time_ms,
+            "error_type": self.error_type,
+            "conversation_history_length": self.conversation_history_length,
+        }