mcp-use 0.0.3__py3-none-any.whl

mcp_use/__init__.py

@@ -0,0 +1,27 @@
+"""
+mcp_use - A model-agnostic MCP (Multi-Channel Platform) library for LLMs.
+
+This library provides a unified interface for connecting different LLMs
+to MCP tools through existing LangChain adapters.
+"""
+
+from .agents.mcpagent import MCPAgent
+from .client import MCPClient
+from .config import create_session_from_config, load_config_file
+from .connectors import BaseConnector, HttpConnector, StdioConnector, WebSocketConnector
+from .logging import logger
+from .session import MCPSession
+
+__version__ = "0.0.3"
+__all__ = [
+    "MCPAgent",
+    "MCPClient",
+    "MCPSession",
+    "BaseConnector",
+    "StdioConnector",
+    "WebSocketConnector",
+    "HttpConnector",
+    "create_session_from_config",
+    "load_config_file",
+    "logger",
+]

mcp_use/agents/__init__.py

@@ -0,0 +1,12 @@
+"""
+Agent implementations for using MCP tools.
+
+This module provides ready-to-use agent implementations
+that are pre-configured for using MCP tools.
+"""
+
+from .base import BaseAgent
+from .langchain_agent import LangChainAgent
+from .mcpagent import MCPAgent
+
+__all__ = ["BaseAgent", "LangChainAgent", "MCPAgent"]

mcp_use/agents/base.py

@@ -0,0 +1,63 @@
+"""
+Base agent interface for MCP tools.
+
+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
+
+
+class BaseAgent(ABC):
+    """Base class for agents that use MCP tools.
+
+    This abstract class defines the interface for agents that use MCP tools.
+    Agents are responsible for integrating LLMs with MCP tools.
+    """
+
+    def __init__(self, session: MCPSession):
+        """Initialize a new agent.
+
+        Args:
+            session: The MCP session to use for tool calls.
+        """
+        self.session = session
+
+    @abstractmethod
+    async def initialize(self) -> None:
+        """Initialize the agent.
+
+        This method should prepare the agent for use, including initializing
+        the MCP session and setting up any necessary components.
+        """
+        pass
+
+    @abstractmethod
+    async def run(self, query: str, max_steps: int = 10) -> dict[str, Any]:
+        """Run the agent with a query.
+
+        Args:
+            query: The query to run.
+            max_steps: The maximum number of steps to run.
+
+        Returns:
+            The final result from the agent.
+        """
+        pass
+
+    @abstractmethod
+    async def step(
+        self, query: str, previous_steps: list[dict[str, Any]] | None = None
+    ) -> dict[str, Any]:
+        """Perform a single step of the agent.
+
+        Args:
+            query: The query to run.
+            previous_steps: Optional list of previous steps.
+
+        Returns:
+            The result of the step.
+        """
+        pass

mcp_use/agents/langchain_agent.py

@@ -0,0 +1,240 @@
+"""
+LangChain agent implementation for MCP tools.
+
+This module provides a LangChain agent implementation that can use MCP tools
+through a unified interface.
+"""
+
+from typing import Any, NoReturn
+
+from jsonschema_pydantic import jsonschema_to_pydantic
+from langchain.agents import AgentExecutor, create_tool_calling_agent
+from langchain.prompts import ChatPromptTemplate, MessagesPlaceholder
+from langchain.schema.language_model import BaseLanguageModel
+from langchain_core.tools import BaseTool, ToolException
+from mcp.types import CallToolResult, EmbeddedResource, ImageContent, TextContent
+from pydantic import BaseModel
+
+from ..connectors.base import BaseConnector
+from ..logging import logger
+
+
+def _parse_mcp_tool_result(tool_result: CallToolResult) -> str:
+    """Parse the content of a CallToolResult into a string.
+
+    Args:
+        tool_result: The result object from calling an MCP tool.
+
+    Returns:
+        A string representation of the tool result content.
+
+    Raises:
+        ToolException: If the tool execution failed, returned no content,
+                       or contained unexpected content types.
+    """
+    if tool_result.isError:
+        raise ToolException(f"Tool execution failed: {tool_result.content}")
+
+    if not tool_result.content:
+        raise ToolException("Tool execution returned no content")
+
+    decoded_result = ""
+    for item in tool_result.content:
+        match item.type:
+            case "text":
+                item: TextContent
+                decoded_result += item.text
+            case "image":
+                item: ImageContent
+                decoded_result += item.data  # Assuming data is string-like or base64
+            case "resource":
+                resource: EmbeddedResource = item.resource
+                if hasattr(resource, "text"):
+                    decoded_result += resource.text
+                elif hasattr(resource, "blob"):
+                    # Assuming blob needs decoding or specific handling; adjust as needed
+                    decoded_result += (
+                        resource.blob.decode()
+                        if isinstance(resource.blob, bytes)
+                        else str(resource.blob)
+                    )
+                else:
+                    raise ToolException(f"Unexpected resource type: {resource.type}")
+            case _:
+                raise ToolException(f"Unexpected content type: {item.type}")
+
+    return decoded_result
+
+
+class LangChainAgent:
+    """LangChain agent that can use MCP tools.
+
+    This agent uses LangChain's agent framework to interact with MCP tools
+    through a unified interface.
+    """
+
+    def __init__(
+        self, connector: BaseConnector, llm: BaseLanguageModel, max_steps: int = 5
+    ) -> None:
+        """Initialize a new LangChain agent.
+
+        Args:
+            connector: The MCP connector to use.
+            llm: The LangChain LLM to use.
+            max_steps: The maximum number of steps to take.
+        """
+        self.connector = connector
+        self.llm = llm
+        self.max_steps = max_steps
+        self.tools: list[BaseTool] = []
+        self.agent: AgentExecutor | None = None
+
+    async def initialize(self) -> None:
+        """Initialize the agent and its tools."""
+        self.tools = await self._create_langchain_tools()
+        self.agent = self._create_agent()
+
+    def fix_schema(self, schema: dict) -> dict:
+        """Convert JSON Schema 'type': ['string', 'null'] to 'anyOf' format.
+
+        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'
+            for key, value in schema.items():
+                schema[key] = self.fix_schema(value)  # Apply recursively
+        return schema
+
+    async def _create_langchain_tools(self) -> list[BaseTool]:
+        """Create LangChain tools from MCP tools.
+
+        Returns:
+            A list of LangChain tools created from MCP tools.
+        """
+        tools = self.connector.tools
+        local_connector = self.connector
+
+        # Wrap MCP tools into LangChain tools
+        langchain_tools: list[BaseTool] = []
+        for tool in tools:
+            # Define adapter class to convert MCP tool to LangChain format
+            class McpToLangChainAdapter(BaseTool):
+                name: str = tool.name or "NO NAME"
+                description: str = tool.description or ""
+                # Convert JSON schema to Pydantic model for argument validation
+                args_schema: type[BaseModel] = jsonschema_to_pydantic(
+                    self.fix_schema(tool.inputSchema)  # Apply schema conversion
+                )
+                connector: BaseConnector = local_connector
+                handle_tool_error: bool = True
+
+                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) -> Any:
+                    """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.info(f'MCP tool: "{self.name}" received input: {kwargs}')
+
+                    try:
+                        tool_result: CallToolResult = await self.connector.call_tool(
+                            self.name, kwargs
+                        )
+                        try:
+                            # Use the helper function to parse the result
+                            return _parse_mcp_tool_result(tool_result)
+                        except Exception as e:
+                            # Log the exception for debugging
+                            logger.error(f"Error parsing tool result: {e}")
+                            # Shortened line:
+                            return (
+                                f"Error parsing result: {e!s}; Raw content: {tool_result.content!r}"
+                            )
+
+                    except Exception as e:
+                        if self.handle_tool_error:
+                            return f"Error executing MCP tool: {str(e)}"
+                        raise
+
+            langchain_tools.append(McpToLangChainAdapter())
+
+        # Log available tools for debugging
+        logger.info(f"Available tools: {[tool.name for tool in langchain_tools]}")
+        return langchain_tools
+
+    def _create_agent(self) -> AgentExecutor:
+        """Create the LangChain agent.
+
+        Returns:
+            An initialized AgentExecutor.
+        """
+        prompt = ChatPromptTemplate.from_messages(
+            [
+                (
+                    "system",
+                    "You are a helpful AI assistant that can use tools to help users.",
+                ),
+                MessagesPlaceholder(variable_name="chat_history"),
+                ("human", "{input}"),
+                MessagesPlaceholder(variable_name="agent_scratchpad"),
+            ]
+        )
+        agent = create_tool_calling_agent(llm=self.llm, tools=self.tools, prompt=prompt)
+        return AgentExecutor(
+            agent=agent, tools=self.tools, max_iterations=self.max_steps, verbose=False
+        )
+
+    async def run(
+        self,
+        query: str,
+        max_steps: int | None = None,
+        chat_history: list | None = None,
+    ) -> str:
+        """Run the agent on a query.
+
+        Args:
+            query: The query to run.
+            max_steps: Optional maximum number of steps to take.
+            chat_history: Optional chat history.
+
+        Returns:
+            The result of running the query.
+
+        Raises:
+            RuntimeError: If the MCP client is not initialized.
+        """
+        if not self.agent:
+            raise RuntimeError("MCP client is not initialized")
+
+        if max_steps is not None:
+            self.agent.max_iterations = max_steps
+
+        # Initialize empty chat history if none provided
+        if chat_history is None:
+            chat_history = []
+
+        # Invoke with all required variables
+        result = await self.agent.ainvoke({"input": query, "chat_history": chat_history})
+
+        return result["output"]

mcp_use/agents/mcpagent.py

@@ -0,0 +1,149 @@
+"""
+Model-Agnostic MCP: Main integration module.
+
+This module provides the main MCPAgent class that integrates all components
+to provide a simple interface for using MCP tools with different LLMs.
+"""
+
+from langchain.schema.language_model import BaseLanguageModel
+
+from mcp_use.client import MCPClient
+from mcp_use.connectors.base import BaseConnector
+from mcp_use.session import MCPSession
+
+from ..logging import logger
+from .langchain_agent import LangChainAgent
+
+
+class MCPAgent:
+    """Main class for using MCP tools with various LLM providers.
+
+    This class provides a unified interface for using MCP tools with different LLM providers
+    through LangChain's agent framework.
+    """
+
+    def __init__(
+        self,
+        llm: BaseLanguageModel,
+        client: MCPClient | None = None,
+        connector: BaseConnector | None = None,
+        server_name: str | None = None,
+        max_steps: int = 5,
+        auto_initialize: bool = False,
+    ):
+        """Initialize a new MCPAgent instance.
+
+        Args:
+            llm: The LangChain LLM to use.
+            client: The MCPClient to use. If provided, connector is ignored.
+            connector: The MCP connector to use if client is not provided.
+            server_name: The name of the server to use if client is provided.
+            max_steps: The maximum number of steps to take.
+            auto_initialize: Whether to automatically initialize the agent when run is called.
+        """
+        self.llm = llm
+        self.client = client
+        self.connector = connector
+        self.server_name = server_name
+        self.max_steps = max_steps
+        self.auto_initialize = auto_initialize
+        self._initialized = False
+
+        # Either client or connector must be provided
+        if not client and not connector:
+            raise ValueError("Either client or connector must be provided")
+
+        self._agent: LangChainAgent | None = None
+        self._session: MCPSession | None = None
+
+    async def initialize(self) -> None:
+        """Initialize the MCP client and agent."""
+        # If using client, get or create a session
+        if self.client:
+            try:
+                self._session = self.client.get_session(self.server_name)
+            except ValueError:
+                self._session = await self.client.create_session(self.server_name)
+            connector_to_use = self._session.connector
+        else:
+            # Using direct connector
+            connector_to_use = self.connector
+            await connector_to_use.connect()
+            await connector_to_use.initialize()
+
+        # Create the agent
+        self._agent = LangChainAgent(
+            connector=connector_to_use, llm=self.llm, max_steps=self.max_steps
+        )
+
+        # Initialize the agent
+        await self._agent.initialize()
+        self._initialized = True
+
+    async def close(self) -> None:
+        """Close the MCP connection."""
+        try:
+            if self._agent:
+                # Clean up the agent first
+                self._agent = None
+
+            # If using client with session, close the session through client
+            if self.client and self._session:
+                await self.client.close_session(self.server_name)
+            # If using direct connector, disconnect
+            elif self.connector:
+                await self.connector.disconnect()
+
+            self._initialized = False
+        except Exception as e:
+            logger.warning(f"Warning: Error during agent closure: {e}")
+            # Still try to clean up even if there was an error
+            self._agent = None
+            self._initialized = False
+
+    async def run(
+        self, query: str, max_steps: int | None = None, manage_connector: bool = True
+    ) -> str:
+        """Run a query using the MCP tools.
+
+        This method handles connecting to the MCP server, initializing the agent,
+        running the query, and then cleaning up the connection.
+
+        Args:
+            query: The query to run.
+            max_steps: Optional maximum number of steps to take.
+            manage_connector: Whether to handle the connector lifecycle internally.
+                If True, this method will connect, initialize, and disconnect from
+                the connector automatically. If False, the caller is responsible
+                for managing the connector lifecycle.
+
+        Returns:
+            The result of running the query.
+        """
+        result = ""
+        try:
+            if manage_connector:
+                # Initialize if needed
+                if not self._initialized or not self._agent:
+                    await self.initialize()
+
+                # Run the query
+                if not self._agent:
+                    raise RuntimeError("MCP client failed to initialize")
+
+                result = await self._agent.run(query, max_steps)
+            else:
+                # Caller is managing connector lifecycle
+                if not self._initialized and self.auto_initialize:
+                    await self.initialize()
+
+                if not self._agent:
+                    raise RuntimeError("MCP client is not initialized")
+
+                result = await self._agent.run(query, max_steps)
+
+            return result
+        finally:
+            # Make sure to clean up the connection if we're managing it
+            if manage_connector and not self.client:
+                await self.close()