mcp-use 1.2.13__tar.gz → 1.3.1__tar.gz

{mcp_use-1.2.13 → mcp_use-1.3.1}/.github/workflows/publish.yml

@@ -1,4 +1,4 @@
-name: Check Version Bump and Publish to PyPI
+name: Release
 
 on:
   workflow_run:
@@ -66,14 +66,64 @@ 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: true
+
+      - name: Update Docs Changelog
+        if: steps.check-version.outputs.is_new_version == 'true'
+        run: |
+          # Get the release notes from the created release
+          RELEASE_NOTES=$(gh release view v${{ steps.check-version.outputs.new_version }} --json body --jq '.body')
+
+          # Get current date in the required format
+          CURRENT_DATE=$(date +"%Y‑%m‑%d")
+
+          # Create the new changelog entry
+          NEW_ENTRY="<Update label=\"$CURRENT_DATE\">
+            ## v${{ steps.check-version.outputs.new_version }}
+            $RELEASE_NOTES
+          </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)
+          "
+
+          # Commit and push the updated changelog
+          git config --local user.email "action@github.com"
+          git config --local user.name "GitHub Action"
+          git add docs/changelog.mdx
+          git commit -m "docs: update changelog for v${{ steps.check-version.outputs.new_version }}" || echo "No changes to commit"
+          git push || echo "No changes to push"
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
 
       - name: Publish to PyPI
         if: steps.check-version.outputs.is_new_version == 'true'

mcp_use-1.3.1/.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.2.13 → mcp_use-1.3.1}/.github/workflows/unittests.yml

@@ -22,7 +22,7 @@ jobs:
       - name: Install dependencies
         run: |
           python -m pip install --upgrade pip
-          pip install .[dev,anthropic,openai,search]
+          pip install .[dev,anthropic,openai,search,e2b]
       - name: Lint with ruff
         run: |
           ruff check .

mcp_use-1.3.1/.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.2.13 → mcp_use-1.3.1}/.gitignore

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

mcp_use-1.3.1/CLAUDE.md

@@ -0,0 +1,204 @@
+# 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
+# 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 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