mcp-use 1.6.0__tar.gz

mcp_use-1.6.0/.env.example

@@ -0,0 +1,61 @@
+# =============================================================================
+# MCP-Use Environment Configuration
+# =============================================================================
+# Copy this file to .env and fill in your actual values
+# The .env file is already in .gitignore and won't be committed
+
+# =============================================================================
+# Observability - Optional but recommended for debugging and monitoring
+# =============================================================================
+
+# Langfuse Configuration (https://langfuse.com)
+# Sign up at https://cloud.langfuse.com or self-host
+LANGFUSE_PUBLIC_KEY=pk-lf-your-public-key-here
+LANGFUSE_SECRET_KEY=sk-lf-your-secret-key-here
+# LANGFUSE_HOST=https://cloud.langfuse.com  # Default, uncomment for self-hosted
+
+# Laminar Configuration (https://www.lmnr.ai)
+# Sign up at https://www.lmnr.ai and get your project API key
+LAMINAR_PROJECT_API_KEY=your-laminar-project-api-key-here
+
+# =============================================================================
+# LLM Provider API Keys
+# =============================================================================
+
+# OpenAI
+OPENAI_API_KEY=sk-your-openai-api-key-here
+
+# Anthropic
+ANTHROPIC_API_KEY=sk-ant-your-anthropic-api-key-here
+
+# Google (for Gemini)
+GOOGLE_API_KEY=your-google-api-key-here
+
+# Azure OpenAI
+AZURE_OPENAI_API_KEY=your-azure-openai-key-here
+AZURE_OPENAI_ENDPOINT=https://your-resource-name.openai.azure.com/
+
+# =============================================================================
+# Debug and Development
+# =============================================================================
+
+# MCP-Use Debug Level (1=INFO, 2=DEBUG)
+DEBUG=1
+# Alternative debug variable
+MCP_USE_DEBUG=1
+
+# Disable specific features (set to 'false' to disable)
+# MCP_USE_LANGFUSE=false
+# MCP_USE_LAMINAR=false
+# MCP_USE_TELEMETRY=false
+
+# =============================================================================
+# MCP Server Specific Configuration
+# =============================================================================
+
+# E2B Sandbox (for sandboxed execution)
+E2B_API_KEY=your-e2b-api-key-here
+
+# Custom MCP server endpoints (if using HTTP/WebSocket servers)
+# MCP_SERVER_URL=http://localhost:8080
+# MCP_WEBSOCKET_URL=ws://localhost:8081

mcp_use-1.6.0/.gitignore

@@ -0,0 +1,128 @@
+
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+
+# PyInstaller
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+.hypothesis/
+.pytest_cache/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+.python-version
+
+# pipenv
+Pipfile.lock
+
+# poetry
+poetry.lock
+
+# Environment variables
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# VS Code
+.vscode/
+*.code-workspace
+
+# PyCharm
+.idea/
+*.iml
+
+# macOS
+.DS_Store
+
+# AI
+.cursor
+.claude

mcp_use-1.6.0/.pre-commit-config.yaml

@@ -0,0 +1,28 @@
+repos:
+-   repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.11.12
+    hooks:
+    -   id: ruff
+        args: [--fix, --exit-non-zero-on-fix]
+    -   id: ruff-format
+
+-   repo: local
+    hooks:
+    -   id: ty
+        name: ty check
+        entry: ty check
+        language: system
+        types: [python]
+        exclude: ^tests/
+
+-   repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v5.0.0
+    hooks:
+    -   id: trailing-whitespace
+    -   id: end-of-file-fixer
+    -   id: check-yaml
+    -   id: check-added-large-files
+    -   id: debug-statements
+
+default_language_version:
+    python: python3.11

mcp_use-1.6.0/CLAUDE.md

@@ -0,0 +1,254 @@
+# CLAUDE.md - Python Library
+
+This file provides guidance for working with the Python implementation of mcp-use.
+
+**IMPORTANT:** Read the root `/CLAUDE.md` first for critical workflow requirements around planning, breaking changes, and testing standards.
+
+---
+
+## Project Overview
+
+**mcp-use** is a unified MCP (Model Context Protocol) client library that enables any LLM to connect to MCP servers and build custom agents with tool access. The library provides a high-level Python interface for connecting LangChain-compatible LLMs to MCP tools like web browsing, file operations, and more.
+
+## Development Commands
+
+### Setup
+
+```bash
+# Activate virtual environment (if it exists)
+source env/bin/activate
+
+# Create virtual environment if it doesn't exist
+# python -m venv env && source env/bin/activate
+
+# Install for development
+pip install -e ".[dev,search]"
+
+# Install with optional dependencies
+pip install -e ".[dev,anthropic,openai,e2b,search]"
+```
+
+### Code Quality
+
+```bash
+# Run linting and formatting
+ruff check --fix
+ruff format
+
+# Run type checking
+ty check
+
+# Run pre-commit hooks
+prek run --all-files
+```
+
+### Testing
+
+```bash
+# Run all tests
+pytest
+
+# Run specific test types
+pytest tests/unit/          # Unit tests only
+pytest tests/integration/   # Integration tests only
+
+# Run with coverage
+pytest --cov=mcp_use --cov-report=html
+
+# Run specific test file
+pytest tests/unit/test_client.py
+
+# Run with debug output
+DEBUG=2 pytest tests/unit/test_client.py -v -s
+```
+
+### Local Development
+
+```bash
+# Debug mode environment variable
+export DEBUG=1  # INFO level
+export DEBUG=2  # DEBUG level (full verbose)
+
+# Or set MCP_USE_DEBUG
+export MCP_USE_DEBUG=2
+```
+
+## Architecture Overview
+
+### Core Components
+
+**MCPClient** (`mcp_use/client.py`)
+
+- Main entry point for MCP server management
+- Handles configuration loading from files or dictionaries
+- Manages multiple MCP server sessions
+- Supports sandboxed execution via E2B
+
+**MCPAgent** (`mcp_use/agents/mcpagent.py`)
+
+- High-level agent interface using LangChain's agent framework
+- Integrates LLMs with MCP tools
+- Supports streaming responses and conversation memory
+- Can use ServerManager for dynamic server selection
+
+**MCPSession** (`mcp_use/session.py`)
+
+- Manages individual MCP server connections
+- Handles tool discovery and resource management
+- Maintains connection state and lifecycle
+
+**Connectors** (`mcp_use/connectors/`)
+
+- Abstraction layer for different MCP transport protocols
+- `StdioConnector`: Process-based MCP servers
+- `HttpConnector`: HTTP-based MCP servers
+- `WebSocketConnector`: WebSocket-based MCP servers
+- `SandboxConnector`: E2B sandboxed execution
+
+**ServerManager** (`mcp_use/managers/server_manager.py`)
+
+- Provides dynamic server selection capabilities
+- Allows agents to choose appropriate servers for tasks
+- Manages server tool discovery and activation
+
+### Key Patterns
+
+**Configuration-Driven Design**: Servers are configured via JSON files or dictionaries with `mcpServers` key containing server definitions.
+
+**Async/Await**: All I/O operations are asynchronous using asyncio patterns.
+
+**LangChain Integration**: Tools are converted to LangChain format via adapters, enabling use with any LangChain-compatible LLM.
+
+**Multi-Transport Support**: Supports stdio, HTTP, WebSocket, and sandboxed connections to MCP servers.
+
+**Telemetry**: Built-in telemetry using PostHog and Scarf.sh for usage analytics (can be disabled).
+
+## Configuration Examples
+
+### Basic Server Configuration
+
+```json
+{
+  "mcpServers": {
+    "playwright": {
+      "command": "npx",
+      "args": ["@playwright/mcp@latest"],
+      "env": { "DISPLAY": ":1" }
+    }
+  }
+}
+```
+
+### HTTP Server Configuration
+
+```json
+{
+  "mcpServers": {
+    "http_server": {
+      "url": "http://localhost:8931/sse"
+    }
+  }
+}
+```
+
+### Multi-Server Configuration
+
+```json
+{
+  "mcpServers": {
+    "playwright": {
+      "command": "npx",
+      "args": ["@playwright/mcp@latest"]
+    },
+    "airbnb": {
+      "command": "npx",
+      "args": ["-y", "@openbnb/mcp-server-airbnb"]
+    }
+  }
+}
+```
+
+## Code Style and Standards
+
+- **Line Length**: 200 characters (configured in ruff.toml)
+- **Python Version**: 3.11+ required
+- **Formatting**: Use Ruff for formatting and linting
+- **Type Hints**: All public APIs should have type hints
+- **Async Patterns**: Use async/await consistently for I/O operations
+- **Error Handling**: Proper exception handling with logging
+- **Documentation**: Docstrings follow Google style
+
+## Testing Strategy
+
+**Tests are MANDATORY for new functionality. See root CLAUDE.md for standards.**
+
+### Unit Tests (`tests/unit/`)
+
+- Test individual components in isolation
+- Mock only external dependencies (network, file I/O), NOT internal logic
+- Focus on business logic and edge cases
+- **DO NOT** create tests that only verify mocks were called
+
+### Integration Tests (`tests/integration/`)
+
+- Test component interactions with real MCP servers
+- Organized by category:
+  - `client/transports/` - stdio, sse, streamable_http
+  - `client/primitives/` - tools, resources, prompts
+  - `agent/` - Full agent workflows (require API keys)
+- Custom test servers in `tests/integration/servers_for_testing/`
+
+### Test Requirements
+
+- Every new public method/function needs tests
+- Test both success cases AND error handling
+- Integration tests preferred over heavily mocked unit tests
+- If you mock everything, you're testing nothing
+
+### Test Configuration
+
+- Uses pytest with asyncio mode
+- Fixtures defined in `conftest.py`
+- Test servers provide controlled MCP environments
+
+## Important Development Notes
+
+- **Environment Setup**: Requires Python 3.11+ and appropriate LangChain provider packages
+- **MCP Protocol**: Built on Model Context Protocol specification
+- **LangChain Compatibility**: Only models with tool calling capabilities are supported
+- **Resource Management**: Always properly close sessions to avoid resource leaks
+- **Debugging**: Use DEBUG environment variable or `mcp_use.set_debug()` for verbose logging
+- **Memory Management**: MCPAgent supports conversation memory for context retention
+- **Security**: Tool access can be restricted via `disallowed_tools` parameter
+
+## Common Development Tasks
+
+### Adding a New Connector
+
+1. Extend `BaseConnector` in `mcp_use/connectors/`
+2. Implement required async methods
+3. Add connector to factory in `config.py`
+4. Write integration tests
+
+### Adding New Agent Features
+
+1. Modify `MCPAgent` class in `mcp_use/agents/mcpagent.py`
+2. Update system prompt templates if needed
+3. Add comprehensive tests
+4. Update documentation
+
+### Testing with Custom MCP Servers
+
+1. Create test server in `tests/integration/servers_for_testing/`
+2. Add integration test in appropriate transport directory
+3. Use custom servers for controlled testing scenarios
+
+## Post-Implementation Checklist
+
+After completing any feature or fix:
+
+1. **Tests pass**: `pytest tests/unit` (and integration if applicable)
+2. **Linting passes**: `ruff check && ruff format --check`
+3. **Documentation updated**: Check `docs/`, README, docstrings
+4. **Examples updated**: Check `examples/` directory if API changed
+5. **PR description ready**: Follow `.github/pull_request_template.md`