mcp-use 1.3.12__py3-none-any.whl → 1.4.0__py3-none-any.whl

mcp_use/client/connectors/http.py

@@ -0,0 +1,304 @@
+"""
+HTTP connector for MCP implementations.
+
+This module provides a connector for communicating with MCP implementations
+through HTTP APIs with SSE or Streamable HTTP for transport.
+"""
+
+from typing import Any
+
+import httpx
+from mcp import ClientSession
+from mcp.client.session import ElicitationFnT, LoggingFnT, MessageHandlerFnT, SamplingFnT
+from mcp.shared.exceptions import McpError
+
+from mcp_use.client.auth.oauth import BearerAuth, OAuth, OAuthClientProvider
+from mcp_use.client.exceptions import OAuthAuthenticationError, OAuthDiscoveryError
+from mcp_use.client.middleware import CallbackClientSession, Middleware
+from mcp_use.client.task_managers import SseConnectionManager, StreamableHttpConnectionManager
+from mcp_use.logging import logger
+
+from .base import BaseConnector
+
+
+class HttpConnector(BaseConnector):
+    """Connector for MCP implementations using HTTP transport with SSE or streamable HTTP.
+
+    This connector uses HTTP/SSE or streamable HTTP to communicate with remote MCP implementations,
+    using a connection manager to handle the proper lifecycle management.
+    """
+
+    def __init__(
+        self,
+        base_url: str,
+        headers: dict[str, str] | None = None,
+        timeout: float = 5,
+        sse_read_timeout: float = 60 * 5,
+        auth: str | dict[str, Any] | httpx.Auth | None = None,
+        sampling_callback: SamplingFnT | None = None,
+        elicitation_callback: ElicitationFnT | None = None,
+        message_handler: MessageHandlerFnT | None = None,
+        logging_callback: LoggingFnT | None = None,
+        middleware: list[Middleware] | None = None,
+    ):
+        """Initialize a new HTTP connector.
+
+        Args:
+            base_url: The base URL of the MCP HTTP API.
+            headers: Optional additional headers.
+            timeout: Timeout for HTTP operations in seconds.
+            sse_read_timeout: Timeout for SSE read operations in seconds.
+            auth: Authentication method - can be:
+                - A string token: Use Bearer token authentication
+                - A dict with OAuth config: {"client_id": "...", "client_secret": "...", "scope": "..."}
+                - An httpx.Auth object: Use custom authentication
+            sampling_callback: Optional sampling callback.
+            elicitation_callback: Optional elicitation callback.
+        """
+        super().__init__(
+            sampling_callback=sampling_callback,
+            elicitation_callback=elicitation_callback,
+            message_handler=message_handler,
+            logging_callback=logging_callback,
+            middleware=middleware,
+        )
+        self.base_url = base_url.rstrip("/")
+        self.headers = headers or {}
+        self.timeout = timeout
+        self.sse_read_timeout = sse_read_timeout
+        self._auth: httpx.Auth | None = None
+        self._oauth: OAuth | None = None
+
+        # Handle authentication
+        if auth is not None:
+            self._set_auth(auth)
+
+    def _set_auth(self, auth: str | dict[str, Any] | httpx.Auth) -> None:
+        """Set authentication method.
+
+        Args:
+            auth: Authentication method - can be:
+                - A string token: Use Bearer token authentication
+                - A dict with OAuth config: {"client_id": "...", "client_secret": "...", "scope": "..."}
+                - An httpx.Auth object: Use custom authentication
+        """
+        if isinstance(auth, str):
+            # Treat as bearer token
+            self._auth = BearerAuth(token=auth)
+            self.headers["Authorization"] = f"Bearer {auth}"
+        elif isinstance(auth, dict):
+            # Check if this is an OAuth provider configuration
+            if "oauth_provider" in auth:
+                oauth_provider = auth["oauth_provider"]
+                if isinstance(oauth_provider, dict):
+                    oauth_provider = OAuthClientProvider(**oauth_provider)
+                self._oauth = OAuth(
+                    self.base_url,
+                    scope=auth.get("scope"),
+                    client_id=auth.get("client_id"),
+                    client_secret=auth.get("client_secret"),
+                    callback_port=auth.get("callback_port"),
+                    oauth_provider=oauth_provider,
+                )
+                self._oauth_config = auth
+            else:
+                self._oauth = OAuth(
+                    self.base_url,
+                    scope=auth.get("scope"),
+                    client_id=auth.get("client_id"),
+                    client_secret=auth.get("client_secret"),
+                    callback_port=auth.get("callback_port"),
+                )
+                self._oauth_config = auth
+        elif isinstance(auth, httpx.Auth):
+            self._auth = auth
+        else:
+            raise ValueError(f"Invalid auth type: {type(auth)}")
+
+    async def connect(self) -> None:
+        """Establish a connection to the MCP implementation."""
+        if self._connected:
+            logger.debug("Already connected to MCP implementation")
+            return
+
+        # Handle OAuth if needed
+        if self._oauth:
+            try:
+                # Create a temporary client for OAuth metadata discovery
+                async with httpx.AsyncClient() as client:
+                    bearer_auth = await self._oauth.initialize(client)
+                    if not bearer_auth:
+                        # Need to perform OAuth flow
+                        logger.info("OAuth authentication required")
+                        bearer_auth = await self._oauth.authenticate()
+
+                    # Update auth and headers
+                    self._auth = bearer_auth
+                    self.headers["Authorization"] = f"Bearer {bearer_auth.token.get_secret_value()}"
+            except OAuthDiscoveryError:
+                # OAuth discovery failed - it means server doesn't support OAuth default urls
+                logger.debug("OAuth discovery failed, continuing without initialization.")
+                self._oauth = None
+                self._auth = None
+            except OAuthAuthenticationError as e:
+                logger.error(f"OAuth initialization failed: {e}")
+                raise
+
+        # Try streamable HTTP first (new transport), fall back to SSE (old transport)
+        # This implements backwards compatibility per MCP specification
+        self.transport_type = None
+        connection_manager = None
+
+        try:
+            # First, try the new streamable HTTP transport
+            logger.debug(f"Attempting streamable HTTP connection to: {self.base_url}")
+            connection_manager = StreamableHttpConnectionManager(
+                self.base_url, self.headers, self.timeout, self.sse_read_timeout, auth=self._auth
+            )
+
+            # Test if this is a streamable HTTP server by attempting initialization
+            read_stream, write_stream = await connection_manager.start()
+
+            # Test if this actually works by trying to create a client session and initialize it
+            raw_test_client = ClientSession(
+                read_stream,
+                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 raw_test_client.__aenter__()
+
+            # Wrap test client with middleware temporarily for testing
+            test_client = CallbackClientSession(raw_test_client, self.public_identifier, self.middleware_manager)
+
+            try:
+                # Try to initialize - this is where streamable HTTP vs SSE difference should show up
+                result = await test_client.initialize()
+                logger.debug(f"Streamable HTTP initialization result: {result}")
+
+                # If we get here, streamable HTTP works
+                self.client_session = test_client
+                self.transport_type = "streamable HTTP"
+                self._initialized = True  # Mark as initialized since we just called initialize()
+
+                # Populate tools, resources, and prompts since we've initialized
+                server_capabilities = result.capabilities
+
+                if server_capabilities.tools:
+                    # Get available tools directly from client session
+                    tools_result = await self.client_session.list_tools()
+                    self._tools = tools_result.tools if tools_result else []
+                else:
+                    self._tools = []
+
+                if server_capabilities.resources:
+                    # Get available resources directly from client session
+                    resources_result = await self.client_session.list_resources()
+                    self._resources = resources_result.resources if resources_result else []
+                else:
+                    self._resources = []
+
+                if server_capabilities.prompts:
+                    # Get available prompts directly from client session
+                    prompts_result = await self.client_session.list_prompts()
+                    self._prompts = prompts_result.prompts if prompts_result else []
+                else:
+                    self._prompts = []
+
+            # Only McpError is raised from client's initialization because
+            # exceptions are handled internally.
+            except McpError as mcp_error:
+                logger.error("MCP protocol error during initialization: %s", mcp_error.error)
+                # Clean up the test client
+                try:
+                    await raw_test_client.__aexit__(None, None, None)
+                except Exception:
+                    pass
+                raise mcp_error
+
+            except Exception as init_error:
+                # This catches non-McpError exceptions, like a direct httpx timeout
+                # but in the most cases this won't happen. It's for safety.
+                try:
+                    await raw_test_client.__aexit__(None, None, None)
+                except Exception:
+                    pass
+                raise init_error
+
+        # Exception from the inner try is propagated here and in
+        # the most cases is an McpError, so checking instances is useless
+        except Exception as streamable_error:
+            logger.debug(f"Streamable HTTP failed: {streamable_error}")
+
+            # Clean up the failed streamable HTTP connection manager
+            if connection_manager:
+                try:
+                    await connection_manager.close()
+                except Exception:
+                    pass
+
+            # It doesn't make sense to check error types. Because client
+            # always return a McpError, if he can't reach the server
+            # because it's offline, or if it has an auth problem.
+            should_fallback = True
+
+            if should_fallback:
+                try:
+                    # Fall back to the old SSE transport
+                    logger.debug(f"Attempting SSE fallback connection to: {self.base_url}")
+                    connection_manager = SseConnectionManager(
+                        self.base_url, self.headers, self.timeout, self.sse_read_timeout, auth=self._auth
+                    )
+
+                    read_stream, write_stream = await connection_manager.start()
+
+                    # Create the client session for SSE
+                    raw_client_session = ClientSession(
+                        read_stream,
+                        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 raw_client_session.__aenter__()
+
+                    # Wrap with middleware
+                    self.client_session = CallbackClientSession(
+                        raw_client_session, self.public_identifier, self.middleware_manager
+                    )
+                    self.transport_type = "SSE"
+
+                except* Exception as sse_error:
+                    # Get the exception from the ExceptionGroup, and here we will get the correct type.
+                    sse_error = sse_error.exceptions[0]
+                    if isinstance(sse_error, httpx.HTTPStatusError) and sse_error.response.status_code in [
+                        401,
+                        403,
+                        407,
+                    ]:
+                        raise OAuthAuthenticationError(
+                            f"Server requires authentication (HTTP {sse_error.response.status_code}) "
+                            "but auth failed. Please provide auth configuration manually."
+                        ) from sse_error
+                    logger.error(
+                        f"Both transport methods failed. Streamable HTTP: {streamable_error}, SSE: {sse_error}"
+                    )
+                    raise sse_error
+            else:
+                raise streamable_error
+
+        # Store the successful connection manager and mark as connected
+        self._connection_manager = connection_manager
+        self._connected = True
+        logger.debug(f"Successfully connected to MCP implementation via {self.transport_type}: {self.base_url}")
+
+    @property
+    def public_identifier(self) -> str:
+        """Get the identifier for the connector."""
+        transport_type = getattr(self, "transport_type", "http")
+        return f"{transport_type}:{self.base_url}"

mcp_use/client/connectors/sandbox.py

@@ -0,0 +1,332 @@
+"""
+Sandbox connector for MCP implementations.
+
+This module provides a connector for communicating with MCP implementations
+that are executed inside a sandbox environment (currently using E2B).
+"""
+
+import asyncio
+import os
+import sys
+import time
+
+import aiohttp
+from mcp import ClientSession
+from mcp.client.session import ElicitationFnT, LoggingFnT, MessageHandlerFnT, SamplingFnT
+
+from mcp_use.client.middleware import CallbackClientSession, Middleware
+from mcp_use.client.task_managers import SseConnectionManager
+from mcp_use.logging import logger
+
+# Import E2B SDK components (optional dependency)
+try:
+    logger.debug("Attempting to import e2b_code_interpreter...")
+    from e2b_code_interpreter import CommandHandle, Sandbox
+
+    logger.debug("Successfully imported e2b_code_interpreter")
+except ImportError as e:
+    logger.debug(f"Failed to import e2b_code_interpreter: {e}")
+    CommandHandle = None
+    Sandbox = None
+
+from typing import NotRequired, TypedDict
+
+from .base import BaseConnector
+
+
+class SandboxOptions(TypedDict):
+    """Configuration options for sandbox execution.
+
+    This type defines the configuration options available when running
+    MCP servers in a sandboxed environment (e.g., using E2B).
+    """
+
+    api_key: str
+    """Direct API key for sandbox provider (e.g., E2B API key).
+    If not provided, will use E2B_API_KEY environment variable."""
+
+    sandbox_template_id: NotRequired[str]
+    """Template ID for the sandbox environment.
+    Default: 'base'"""
+
+    supergateway_command: NotRequired[str]
+    """Command to run supergateway.
+    Default: 'npx -y supergateway'"""
+
+
+class SandboxConnector(BaseConnector):
+    """Connector for MCP implementations running in a sandbox environment.
+
+    This connector runs a user-defined stdio command within a sandbox environment,
+    currently implemented using E2B, potentially wrapped by a utility like 'supergateway'
+    to expose its stdio.
+    """
+
+    def __init__(
+        self,
+        command: str,
+        args: list[str],
+        env: dict[str, str] | None = None,
+        e2b_options: SandboxOptions | None = None,
+        timeout: float = 5,
+        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,
+        middleware: list[Middleware] | None = None,
+    ):
+        """Initialize a new sandbox connector.
+
+        Args:
+            command: The user's MCP server command to execute in the sandbox.
+            args: Command line arguments for the user's MCP server command.
+            env: Environment variables for the user's MCP server command.
+            e2b_options: Configuration options for the E2B sandbox environment.
+                        See SandboxOptions for available options and defaults.
+            timeout: Timeout for the sandbox process in seconds.
+            sse_read_timeout: Timeout for the SSE connection in seconds.
+            sampling_callback: Optional sampling callback.
+            elicitation_callback: Optional elicitation callback.
+        """
+        super().__init__(
+            sampling_callback=sampling_callback,
+            elicitation_callback=elicitation_callback,
+            message_handler=message_handler,
+            logging_callback=logging_callback,
+            middleware=middleware,
+        )
+        if Sandbox is None:
+            raise ImportError(
+                "E2B SDK (e2b-code-interpreter) not found. Please install it with "
+                "'pip install mcp-use[e2b]' (or 'pip install e2b-code-interpreter')."
+            )
+
+        self.user_command = command
+        self.user_args = args or []
+        self.user_env = env or {}
+
+        _e2b_options = e2b_options or {}
+
+        self.api_key = _e2b_options.get("api_key") or os.environ.get("E2B_API_KEY")
+        if not self.api_key:
+            raise ValueError(
+                "E2B API key is required. Provide it via 'sandbox_options.api_key'"
+                " or the E2B_API_KEY environment variable."
+            )
+
+        self.sandbox_template_id = _e2b_options.get("sandbox_template_id", "base")
+        self.supergateway_cmd_parts = _e2b_options.get("supergateway_command", "npx -y supergateway")
+
+        self.sandbox: Sandbox | None = None
+        self.process: CommandHandle | None = None
+        self.client_session: ClientSession | None = None
+        self.errlog = sys.stderr
+        self.base_url: str | None = None
+        self._connected = False
+        self._connection_manager: SseConnectionManager | None = None
+
+        # SSE connection parameters
+        self.headers = {}
+        self.timeout = timeout
+        self.sse_read_timeout = sse_read_timeout
+
+        self.stdout_lines: list[str] = []
+        self.stderr_lines: list[str] = []
+        self._server_ready = asyncio.Event()
+
+    def _handle_stdout(self, data: str) -> None:
+        """Handle stdout data from the sandbox process."""
+        self.stdout_lines.append(data)
+        logger.debug(f"[SANDBOX STDOUT] {data}", end="", flush=True)
+
+    def _handle_stderr(self, data: str) -> None:
+        """Handle stderr data from the sandbox process."""
+        self.stderr_lines.append(data)
+        logger.debug(f"[SANDBOX STDERR] {data}", file=self.errlog, end="", flush=True)
+
+    async def wait_for_server_response(self, base_url: str, timeout: int = 30) -> bool:
+        """Wait for the server to respond to HTTP requests.
+        Args:
+            base_url: The base URL to check for server readiness
+            timeout: Maximum time to wait in seconds
+        Returns:
+            True if server is responding, raises TimeoutError otherwise
+        """
+        logger.info(f"Waiting for server at {base_url} to respond...")
+        sys.stdout.flush()
+
+        start_time = time.time()
+        ping_url = f"{base_url}/sse"
+
+        # Try to connect to the server
+        while time.time() - start_time < timeout:
+            try:
+                async with aiohttp.ClientSession() as session:
+                    try:
+                        # First try the endpoint
+                        async with session.get(ping_url, timeout=2) as response:
+                            if response.status == 200:
+                                elapsed = time.time() - start_time
+                                logger.info(f"Server is ready! SSE endpoint responded with 200 after {elapsed:.1f}s")
+                                return True
+                    except Exception:
+                        # If sse endpoint doesn't work, try the base URL
+                        async with session.get(base_url, timeout=2) as response:
+                            if response.status < 500:  # Accept any non-server error
+                                elapsed = time.time() - start_time
+                                logger.info(
+                                    f"Server is ready! Base URL responded with {response.status} after {elapsed:.1f}s"
+                                )
+                                return True
+            except Exception:
+                # Wait a bit before trying again
+                await asyncio.sleep(0.5)
+                continue
+
+            # If we get here, the request failed
+            await asyncio.sleep(0.5)
+
+            # Log status every 5 seconds
+            elapsed = time.time() - start_time
+            if int(elapsed) % 5 == 0:
+                logger.info(f"Still waiting for server to respond... ({elapsed:.1f}s elapsed)")
+                sys.stdout.flush()
+
+        # If we get here, we timed out
+        raise TimeoutError(f"Timeout waiting for server to respond (waited {timeout} seconds)")
+
+    async def connect(self):
+        """Connect to the sandbox and start the MCP server."""
+
+        if self._connected:
+            logger.debug("Already connected to MCP implementation")
+            return
+
+        logger.debug("Connecting to MCP implementation in sandbox")
+
+        try:
+            # Create and start the sandbox
+            self.sandbox = Sandbox(
+                template=self.sandbox_template_id,
+                api_key=self.api_key,
+            )
+
+            # Get the host for the sandbox
+            host = self.sandbox.get_host(3000)
+            self.base_url = f"https://{host}".rstrip("/")
+
+            # Append command with args
+            command = f"{self.user_command} {' '.join(self.user_args)}"
+
+            # Construct the full command with supergateway
+            full_command = f'{self.supergateway_cmd_parts} \
+                --base-url {self.base_url} \
+                --port 3000 \
+                --cors \
+                --stdio "{command}"'
+
+            logger.debug(f"Full command: {full_command}")
+
+            # Start the process in the sandbox with our stdout/stderr handlers
+            self.process: CommandHandle = self.sandbox.commands.run(
+                full_command,
+                envs=self.user_env,
+                timeout=1000 * 60 * 10,  # 10 minutes timeout
+                background=True,
+                on_stdout=self._handle_stdout,
+                on_stderr=self._handle_stderr,
+            )
+
+            # Wait for the server to be ready
+            await self.wait_for_server_response(self.base_url, timeout=30)
+            logger.debug("Initializing connection manager...")
+
+            # Create the SSE connection URL
+            sse_url = f"{self.base_url}/sse"
+
+            # Create and start the connection manager
+            self._connection_manager = SseConnectionManager(sse_url, self.headers, self.timeout, self.sse_read_timeout)
+            read_stream, write_stream = await self._connection_manager.start()
+
+            # Create the client session
+            raw_client_session = ClientSession(
+                read_stream,
+                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 raw_client_session.__aenter__()
+
+            # Wrap with middleware
+            self.client_session = CallbackClientSession(
+                raw_client_session, self.public_identifier, self.middleware_manager
+            )
+
+            # Mark as connected
+            self._connected = True
+            logger.debug(f"Successfully connected to MCP implementation via HTTP/SSE: {self.base_url}")
+
+        except Exception as e:
+            logger.error(f"Failed to connect to MCP implementation: {e}")
+
+            # Clean up any resources if connection failed
+            await self._cleanup_resources()
+
+            raise e
+
+    async def _cleanup_resources(self) -> None:
+        """Clean up all resources associated with this connector, including the sandbox.
+        This method extends the base implementation to also terminate the sandbox instance
+        and clean up any processes running in the sandbox.
+        """
+        logger.debug("Cleaning up sandbox resources")
+
+        # Terminate any running process
+        if self.process:
+            try:
+                logger.debug("Terminating sandbox process")
+                self.process.kill()
+            except Exception as e:
+                logger.warning(f"Error terminating sandbox process: {e}")
+            finally:
+                self.process = None
+
+        # Close the sandbox
+        if self.sandbox:
+            try:
+                logger.debug("Closing sandbox instance")
+                self.sandbox.kill()
+                logger.debug("Sandbox instance closed successfully")
+            except Exception as e:
+                logger.warning(f"Error closing sandbox: {e}")
+            finally:
+                self.sandbox = None
+
+        # Then call the parent method to clean up the rest
+        await super()._cleanup_resources()
+
+        # Clear any collected output
+        self.stdout_lines = []
+        self.stderr_lines = []
+        self.base_url = None
+
+    async def disconnect(self) -> None:
+        """Close the connection to the MCP implementation."""
+        if not self._connected:
+            logger.debug("Not connected to MCP implementation")
+            return
+
+        logger.debug("Disconnecting from MCP implementation")
+        await self._cleanup_resources()
+        self._connected = False
+        logger.debug("Disconnected from MCP implementation")
+
+    @property
+    def public_identifier(self) -> str:
+        """Get the identifier for the connector."""
+        args_str = " ".join(self.user_args) if self.user_args else ""
+        return f"sandbox:{self.user_command} {args_str}".strip()