mcp-use 0.1.0__tar.gz

mcp_use-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 pietrozullo
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

mcp_use-0.1.0/PKG-INFO

@@ -0,0 +1,287 @@
+Metadata-Version: 2.4
+Name: mcp_use
+Version: 0.1.0
+Summary: Model-Agnostic MCP Library for LLMs
+Home-page: https://github.com/pietrozullo/mcp_use
+Author: Pietro Zullo
+Author-email: pietro.zullo@gmail.com
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: mcp
+Requires-Dist: langchain>=0.1.0
+Requires-Dist: langchain-community>=0.0.10
+Requires-Dist: websockets>=12.0
+Requires-Dist: aiohttp>=3.9.0
+Requires-Dist: pydantic>=2.0.0
+Requires-Dist: typing-extensions>=4.8.0
+Requires-Dist: jsonschema-pydantic>=0.1.0
+Requires-Dist: python-dotenv>=1.0.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.4.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.21.0; extra == "dev"
+Requires-Dist: pytest-cov>=4.1.0; extra == "dev"
+Requires-Dist: black>=23.9.0; extra == "dev"
+Requires-Dist: isort>=5.12.0; extra == "dev"
+Requires-Dist: mypy>=1.5.0; extra == "dev"
+Requires-Dist: ruff>=0.1.0; extra == "dev"
+Provides-Extra: anthropic
+Requires-Dist: anthropic>=0.15.0; extra == "anthropic"
+Provides-Extra: openai
+Requires-Dist: openai>=1.10.0; extra == "openai"
+Dynamic: author
+Dynamic: author-email
+Dynamic: classifier
+Dynamic: description
+Dynamic: description-content-type
+Dynamic: home-page
+Dynamic: license-file
+Dynamic: provides-extra
+Dynamic: requires-dist
+Dynamic: requires-python
+Dynamic: summary
+
+# Model-Agnostic MCP Library for LLMs
+
+A Python library that lets any LLM (Language Learning Model) use MCP (Multi-Channel Platform) tools through a unified interface. The goal is to let developers easily connect any LLM to tools like web browsing, file operations, etc.
+
+## Core Concept
+
+- Leverage existing LangChain adapters rather than reinventing them
+- Focus on bridging MCPs and LangChain's tool ecosystem
+
+## Key Components
+
+### Connectors
+
+Bridge to MCP implementations:
+
+- `stdio.py`: For local MCP processes
+- `websocket.py`: For remote WebSocket MCPs
+- `http.py`: For HTTP API MCPs
+
+### Tool Conversion
+
+Convert between MCP and LangChain formats:
+
+- Convert MCP tool schemas to formats needed by different LLMs
+- Support OpenAI function calling, Anthropic tool format, etc.
+
+### Session Management
+
+Handle connection lifecycle:
+
+- Authenticate and initialize MCP connections
+- Discover and register available tools
+- Handle tool calling with proper error management
+
+### Agent Integration
+
+Ready-to-use agent implementations:
+
+- Pre-configured for MCP tool usage
+- Optimized prompts for tool selection
+
+## Installation
+
+```bash
+pip install mcp_use
+```
+
+Or install from source:
+
+```bash
+git clone https://github.com/pietrozullo/mcp_use.git
+cd mcp_use
+pip install -e .
+```
+
+## Quick Start
+
+Here's a simple example to get you started:
+
+```python
+import asyncio
+from mcp import StdioServerParameters
+from mcp_use import MCPAgent
+
+async def main():
+    # Create server parameters for stdio connection
+    server_params = StdioServerParameters(
+        command="npx",
+        args=["@playwright/mcp@latest"],
+    )
+
+    # Create a model-agnostic MCP client
+    mcp_client = MCPAgent(
+        server_params=server_params,
+        model_provider="anthropic",  # Or "openai"
+        model_name="claude-3-7-sonnet-20250219",  # Or "gpt-4o" for OpenAI
+        temperature=0.7
+    )
+
+    # Initialize the client
+    await mcp_client.initialize()
+
+    # Run a query using the agent with tools
+    result = await mcp_client.run_query(
+        "Using internet tell me how many people work at OpenAI"
+    )
+
+    print("Result:")
+    print(result)
+
+    # Close the client
+    await mcp_client.close()
+
+if __name__ == "__main__":
+    asyncio.run(main())
+```
+
+## Simplified Usage
+
+You can also use the simplified interface that handles connector lifecycle management automatically:
+
+```python
+import asyncio
+from langchain_openai import ChatOpenAI
+from mcp_use import MCPAgent
+from mcp_use.connectors.stdio import StdioConnector
+
+async def main():
+    # Create the connector
+    connector = StdioConnector(
+        command="npx",
+        args=["@playwright/mcp@latest"],
+    )
+
+    # Create the LLM
+    llm = ChatOpenAI(model="gpt-4o-mini")
+
+    # Create MCP client
+    mcp_client = MCPAgent(connector=connector, llm=llm, max_steps=30)
+
+    # Run a query - MCPAgent handles connector lifecycle internally
+    result = await mcp_client.run(
+        "Using internet tell me how many people work at OpenAI",
+        # manage_connector=True is the default
+    )
+
+    print("Result:")
+    print(result)
+
+if __name__ == "__main__":
+    asyncio.run(main())
+```
+
+## Configuration File Support
+
+mcp_use supports initialization from configuration files, making it easy to manage and switch between different MCP server setups:
+
+```python
+import asyncio
+from mcp_use import create_session_from_config
+
+async def main():
+    # Create an MCP session from a config file
+    session = create_session_from_config("mcp-config.json")
+
+    # Initialize the session
+    await session.initialize()
+
+    # Use the session...
+
+    # Disconnect when done
+    await session.disconnect()
+
+if __name__ == "__main__":
+    asyncio.run(main())
+```
+
+Example configuration file (`mcp-config.json`):
+
+```json
+{
+  "mcpServers": {
+    "playwright": {
+      "command": "npx",
+      "args": ["@playwright/mcp@latest", "headless"],
+      "env": {
+        "PLAYWRIGHT_WS_ENDPOINT": "ws://localhost:41965/"
+      }
+    }
+  }
+}
+```
+
+## MCPClient for Managing Multiple Servers
+
+The `MCPClient` class provides a higher-level abstraction for managing multiple MCP servers from a single client:
+
+```python
+import asyncio
+from langchain_anthropic import ChatAnthropic
+from mcp_use import MCPAgent, MCPClient
+
+async def main():
+    # Create a client from a config file
+    client = MCPClient.from_config_file("mcp-config.json")
+
+    # Or initialize with a config file path
+    # client = MCPClient("mcp-config.json")
+
+    # Or programmatically add servers
+    client.add_server(
+        "local-ws",
+        {
+            "command": "npx",
+            "args": ["@playwright/mcp@latest", "headless"]
+        }
+    )
+
+    # Create an LLM
+    llm = ChatAnthropic(model="claude-3-5-sonnet-20240620")
+
+    # Create an agent using the client
+    agent = MCPAgent(
+        llm=llm,
+        client=client,
+        server_name="playwright",  # Optional, uses first server if not specified
+        max_steps=30
+    )
+
+    # Run a query
+    result = await agent.run("Your query here")
+
+    # Close all sessions
+    await client.close_all_sessions()
+
+if __name__ == "__main__":
+    asyncio.run(main())
+```
+
+This approach simplifies working with multiple MCP servers and allows for more dynamic configuration management.
+
+## Advanced Usage
+
+See the `examples` directory for more advanced usage examples:
+
+- `browser_use.py`: Shows how to use MCPClient with configuration files for browser automation
+
+## Requirements
+
+- Python 3.11+
+- MCP implementation (like Playwright MCP)
+- LangChain and appropriate model libraries (OpenAI, Anthropic, etc.)
+
+## License
+
+MIT

mcp_use-0.1.0/README.md

@@ -0,0 +1,236 @@
+# Model-Agnostic MCP Library for LLMs
+
+A Python library that lets any LLM (Language Learning Model) use MCP (Multi-Channel Platform) tools through a unified interface. The goal is to let developers easily connect any LLM to tools like web browsing, file operations, etc.
+
+## Core Concept
+
+- Leverage existing LangChain adapters rather than reinventing them
+- Focus on bridging MCPs and LangChain's tool ecosystem
+
+## Key Components
+
+### Connectors
+
+Bridge to MCP implementations:
+
+- `stdio.py`: For local MCP processes
+- `websocket.py`: For remote WebSocket MCPs
+- `http.py`: For HTTP API MCPs
+
+### Tool Conversion
+
+Convert between MCP and LangChain formats:
+
+- Convert MCP tool schemas to formats needed by different LLMs
+- Support OpenAI function calling, Anthropic tool format, etc.
+
+### Session Management
+
+Handle connection lifecycle:
+
+- Authenticate and initialize MCP connections
+- Discover and register available tools
+- Handle tool calling with proper error management
+
+### Agent Integration
+
+Ready-to-use agent implementations:
+
+- Pre-configured for MCP tool usage
+- Optimized prompts for tool selection
+
+## Installation
+
+```bash
+pip install mcp_use
+```
+
+Or install from source:
+
+```bash
+git clone https://github.com/pietrozullo/mcp_use.git
+cd mcp_use
+pip install -e .
+```
+
+## Quick Start
+
+Here's a simple example to get you started:
+
+```python
+import asyncio
+from mcp import StdioServerParameters
+from mcp_use import MCPAgent
+
+async def main():
+    # Create server parameters for stdio connection
+    server_params = StdioServerParameters(
+        command="npx",
+        args=["@playwright/mcp@latest"],
+    )
+
+    # Create a model-agnostic MCP client
+    mcp_client = MCPAgent(
+        server_params=server_params,
+        model_provider="anthropic",  # Or "openai"
+        model_name="claude-3-7-sonnet-20250219",  # Or "gpt-4o" for OpenAI
+        temperature=0.7
+    )
+
+    # Initialize the client
+    await mcp_client.initialize()
+
+    # Run a query using the agent with tools
+    result = await mcp_client.run_query(
+        "Using internet tell me how many people work at OpenAI"
+    )
+
+    print("Result:")
+    print(result)
+
+    # Close the client
+    await mcp_client.close()
+
+if __name__ == "__main__":
+    asyncio.run(main())
+```
+
+## Simplified Usage
+
+You can also use the simplified interface that handles connector lifecycle management automatically:
+
+```python
+import asyncio
+from langchain_openai import ChatOpenAI
+from mcp_use import MCPAgent
+from mcp_use.connectors.stdio import StdioConnector
+
+async def main():
+    # Create the connector
+    connector = StdioConnector(
+        command="npx",
+        args=["@playwright/mcp@latest"],
+    )
+
+    # Create the LLM
+    llm = ChatOpenAI(model="gpt-4o-mini")
+
+    # Create MCP client
+    mcp_client = MCPAgent(connector=connector, llm=llm, max_steps=30)
+
+    # Run a query - MCPAgent handles connector lifecycle internally
+    result = await mcp_client.run(
+        "Using internet tell me how many people work at OpenAI",
+        # manage_connector=True is the default
+    )
+
+    print("Result:")
+    print(result)
+
+if __name__ == "__main__":
+    asyncio.run(main())
+```
+
+## Configuration File Support
+
+mcp_use supports initialization from configuration files, making it easy to manage and switch between different MCP server setups:
+
+```python
+import asyncio
+from mcp_use import create_session_from_config
+
+async def main():
+    # Create an MCP session from a config file
+    session = create_session_from_config("mcp-config.json")
+
+    # Initialize the session
+    await session.initialize()
+
+    # Use the session...
+
+    # Disconnect when done
+    await session.disconnect()
+
+if __name__ == "__main__":
+    asyncio.run(main())
+```
+
+Example configuration file (`mcp-config.json`):
+
+```json
+{
+  "mcpServers": {
+    "playwright": {
+      "command": "npx",
+      "args": ["@playwright/mcp@latest", "headless"],
+      "env": {
+        "PLAYWRIGHT_WS_ENDPOINT": "ws://localhost:41965/"
+      }
+    }
+  }
+}
+```
+
+## MCPClient for Managing Multiple Servers
+
+The `MCPClient` class provides a higher-level abstraction for managing multiple MCP servers from a single client:
+
+```python
+import asyncio
+from langchain_anthropic import ChatAnthropic
+from mcp_use import MCPAgent, MCPClient
+
+async def main():
+    # Create a client from a config file
+    client = MCPClient.from_config_file("mcp-config.json")
+
+    # Or initialize with a config file path
+    # client = MCPClient("mcp-config.json")
+
+    # Or programmatically add servers
+    client.add_server(
+        "local-ws",
+        {
+            "command": "npx",
+            "args": ["@playwright/mcp@latest", "headless"]
+        }
+    )
+
+    # Create an LLM
+    llm = ChatAnthropic(model="claude-3-5-sonnet-20240620")
+
+    # Create an agent using the client
+    agent = MCPAgent(
+        llm=llm,
+        client=client,
+        server_name="playwright",  # Optional, uses first server if not specified
+        max_steps=30
+    )
+
+    # Run a query
+    result = await agent.run("Your query here")
+
+    # Close all sessions
+    await client.close_all_sessions()
+
+if __name__ == "__main__":
+    asyncio.run(main())
+```
+
+This approach simplifies working with multiple MCP servers and allows for more dynamic configuration management.
+
+## Advanced Usage
+
+See the `examples` directory for more advanced usage examples:
+
+- `browser_use.py`: Shows how to use MCPClient with configuration files for browser automation
+
+## Requirements
+
+- Python 3.11+
+- MCP implementation (like Playwright MCP)
+- LangChain and appropriate model libraries (OpenAI, Anthropic, etc.)
+
+## License
+
+MIT

mcp_use-0.1.0/mcp_use/__init__.py

@@ -0,0 +1,30 @@
+"""
+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
+from .tools.converter import ModelProvider, ToolConverter
+
+__version__ = "0.1.0"
+__all__ = [
+    "MCPAgent",
+    "MCPClient",
+    "MCPSession",
+    "BaseConnector",
+    "StdioConnector",
+    "WebSocketConnector",
+    "HttpConnector",
+    "ModelProvider",
+    "ToolConverter",
+    "create_session_from_config",
+    "load_config_file",
+    "logger",
+]

mcp_use-0.1.0/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-0.1.0/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