mcp-use 1.3.0__tar.gz → 1.3.2__tar.gz

mcp_use-1.3.2/.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.3.2/.github/release-drafter.yml

@@ -0,0 +1,32 @@
+name-template: 'v$RESOLVED_VERSION 🌈'
+tag-template: 'v$RESOLVED_VERSION'
+categories:
+  - title: '🚀 Features'
+    labels:
+      - 'feature'
+      - 'feat'
+      - 'enhancement'
+  - title: '🐛 Bug Fixes'
+    labels:
+      - 'fix'
+      - 'bugfix'
+      - 'bug'
+  - title: '🧰 Maintenance'
+    label: 'chore'
+change-template: '- $TITLE @$AUTHOR (#$NUMBER)'
+change-title-escapes: '\<*_&' # You can add # and @ to disable mentions, and add ` to disable code blocks.
+version-resolver:
+  major:
+    labels:
+      - 'major'
+  minor:
+    labels:
+      - 'minor'
+  patch:
+    labels:
+      - 'patch'
+  default: patch
+template: |
+  ## Changes
+
+  $CHANGES

mcp_use-1.3.2/.github/workflows/changelog.yml

@@ -0,0 +1,74 @@
+name: "Update Changelogs"
+
+on:
+  release:
+    types: [released]
+
+jobs:
+  update:
+    runs-on: ubuntu-latest
+
+    permissions:
+      # Give the default GITHUB_TOKEN write permission to commit and push the
+      # updated CHANGELOG back to the repository.
+      # https://github.blog/changelog/2023-02-02-github-actions-updating-the-default-github_token-permissions-to-read-only/
+      contents: write
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+        with:
+          ref: ${{ github.event.release.target_commitish }}
+          fetch-depth: 0
+          token: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Update Changelog
+        uses: stefanzweifel/changelog-updater-action@v1
+        with:
+          latest-version: ${{ github.event.release.tag_name }}
+          release-notes: ${{ github.event.release.body }}
+
+      - name: Update Docs Changelog
+        run: |
+          # Get current date in the required format
+          CURRENT_DATE=$(date +"%Y‑%m‑%d")
+
+          # Create the new changelog entry
+          NEW_ENTRY="<Update label=\"$CURRENT_DATE\">
+            ## ${{ github.event.release.tag_name }}
+            ${{ github.event.release.body }}
+          </Update>
+
+          "
+
+          # Read the current changelog and insert the new entry after the front matter
+          python -c "
+          import re
+
+          # Read the current changelog
+          with open('docs/changelog.mdx', 'r') as f:
+              content = f.read()
+
+          # Find the end of the front matter
+          front_matter_end = content.find('---', content.find('---') + 1) + 3
+
+          # Split content into front matter and body
+          front_matter = content[:front_matter_end]
+          body = content[front_matter_end:]
+
+          # Create new entry
+          new_entry = '''$NEW_ENTRY'''
+
+          # Combine and write back
+          new_content = front_matter + '\n\n' + new_entry + body.lstrip()
+
+          with open('docs/changelog.mdx', 'w') as f:
+              f.write(new_content)
+          "
+
+      - name: Commit updated CHANGELOG
+        uses: stefanzweifel/git-auto-commit-action@v5
+        with:
+          branch: ${{ github.event.release.target_commitish }}
+          commit_message: Update CHANGELOG and docs changelog
+          file_pattern: CHANGELOG.md docs/changelog.mdx

mcp_use-1.3.2/.github/workflows/claude.yml

@@ -0,0 +1,36 @@
+name: Claude PR Assistant
+
+on:
+  issue_comment:
+    types: [created]
+  pull_request_review_comment:
+    types: [created]
+  issues:
+    types: [opened, assigned]
+  pull_request_review:
+    types: [submitted]
+
+jobs:
+  claude-code-action:
+    if: |
+      (github.event_name == 'issue_comment' && contains(github.event.comment.body, '@claude')) ||
+      (github.event_name == 'pull_request_review_comment' && contains(github.event.comment.body, '@claude')) ||
+      (github.event_name == 'pull_request_review' && contains(github.event.review.body, '@claude')) ||
+      (github.event_name == 'issues' && contains(github.event.issue.body, '@claude'))
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      pull-requests: read
+      issues: read
+      id-token: write
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 1
+
+      - name: Run Claude PR Action
+        uses: anthropics/claude-code-action@beta
+        with:
+          anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
+          timeout_minutes: "60"

{mcp_use-1.3.0 → mcp_use-1.3.2}/.github/workflows/publish.yml

@@ -1,4 +1,4 @@
-name: Check Version Bump and Publish to PyPI
+name: Release
 
 on:
   workflow_run:
@@ -66,14 +66,13 @@ jobs:
       - name: Create Release
         if: steps.check-version.outputs.is_new_version == 'true'
         id: create_release
-        uses: actions/create-release@v1
-        env:
-          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        uses: ncipollo/release-action@v1
         with:
-          tag_name: v${{ steps.check-version.outputs.new_version }}
-          release_name: Release v${{ steps.check-version.outputs.new_version }}
+          tag: v${{ steps.check-version.outputs.new_version }}
+          name: Release v${{ steps.check-version.outputs.new_version }}
           draft: false
           prerelease: false
+          generateReleaseNotes: false
 
       - name: Publish to PyPI
         if: steps.check-version.outputs.is_new_version == 'true'

mcp_use-1.3.2/.github/workflows/release-drafter.yml

@@ -0,0 +1,41 @@
+name: Release Drafter
+
+on:
+  push:
+    branches:
+      - main
+
+  # pull_request event is required only for autolabeler
+  pull_request:
+    # Only following types are handled by the action, but one can default to all as well
+    types: [opened, reopened, synchronize]
+  # pull_request_target event is required for autolabeler to support PRs from forks
+  # pull_request_target:
+  #   types: [opened, reopened, synchronize]
+
+permissions:
+  contents: read
+
+jobs:
+  update_release_draft:
+    permissions:
+      # write permission is required to create a github release
+      contents: write
+      # write permission is required for autolabeler
+      # otherwise, read permission is required at least
+      pull-requests: write
+    runs-on: ubuntu-latest
+    steps:
+      # (Optional) GitHub Enterprise requires GHE_HOST variable set
+      #- name: Set GHE_HOST
+      #  run: |
+      #    echo "GHE_HOST=${GITHUB_SERVER_URL##https:\/\/}" >> $GITHUB_ENV
+
+      # Drafts your next Release notes as Pull Requests are merged into "master"
+      - uses: release-drafter/release-drafter@v6
+        # (Optional) specify config name to use, relative to .github/. Default: release-drafter.yml
+        # with:
+        #   config-name: my-config.yml
+        #   disable-autolabeler: true
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

mcp_use-1.3.2/.github/workflows/transportstests.yml

@@ -0,0 +1,41 @@
+name: Transports
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  transports:
+    name: "${{ matrix.transport }}"
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        transport: [stdio, sse, streamableHttp]
+        python-version: ["3.11"]
+
+    steps:
+      - uses: actions/checkout@v3
+
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v4
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install uv
+        run: |
+          pip install uv
+
+      - name: Install dependencies
+        run: |
+          # Install project with dev and optional extras similar to unit tests environment
+          uv pip install --system .[dev,anthropic,openai,search,e2b]
+
+      - name: Lint with ruff
+        run: |
+          ruff check .
+
+      - name: Run integration tests for ${{ matrix.transport }} transport
+        run: |
+          pytest tests/integration/transports/${{ matrix.transport }}

mcp_use-1.3.2/.github/workflows/update-readme.yml

@@ -0,0 +1,110 @@
+name: Update README
+
+on:
+  # On manual launch
+  workflow_dispatch:
+  # Scheduled interval: Use CRON format https://crontab.guru/
+  schedule:
+    - cron: "0 0 * * 0" # Every sunday at midnight
+
+permissions: read-all
+
+concurrency:
+  group: ${{ github.ref }}-${{ github.workflow }}
+  cancel-in-progress: true
+
+jobs:
+  update-dependents:
+    name: Update GitHub Dependents Info
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+      pull-requests: write
+    steps:
+      # Git Checkout
+      - name: Checkout Code
+        uses: actions/checkout@v4
+        with:
+          token: ${{ secrets.GITHUB_TOKEN }}
+          fetch-depth: 0
+
+      # Setup Python
+      - name: Setup Python
+        uses: actions/setup-python@v4
+        with:
+          python-version: '3.11'
+
+      # Install github-dependents-info
+      - name: Install github-dependents-info
+        run: pip install -U github-dependents-info
+
+      # Generate dependents info
+      - name: Generate GitHub Dependents Info
+        run: |
+          # Get dependents data in JSON format
+          github-dependents-info --repo ${{ github.repository }} --sort stars --minstars 1 --json > dependents.json
+
+          # Extract total count and stars
+          TOTAL_REPOS=$(jq -r '.total_dependents_number' dependents.json)
+          PUBLIC_REPOS=$(jq -r '.public_dependents_number' dependents.json)
+          TOTAL_STARS=$(jq -r '[.all_public_dependent_repos[].stars] | add' dependents.json)
+
+          # Create the dependents table using HTML for full width
+          cat > dependents_table.md << 'EOF'
+          <table>
+            <tr>
+              <th width="400">Repository</th>
+              <th>Stars</th>
+            </tr>
+          EOF
+
+          # Add top repositories to the table (limit to top 10) with avatars
+          jq -r '.all_public_dependent_repos[:10] | .[] | "  <tr>\n    <td><img src=\"\(.img)\" width=\"20\" height=\"20\" style=\"vertical-align: middle; margin-right: 8px;\"> <a href=\"https://github.com/\(.name)\"><strong>\(.owner)/\(.repo_name)</strong></a></td>\n    <td>⭐ \(.stars)</td>\n  </tr>"' dependents.json >> dependents_table.md
+
+          # Close the table
+          echo "</table>" >> dependents_table.md
+
+          # Update README by replacing content between tags
+          awk '
+          BEGIN { in_section = 0 }
+          /<!-- gh-dependents-info-used-by-start -->/ {
+            print $0
+            print ""
+            system("cat dependents_table.md")
+            print ""
+            in_section = 1
+            next
+          }
+          /<!-- gh-dependents-info-used-by-end -->/ {
+            in_section = 0
+            print $0
+            next
+          }
+          !in_section { print }
+          ' README.md > README_updated.md
+
+          mv README_updated.md README.md
+          rm dependents_table.md dependents.json
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+
+      # Check for changes and commit directly
+      - name: Check for changes
+        id: changes
+        run: |
+          if git diff --quiet README.md; then
+            echo "has_changes=false" >> $GITHUB_OUTPUT
+          else
+            echo "has_changes=true" >> $GITHUB_OUTPUT
+          fi
+
+      - name: Create Pull Request
+        if: steps.changes.outputs.has_changes == 'true'
+        uses: peter-evans/create-pull-request@v6
+        with:
+          token: ${{ secrets.GITHUB_TOKEN }}
+          commit-message: "chore: update dependents info (automated)"
+          title: "chore: update dependents info (automated)"
+          body: "This PR updates the README with the latest dependents information."
+          branch: chore/update-dependents-info-${{ github.run_id }}
+          delete-branch: true

{mcp_use-1.3.0 → mcp_use-1.3.2}/.gitignore

@@ -122,3 +122,7 @@ dmypy.json
 
 # macOS
 .DS_Store
+
+# AI
+.cursor
+.claude

mcp_use-1.3.2/CLAUDE.md

@@ -0,0 +1,228 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## 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
+mypy mcp_use/
+
+# Run pre-commit hooks
+pre-commit 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
+
+### Unit Tests (`tests/unit/`)
+
+- Test individual components in isolation
+- Mock external dependencies
+- Focus on business logic and edge cases
+
+### Integration Tests (`tests/integration/`)
+
+- Test component interactions
+- Include real MCP server integrations
+- Organized by transport type (stdio, sse, websocket, etc.)
+- Custom test servers in `tests/integration/servers_for_testing/`
+
+### 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