mcp-use 1.3.5__tar.gz → 1.3.7__tar.gz

mcp_use-1.3.7/.github/workflows/publish.yml

@@ -0,0 +1,81 @@
+name: Release
+
+on:
+  release:
+    types: [published]
+
+# Required for PyPI trusted publishing
+permissions:
+  id-token: write
+  contents: read
+
+jobs:
+  check-version-and-publish:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v3
+        with:
+          fetch-depth: 0
+
+      - name: Set up Python
+        uses: actions/setup-python@v4
+        with:
+          python-version: "3.11"
+
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install build twine wheel tomli
+
+      - name: Verify version match
+        id: check-version
+        run: |
+          # Extract current version from pyproject.toml
+          PYPROJECT_VERSION=$(python -c "
+          import tomli
+          with open('pyproject.toml', 'rb') as f:
+              data = tomli.load(f)
+          print(data['project']['version'])
+          ")
+
+          # Get release tag version (remove 'v' prefix if present)
+          RELEASE_VERSION="${{ github.event.release.tag_name }}"
+          RELEASE_VERSION=${RELEASE_VERSION#v}
+
+          echo "PyProject version: $PYPROJECT_VERSION"
+          echo "Release version: $RELEASE_VERSION"
+
+          if [ "$PYPROJECT_VERSION" = "$RELEASE_VERSION" ]; then
+            echo "✅ Versions match! Proceeding with PyPI publish"
+            echo "should_publish=true" >> $GITHUB_OUTPUT
+            echo "version=$PYPROJECT_VERSION" >> $GITHUB_OUTPUT
+          else
+            echo "❌ Version mismatch! PyProject: $PYPROJECT_VERSION, Release: $RELEASE_VERSION"
+            echo "should_publish=false" >> $GITHUB_OUTPUT
+            exit 1
+          fi
+
+      - name: Build package
+        if: steps.check-version.outputs.should_publish == 'true'
+        run: |
+          python -m build
+
+      - name: Check if already published to PyPI
+        if: steps.check-version.outputs.should_publish == 'true'
+        id: check-pypi
+        run: |
+          # Check if this version exists on PyPI
+          VERSION="${{ steps.check-version.outputs.version }}"
+          if pip index versions mcp-use | grep -q "Available versions: .*$VERSION"; then
+            echo "Version $VERSION already exists on PyPI"
+            echo "publish_needed=false" >> $GITHUB_OUTPUT
+          else
+            echo "Version $VERSION not found on PyPI, will publish"
+            echo "publish_needed=true" >> $GITHUB_OUTPUT
+          fi
+
+      - name: Publish to PyPI
+        if: steps.check-pypi.outputs.publish_needed == 'true'
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          password: ${{ secrets.PYPI_API_TOKEN }}

mcp_use-1.3.7/.github/workflows/tests.yml

@@ -0,0 +1,95 @@
+name: Tests
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v3
+      - name: Set up Python 3.11
+        uses: actions/setup-python@v4
+        with:
+          python-version: "3.11"
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install ruff
+      - name: Lint with ruff
+        run: |
+          ruff check .
+      - name: Format check with ruff
+        run: |
+          ruff format --check .
+
+  unit-tests:
+    needs: lint
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.11", "3.12"]
+    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 dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install .[dev,anthropic,openai,search,e2b]
+      - name: Test with pytest
+        run: |
+          pytest tests/unit
+
+  transport-tests:
+    needs: lint
+    name: "transport/${{ matrix.transport }}"
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        transport: [stdio, sse, streamableHttp]
+    steps:
+      - uses: actions/checkout@v3
+      - name: Set up Python 3.11
+        uses: actions/setup-python@v4
+        with:
+          python-version: "3.11"
+      - name: Install uv
+        run: |
+          pip install uv
+      - name: Install dependencies
+        run: |
+          uv pip install --system .[dev,anthropic,openai,search,e2b]
+      - name: Run integration tests for ${{ matrix.transport }} transport
+        run: |
+          pytest tests/integration/transports/${{ matrix.transport }}
+
+  primitive-tests:
+    needs: lint
+    name: "primitive/${{ matrix.primitive }}"
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        primitive: [sampling, tools, resources, prompts, elicitation]
+    steps:
+      - uses: actions/checkout@v3
+      - name: Set up Python 3.11
+        uses: actions/setup-python@v4
+        with:
+          python-version: "3.11"
+      - name: Install uv
+        run: |
+          pip install uv
+      - name: Install dependencies
+        run: |
+          uv pip install --system .[dev,anthropic,openai,search,e2b]
+      - name: Run integration tests for ${{ matrix.primitive }} primitive
+        run: |
+          pytest tests/integration/primitives/test_${{ matrix.primitive }}.py

{mcp_use-1.3.5 → mcp_use-1.3.7}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mcp-use
-Version: 1.3.5
+Version: 1.3.7
 Summary: MCP Library for LLMs
 Author-email: Pietro Zullo <pietro.zullo@gmail.com>
 License: MIT
@@ -28,7 +28,7 @@ Requires-Dist: langchain-anthropic; extra == 'anthropic'
 Provides-Extra: dev
 Requires-Dist: black>=23.9.0; extra == 'dev'
 Requires-Dist: fastapi; extra == 'dev'
-Requires-Dist: fastmcp==2.8.0; extra == 'dev'
+Requires-Dist: fastmcp==2.10.5; extra == 'dev'
 Requires-Dist: isort>=5.12.0; extra == 'dev'
 Requires-Dist: mypy>=1.5.0; extra == 'dev'
 Requires-Dist: pytest-asyncio>=0.21.0; extra == 'dev'
@@ -89,7 +89,12 @@ Description-Content-Type: text/markdown
 
 💬 Get started quickly - chat with your servers on our <b>hosted version</b>! [Try mcp-use chat (beta)](https://chat.mcp-use.com).
 
-# Features
+| Supports  | |
+| :--- | :--- |
+| **Primitives** | [![Tools](https://img.shields.io/github/actions/workflow/status/pietrozullo/mcp-use/tests.yml?job=primitive-tools&label=Tools&style=flat)](https://github.com/pietrozullo/mcp-use/actions/workflows/tests.yml) [![Resources](https://img.shields.io/github/actions/workflow/status/pietrozullo/mcp-use/tests.yml?job=primitive-resources&label=Resources&style=flat)](https://github.com/pietrozullo/mcp-use/actions/workflows/tests.yml) [![Prompts](https://img.shields.io/github/actions/workflow/status/pietrozullo/mcp-use/tests.yml?job=primitive-prompts&label=Prompts&style=flat)](https://github.com/pietrozullo/mcp-use/actions/workflows/tests.yml) [![Sampling](https://img.shields.io/github/actions/workflow/status/pietrozullo/mcp-use/tests.yml?job=primitive-sampling&label=Sampling&style=flat)](https://github.com/pietrozullo/mcp-use/actions/workflows/tests.yml) [![Elicitation](https://img.shields.io/github/actions/workflow/status/pietrozullo/mcp-use/tests.yml?job=primitive-elicitation&label=Elicitation&style=flat)](https://github.com/pietrozullo/mcp-use/actions/workflows/tests.yml) |
+| **Transports** | [![Stdio](https://img.shields.io/github/actions/workflow/status/pietrozullo/mcp-use/tests.yml?job=transport-stdio&label=Stdio&style=flat)](https://github.com/pietrozullo/mcp-use/actions/workflows/tests.yml) [![SSE](https://img.shields.io/github/actions/workflow/status/pietrozullo/mcp-use/tests.yml?job=transport-sse&label=SSE&style=flat)](https://github.com/pietrozullo/mcp-use/actions/workflows/tests.yml) [![Streamable HTTP](https://img.shields.io/github/actions/workflow/status/pietrozullo/mcp-use/tests.yml?job=transport-streamableHttp&label=Streamable%20HTTP&style=flat)](https://github.com/pietrozullo/mcp-use/actions/workflows/tests.yml) |
+
+## Features
 
 <table>
   <tr>

{mcp_use-1.3.5 → mcp_use-1.3.7}/README.md

@@ -44,7 +44,12 @@
 
 💬 Get started quickly - chat with your servers on our <b>hosted version</b>! [Try mcp-use chat (beta)](https://chat.mcp-use.com).
 
-# Features
+| Supports  | |
+| :--- | :--- |
+| **Primitives** | [![Tools](https://img.shields.io/github/actions/workflow/status/pietrozullo/mcp-use/tests.yml?job=primitive-tools&label=Tools&style=flat)](https://github.com/pietrozullo/mcp-use/actions/workflows/tests.yml) [![Resources](https://img.shields.io/github/actions/workflow/status/pietrozullo/mcp-use/tests.yml?job=primitive-resources&label=Resources&style=flat)](https://github.com/pietrozullo/mcp-use/actions/workflows/tests.yml) [![Prompts](https://img.shields.io/github/actions/workflow/status/pietrozullo/mcp-use/tests.yml?job=primitive-prompts&label=Prompts&style=flat)](https://github.com/pietrozullo/mcp-use/actions/workflows/tests.yml) [![Sampling](https://img.shields.io/github/actions/workflow/status/pietrozullo/mcp-use/tests.yml?job=primitive-sampling&label=Sampling&style=flat)](https://github.com/pietrozullo/mcp-use/actions/workflows/tests.yml) [![Elicitation](https://img.shields.io/github/actions/workflow/status/pietrozullo/mcp-use/tests.yml?job=primitive-elicitation&label=Elicitation&style=flat)](https://github.com/pietrozullo/mcp-use/actions/workflows/tests.yml) |
+| **Transports** | [![Stdio](https://img.shields.io/github/actions/workflow/status/pietrozullo/mcp-use/tests.yml?job=transport-stdio&label=Stdio&style=flat)](https://github.com/pietrozullo/mcp-use/actions/workflows/tests.yml) [![SSE](https://img.shields.io/github/actions/workflow/status/pietrozullo/mcp-use/tests.yml?job=transport-sse&label=SSE&style=flat)](https://github.com/pietrozullo/mcp-use/actions/workflows/tests.yml) [![Streamable HTTP](https://img.shields.io/github/actions/workflow/status/pietrozullo/mcp-use/tests.yml?job=transport-streamableHttp&label=Streamable%20HTTP&style=flat)](https://github.com/pietrozullo/mcp-use/actions/workflows/tests.yml) |
+
+## Features
 
 <table>
   <tr>

{mcp_use-1.3.5 → mcp_use-1.3.7}/docs/docs.json

@@ -8,10 +8,32 @@
     "dark": "#000000"
   },
   "favicon": "/favicon.svg",
+  "contextual": {
+    "options": [
+      "copy",
+      "view",
+      "chatgpt",
+      "claude"
+    ]
+  },
   "icons": {
     "library": "lucide"
   },
   "navigation": {
+    "global": {
+      "anchors": [
+        {
+          "anchor": "Website",
+          "href": "https://mcp-use.com",
+          "icon": "globe"
+        },
+        {
+          "anchor": "Forum",
+          "href": "https://discord.gg/XkNkSkMz3V",
+          "icon": "discord"
+        }
+      ]
+    },
     "tabs": [
       {
         "tab": "Documentation",
@@ -30,7 +52,15 @@
             "pages": [
               "essentials/configuration",
               "essentials/client-configuration",
-              "essentials/connection-types"
+              {
+                "group": "Client Features",
+                "icon": "list-plus",
+                "pages": [
+                  "essentials/connection-types",
+                  "essentials/sampling",
+                  "essentials/elicitation"
+                ]
+              }
             ]
           },
           {
@@ -196,14 +226,6 @@
       }
     ]
   },
-  "contextual": {
-    "options": [
-      "copy",
-      "view",
-      "chatgpt",
-      "claude"
-    ]
-  },
   "seo": {
     "metatags": {
       "charset": "UTF-8",

mcp_use-1.3.7/docs/essentials/elicitation.mdx

@@ -0,0 +1,363 @@
+---
+title: "Elicitation"
+description: "Enable user input requests for MCP tools"
+icon: "user-question"
+---
+
+# Elicitation
+
+<Info>
+Elicitation allows MCP tools to request additional information from users during their execution.
+</Info>
+
+## Configuration
+
+To enable elicitation, provide an `elicitation_callback` function when initializing the MCPClient:
+
+```python
+from mcp_use.client import MCPClient
+from mcp.client.session import RequestContext
+from mcp.types import ElicitRequestParams, ElicitResult
+
+async def elicitation_callback(
+    context: RequestContext,
+    params: ElicitRequestParams
+) -> ElicitResult:
+    """
+    Your elicitation callback implementation.
+    This function receives a request for user input and returns the user's response.
+    """
+    # Display the message to the user and collect their input
+    print(f"Server requests: {params.message}")
+
+    # Example: Get user input (replace with your UI logic)
+    if hasattr(params, 'requestedSchema'):
+        # Handle structured input based on the schema
+        user_input = await collect_structured_input(params.requestedSchema)
+    else:
+        # Handle simple text input
+        user_input = input("Please provide your response: ")
+
+    # Return the result
+    return ElicitResult(
+        action="accept",  # or "decline" or "cancel"
+        content=user_input
+    )
+
+# Initialize client with elicitation support
+client = MCPClient(
+    config="config.json",
+    elicitation_callback=elicitation_callback
+)
+```
+
+## Handler Parameters
+
+The elicitation handler receives two parameters:
+
+### Elicitation Handler Parameters
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| **context** | `RequestContext` | Request context containing metadata about the elicitation request |
+| **params** | `ElicitRequestParams` | The MCP elicitation request parameters containing the message and optional schema |
+
+#### ElicitRequestParams Structure
+
+| Field | Type | Description |
+|-------|------|-------------|
+| **message** | `str` | The prompt message to display to the user |
+| **requestedSchema** | `dict \| None` | Optional JSON schema defining the expected response structure |
+
+### Response Structure
+
+The handler must return an `ElicitResult` object that specifies how the user responded:
+
+#### ElicitResult Structure
+
+| Field | Type | Description |
+|-------|------|-------------|
+| **action** | `Literal['accept', 'decline', 'cancel']` | How the user responded to the elicitation request |
+| **content** | `dict \| str \| None` | The user's input data (required for "accept", omitted for "decline"/"cancel") |
+
+#### Action Types:
+
+- **accept**: User provided valid input - include their data in the `content` field
+- **decline**: User chose not to provide the requested information - omit `content`
+- **cancel**: User cancelled the entire operation - omit `content`
+
+### Example Parameter Usage
+
+```python
+async def detailed_elicitation_callback(
+    context: RequestContext,
+    params: ElicitRequestParams
+) -> ElicitResult:
+    """Example showing how to use all parameters."""
+
+    # Access the user message
+    user_message = params.message
+    print(f"Request: {user_message}")
+
+    # Check if schema is provided for structured data
+    schema = getattr(params, 'requestedSchema', None)
+
+    if schema:
+        # Handle structured input
+        schema_type = schema.get('type')
+        properties = schema.get('properties', {})
+        required_fields = schema.get('required', [])
+
+        print(f"Expecting {schema_type} with fields: {list(properties.keys())}")
+        print(f"Required fields: {required_fields}")
+
+        # Collect structured data
+        user_data = {}
+        for field_name, field_def in properties.items():
+            field_type = field_def.get('type', 'string')
+            description = field_def.get('description', '')
+
+            prompt = f"Enter {field_name}"
+            if description:
+                prompt += f" ({description})"
+            prompt += ": "
+
+            value = input(prompt)
+
+            # Basic type conversion
+            if field_type == 'number':
+                value = float(value) if value else None
+            elif field_type == 'integer':
+                value = int(value) if value else None
+            elif field_type == 'boolean':
+                value = value.lower() in ('true', '1', 'yes') if value else None
+
+            user_data[field_name] = value
+
+        # Validate required fields
+        missing = [f for f in required_fields if not user_data.get(f)]
+        if missing:
+            print(f"Missing required fields: {missing}")
+            return ElicitResult(action="cancel")
+
+        return ElicitResult(action="accept", content=user_data)
+
+    else:
+        # Handle simple text input
+        response = input(f"{user_message}: ")
+        if not response:
+            return ElicitResult(action="cancel")
+
+        return ElicitResult(action="accept", content=response)
+```
+
+## Response Actions
+
+Elicitation responses use a three-action model to clearly distinguish between different user intentions:
+
+### Accept
+User explicitly approved and submitted data:
+```python
+return ElicitResult(
+    action="accept",
+    content={"name": "John Doe", "email": "john@example.com"}
+)
+```
+
+### Decline
+User explicitly declined the request:
+```python
+return ElicitResult(
+    action="decline"
+    # content field is typically omitted
+)
+```
+
+### Cancel
+User dismissed without making an explicit choice:
+```python
+return ElicitResult(
+    action="cancel"
+    # content field is typically omitted
+)
+```
+
+## Structured Data Requests
+
+MCP tools can request structured data using JSON schemas. The schema defines the expected format and validation rules:
+
+```python
+async def advanced_elicitation_callback(
+    context: RequestContext,
+    params: ElicitRequestParams
+) -> ElicitResult:
+    """Handle structured data requests with validation."""
+
+    # Check if a schema is provided
+    if hasattr(params, 'requestedSchema') and params.requestedSchema:
+        schema = params.requestedSchema
+
+        # Example: Handle different schema types
+        if schema.get('type') == 'object':
+            properties = schema.get('properties', {})
+            required_fields = schema.get('required', [])
+
+            # Collect data for each property
+            user_data = {}
+            for field_name, field_schema in properties.items():
+                field_type = field_schema.get('type', 'string')
+                field_description = field_schema.get('description', '')
+
+                print(f"{field_name} ({field_type}): {field_description}")
+
+                # Collect input based on field type
+                if field_type == 'string':
+                    value = input(f"Enter {field_name}: ")
+                elif field_type == 'number':
+                    value = float(input(f"Enter {field_name}: "))
+                elif field_type == 'boolean':
+                    value = input(f"Enter {field_name} (true/false): ").lower() == 'true'
+                elif field_type == 'integer':
+                    value = int(input(f"Enter {field_name}: "))
+                else:
+                    value = input(f"Enter {field_name}: ")
+
+                user_data[field_name] = value
+
+            # Basic validation for required fields
+            missing_fields = [field for field in required_fields if field not in user_data or not user_data[field]]
+            if missing_fields:
+                print(f"Missing required fields: {missing_fields}")
+                return ElicitResult(action="cancel")
+
+            return ElicitResult(action="accept", content=user_data)
+
+    # Fallback to simple text input
+    response = input(f"{params.message}: ")
+    return ElicitResult(action="accept", content=response)
+```
+
+## Creating Elicitation-Enabled Tools
+
+When building MCP servers, tools can request user input using the context parameter:
+
+```python
+from fastmcp import Context, FastMCP
+
+mcp = FastMCP(name="MyServer")
+
+@mcp.tool
+async def purchase_item(ctx: Context) -> str:
+    """Purchase an item with user-provided details."""
+
+    # Define the schema for purchase information
+    purchase_schema = {
+        "type": "object",
+        "properties": {
+            "quantity": {
+                "type": "number",
+                "minimum": 1,
+                "description": "Number of items to purchase"
+            },
+            "unit": {
+                "type": "string",
+                "enum": ["kg", "lbs", "pieces"],
+                "description": "Unit of measurement"
+            },
+            "item_name": {
+                "type": "string",
+                "description": "Name of the item to purchase"
+            }
+        },
+        "required": ["quantity", "unit", "item_name"]
+    }
+
+    # Request purchase details from the user
+    result = await ctx.elicit(
+        message="Please provide purchase details",
+        response_type=purchase_schema
+    )
+
+    # Handle different response actions
+    if result.action == "accept":
+        data = result.data
+        return f"Purchasing {data['quantity']} {data['unit']} of {data['item_name']}"
+    elif result.action == "decline":
+        return "Purchase declined by user"
+    else:
+        return "Purchase cancelled"
+
+@mcp.tool
+async def collect_feedback(ctx: Context) -> str:
+    """Collect user feedback with a simple text request."""
+
+    result = await ctx.elicit(
+        message="Please provide your feedback about our service"
+    )
+
+    if result.action == "accept":
+        return f"Thank you for your feedback: {result.data}"
+    else:
+        return "No feedback provided"
+```
+
+## Integration with MCPAgent
+
+When using elicitation with MCPAgent, the elicitation callback is automatically used during tool execution:
+
+```python
+import asyncio
+from mcp_use import MCPAgent, MCPClient
+from langchain_openai import ChatOpenAI
+
+async def main():
+    # Define elicitation callback
+    async def handle_user_input(ctx, params):
+        # Your UI logic here - this example uses simple input
+        print(f"\n🤖 Server Request: {params.message}")
+
+        if hasattr(params, 'requestedSchema') and params.requestedSchema:
+            # Handle structured input
+            schema = params.requestedSchema
+            if schema.get('type') == 'object':
+                data = {}
+                for field, field_schema in schema.get('properties', {}).items():
+                    value = input(f"Enter {field}: ")
+                    data[field] = value
+                return ElicitResult(action="accept", content=data)
+
+        # Simple text input
+        response = input("Your response: ")
+        return ElicitResult(action="accept", content=response)
+
+    # Create client with elicitation support
+    client = MCPClient.from_config_file(
+        "config.json",
+        elicitation_callback=handle_user_input
+    )
+
+    # Create agent
+    llm = ChatOpenAI(model="gpt-4")
+    agent = MCPAgent(llm=llm, client=client)
+
+    # Run agent - tools can now request user input
+    result = await agent.run("Help me purchase some items from the store")
+    print(result)
+
+if __name__ == "__main__":
+    asyncio.run(main())
+```
+
+## Error Handling
+
+If no elicitation callback is provided but a tool requests user input:
+
+```python
+# Without elicitation callback
+client = MCPClient(config="config.json")  # No elicitation_callback
+
+# Tool that requires elicitation will return an error
+session = client.get_session("server_name")
+result = await session.connector.call_tool("purchase_item", {})
+# This will fail because no elicitation callback is configured
+```