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

mcp_use/agents/adapters/base.py

@@ -0,0 +1,316 @@
+"""
+Base adapter interface for MCP tools.
+
+This module provides the abstract base class that all MCP tool adapters should inherit from.
+"""
+
+from abc import ABC, abstractmethod
+from typing import Any, TypeVar
+
+from mcp.types import Prompt, Resource, Tool
+
+from mcp_use.client.client import MCPClient
+from mcp_use.client.connectors.base import BaseConnector
+from mcp_use.logging import logger
+from mcp_use.telemetry.telemetry import telemetry
+
+# Generic type for the tools created by the adapter
+T = TypeVar("T")
+
+
+class BaseAdapter(ABC):
+    """Abstract base class for converting MCP tools to other framework formats.
+
+    This class defines the common interface that all adapter implementations
+    should follow to ensure consistency across different frameworks.
+    """
+
+    def __init__(self, disallowed_tools: list[str] | None = None) -> None:
+        """Initialize a new adapter.
+
+        Args:
+            disallowed_tools: list of tool names that should not be available.
+        """
+        self.disallowed_tools = disallowed_tools or []
+
+        # Three maps to optimize and cache only what is needed
+        self._connector_tool_map: dict[BaseConnector, list[T]] = {}
+        self._connector_resource_map: dict[BaseConnector, list[T]] = {}
+        self._connector_prompt_map: dict[BaseConnector, list[T]] = {}
+
+        self.tools: list[T] = []
+        self.resources: list[T] = []
+        self.prompts: list[T] = []
+
+    def parse_result(self, tool_result: Any) -> str:
+        """Parse the result from any MCP operation (tool, resource, or prompt) into a string.
+
+        Args:
+            tool_result: The result object from an MCP operation.
+
+        Returns:
+            A string representation of the result content.
+        """
+        if getattr(tool_result, "isError", False):
+            # Handle errors first
+            error_content = tool_result.content or "Unknown error"
+            return f"Error: {error_content}"
+        elif hasattr(tool_result, "contents"):  # For Resources (ReadResourceResult)
+            return "\n".join(c.decode() if isinstance(c, bytes) else str(c) for c in tool_result.contents)
+        elif hasattr(tool_result, "messages"):  # For Prompts (GetPromptResult)
+            return "\n".join(str(s) for s in tool_result.messages)
+        elif hasattr(tool_result, "content"):  # For Tools (CallToolResult)
+            return str(tool_result.content)
+        else:
+            # Fallback for unexpected types
+            return str(tool_result)
+
+    @telemetry("adapter_fix_schema")
+    def fix_schema(self, schema: dict) -> dict:
+        """Convert JSON Schema 'type': ['string', 'null'] to 'anyOf' format and fix enum handling.
+
+        Args:
+            schema: The JSON schema to fix.
+
+        Returns:
+            The fixed JSON schema.
+        """
+        if isinstance(schema, dict):
+            if "type" in schema and isinstance(schema["type"], list):
+                schema["anyOf"] = [{"type": t} for t in schema["type"]]
+                del schema["type"]  # Remove 'type' and standardize to 'anyOf'
+
+            # Fix enum handling - ensure enum fields are properly typed as strings
+            if "enum" in schema and "type" not in schema:
+                schema["type"] = "string"
+
+            for key, value in schema.items():
+                schema[key] = self.fix_schema(value)  # Apply recursively
+        return schema
+
+    async def _get_connectors(self, client: MCPClient) -> list[BaseConnector]:
+        """Get all connectors from the client, creating sessions if needed."""
+        if not client.active_sessions:
+            logger.info("No active sessions found, creating new ones...")
+            await client.create_all_sessions()
+
+        sessions = client.get_all_active_sessions()
+        return [session.connector for session in sessions.values()]
+
+    async def create_all(self, client: MCPClient) -> None:
+        """Create tools, resources, and prompts from an MCPClient instance."""
+        await self.create_tools(client)
+        await self.create_resources(client)
+        await self.create_prompts(client)
+
+    async def create_tools(self, client: MCPClient) -> list[T]:
+        """Create tools from the MCPClient instance.
+
+        This handles session creation and connector extraction automatically.
+        The created tools are stored in `self.tools`.
+
+        Returns:
+            A list of tools in the target framework's format.
+        """
+        connectors = await self._get_connectors(client)
+        self.tools = await self._create_tools_from_connectors(connectors)
+
+        return self.tools
+
+    async def create_resources(self, client: MCPClient) -> list[T]:
+        """Create resources from the MCPClient instance.
+
+        This handles session creation and connector extraction automatically.
+        The created resources are stored in `self.resources`.
+
+        Returns:
+            A list of resources in the target framework's format.
+        """
+        connectors = await self._get_connectors(client)
+        self.resources = await self._create_resources_from_connectors(connectors)
+
+        return self.resources
+
+    async def create_prompts(self, client: MCPClient) -> list[T]:
+        """Create prompts from the MCPClient instance.
+
+        This handles session creation and connector extraction automatically.
+        The created prompts are stored in `self.prompts`.
+
+        Returns:
+            A list of prompts in the target framework's format.
+        """
+        connectors = await self._get_connectors(client)
+        self.prompts = await self._create_prompts_from_connectors(connectors)
+
+        return self.prompts
+
+    @telemetry("adapter_load_tools")
+    async def load_tools_for_connector(self, connector: BaseConnector) -> list[T]:
+        """Dynamically load tools for a specific connector.
+
+        Args:
+            connector: The connector to load tools for.
+
+        Returns:
+            The list of tools that were loaded in the target framework's format.
+        """
+        # Check if we already have tools for this connector
+        if connector in self._connector_tool_map:
+            logger.debug(f"Returning {len(self._connector_tool_map[connector])} existing tools for connector")
+            return self._connector_tool_map[connector]
+
+        if not await self._ensure_connector_initialized(connector):
+            return []
+
+        connector_tools = []
+        for tool in await connector.list_tools():
+            converted_tool = self._convert_tool(tool, connector)
+            if converted_tool:
+                connector_tools.append(converted_tool)
+
+        # Store the tools for this connector
+        self._connector_tool_map[connector] = connector_tools
+
+        # Log available tools for debugging
+        logger.debug(
+            f"Loaded {len(connector_tools)} new tools for connector: "
+            f"{[getattr(tool, 'name', str(tool)) for tool in connector_tools]}"
+        )
+
+        return connector_tools
+
+    @telemetry("adapter_load_resources")
+    async def load_resources_for_connector(self, connector: BaseConnector):
+        """Dynamically load resources for a specific connector.
+
+        Args:
+            connector: The connector to load resources for.
+
+        Returns:
+            The list of resources that were loaded in the target framework's format.
+        """
+        if connector in self._connector_resource_map:
+            logger.debug(f"Returning {len(self._connector_resource_map[connector])} existing resources for connector")
+            return self._connector_resource_map[connector]
+
+        if not await self._ensure_connector_initialized(connector):
+            return []
+
+        connector_resources = []
+        for resource in await connector.list_resources() or []:
+            converted_resource = self._convert_resource(resource, connector)
+            if converted_resource:
+                connector_resources.append(converted_resource)
+
+        self._connector_resource_map[connector] = connector_resources
+        logger.debug(
+            f"Loaded {len(connector_resources)} new resources for connector: "
+            f"{[getattr(r, 'name', str(r)) for r in connector_resources]}"
+        )
+        return connector_resources
+
+    @telemetry("adapter_load_prompts")
+    async def load_prompts_for_connector(self, connector: BaseConnector) -> list[T]:
+        """Dynamically load prompts for a specific connector.
+
+        Args:
+            connector: The connector to load prompts for.
+
+        Returns:
+            The list of prompts that were loaded in the target framework's format.
+        """
+        if connector in self._connector_prompt_map:
+            logger.debug(f"Returning {len(self._connector_prompt_map[connector])} existing prompts for connector")
+            return self._connector_prompt_map[connector]
+
+        if not await self._ensure_connector_initialized(connector):
+            return []
+
+        connector_prompts = []
+        for prompt in await connector.list_prompts() or []:
+            converted_prompt = self._convert_prompt(prompt, connector)
+            if converted_prompt:
+                connector_prompts.append(converted_prompt)
+
+        self._connector_prompt_map[connector] = connector_prompts
+        logger.debug(
+            f"Loaded {len(connector_prompts)} new prompts for connector: "
+            f"{[getattr(p, 'name', str(p)) for p in connector_prompts]}"
+        )
+        return connector_prompts
+
+    @abstractmethod
+    def _convert_tool(self, mcp_tool: Tool, connector: BaseConnector) -> T:
+        """Convert an MCP tool to the target framework's tool format."""
+        pass
+
+    @abstractmethod
+    def _convert_resource(self, mcp_resource: Resource, connector: BaseConnector) -> T:
+        """Convert an MCP resource to the target framework's resource format."""
+        pass
+
+    @abstractmethod
+    def _convert_prompt(self, mcp_prompt: Prompt, connector: BaseConnector) -> T:
+        """Convert an MCP prompt to the target framework's prompt format."""
+        pass
+
+    async def _create_tools_from_connectors(self, connectors: list[BaseConnector]) -> list[T]:
+        """Create tools from MCP tools in all provided connectors."""
+        tools = []
+        for connector in connectors:
+            connector_tools = await self.load_tools_for_connector(connector)
+            tools.extend(connector_tools)
+
+        logger.debug(f"Available tools: {len(tools)}")
+        return tools
+
+    async def _create_resources_from_connectors(self, connectors: list[BaseConnector]) -> list[T]:
+        """Create resources from MCP resources in all provided connectors."""
+        resources = []
+        for connector in connectors:
+            connector_resources = await self.load_resources_for_connector(connector)
+            resources.extend(connector_resources)
+
+        logger.debug(f"Available resources: {len(resources)}")
+        return resources
+
+    async def _create_prompts_from_connectors(self, connectors: list[BaseConnector]) -> list[T]:
+        """Create prompts from MCP prompts in all provided connectors."""
+        prompts = []
+        for connector in connectors:
+            connector_prompts = await self.load_prompts_for_connector(connector)
+            prompts.extend(connector_prompts)
+
+        logger.debug(f"Available prompts: {len(prompts)}")
+        return prompts
+
+    def _check_connector_initialized(self, connector: BaseConnector) -> bool:
+        """Check if a connector is initialized and has tools.
+
+        Args:
+            connector: The connector to check.
+
+        Returns:
+            True if the connector is initialized and has tools, False otherwise.
+        """
+        return hasattr(connector, "tools") and connector.tools
+
+    async def _ensure_connector_initialized(self, connector: BaseConnector) -> bool:
+        """Ensure a connector is initialized.
+
+        Args:
+            connector: The connector to initialize.
+
+        Returns:
+            True if initialization succeeded, False otherwise.
+        """
+        if not self._check_connector_initialized(connector):
+            logger.debug("Connector doesn't have tools, initializing it")
+            try:
+                await connector.initialize()
+                return True
+            except Exception as e:
+                logger.error(f"Error initializing connector: {e}")
+                return False
+        return True

mcp_use/agents/adapters/google.py

@@ -0,0 +1,103 @@
+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
+
+try:
+    from google.genai import types
+except ImportError as e:
+    raise ImportError(
+        "google-genai is required for GoogleMCPAdapter. Install it with: uv pip install google-genai"
+    ) from e
+
+
+def _sanitize_for_tool_name(name: str) -> str:
+    """Sanitizes a string to be a valid tool name for Google."""
+    # Google 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 GoogleMCPAdapter(BaseAdapter):
+    def __init__(self, disallowed_tools: list[str] | None = None) -> None:
+        """Initialize a new Google 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[types.FunctionDeclaration]] = {}
+        self._connector_resource_map: dict[BaseConnector, list[types.FunctionDeclaration]] = {}
+        self._connector_prompt_map: dict[BaseConnector, list[types.FunctionDeclaration]] = {}
+
+        self.tools: list[types.FunctionDeclaration] = []
+        self.resources: list[types.FunctionDeclaration] = []
+        self.prompts: list[types.FunctionDeclaration] = []
+
+    def _convert_tool(self, mcp_tool: Tool, connector: BaseConnector) -> types.FunctionDeclaration:
+        """Convert an MCP tool to the Google 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)
+        function_declaration = types.FunctionDeclaration(
+            name=mcp_tool.name, description=mcp_tool.description, parameters_json_schema=fixed_schema
+        )
+        return function_declaration
+
+    def _convert_resource(self, mcp_resource: Resource, connector: BaseConnector) -> types.FunctionDeclaration:
+        """Convert an MCP resource to a readable tool in Google format."""
+        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)
+        )
+
+        function_declaration = types.FunctionDeclaration(
+            name=tool_name,
+            description=mcp_resource.description,
+            parameters_json_schema={"input_schema": {"type": "object", "properties": {}}},
+        )
+        return function_declaration
+
+    def _convert_prompt(self, mcp_prompt: Prompt, connector: BaseConnector) -> types.FunctionDeclaration:
+        """Convert an MCP prompt to a usable tool in Google 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)
+        )
+
+        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
+
+        function_declaration = types.FunctionDeclaration(
+            name=mcp_prompt.name, description=mcp_prompt.description, parameters_json_schema=parameters_schema
+        )
+        return function_declaration

mcp_use/agents/adapters/langchain_adapter.py

@@ -0,0 +1,212 @@
+"""
+LangChain adapter for MCP tools.
+
+This module provides utilities to convert MCP tools to LangChain tools.
+"""
+
+import re
+from typing import Any, NoReturn
+
+from jsonschema_pydantic import jsonschema_to_pydantic
+from langchain_core.tools import BaseTool
+from mcp.types import (
+    CallToolResult,
+    Prompt,
+    ReadResourceRequestParams,
+    Resource,
+)
+from pydantic import BaseModel, Field, create_model
+
+from mcp_use.agents.adapters.base import BaseAdapter
+from mcp_use.client.connectors.base import BaseConnector
+from mcp_use.errors.error_formatting import format_error
+from mcp_use.logging import logger
+from mcp_use.telemetry.telemetry import telemetry
+
+
+class LangChainAdapter(BaseAdapter):
+    """Adapter for converting MCP tools to LangChain tools."""
+
+    def __init__(self, disallowed_tools: list[str] | None = None) -> None:
+        """Initialize a new LangChain adapter.
+
+        Args:
+            disallowed_tools: list of tool names that should not be available.
+        """
+        super().__init__(disallowed_tools)
+        self._connector_tool_map: dict[BaseConnector, list[BaseTool]] = {}
+        self._connector_resource_map: dict[BaseConnector, list[BaseTool]] = {}
+        self._connector_prompt_map: dict[BaseConnector, list[BaseTool]] = {}
+
+        self.tools: list[BaseTool] = []
+        self.resources: list[BaseTool] = []
+        self.prompts: list[BaseTool] = []
+
+    @telemetry("adapter_convert_tool")
+    def _convert_tool(self, mcp_tool: dict[str, Any], connector: BaseConnector) -> BaseTool:
+        """Convert an MCP tool to LangChain's tool format.
+
+        Args:
+            mcp_tool: The MCP tool to convert.
+            connector: The connector that provides this tool.
+
+        Returns:
+            A LangChain BaseTool.
+        """
+        # Skip disallowed tools
+        if mcp_tool.name in self.disallowed_tools:
+            return None
+
+        # This is a dynamic class creation, we need to work with the self reference
+        adapter_self = self
+
+        class McpToLangChainAdapter(BaseTool):
+            name: str = mcp_tool.name or "NO NAME"
+            description: str = mcp_tool.description or ""
+            # Convert JSON schema to Pydantic model for argument validation
+            args_schema: type[BaseModel] = jsonschema_to_pydantic(
+                adapter_self.fix_schema(mcp_tool.inputSchema)  # Apply schema conversion
+            )
+            tool_connector: BaseConnector = connector  # Renamed variable to avoid name conflict
+            handle_tool_error: bool = True
+
+            def __repr__(self) -> str:
+                return f"MCP tool: {self.name}: {self.description}"
+
+            def _run(self, **kwargs: Any) -> NoReturn:
+                """Synchronous run method that always raises an error.
+
+                Raises:
+                    NotImplementedError: Always raises this error because MCP tools
+                        only support async operations.
+                """
+                raise NotImplementedError("MCP tools only support async operations")
+
+            async def _arun(self, **kwargs: Any) -> str | dict:
+                """Asynchronously execute the tool with given arguments.
+
+                Args:
+                    kwargs: The arguments to pass to the tool.
+
+                Returns:
+                    The result of the tool execution.
+
+                Raises:
+                    ToolException: If tool execution fails.
+                """
+                logger.debug(f'MCP tool: "{self.name}" received input: {kwargs}')
+
+                try:
+                    tool_result: CallToolResult = await self.tool_connector.call_tool(self.name, kwargs)
+                    try:
+                        # Use the helper function to parse the result
+                        return str(tool_result.content)
+                    except Exception as e:
+                        # Log the exception for debugging
+                        logger.error(f"Error parsing tool result: {e}")
+                        return format_error(e, tool=self.name, tool_content=tool_result.content)
+
+                except Exception as e:
+                    if self.handle_tool_error:
+                        return format_error(e, tool=self.name)  # Format the error to make LLM understand it
+                    raise
+
+        return McpToLangChainAdapter()
+
+    def _convert_resource(self, mcp_resource: Resource, connector: BaseConnector) -> BaseTool:
+        """Convert an MCP resource to LangChain's tool format.
+
+        Each resource becomes an async tool that returns its content when called.
+        The tool takes **no** arguments because the resource URI is fixed.
+        """
+
+        def _sanitize(name: str) -> str:
+            return re.sub(r"[^A-Za-z0-9_]+", "_", name).lower().strip("_")
+
+        class ResourceTool(BaseTool):
+            name: str = _sanitize(mcp_resource.name or f"resource_{mcp_resource.uri}")
+            description: str = (
+                mcp_resource.description or f"Return the content of the resource located at URI {mcp_resource.uri}."
+            )
+            args_schema: type[BaseModel] = ReadResourceRequestParams
+            tool_connector: BaseConnector = connector
+            handle_tool_error: bool = True
+
+            def _run(self, **kwargs: Any) -> NoReturn:
+                raise NotImplementedError("Resource tools only support async operations")
+
+            async def _arun(self, **kwargs: Any) -> Any:
+                logger.debug(f'Resource tool: "{self.name}" called')
+                try:
+                    result = await self.tool_connector.read_resource(mcp_resource.uri)
+                    for content in result.contents:
+                        # Attempt to decode bytes if necessary
+                        if isinstance(content, bytes):
+                            content_decoded = content.decode()
+                        else:
+                            content_decoded = str(content)
+
+                    return content_decoded
+                except Exception as e:
+                    if self.handle_tool_error:
+                        return format_error(e, tool=self.name)  # Format the error to make LLM understand it
+                    raise
+
+        return ResourceTool()
+
+    def _convert_prompt(self, mcp_prompt: Prompt, connector: BaseConnector) -> BaseTool:
+        """Convert an MCP prompt to LangChain's tool format.
+
+        The resulting tool executes `get_prompt` on the connector with the prompt's name and
+        the user-provided arguments (if any). The tool returns the decoded prompt content.
+        """
+        prompt_arguments = mcp_prompt.arguments
+
+        # Sanitize the prompt name to create a valid Python identifier for the model name
+        base_model_name = re.sub(r"[^a-zA-Z0-9_]", "_", mcp_prompt.name)
+        if not base_model_name or base_model_name[0].isdigit():
+            base_model_name = "PromptArgs_" + base_model_name
+        dynamic_model_name = f"{base_model_name}_InputSchema"
+
+        if prompt_arguments:
+            field_definitions_for_create: dict[str, Any] = {}
+            for arg in prompt_arguments:
+                param_type: type = getattr(arg, "type", str)
+                if arg.required:
+                    field_definitions_for_create[arg.name] = (
+                        param_type,
+                        Field(description=arg.description),
+                    )
+                else:
+                    field_definitions_for_create[arg.name] = (
+                        param_type | None,
+                        Field(None, description=arg.description),
+                    )
+
+            InputSchema = create_model(dynamic_model_name, **field_definitions_for_create, __base__=BaseModel)
+        else:
+            # Create an empty Pydantic model if there are no arguments
+            InputSchema = create_model(dynamic_model_name, __base__=BaseModel)
+
+        class PromptTool(BaseTool):
+            name: str = mcp_prompt.name
+            description: str = mcp_prompt.description
+
+            args_schema: type[BaseModel] = InputSchema
+            tool_connector: BaseConnector = connector
+            handle_tool_error: bool = True
+
+            def _run(self, **kwargs: Any) -> NoReturn:
+                raise NotImplementedError("Prompt tools only support async operations")
+
+            async def _arun(self, **kwargs: Any) -> Any:
+                logger.debug(f'Prompt tool: "{self.name}" called with args: {kwargs}')
+                try:
+                    result = await self.tool_connector.get_prompt(self.name, kwargs)
+                    return result.messages
+                except Exception as e:
+                    if self.handle_tool_error:
+                        return format_error(e, tool=self.name)  # Format the error to make LLM understand it
+                    raise
+
+        return PromptTool()