mcp-use 1.2.5__tar.gz → 1.2.7__tar.gz

mcp_use-1.2.7/.github/pull_request_template.md

@@ -0,0 +1,43 @@
+# Pull Request Description
+
+## Changes
+
+Describe the changes introduced by this PR in a concise manner.
+
+## Implementation Details
+
+1. List the specific implementation details
+2. Include code organization, architectural decisions
+3. Note any dependencies that were added or modified
+
+## Example Usage (Before)
+
+```python
+# Include example code showing how things worked before (if applicable)
+```
+
+## Example Usage (After)
+
+```python
+# Include example code showing how things work after your changes
+```
+
+## Documentation Updates
+
+* List any documentation files that were updated
+* Explain what was changed in each file
+
+## Testing
+
+Describe how you tested these changes:
+- Unit tests added/modified
+- Manual testing performed
+- Edge cases considered
+
+## Backwards Compatibility
+
+Explain whether these changes are backwards compatible. If not, describe what users will need to do to adapt to these changes.
+
+## Related Issues
+
+Closes #[issue_number]

{mcp_use-1.2.5 → mcp_use-1.2.7}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mcp-use
-Version: 1.2.5
+Version: 1.2.7
 Summary: MCP Library for LLMs
 Author-email: Pietro Zullo <pietro.zullo@gmail.com>
 License: MIT
@@ -18,7 +18,7 @@ Requires-Dist: aiohttp>=3.9.0
 Requires-Dist: jsonschema-pydantic>=0.1.0
 Requires-Dist: langchain-community>=0.0.10
 Requires-Dist: langchain>=0.1.0
-Requires-Dist: mcp
+Requires-Dist: mcp>=1.5.0
 Requires-Dist: pydantic>=2.0.0
 Requires-Dist: python-dotenv>=1.0.0
 Requires-Dist: typing-extensions>=4.8.0
@@ -69,6 +69,7 @@ Description-Content-Type: text/markdown
 | ⚙️ **Dynamic Server Selection** | Agents can dynamically choose the most appropriate MCP server for a given task from the available pool |
 | 🧩 **Multi-Server Support** | Use multiple MCP servers simultaneously in a single agent |
 | 🛡️ **Tool Restrictions** | Restrict potentially dangerous tools like file system or network access |
+| 🔧 **Custom Agents** | Build your own agents with any framework using the LangChain adapter or create new adapters |
 
 
 # Quick start
@@ -503,6 +504,41 @@ if __name__ == "__main__":
     asyncio.run(main())
 ```
 
+# Build a Custom Agent:
+
+You can also build your own custom agent using the LangChain adapter:
+
+```python
+import asyncio
+from langchain_openai import ChatOpenAI
+from mcp_use.client import MCPClient
+from mcp_use.adapters.langchain_adapter import LangChainAdapter
+from dotenv import load_dotenv
+
+load_dotenv()
+
+
+async def main():
+    # Initialize MCP client
+    client = MCPClient.from_config_file("examples/browser_mcp.json")
+    llm = ChatOpenAI(model="gpt-4o")
+
+    # Create adapter instance
+    adapter = LangChainAdapter()
+    # Get LangChain tools with a single line
+    tools = await adapter.create_tools(client)
+
+    # Create a custom LangChain agent
+    llm_with_tools = llm.bind_tools(tools)
+    result = await llm_with_tools.ainvoke("What tools do you have avilable ? ")
+    print(result)
+
+
+if __name__ == "__main__":
+    asyncio.run(main())
+
+
+```
 
 # Debugging
 

{mcp_use-1.2.5 → mcp_use-1.2.7}/README.md

@@ -30,6 +30,7 @@
 | ⚙️ **Dynamic Server Selection** | Agents can dynamically choose the most appropriate MCP server for a given task from the available pool |
 | 🧩 **Multi-Server Support** | Use multiple MCP servers simultaneously in a single agent |
 | 🛡️ **Tool Restrictions** | Restrict potentially dangerous tools like file system or network access |
+| 🔧 **Custom Agents** | Build your own agents with any framework using the LangChain adapter or create new adapters |
 
 
 # Quick start
@@ -464,6 +465,41 @@ if __name__ == "__main__":
     asyncio.run(main())
 ```
 
+# Build a Custom Agent:
+
+You can also build your own custom agent using the LangChain adapter:
+
+```python
+import asyncio
+from langchain_openai import ChatOpenAI
+from mcp_use.client import MCPClient
+from mcp_use.adapters.langchain_adapter import LangChainAdapter
+from dotenv import load_dotenv
+
+load_dotenv()
+
+
+async def main():
+    # Initialize MCP client
+    client = MCPClient.from_config_file("examples/browser_mcp.json")
+    llm = ChatOpenAI(model="gpt-4o")
+
+    # Create adapter instance
+    adapter = LangChainAdapter()
+    # Get LangChain tools with a single line
+    tools = await adapter.create_tools(client)
+
+    # Create a custom LangChain agent
+    llm_with_tools = llm.bind_tools(tools)
+    result = await llm_with_tools.ainvoke("What tools do you have avilable ? ")
+    print(result)
+
+
+if __name__ == "__main__":
+    asyncio.run(main())
+
+
+```
 
 # Debugging
 

mcp_use-1.2.7/docs/building-custom-agents.mdx

@@ -0,0 +1,175 @@
+---
+title: Building Custom Agents
+description: Learn how to build custom agents using MCPClient and integrate tools with different agent frameworks
+---
+
+# Building Custom Agents
+
+MCP-Use provides flexible options for building custom agents that can utilize MCP tools. This guide will show you how to create your own agents by leveraging the existing adapters, particularly focusing on the LangChain adapter.
+
+## Overview
+
+MCP-Use allows you to:
+
+1. Access powerful tools from MCP through connectors
+2. Convert those tools to different frameworks using adapters
+3. Build custom agents that utilize these tools
+
+While MCP-Use provides a built-in `MCPAgent` class, you may want to create your own custom agent implementation for more flexibility or to integrate with other frameworks.
+
+## Using the LangChain Adapter
+
+The `LangChainAdapter` is a powerful component that converts MCP tools to LangChain tools, enabling you to use MCP tools with any LangChain-compatible agent.
+
+### Basic Example
+
+Here's a simple example of creating a custom agent using the LangChain adapter with the simplified API:
+
+```python
+import asyncio
+from langchain_openai import ChatOpenAI
+from langchain.agents import AgentExecutor, create_tool_calling_agent
+from langchain.prompts import ChatPromptTemplate, MessagesPlaceholder
+
+from mcp_use.client import MCPClient
+from mcp_use.adapters import LangChainAdapter
+
+async def main():
+    # Initialize the MCP client
+    client = MCPClient.from_config_file("path/to/config.json")
+
+    # Create adapter instance
+    adapter = LangChainAdapter()
+
+    # Get LangChain tools directly from the client with a single line
+    tools = await adapter.create_tools(client)
+
+    # Initialize your language model
+    llm = ChatOpenAI(model="gpt-4o")
+
+    # Create a prompt template
+    prompt = ChatPromptTemplate.from_messages([
+        ("system", "You are a helpful assistant with access to powerful tools."),
+        MessagesPlaceholder(variable_name="chat_history"),
+        ("human", "{input}"),
+        MessagesPlaceholder(variable_name="agent_scratchpad"),
+    ])
+
+    # Create the agent
+    agent = create_tool_calling_agent(llm=llm, tools=tools, prompt=prompt)
+
+    # Create the agent executor
+    agent_executor = AgentExecutor(agent=agent, tools=tools, verbose=True)
+
+    # Run the agent
+    result = await agent_executor.ainvoke({"input": "What can you do?"})
+    print(result["output"])
+
+if __name__ == "__main__":
+    asyncio.run(main())
+```
+
+Note how the API simplifies tool creation - all you need is to create an adapter instance and call its `create_tools` method:
+```python
+adapter = LangChainAdapter()
+tools = await adapter.create_tools(client)
+```
+
+You don't need to worry about sessions, connectors, or initialization. The adapter handles everything for you.
+
+## Contributing New Adapters
+
+MCP-Use welcomes contributions for integrating with different agent frameworks. The adapter architecture is designed to make this process straightforward.
+
+### Adapter Architecture
+
+MCP-Use provides a `BaseAdapter` abstract class that handles most of the common functionality:
+- Managing tool caching
+- Loading tools from connectors
+- Handling connector initialization
+- Iterating through tools from multiple connectors
+
+To create an adapter for a new framework, you only need to implement one required method:
+
+- `_convert_tool`: Convert a single MCP tool to your framework's tool format
+
+### Creating a New Adapter
+
+Here's a simple template for creating a new adapter:
+
+```python
+from typing import Any
+
+from mcp_use.adapters.base import BaseAdapter
+from mcp_use.connectors.base import BaseConnector
+from your_framework import YourFrameworkTool  # Import your framework's tool class
+
+class YourFrameworkAdapter(BaseAdapter):
+    """Adapter for converting MCP tools to YourFramework tools."""
+
+    def _convert_tool(self, mcp_tool: dict[str, Any], connector: BaseConnector) -> YourFrameworkTool:
+        """Convert an MCP tool to your framework's tool format.
+
+        Args:
+            mcp_tool: The MCP tool to convert.
+            connector: The connector that provides this tool.
+
+        Returns:
+            A tool in your framework's format, or None if conversion failed.
+        """
+        try:
+            # Implement your framework-specific conversion logic
+            converted_tool = YourFrameworkTool(
+                name=mcp_tool.name,
+                description=mcp_tool.description,
+                # Map the MCP tool properties to your framework's tool properties
+                # You might need custom handling for argument schemas, function execution, etc.
+            )
+
+            return converted_tool
+        except Exception as e:
+            self.logger.error(f"Error converting tool {mcp_tool.name}: {e}")
+            return None
+```
+
+### Using Your Custom Adapter
+
+Once you've implemented your adapter, you can use it with the simplified API:
+
+```python
+from your_module import YourFrameworkAdapter
+from mcp_use.client import MCPClient
+
+# Initialize the client
+client = MCPClient.from_config_file("config.json")
+
+# Create an adapter instance
+adapter = YourFrameworkAdapter()
+
+# Get tools with a single line
+tools = await adapter.create_tools(client)
+
+# Use the tools with your framework
+agent = your_framework.create_agent(tools=tools)
+```
+
+### Tips for Implementing an Adapter
+
+1. **Schema Conversion**: Most frameworks have their own way of handling argument schemas. You'll need to convert the MCP tool's JSON Schema to your framework's format.
+
+2. **Tool Execution**: When a tool is called in your framework, you'll need to pass the call to the connector's `call_tool` method and handle the result.
+
+3. **Result Parsing**: MCP tools return structured data with types like text, images, or embedded resources. Your adapter should parse these into a format your framework understands.
+
+4. **Error Handling**: Ensure your adapter handles errors gracefully, both during tool conversion and execution.
+
+
+## Conclusion
+
+Building custom agents with MCP-Use offers tremendous flexibility while leveraging the power of MCP tools. By combining different connectors and adapters, you can create specialized agents tailored to specific tasks or integrate MCP capabilities into existing agent frameworks.
+
+The adapter architecture makes it easy to extend MCP-Use to support new frameworks - you just need to implement the `_convert_tool` method to bridge between MCP tools and your framework of choice.
+
+With the simplified API, you can create tools for your framework directly from an MCPClient by instantiating the appropriate adapter and calling its `create_tools` method, hiding all the complexity of session and connector management.
+
+We welcome contributions to expand the adapter ecosystem - if you develop an adapter for a new framework, please consider contributing it back to the project!

{mcp_use-1.2.5 → mcp_use-1.2.7}/docs/docs.json

@@ -15,19 +15,32 @@
         "groups": [
           {
             "group": "Getting Started",
-            "pages": ["introduction", "quickstart"]
+            "pages": [
+              "introduction",
+              "quickstart"
+            ]
           },
           {
             "group": "Essentials",
-            "pages": ["essentials/configuration", "essentials/llm-integration", "essentials/debugging", "essentials/connection-types"]
+            "pages": [
+              "essentials/configuration",
+              "essentials/llm-integration",
+              "essentials/debugging",
+              "essentials/connection-types",
+              "building-custom-agents"
+            ]
           },
           {
             "group": "API Reference",
-            "pages": ["api-reference/introduction"]
+            "pages": [
+              "api-reference/introduction"
+            ]
           },
           {
             "group": "Development",
-            "pages": ["development"]
+            "pages": [
+              "development"
+            ]
           }
         ]
       }

mcp_use-1.2.7/docs/favicon.svg

@@ -0,0 +1,8 @@
+<svg width="303" height="303" viewBox="0 0 303 303" fill="white" xmlns="http://www.w3.org/2000/svg">
+  <rect height="100%" width="100%" rx="55px" fill="white"/>
+<path d="M106.066 106.066C86.5398 125.592 54.8816 125.592 35.3554 106.066V106.066C15.8291 86.5397 15.8291 54.8815 35.3554 35.3552V35.3552C54.8816 15.829 86.5398 15.829 106.066 35.3552V35.3552C125.592 54.8815 125.592 86.5397 106.066 106.066V106.066Z" fill="black"/>
+<path d="M267.286 267.286C247.76 286.812 216.102 286.812 196.576 267.286V267.286C177.049 247.76 177.049 216.102 196.576 196.576V196.576C216.102 177.049 247.76 177.049 267.286 196.576V196.576C286.813 216.102 286.813 247.76 267.286 267.286V267.286Z" fill="black"/>
+<path fill-rule="evenodd" clip-rule="evenodd" d="M181.957 230.04L211.425 259.508L260.922 210.011L232.851 181.94C204.215 181.726 175.645 170.695 153.796 148.846C131.947 126.997 120.915 98.4264 120.702 69.7903L92.631 41.7193L43.1335 91.2168L72.6014 120.685C100.313 121.56 127.765 132.573 148.917 153.725C170.069 174.877 181.082 202.328 181.957 230.04Z" fill="black"/>
+<circle cx="70.3209" cy="232.321" r="50" fill="black"/>
+<circle cx="232.321" cy="70.3209" r="50" fill="black"/>
+</svg>

{mcp_use-1.2.5 → mcp_use-1.2.7}/docs/quickstart.mdx

@@ -121,6 +121,54 @@ Example configuration file (`browser_mcp.json`):
 }
 ```
 
+## Working with Adapters Directly
+
+If you want more control over how tools are created, you can work with the adapters directly. The `BaseAdapter` class provides a unified interface for converting MCP tools to various framework formats, with `LangChainAdapter` being the most commonly used implementation.
+
+```python
+import asyncio
+from langchain_openai import ChatOpenAI
+from langchain.agents import AgentExecutor, create_tool_calling_agent
+from langchain.prompts import ChatPromptTemplate, MessagesPlaceholder
+
+from mcp_use.client import MCPClient
+from mcp_use.adapters import LangChainAdapter
+
+async def main():
+    # Initialize client
+    client = MCPClient.from_config_file("browser_mcp.json")
+
+    # Create an adapter instance
+    adapter = LangChainAdapter()
+
+    # Get tools directly from the client
+    tools = await adapter.create_tools(client)
+
+    # Use the tools with any LangChain agent
+    llm = ChatOpenAI(model="gpt-4o")
+    prompt = ChatPromptTemplate.from_messages([
+        ("system", "You are a helpful assistant with access to powerful tools."),
+        MessagesPlaceholder(variable_name="chat_history"),
+        ("human", "{input}"),
+        MessagesPlaceholder(variable_name="agent_scratchpad"),
+    ])
+
+    agent = create_tool_calling_agent(llm=llm, tools=tools, prompt=prompt)
+    agent_executor = AgentExecutor(agent=agent, tools=tools, verbose=True)
+
+    result = await agent_executor.ainvoke({"input": "Search for information about climate change"})
+    print(result["output"])
+
+if __name__ == "__main__":
+    asyncio.run(main())
+```
+
+The adapter pattern makes it easy to:
+
+1. Create tools directly from an MCPClient
+2. Filter or customize which tools are available
+3. Integrate with different agent frameworks
+
 ## Using Multiple Servers
 
 The `MCPClient` can be configured with multiple MCP servers, allowing your agent to access tools from different sources. This capability enables complex workflows spanning various domains (e.g., web browsing and API interaction).

mcp_use-1.2.7/mcp_use/adapters/__init__.py

@@ -0,0 +1,10 @@
+"""
+Adapters for converting MCP tools to different frameworks.
+
+This package provides adapters for converting MCP tools to different frameworks.
+"""
+
+from .base import BaseAdapter
+from .langchain_adapter import LangChainAdapter
+
+__all__ = ["BaseAdapter", "LangChainAdapter"]

mcp_use-1.2.7/mcp_use/adapters/base.py

@@ -0,0 +1,178 @@
+"""
+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 ..client import MCPClient
+from ..connectors.base import BaseConnector
+from ..logging import logger
+
+# 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 []
+        self._connector_tool_map: dict[BaseConnector, list[T]] = {}
+
+    @classmethod
+    async def create_tools(
+        cls, client: "MCPClient", disallowed_tools: list[str] | None = None
+    ) -> list[T]:
+        """Create tools from an MCPClient instance.
+
+        This is the recommended way to create tools from an MCPClient, as it handles
+        session creation and connector extraction automatically.
+
+        Args:
+            client: The MCPClient to extract tools from.
+            disallowed_tools: Optional list of tool names to exclude.
+
+        Returns:
+            A list of tools in the target framework's format.
+
+        Example:
+            ```python
+            from mcp_use.client import MCPClient
+            from mcp_use.adapters import YourAdapter
+
+            client = MCPClient.from_config_file("config.json")
+            tools = await YourAdapter.create_tools(client)
+            ```
+        """
+        # Create the adapter
+        adapter = cls(disallowed_tools=disallowed_tools)
+
+        # Ensure we have active sessions
+        if not client.active_sessions:
+            logger.info("No active sessions found, creating new ones...")
+            await client.create_all_sessions()
+
+        # Get all active sessions
+        sessions = client.get_all_active_sessions()
+
+        # Extract connectors from sessions
+        connectors = [session.connector for session in sessions.values()]
+
+        # Create tools from connectors
+        return await adapter._create_tools_from_connectors(connectors)
+
+    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]
+
+        # Create tools for this connector
+        connector_tools = []
+
+        # Make sure the connector is initialized and has tools
+        success = await self._ensure_connector_initialized(connector)
+        if not success:
+            return []
+
+        # Now create tools for each MCP tool
+        for tool in connector.tools:
+            # Convert the tool and add it to the list if conversion was successful
+            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
+
+    @abstractmethod
+    def _convert_tool(self, mcp_tool: dict[str, Any], connector: BaseConnector) -> T:
+        """Convert an MCP tool to the target framework's tool format.
+
+        Args:
+            mcp_tool: The MCP tool to convert.
+            connector: The connector that provides this tool.
+
+        Returns:
+            A tool in the target framework's format.
+        """
+        pass
+
+    async def _create_tools_from_connectors(self, connectors: list[BaseConnector]) -> list[T]:
+        """Create tools from MCP tools in all provided connectors.
+
+        Args:
+            connectors: list of MCP connectors to create tools from.
+
+        Returns:
+            A list of tools in the target framework's format.
+        """
+        tools = []
+        for connector in connectors:
+            # Create tools for this connector
+            connector_tools = await self.load_tools_for_connector(connector)
+            tools.extend(connector_tools)
+
+        # Log available tools for debugging
+        logger.debug(f"Available tools: {len(tools)}")
+        return tools
+
+    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