mcp-use 1.0.0__tar.gz → 1.0.2__tar.gz

{mcp_use-1.0.0 → mcp_use-1.0.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mcp-use
-Version: 1.0.0
+Version: 1.0.2
 Summary: MCP Library for LLMs
 Author-email: Pietro Zullo <pietro.zullo@gmail.com>
 License: MIT
@@ -38,7 +38,7 @@ Requires-Dist: openai>=1.10.0; extra == 'openai'
 Description-Content-Type: text/markdown
 
 <picture>
-  <img alt="" src="./static/mcpusegrass.png"  width="full">
+  <img alt="" src="./static/image.jpg"  width="full">
 </picture>
 
 <h1 align="center">Open Source MCP CLient Library </h1>
@@ -47,6 +47,7 @@ Description-Content-Type: text/markdown
 [![PyPI Downloads](https://img.shields.io/pypi/dm/mcp_use.svg)](https://pypi.org/project/mcp_use/)
 [![PyPI Version](https://img.shields.io/pypi/v/mcp_use.svg)](https://pypi.org/project/mcp_use/)
 [![Python Versions](https://img.shields.io/pypi/pyversions/mcp_use.svg)](https://pypi.org/project/mcp_use/)
+[![Documentation](https://img.shields.io/badge/docs-mcp--use.io-blue)](https://docs.mcp-use.io)
 [![License](https://img.shields.io/github/license/pietrozullo/mcp-use)](https://github.com/pietrozullo/mcp-use/blob/main/LICENSE)
 [![Code style: Ruff](https://img.shields.io/badge/code%20style-ruff-000000.svg)](https://github.com/astral-sh/ruff)
 [![GitHub stars](https://img.shields.io/github/stars/pietrozullo/mcp-use?style=social)](https://github.com/pietrozullo/mcp-use/stargazers)

{mcp_use-1.0.0 → mcp_use-1.0.2}/README.md

@@ -1,5 +1,5 @@
 <picture>
-  <img alt="" src="./static/mcpusegrass.png"  width="full">
+  <img alt="" src="./static/image.jpg"  width="full">
 </picture>
 
 <h1 align="center">Open Source MCP CLient Library </h1>
@@ -8,6 +8,7 @@
 [![PyPI Downloads](https://img.shields.io/pypi/dm/mcp_use.svg)](https://pypi.org/project/mcp_use/)
 [![PyPI Version](https://img.shields.io/pypi/v/mcp_use.svg)](https://pypi.org/project/mcp_use/)
 [![Python Versions](https://img.shields.io/pypi/pyversions/mcp_use.svg)](https://pypi.org/project/mcp_use/)
+[![Documentation](https://img.shields.io/badge/docs-mcp--use.io-blue)](https://docs.mcp-use.io)
 [![License](https://img.shields.io/github/license/pietrozullo/mcp-use)](https://github.com/pietrozullo/mcp-use/blob/main/LICENSE)
 [![Code style: Ruff](https://img.shields.io/badge/code%20style-ruff-000000.svg)](https://github.com/astral-sh/ruff)
 [![GitHub stars](https://img.shields.io/github/stars/pietrozullo/mcp-use?style=social)](https://github.com/pietrozullo/mcp-use/stargazers)

mcp_use-1.0.2/docs/README.md

@@ -0,0 +1,32 @@
+# Mintlify Starter Kit
+
+Click on `Use this template` to copy the Mintlify starter kit. The starter kit contains examples including
+
+- Guide pages
+- Navigation
+- Customizations
+- API Reference pages
+- Use of popular components
+
+### Development
+
+Install the [Mintlify CLI](https://www.npmjs.com/package/mintlify) to preview the documentation changes locally. To install, use the following command
+
+```
+npm i -g mintlify
+```
+
+Run the following command at the root of your documentation (where docs.json is)
+
+```
+mintlify dev
+```
+
+### Publishing Changes
+
+Install our Github App to auto propagate changes from your repo to your deployment. Changes will be deployed to production automatically after pushing to the default branch. Find the link to install on your dashboard.
+
+#### Troubleshooting
+
+- Mintlify dev isn't running - Run `mintlify install` it'll re-install dependencies.
+- Page loads as a 404 - Make sure you are running in a folder with `docs.json`

mcp_use-1.0.2/docs/api-reference/introduction.mdx

@@ -0,0 +1,385 @@
+---
+title: API Reference
+description: "Complete mcp_use API Documentation"
+---
+
+# API Reference
+
+This section provides comprehensive documentation for the mcp_use API, including all components, methods, their arguments, and when to use different options.
+
+## MCPClient
+
+The `MCPClient` is the core class for interacting with MCP servers. It handles connection management, session creation, and communication with MCP servers.
+
+### Initialization Methods
+
+#### From Config File
+
+```python
+from mcp_use import MCPClient
+
+client = MCPClient.from_config_file(config_path="config.json")
+```
+
+| Parameter     | Type | Required | Description                         |
+| ------------- | ---- | -------- | ----------------------------------- |
+| `config_path` | str  | Yes      | Path to the JSON configuration file |
+
+#### From Dictionary
+
+```python
+from mcp_use import MCPClient
+
+config = {
+  "mcpServers": {
+    "my_server": {
+      "command": "npx",
+      "args": ["@my-mcp/server"],
+      "env": {
+        "PORT": "3000"
+      }
+    }
+  }
+}
+
+client = MCPClient.from_dict(config=config)
+```
+
+| Parameter | Type | Required | Description                                    |
+| --------- | ---- | -------- | ---------------------------------------------- |
+| `config`  | dict | Yes      | Dictionary containing MCP server configuration |
+
+### Core Methods
+
+#### create_session
+
+Creates a new session with an MCP server.
+
+```python
+session = await client.create_session(server_name="my_server")
+```
+
+| Parameter     | Type  | Required | Default | Description                             |
+| ------------- | ----- | -------- | ------- | --------------------------------------- |
+| `server_name` | str   | Yes      | -       | Name of the server as defined in config |
+| `timeout`     | float | No       | 30.0    | Connection timeout in seconds           |
+| `retry_count` | int   | No       | 3       | Number of connection retry attempts     |
+
+**When to use**:
+
+- Use a longer `timeout` for servers that take more time to initialize
+- Increase `retry_count` in unstable network environments
+- Use specific `server_name` when working with multiple servers in the same config
+
+#### close_session
+
+Closes a specific session.
+
+```python
+await client.close_session(session_id="session_id")
+```
+
+| Parameter    | Type | Required | Description                |
+| ------------ | ---- | -------- | -------------------------- |
+| `session_id` | str  | Yes      | ID of the session to close |
+
+#### close_all_sessions
+
+Closes all active sessions.
+
+```python
+await client.close_all_sessions()
+```
+
+**When to use**:
+
+- Always call this at the end of your application to clean up resources
+- Use when switching between different tasks that require different servers
+
+#### get_server
+
+Gets a server instance by name.
+
+```python
+server = client.get_server(name="my_server")
+```
+
+| Parameter | Type | Required | Description                             |
+| --------- | ---- | -------- | --------------------------------------- |
+| `name`    | str  | Yes      | Name of the server as defined in config |
+
+## MCPAgent
+
+The `MCPAgent` class combines an LLM with an MCPClient to create an intelligent agent capable of using MCP tools.
+
+### Initialization
+
+```python
+from mcp_use import MCPAgent, MCPClient
+from langchain_openai import ChatOpenAI
+
+agent = MCPAgent(
+    llm=ChatOpenAI(model="gpt-4o", temperature=0.7),
+    client=MCPClient.from_config_file("config.json"),
+    max_steps=30,
+    session_options={"timeout": 60.0},
+    auto_initialize=True,
+    memory_enabled=True,
+    system_prompt=None,
+    system_prompt_template=None,
+    additional_instructions=None
+)
+```
+
+| Parameter                 | Type                | Required | Default | Description                                |
+| ------------------------- | ------------------- | -------- | ------- | ------------------------------------------ |
+| `llm`                     | BaseLanguageModel   | Yes      | -       | Any LangChain-compatible language model    |
+| `client`                  | MCPClient           | No       | None    | The MCPClient instance                     |
+| `connectors`              | list[BaseConnector] | No       | None    | List of connectors if not using client     |
+| `server_name`             | str                 | No       | None    | Name of the server to use                  |
+| `max_steps`               | int                 | No       | 5       | Maximum number of steps the agent can take |
+| `auto_initialize`         | bool                | No       | False   | Whether to initialize automatically        |
+| `memory_enabled`          | bool                | No       | True    | Whether to enable memory                   |
+| `system_prompt`           | str                 | No       | None    | Custom system prompt                       |
+| `system_prompt_template`  | str                 | No       | None    | Custom system prompt template              |
+| `additional_instructions` | str                 | No       | None    | Additional instructions for the agent      |
+| `session_options`         | dict                | No       | {}      | Additional options for session creation    |
+| `output_parser`           | OutputParser        | No       | None    | Custom output parser for LLM responses     |
+
+**When to use different parameters**:
+
+- **llm**:
+
+  - mcp_use supports ANY LLM that is compatible with LangChain
+  - You can use models from OpenAI, Anthropic, Google, Mistral, Groq, Cohere, or any other provider with a LangChain integration
+  - You can even use open source models via LlamaCpp, HuggingFace, or other interfaces
+  - Custom or self-hosted models are also supported as long as they implement LangChain's interface
+
+- **max_steps**:
+
+  - Increase for complex tasks that require many interactions
+  - Decrease for simpler tasks to improve efficiency
+  - Use higher values (50+) for web browsing or multi-stage tasks
+  - Use lower values (10-20) for targeted, specific tasks
+
+- **system_prompt / system_prompt_template**:
+
+  - Use to customize the initial instructions given to the LLM
+  - Helps shape the agent's behavior and capabilities
+  - Use for specialized tasks or custom interaction patterns
+
+- **memory_enabled**:
+
+  - Enable to maintain conversation history
+  - Disable for stateless operation or to save on token usage
+
+- **session_options**:
+  - Customize timeout for long-running server operations
+  - Set retry parameters for unstable connections
+
+### Core Methods
+
+#### run
+
+Runs the agent with a given query.
+
+```python
+result = await agent.run(
+    query="Find information about Python libraries",
+    max_steps=25,
+    stop_on_first_result=False
+)
+```
+
+| Parameter              | Type | Required | Default | Description                      |
+| ---------------------- | ---- | -------- | ------- | -------------------------------- |
+| `query`                | str  | Yes      | -       | The query to run                 |
+| `max_steps`            | int  | No       | None    | Overrides the instance max_steps |
+| `stop_on_first_result` | bool | No       | False   | Whether to stop at first result  |
+| `server_name`          | str  | No       | None    | Specific server to use           |
+| `callbacks`            | list | No       | None    | Callback functions for events    |
+
+**When to use different parameters**:
+
+- **max_steps**: Override the instance default for specific queries
+- **stop_on_first_result**: Use True for simple lookups, False for thorough exploration
+- **server_name**: Specify when using multiple servers for different tasks
+- **callbacks**: Add for monitoring or logging specific runs
+
+#### reset
+
+Resets the agent state.
+
+```python
+agent.reset()
+```
+
+**When to use**:
+
+- Between different tasks to clear context
+- When starting a new conversation thread
+- When agent gets stuck in a particular strategy
+
+#### get_history
+
+Gets the agent's interaction history.
+
+```python
+history = agent.get_history()
+```
+
+**When to use**:
+
+- For debugging agent behavior
+- When implementing custom logging
+- To provide context for follow-up queries
+
+## Configuration Details
+
+### MCP Server Configuration Schema
+
+```json
+{
+  "mcpServers": {
+    "server_name": {
+      "command": "command_to_run",
+      "args": ["arg1", "arg2"],
+      "env": {
+        "ENV_VAR": "value"
+      },
+      "timeout": 30.0,
+      "retry": {
+        "max_attempts": 3,
+        "backoff_factor": 1.5
+      }
+    }
+  }
+}
+```
+
+| Field                  | Type   | Required | Description                          |
+| ---------------------- | ------ | -------- | ------------------------------------ |
+| `command`              | string | Yes      | The command to start the MCP server  |
+| `args`                 | array  | No       | Arguments to pass to the command     |
+| `env`                  | object | No       | Environment variables for the server |
+| `timeout`              | number | No       | Connection timeout in seconds        |
+| `retry`                | object | No       | Retry configuration                  |
+| `retry.max_attempts`   | number | No       | Maximum retry attempts               |
+| `retry.backoff_factor` | number | No       | Backoff multiplier between retries   |
+
+**When to use different options**:
+
+- **command & args**: Vary based on the specific MCP server implementation
+- **env**:
+
+  - Set environment-specific variables needed by the server
+  - Override default server settings (ports, directories)
+  - Set display settings for GUI-based servers
+
+- **timeout**:
+
+  - Increase for servers with longer startup times
+  - Lower for simpler servers to fail fast
+
+- **retry configuration**:
+  - Adjust for different network conditions
+  - Increase max_attempts in unstable environments
+  - Adjust backoff_factor based on server behavior
+
+## Error Handling
+
+mcp_use provides several exception types to handle different error scenarios:
+
+| Exception                | Description                       | When It Occurs                      |
+| ------------------------ | --------------------------------- | ----------------------------------- |
+| `MCPConnectionError`     | Connection to MCP server failed   | Network issues, server not running  |
+| `MCPAuthenticationError` | Authentication with server failed | Invalid credentials or tokens       |
+| `MCPTimeoutError`        | Operation timed out               | Server takes too long to respond    |
+| `MCPServerError`         | Server returned an error          | Internal server error               |
+| `MCPClientError`         | Client-side error                 | Invalid configuration or parameters |
+| `MCPError`               | Generic MCP-related error         | Any other MCP-related issue         |
+
+**Handling Strategies**:
+
+```python
+from mcp_use.exceptions import MCPConnectionError, MCPTimeoutError
+
+try:
+    result = await agent.run("Find information")
+except MCPConnectionError:
+    # Handle connection issues
+    print("Failed to connect to the MCP server")
+except MCPTimeoutError:
+    # Handle timeout issues
+    print("Operation timed out")
+except Exception as e:
+    # Handle other exceptions
+    print(f"An error occurred: {e}")
+```
+
+## Advanced Usage
+
+### Multi-Server Configuration
+
+Configure and use multiple MCP servers in a single application:
+
+```python
+from mcp_use import MCPClient, MCPAgent
+from langchain_openai import ChatOpenAI
+
+# Create client with multiple servers
+client = MCPClient.from_dict({
+    "mcpServers": {
+        "browser": {
+            "command": "npx",
+            "args": ["@playwright/mcp@latest"]
+        },
+        "custom_server": {
+            "command": "python",
+            "args": ["-m", "my_custom_mcp_server"]
+        }
+    }
+})
+
+# Create agent
+agent = MCPAgent(llm=ChatOpenAI(model="gpt-4o"), client=client)
+
+# Run with specific server
+result_browser = await agent.run(
+    "Search the web for Python libraries",
+    server_name="browser"
+)
+
+# Run with different server
+result_custom = await agent.run(
+    "Perform custom operation",
+    server_name="custom_server"
+)
+```
+
+### Custom Output Parsing
+
+Implement custom output parsers for specialized MCP servers:
+
+```python
+from langchain.schema import OutputParser
+from mcp_use import MCPAgent, MCPClient
+
+class CustomOutputParser(OutputParser):
+    def parse(self, text):
+        # Custom parsing logic
+        return processed_result
+
+# Use the custom parser
+agent = MCPAgent(
+    llm=llm,
+    client=client,
+    output_parser=CustomOutputParser()
+)
+```
+
+This approach is useful when:
+
+- The MCP server returns structured data that needs special handling
+- You need to extract specific information from responses
+- You're integrating with custom or specialized MCP servers

mcp_use-1.0.2/docs/development.mdx

@@ -0,0 +1,135 @@
+---
+title: Development
+description: "Contributing to mcp_use"
+---
+
+# Development Guide
+
+This guide will help you set up your development environment and contribute to mcp_use.
+
+## Prerequisites
+
+- Python 3.8 or higher
+- Git
+- Node.js and npm (for MCP server dependencies)
+
+## Setting Up Development Environment
+
+1. Clone the repository:
+
+```bash
+git clone https://github.com/pietrozullo/mcp-use.git
+cd mcp-use
+```
+
+2. Install development dependencies:
+
+```bash
+pip install -e ".[dev]"
+```
+
+3. Install pre-commit hooks:
+
+```bash
+pre-commit install
+```
+
+## Code Style
+
+mcp_use uses Ruff for code formatting and linting. The project follows these style guidelines:
+
+- Use type hints for all function parameters and return values
+- Follow PEP 8 style guide
+- Use docstrings for all public functions and classes
+- Keep functions focused and single-purpose
+
+## Running Tests
+
+The project uses pytest for testing. To run the test suite:
+
+```bash
+pytest
+```
+
+For more specific test runs:
+
+```bash
+# Run tests with coverage
+pytest --cov=mcp_use
+
+# Run specific test file
+pytest tests/test_client.py
+
+# Run tests with verbose output
+pytest -v
+```
+
+## Documentation
+
+Documentation is written in MDX format and uses Mintlify for rendering. To preview documentation changes:
+
+1. Install Mintlify CLI:
+
+```bash
+npm i -g mintlify
+```
+
+2. Run the development server:
+
+```bash
+mintlify dev
+```
+
+## Contributing
+
+1. Create a new branch for your feature:
+
+```bash
+git checkout -b feature/your-feature-name
+```
+
+2. Make your changes and commit them:
+
+```bash
+git add .
+git commit -m "Description of your changes"
+```
+
+3. Push your changes and create a pull request:
+
+```bash
+git push origin feature/your-feature-name
+```
+
+## Project Structure
+
+```
+mcp-use/
+├── mcp_use/           # Main package code
+├── tests/             # Test files
+├── examples/          # Example usage
+├── docs/             # Documentation
+├── static/           # Static assets
+└── pyproject.toml    # Project configuration
+```
+
+## Adding New MCP Servers
+
+To add support for a new MCP server:
+
+1. Create a new configuration template in the examples directory
+2. Add necessary server-specific code in the `mcp_use` package
+3. Update documentation with new server information
+4. Add tests for the new server functionality
+
+## Release Process
+
+1. Update version in `pyproject.toml`
+2. Update CHANGELOG.md
+3. Create a new release tag
+4. Build and publish to PyPI:
+
+```bash
+python -m build
+python -m twine upload dist/*
+```

mcp_use-1.0.2/docs/docs.json

@@ -0,0 +1,74 @@
+{
+  "$schema": "https://mintlify.com/docs.json",
+  "theme": "mint",
+  "name": "mcp_use",
+  "colors": {
+    "primary": "#062c24",
+    "light": "#55e4c8",
+    "dark": "#000000"
+  },
+  "favicon": "/favicon.svg",
+  "navigation": {
+    "tabs": [
+      {
+        "tab": "Documentation",
+        "groups": [
+          {
+            "group": "Getting Started",
+            "pages": ["introduction", "quickstart"]
+          },
+          {
+            "group": "Essentials",
+            "pages": ["essentials/configuration", "essentials/llm-integration"]
+          },
+          {
+            "group": "API Reference",
+            "pages": ["api-reference/introduction"]
+          },
+          {
+            "group": "Development",
+            "pages": ["development"]
+          }
+        ]
+      }
+    ]
+  },
+  "logo": {
+    "light": "/logo/light.svg",
+    "dark": "/logo/dark.svg"
+  },
+  "navbar": {
+    "links": [
+      {
+        "label": "GitHub",
+        "href": "https://github.com/pietrozullo/mcp-use"
+      }
+    ]
+  },
+  "footer": {
+    "socials": {
+      "github": "https://github.com/pietrozullo/mcp-use"
+    }
+  },
+  "anchors": [
+    {
+      "name": "Documentation",
+      "icon": "book-open",
+      "url": "/"
+    },
+    {
+      "name": "API Reference",
+      "icon": "code",
+      "url": "/api-reference"
+    },
+    {
+      "name": "Development",
+      "icon": "code-branch",
+      "url": "/development"
+    }
+  ],
+  "feedback": {
+    "suggestEdit": true,
+    "raiseIssue": true
+  }
+}