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

mcp_use/agents/adapters/openai.py

@@ -0,0 +1,111 @@
+import re
+from collections.abc import Callable, Coroutine
+from typing import Any
+
+from mcp.types import Prompt, Resource, Tool
+
+from mcp_use.agents.adapters.base import BaseAdapter
+from mcp_use.client.connectors.base import BaseConnector
+
+
+def _sanitize_for_tool_name(name: str) -> str:
+    """Sanitizes a string to be a valid tool name for OpenAI."""
+    # OpenAI tool names can only contain a-z, A-Z, 0-9, and underscores,
+    # and must be 64 characters or less.
+    return re.sub(r"[^a-zA-Z0-9_]+", "_", name).strip("_")[:64]
+
+
+class OpenAIMCPAdapter(BaseAdapter):
+    def __init__(self, disallowed_tools: list[str] | None = None) -> None:
+        """Initialize a new OpenAI adapter.
+
+        Args:
+            disallowed_tools: list of tool names that should not be available.
+        """
+        super().__init__(disallowed_tools)
+        # This map stores the actual async function to call for each tool.
+        self.tool_executors: dict[str, Callable[..., Coroutine[Any, Any, Any]]] = {}
+
+        self._connector_tool_map: dict[BaseConnector, list[dict[str, Any]]] = {}
+        self._connector_resource_map: dict[BaseConnector, list[dict[str, Any]]] = {}
+        self._connector_prompt_map: dict[BaseConnector, list[dict[str, Any]]] = {}
+
+        self.tools: list[dict[str, Any]] = []
+        self.resources: list[dict[str, Any]] = []
+        self.prompts: list[dict[str, Any]] = []
+
+    def _convert_tool(self, mcp_tool: Tool, connector: BaseConnector) -> dict[str, Any]:
+        """Convert an MCP tool to the OpenAI tool format."""
+        if mcp_tool.name in self.disallowed_tools:
+            return None
+
+        self.tool_executors[mcp_tool.name] = (
+            lambda connector=connector, name=mcp_tool.name, **kwargs: connector.call_tool(name, kwargs)
+        )
+
+        fixed_schema = self.fix_schema(mcp_tool.inputSchema)
+        return {
+            "type": "function",
+            "function": {
+                "name": mcp_tool.name,
+                "description": mcp_tool.description,
+                "parameters": fixed_schema,
+            },
+        }
+
+    def _convert_resource(self, mcp_resource: Resource, connector: BaseConnector) -> dict[str, Any]:
+        """Convert an MCP resource to a readable tool in OpenAI format."""
+        # Sanitize the name to be a valid function name for OpenAI
+        tool_name = _sanitize_for_tool_name(f"resource_{mcp_resource.name}")
+
+        if tool_name in self.disallowed_tools:
+            return None
+
+        self.tool_executors[tool_name] = (
+            lambda connector=connector, uri=mcp_resource.uri, **kwargs: connector.read_resource(uri)
+        )
+
+        mcp_resource_desc = mcp_resource.description
+        return {
+            "type": "function",
+            "function": {
+                "name": tool_name,
+                "description": mcp_resource_desc,
+                # They take no arguments
+                "parameters": {"type": "object", "properties": {}},
+            },
+        }
+
+    def _convert_prompt(self, mcp_prompt: Prompt, connector: BaseConnector) -> dict[str, Any]:
+        """Convert an MCP prompt to a usable tool in OpenAI format."""
+        if mcp_prompt.name in self.disallowed_tools:
+            return None
+
+        self.tool_executors[mcp_prompt.name] = (
+            lambda connector=connector, name=mcp_prompt.name, **kwargs: connector.get_prompt(name, kwargs)
+        )
+
+        # Preparing JSON schema for prompt arguments
+        properties = {}
+        required_args = []
+        if mcp_prompt.arguments:
+            for arg in mcp_prompt.arguments:
+                prop = {"type": "string"}
+                if arg.description:
+                    prop["description"] = arg.description
+                properties[arg.name] = prop
+                if arg.required:
+                    required_args.append(arg.name)
+
+        parameters_schema = {"type": "object", "properties": properties}
+        if required_args:
+            parameters_schema["required"] = required_args
+
+        return {
+            "type": "function",
+            "function": {
+                "name": mcp_prompt.name,
+                "description": mcp_prompt.description,
+                "parameters": parameters_schema,
+            },
+        }

mcp_use/agents/base.py

@@ -7,7 +7,7 @@ This module provides a base class for agents that use MCP tools.
 from abc import ABC, abstractmethod
 from typing import Any
 
-from ..session import MCPSession
+from mcp_use.client.session import MCPSession
 
 
 class BaseAgent(ABC):

mcp_use/agents/managers/__init__.py

@@ -0,0 +1,19 @@
+from .server_manager import ServerManager
+from .tools import (
+    ConnectServerTool,
+    DisconnectServerTool,
+    GetActiveServerTool,
+    ListServersTool,
+    MCPServerTool,
+    SearchToolsTool,
+)
+
+__all__ = [
+    "ServerManager",
+    "MCPServerTool",
+    "ConnectServerTool",
+    "DisconnectServerTool",
+    "GetActiveServerTool",
+    "ListServersTool",
+    "SearchToolsTool",
+]

mcp_use/agents/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/agents/managers/server_manager.py

@@ -0,0 +1,131 @@
+from langchain_core.tools import BaseTool
+
+from mcp_use.agents.adapters.base import BaseAdapter
+from mcp_use.agents.managers.base import BaseServerManager
+from mcp_use.agents.managers.tools import (
+    ConnectServerTool,
+    DisconnectServerTool,
+    GetActiveServerTool,
+    ListServersTool,
+    SearchToolsTool,
+)
+from mcp_use.client import MCPClient
+from mcp_use.logging import logger
+from mcp_use.telemetry.telemetry import telemetry
+
+
+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,
+    dynamically activating the tools for the selected server.
+    """
+
+    def __init__(self, client: MCPClient, adapter: BaseAdapter) -> 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]] = {}
+
+    @telemetry("server_manager_initialize")
+    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 _prefetch_server_tools(self) -> None:
+        """Pre-fetch tools for all servers to populate the tool search index."""
+        servers = self.client.get_server_names()
+        for server_name in servers:
+            try:
+                # Only create session if needed, don't set active
+                session = None
+                try:
+                    session = self.client.get_session(server_name)
+                    logger.debug(f"Using existing session for server '{server_name}' to prefetch tools.")
+                except ValueError:
+                    try:
+                        session = await self.client.create_session(server_name)
+                        logger.debug(f"Temporarily created session for '{server_name}' to prefetch tools")
+                    except Exception:
+                        logger.warning(f"Could not create session for '{server_name}' during prefetch")
+                        continue
+
+                # Fetch tools if session is available
+                if session:
+                    connector = session.connector
+                    tools = await self.adapter._create_tools_from_connectors([connector])
+
+                    # Check if this server's tools have changed
+                    if server_name not in self._server_tools or self._server_tools[server_name] != tools:
+                        self._server_tools[server_name] = tools  # Cache tools
+                        self.initialized_servers[server_name] = True  # Mark as initialized
+                        logger.debug(f"Prefetched {len(tools)} tools for server '{server_name}'.")
+                    else:
+                        logger.debug(f"Tools for server '{server_name}' unchanged, using cached version.")
+            except Exception as e:
+                logger.error(f"Error prefetching tools for server '{server_name}': {e}")
+
+    def get_active_server_tools(self) -> list[BaseTool]:
+        """Get tools from the currently active server.
+
+        Returns:
+            List of tools from the active server, or empty list if no server is active
+        """
+        if self.active_server and self.active_server in self._server_tools:
+            return self._server_tools[self.active_server]
+        return []
+
+    def get_management_tools(self) -> list[BaseTool]:
+        """Get the server management tools.
+
+        Returns:
+            List of server management tools
+        """
+        return [
+            ListServersTool(self),
+            ConnectServerTool(self),
+            GetActiveServerTool(self),
+            DisconnectServerTool(self),
+            SearchToolsTool(self),
+        ]
+
+    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
+        """
+        new_tool_names = {tool.name for tool in self.tools}
+        return new_tool_names != current_tool_names
+
+    @property
+    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
+        """
+        management_tools = self.get_management_tools()
+
+        # Add tools from the active server if available
+        if self.active_server and self.active_server in self._server_tools:
+            server_tools = self._server_tools[self.active_server]
+            logger.debug(f"Including {len(server_tools)} tools from active server '{self.active_server}'")
+            logger.debug(f"Server tools: {[tool.name for tool in server_tools]}")
+            return management_tools + server_tools
+        else:
+            logger.debug("No active server - returning only management tools")
+
+        return management_tools

mcp_use/agents/managers/tools/__init__.py

@@ -0,0 +1,15 @@
+from .base_tool import MCPServerTool
+from .connect_server import ConnectServerTool
+from .disconnect_server import DisconnectServerTool
+from .get_active_server import GetActiveServerTool
+from .list_servers_tool import ListServersTool
+from .search_tools import SearchToolsTool
+
+__all__ = [
+    "MCPServerTool",
+    "ConnectServerTool",
+    "DisconnectServerTool",
+    "GetActiveServerTool",
+    "ListServersTool",
+    "SearchToolsTool",
+]

mcp_use/agents/managers/tools/base_tool.py

@@ -0,0 +1,19 @@
+from typing import ClassVar
+
+from langchain_core.tools import BaseTool
+
+
+class MCPServerTool(BaseTool):
+    """Base tool for MCP server operations."""
+
+    name: ClassVar[str] = "mcp_server_tool"
+    description: ClassVar[str] = "Base tool for MCP server operations."
+
+    def __init__(self, server_manager):
+        """Initialize with server manager."""
+        super().__init__()
+        self._server_manager = server_manager
+
+    @property
+    def server_manager(self):
+        return self._server_manager

mcp_use/agents/managers/tools/connect_server.py

@@ -0,0 +1,69 @@
+from typing import ClassVar
+
+from pydantic import BaseModel, Field
+
+from mcp_use.agents.managers.tools.base_tool import MCPServerTool
+from mcp_use.errors.error_formatting import format_error
+from mcp_use.logging import logger
+
+
+class ServerActionInput(BaseModel):
+    """Base input for server-related actions"""
+
+    server_name: str = Field(description="The name of the MCP server")
+
+
+class ConnectServerTool(MCPServerTool):
+    """Tool for connecting to a specific MCP server."""
+
+    name: ClassVar[str] = "connect_to_mcp_server"
+    description: ClassVar[str] = (
+        "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: ClassVar[type[BaseModel]] = ServerActionInput
+
+    async def _arun(self, server_name: str) -> str:
+        """Connect to a specific MCP server."""
+        # Check if server exists
+        servers = self.server_manager.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.server_manager.active_server == server_name:
+            return f"Already connected to MCP server '{server_name}'"
+
+        try:
+            # Create or get session for this server
+            try:
+                session = self.server_manager.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.server_manager.client.create_session(server_name)
+
+            # Set as active server
+            self.server_manager.active_server = server_name
+
+            # Initialize server tools if not already initialized
+            if server_name not in self.server_manager._server_tools:
+                connector = session.connector
+                self.server_manager._server_tools[
+                    server_name
+                ] = await self.server_manager.adapter._create_tools_from_connectors([connector])
+                self.server_manager.initialized_servers[server_name] = True
+
+            server_tools = self.server_manager._server_tools.get(server_name, [])
+            num_tools = len(server_tools)
+
+            return f"Connected to MCP server '{server_name}'. {num_tools} tools are now available."
+
+        except Exception as e:
+            logger.error(f"Error connecting to server '{server_name}': {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."""
+        raise NotImplementedError("ConnectServerTool requires async execution. Use _arun instead.")

mcp_use/agents/managers/tools/disconnect_server.py

@@ -0,0 +1,43 @@
+from typing import ClassVar
+
+from pydantic import BaseModel
+
+from mcp_use.agents.managers.tools.base_tool import MCPServerTool
+from mcp_use.errors.error_formatting import format_error
+from mcp_use.logging import logger
+
+
+class DisconnectServerInput(BaseModel):
+    """Empty input for disconnecting from the current server"""
+
+    pass
+
+
+class DisconnectServerTool(MCPServerTool):
+    """Tool for disconnecting from the currently active MCP server."""
+
+    name: ClassVar[str] = "disconnect_from_mcp_server"
+    description: ClassVar[str] = "Disconnect from the currently active MCP (Model Context Protocol) server"
+    args_schema: ClassVar[type[BaseModel]] = DisconnectServerInput
+
+    def _run(self, **kwargs) -> str:
+        """Disconnect from the currently active MCP server."""
+        if not self.server_manager.active_server:
+            return "No MCP server is currently active, so there's nothing to disconnect from."
+
+        server_name = self.server_manager.active_server
+        try:
+            # Clear the active server
+            self.server_manager.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
+
+            return f"Successfully disconnected from MCP server '{server_name}'."
+        except Exception as e:
+            logger.error(f"Error disconnecting from server '{server_name}': {e}")
+            return format_error(e, server_name=server_name)
+
+    async def _arun(self, **kwargs) -> str:
+        """Async implementation of _run."""
+        return self._run(**kwargs)

mcp_use/agents/managers/tools/get_active_server.py

@@ -0,0 +1,29 @@
+from typing import ClassVar
+
+from pydantic import BaseModel
+
+from mcp_use.agents.managers.tools.base_tool import MCPServerTool
+
+
+class CurrentServerInput(BaseModel):
+    """Empty input for checking current server"""
+
+    pass
+
+
+class GetActiveServerTool(MCPServerTool):
+    """Tool for getting the currently active MCP server."""
+
+    name: ClassVar[str] = "get_active_mcp_server"
+    description: ClassVar[str] = "Get the currently active MCP (Model Context Protocol) server"
+    args_schema: ClassVar[type[BaseModel]] = CurrentServerInput
+
+    def _run(self, **kwargs) -> str:
+        """Get the currently active MCP server."""
+        if not self.server_manager.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.server_manager.active_server}"
+
+    async def _arun(self, **kwargs) -> str:
+        """Async implementation of _run."""
+        return self._run(**kwargs)

mcp_use/agents/managers/tools/list_servers_tool.py

@@ -0,0 +1,53 @@
+from typing import ClassVar
+
+from pydantic import BaseModel
+
+from mcp_use.agents.managers.tools.base_tool import MCPServerTool
+from mcp_use.errors.error_formatting import format_error
+from mcp_use.logging import logger
+
+
+class listServersInput(BaseModel):
+    """Empty input for listing available servers"""
+
+    pass
+
+
+class ListServersTool(MCPServerTool):
+    """Tool for listing available MCP servers."""
+
+    name: ClassVar[str] = "list_mcp_servers"
+    description: ClassVar[str] = (
+        "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: ClassVar[type[BaseModel]] = listServersInput
+
+    def _run(self, **kwargs) -> str:
+        """List all available MCP servers along with their available tools."""
+        servers = self.server_manager.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.server_manager.active_server else ""
+            result += f"{i + 1}. {server_name}{active_marker}\n"
+
+            tools: list = []
+            try:
+                # Check cache first
+                if server_name in self.server_manager._server_tools:
+                    tools = self.server_manager._server_tools[server_name]
+                    tool_count = len(tools)
+                    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
+
+    async def _arun(self, **kwargs) -> str:
+        """Async implementation of _run - calls the synchronous version."""
+        return self._run(**kwargs)