iflow-mcp_janspoerer-mcp_browser_use 0.1.0__py3-none-any.whl

mcp_browser_use/tools/interaction.py

@@ -0,0 +1,323 @@
+"""Element interaction tool implementations."""
+
+import json
+import time
+from typing import Optional
+from selenium.common.exceptions import (
+    TimeoutException,
+    StaleElementReferenceException,
+    ElementClickInterceptedException,
+)
+from ..context import get_context
+from ..utils.diagnostics import collect_diagnostics
+from ..actions.elements import find_element, _wait_clickable_element
+from ..actions.navigation import _wait_document_ready
+from ..actions.screenshots import _make_page_snapshot
+from ..utils.retry import retry_op
+
+
+async def fill_text(
+    selector,
+    text,
+    selector_type,
+    clear_first,
+    timeout,
+    iframe_selector,
+    iframe_selector_type,
+    shadow_root_selector,
+    shadow_root_selector_type,
+):
+    """Fill text into an element."""
+    ctx = get_context()
+
+    try:
+        el = retry_op(fn=lambda: find_element(
+            driver=ctx.driver,
+            selector=selector,
+            selector_type=selector_type,
+            timeout=int(timeout),
+            visible_only=True,
+            iframe_selector=iframe_selector,
+            iframe_selector_type=iframe_selector_type,
+            shadow_root_selector=shadow_root_selector,
+            shadow_root_selector_type=shadow_root_selector_type,
+            stay_in_context=True,
+        ))
+
+        if clear_first:
+            try:
+                el.clear()
+            except Exception:
+                pass
+        el.send_keys(text)
+        _wait_document_ready(timeout=5.0)
+
+        snapshot = _make_page_snapshot()
+        return json.dumps({"ok": True, "action": "fill_text", "selector": selector, "snapshot": snapshot})
+
+    except Exception as e:
+        diag = collect_diagnostics(driver=ctx.driver, exc=e, config=ctx.config)
+        snapshot = _make_page_snapshot()
+        return json.dumps({"ok": False, "error": str(e), "diagnostics": diag, "snapshot": snapshot})
+
+    finally:
+        try:
+            if ctx.is_driver_initialized():
+                ctx.driver.switch_to.default_content()
+        except Exception:
+            pass
+
+async def click_element(
+    selector,
+    selector_type,
+    timeout,
+    force_js,
+    iframe_selector,
+    iframe_selector_type,
+    shadow_root_selector,
+    shadow_root_selector_type,
+) -> str:
+    """Click an element."""
+    ctx = get_context()
+
+    try:
+        el = retry_op(fn=lambda: find_element(
+            driver=ctx.driver,
+            selector=selector,
+            selector_type=selector_type,
+            timeout=int(timeout),
+            visible_only=True,
+            iframe_selector=iframe_selector,
+            iframe_selector_type=iframe_selector_type,
+            shadow_root_selector=shadow_root_selector,
+            shadow_root_selector_type=shadow_root_selector_type,
+            stay_in_context=True,
+        ))
+
+        _wait_clickable_element(el=el, driver=ctx.driver, timeout=timeout)
+
+        if force_js:
+            ctx.driver.execute_script("arguments[0].click();", el)
+        else:
+            try:
+                el.click()
+            except (ElementClickInterceptedException, StaleElementReferenceException):
+                el = retry_op(fn=lambda: find_element(
+                    driver=ctx.driver,
+                    selector=selector,
+                    selector_type=selector_type,
+                    timeout=int(timeout),
+                    visible_only=True,
+                    iframe_selector=iframe_selector,
+                    iframe_selector_type=iframe_selector_type,
+                    shadow_root_selector=shadow_root_selector,
+                    shadow_root_selector_type=shadow_root_selector_type,
+                    stay_in_context=True,
+                ))
+                ctx.driver.execute_script("arguments[0].click();", el)
+
+        _wait_document_ready(timeout=10.0)
+
+        snapshot = _make_page_snapshot()
+        return json.dumps({
+            "ok": True,
+            "action": "click",
+            "selector": selector,
+            "selector_type": selector_type,
+            "snapshot": snapshot,
+        })
+
+    except TimeoutException:
+        snapshot = _make_page_snapshot()
+        return json.dumps({
+            "ok": False,
+            "error": "timeout",
+            "selector": selector,
+            "selector_type": selector_type,
+            "snapshot": snapshot,
+        })
+
+    except Exception as e:
+        diag = collect_diagnostics(driver=ctx.driver, exc=e, config=ctx.config)
+        snapshot = _make_page_snapshot()
+        return json.dumps({"ok": False, "error": str(e), "diagnostics": diag, "snapshot": snapshot})
+
+    finally:
+        try:
+            if ctx.is_driver_initialized():
+                ctx.driver.switch_to.default_content()
+        except Exception:
+            pass
+
+
+async def send_keys(
+    key: str,
+    selector: Optional[str] = None,
+    selector_type: str = "css",
+    timeout: float = 10.0,
+) -> str:
+    """
+    Send keyboard keys to an element or to the active element.
+
+    Args:
+        key: Key to send (ENTER, TAB, ESCAPE, ARROW_DOWN, etc.)
+        selector: Optional CSS selector, XPath, or ID of element to send keys to
+        selector_type: Type of selector (css, xpath, id)
+        timeout: Maximum time to wait for element in seconds
+
+    Returns:
+        JSON string with ok status, action, key sent, and page snapshot
+    """
+    ctx = get_context()
+
+    try:
+        from selenium.webdriver.common.keys import Keys
+
+        if not ctx.is_driver_initialized():
+            return json.dumps({"ok": False, "error": "driver_not_initialized"})
+
+        # Map string key names to Selenium Keys
+        key_mapping = {
+            "ENTER": Keys.ENTER,
+            "RETURN": Keys.RETURN,
+            "TAB": Keys.TAB,
+            "ESCAPE": Keys.ESCAPE,
+            "ESC": Keys.ESCAPE,
+            "SPACE": Keys.SPACE,
+            "BACKSPACE": Keys.BACKSPACE,
+            "DELETE": Keys.DELETE,
+            "ARROW_UP": Keys.ARROW_UP,
+            "ARROW_DOWN": Keys.ARROW_DOWN,
+            "ARROW_LEFT": Keys.ARROW_LEFT,
+            "ARROW_RIGHT": Keys.ARROW_RIGHT,
+            "PAGE_UP": Keys.PAGE_UP,
+            "PAGE_DOWN": Keys.PAGE_DOWN,
+            "HOME": Keys.HOME,
+            "END": Keys.END,
+            "F1": Keys.F1,
+            "F2": Keys.F2,
+            "F3": Keys.F3,
+            "F4": Keys.F4,
+            "F5": Keys.F5,
+            "F6": Keys.F6,
+            "F7": Keys.F7,
+            "F8": Keys.F8,
+            "F9": Keys.F9,
+            "F10": Keys.F10,
+            "F11": Keys.F11,
+            "F12": Keys.F12,
+        }
+
+        selenium_key = key_mapping.get(key.upper(), key)
+
+        if selector:
+            # Send keys to specific element
+            el = retry_op(fn=lambda: find_element(
+                driver=ctx.driver,
+                selector=selector,
+                selector_type=selector_type,
+                timeout=int(timeout),
+                visible_only=True,
+            ))
+            el.send_keys(selenium_key)
+        else:
+            # Send keys to active element (usually body or focused element)
+            from selenium.webdriver.common.action_chains import ActionChains
+            ActionChains(ctx.driver).send_keys(selenium_key).perform()
+
+        time.sleep(0.2)  # Brief pause
+        snapshot = _make_page_snapshot()
+
+        return json.dumps({
+            "ok": True,
+            "action": "send_keys",
+            "key": key,
+            "selector": selector,
+            "snapshot": snapshot,
+        })
+
+    except Exception as e:
+        diag = collect_diagnostics(driver=ctx.driver, exc=e, config=ctx.config)
+        snapshot = _make_page_snapshot()
+        return json.dumps({"ok": False, "error": str(e), "diagnostics": diag, "snapshot": snapshot})
+
+async def wait_for_element(
+    selector: str,
+    selector_type: str = "css",
+    timeout: float = 10.0,
+    condition: str = "visible",
+    iframe_selector: Optional[str] = None,
+    iframe_selector_type: str = "css",
+) -> str:
+    """
+    Wait for an element to meet a specific condition.
+
+    Args:
+        selector: CSS selector, XPath, or ID of the element
+        selector_type: Type of selector (css, xpath, id)
+        timeout: Maximum time to wait in seconds
+        condition: Condition to wait for - 'present', 'visible', or 'clickable'
+        iframe_selector: Optional selector for iframe containing the element
+        iframe_selector_type: Selector type for the iframe
+
+    Returns:
+        JSON string with ok status, element found status, and page snapshot
+    """
+    ctx = get_context()
+
+    try:
+        if not ctx.is_driver_initialized():
+            return json.dumps({"ok": False, "error": "driver_not_initialized"})
+
+        visible_only = condition in ("visible", "clickable")
+
+        el = find_element(
+            driver=ctx.driver,
+            selector=selector,
+            selector_type=selector_type,
+            timeout=int(timeout),
+            visible_only=visible_only,
+            iframe_selector=iframe_selector,
+            iframe_selector_type=iframe_selector_type,
+        )
+
+        if condition == "clickable":
+            _wait_clickable_element(el=el, driver=ctx.driver, timeout=timeout)
+
+        snapshot = _make_page_snapshot()
+        return json.dumps({
+            "ok": True,
+            "action": "wait_for_element",
+            "selector": selector,
+            "condition": condition,
+            "found": True,
+            "snapshot": snapshot,
+            "message": f"Element '{selector}' is now {condition}"
+        })
+
+    except TimeoutException:
+        snapshot = _make_page_snapshot()
+        return json.dumps({
+            "ok": False,
+            "error": "timeout",
+            "selector": selector,
+            "condition": condition,
+            "found": False,
+            "snapshot": snapshot,
+            "message": f"Element '{selector}' did not become {condition} within {timeout}s"
+        })
+
+    except Exception as e:
+        diag = collect_diagnostics(driver=ctx.driver, exc=e, config=ctx.config)
+        snapshot = _make_page_snapshot()
+        return json.dumps({"ok": False, "error": str(e), "diagnostics": diag, "snapshot": snapshot})
+
+    finally:
+        try:
+            if ctx.is_driver_initialized():
+                ctx.driver.switch_to.default_content()
+        except Exception:
+            pass
+
+
+__all__ = ['fill_text', 'click_element', 'send_keys', 'wait_for_element']

mcp_browser_use/tools/navigation.py

@@ -0,0 +1,84 @@
+"""Navigation and scrolling tool implementations."""
+
+import json
+import time
+from selenium.webdriver.support.ui import WebDriverWait
+from ..context import get_context
+from ..utils.diagnostics import collect_diagnostics
+from ..actions.navigation import _wait_document_ready
+from ..actions.screenshots import _make_page_snapshot
+
+
+async def navigate_to_url(
+    url: str,
+    wait_for: str = "load",     # "load" or "complete"
+    timeout_sec: int = 30,
+) -> str:
+    """Navigate to a URL and return JSON with a raw snapshot."""
+    ctx = get_context()
+
+    try:
+        if not ctx.is_driver_initialized():
+            return json.dumps({"ok": False, "error": "driver_not_initialized"})
+
+        ctx.driver.get(url)
+
+        # DOM readiness
+        try:
+            _wait_document_ready(timeout=min(max(timeout_sec, 0), 60))
+        except Exception:
+            pass
+
+        if (wait_for or "load").lower() == "complete":
+            try:
+                WebDriverWait(ctx.driver, timeout_sec).until(
+                    lambda d: d.execute_script("return document.readyState") == "complete"
+                )
+            except Exception:
+                pass
+
+        snapshot = _make_page_snapshot()
+        return json.dumps({"ok": True, "action": "navigate", "url": url, "snapshot": snapshot})
+
+    except Exception as e:
+        diag = collect_diagnostics(driver=ctx.driver, exc=e, config=ctx.config)
+        snapshot = _make_page_snapshot()
+        return json.dumps({"ok": False, "error": str(e), "diagnostics": diag, "snapshot": snapshot})
+
+
+async def scroll(x: int, y: int) -> str:
+    """
+    Scroll the page by the specified pixel amounts.
+
+    Args:
+        x: Horizontal scroll amount in pixels (positive = right, negative = left)
+        y: Vertical scroll amount in pixels (positive = down, negative = up)
+
+    Returns:
+        JSON string with ok status, action, scroll amounts, and page snapshot
+    """
+    ctx = get_context()
+
+    try:
+        if not ctx.is_driver_initialized():
+            return json.dumps({"ok": False, "error": "driver_not_initialized"})
+
+        ctx.driver.execute_script(f"window.scrollBy({int(x)}, {int(y)});")
+        time.sleep(0.3)  # Brief pause to allow scroll to complete
+
+        snapshot = _make_page_snapshot()
+        return json.dumps({
+            "ok": True,
+            "action": "scroll",
+            "x": int(x),
+            "y": int(y),
+            "snapshot": snapshot,
+        })
+
+    except Exception as e:
+        diag = collect_diagnostics(driver=ctx.driver, exc=e, config=ctx.config)
+        snapshot = _make_page_snapshot()
+        return json.dumps({"ok": False, "error": str(e), "diagnostics": diag, "snapshot": snapshot})
+
+
+__all__ = ['navigate_to_url', 'scroll']

mcp_browser_use/tools/screenshots.py

@@ -0,0 +1,116 @@
+"""Screenshot capture tool implementations."""
+
+import io
+import json
+import base64
+from typing import Optional
+from ..context import get_context
+from ..utils.diagnostics import collect_diagnostics
+from ..actions.screenshots import _make_page_snapshot
+
+
+async def take_screenshot(screenshot_path, return_base64, return_snapshot, thumbnail_width=None) -> str:
+    """
+    Take a screenshot of the current page.
+
+    Args:
+        screenshot_path: Optional path to save the full screenshot
+        return_base64: Whether to return base64 encoded image
+        return_snapshot: Whether to return page HTML snapshot
+        thumbnail_width: Optional width in pixels for thumbnail (requires return_base64=True)
+                        Default: 200px if return_base64 is True (accounts for MCP overhead)
+
+    Returns:
+        JSON string with ok status, saved path, optional base64 thumbnail, and snapshot
+    """
+    ctx = get_context()
+
+    try:
+        if not ctx.is_driver_initialized():
+            return json.dumps({"ok": False, "error": "driver_not_initialized"})
+
+        # Get full screenshot
+        png_bytes = ctx.driver.get_screenshot_as_png()
+
+        # Save full screenshot to disk if path provided
+        if screenshot_path:
+            with open(screenshot_path, "wb") as f:
+                f.write(png_bytes)
+
+        payload = {"ok": True, "saved_to": screenshot_path}
+
+        # Handle base64 return with thumbnail
+        if return_base64:
+            # Default thumbnail width to 200px to account for MCP protocol overhead (~3x)
+            # 200px thumbnail = ~6K tokens, plus MCP overhead = ~18K total (under 25K limit)
+            if thumbnail_width is None:
+                thumbnail_width = 200
+
+            # Validate thumbnail width
+            if thumbnail_width < 50:
+                return json.dumps({
+                    "ok": False,
+                    "error": "thumbnail_width_too_small",
+                    "message": "thumbnail_width must be at least 50 pixels",
+                    "min_width": 50,
+                })
+
+            try:
+                from PIL import Image
+            except ImportError:
+                return json.dumps({
+                    "ok": False,
+                    "error": "pillow_not_installed",
+                    "message": "Pillow is required for thumbnails. Install with: pip install Pillow",
+                })
+
+            try:
+                # Create thumbnail
+                img = Image.open(io.BytesIO(png_bytes))
+                original_size = img.size
+
+                # Calculate thumbnail dimensions maintaining aspect ratio
+                aspect_ratio = img.height / img.width
+                thumb_height = int(thumbnail_width * aspect_ratio)
+
+                # Resize to thumbnail
+                img.thumbnail((thumbnail_width, thumb_height), Image.Resampling.LANCZOS)
+
+                # Encode thumbnail to base64
+                thumb_buffer = io.BytesIO()
+                img.save(thumb_buffer, format='PNG', optimize=True)
+                thumb_b64 = base64.b64encode(thumb_buffer.getvalue()).decode('utf-8')
+
+                payload["base64"] = thumb_b64
+                payload["thumbnail_width"] = thumbnail_width
+                payload["thumbnail_height"] = img.height
+                payload["original_width"] = original_size[0]
+                payload["original_height"] = original_size[1]
+                payload["message"] = f"Screenshot saved (thumbnail: {thumbnail_width}x{img.height}px, original: {original_size[0]}x{original_size[1]}px)"
+
+            except Exception as thumb_error:
+                # Thumbnail failed but full screenshot was saved
+                return json.dumps({
+                    "ok": True,
+                    "saved_to": screenshot_path,
+                    "thumbnail_error": str(thumb_error),
+                    "message": "Full screenshot saved, but thumbnail generation failed"
+                })
+
+        if return_snapshot:
+            payload["snapshot"] = _make_page_snapshot()
+        else:
+            payload["snapshot"] = "Omitted to save tokens."
+
+        return json.dumps(payload)
+
+    except Exception as e:
+        diag = collect_diagnostics(ctx.driver, e, ctx.config)
+        if return_snapshot:
+            snapshot = _make_page_snapshot()
+        else:
+            snapshot = "Omitted to save tokens."
+        return json.dumps({"ok": False, "error": str(e), "diagnostics": diag, "snapshot": snapshot})
+
+
+__all__ = ['take_screenshot']

mcp_browser_use/utils/__init__.py

@@ -0,0 +1 @@
+"""Utility functions and helpers."""

mcp_browser_use/utils/diagnostics.py

@@ -0,0 +1,85 @@
+"""Diagnostics and debugging information utility functions."""
+
+import sys
+import platform
+from typing import Optional
+from selenium import webdriver
+import selenium
+
+from ..context import get_context
+from ..browser.chrome_executable import get_chrome_binary_for_platform
+
+
+def collect_diagnostics(
+    driver: Optional[webdriver.Chrome] = None,
+    exc: Optional[Exception] = None,
+    config: Optional[dict] = None
+) -> str:
+    """
+    Collect diagnostic information about the browser, driver, and environment.
+
+    Args:
+        driver: Selenium WebDriver instance (if None, will try to get from context)
+        exc: Exception that occurred (can be None)
+        config: Configuration dictionary (if None, will get from context)
+
+    Returns:
+        str: Formatted diagnostic information
+    """
+    ctx = get_context()
+
+    # Use context if parameters not provided
+    if driver is None:
+        driver = ctx.driver
+
+    if config is None:
+        config = ctx.config
+
+    # Get Chrome binary path
+    chrome_path = config.get('chrome_path')
+    if not chrome_path:
+        try:
+            chrome_path = get_chrome_binary_for_platform()
+        except Exception:
+            chrome_path = '<unknown>'
+
+    parts = [
+        f"OS                : {platform.system()} {platform.release()}",
+        f"Python            : {sys.version.split()[0]}",
+        f"Selenium          : {getattr(selenium, '__version__', '?')}",
+        f"User-data dir     : {config.get('user_data_dir')}",
+        f"Profile name      : {config.get('profile_name')}",
+        f"Chrome binary     : {chrome_path}",
+        f"Driver initialized: {driver is not None}",
+        f"Debugger address  : {ctx.get_debugger_address() or '<none>'}",
+        f"Window ready      : {ctx.is_window_ready()}",
+    ]
+
+    if driver:
+        try:
+            ver = driver.execute_cdp_cmd("Browser.getVersion", {}) or {}
+            parts.append(f"Browser version   : {ver.get('product', '<unknown>')}")
+        except Exception:
+            parts.append("Browser version   : <unknown>")
+
+        cap = getattr(driver, "capabilities", None) or {}
+        drv_ver = cap.get("chromedriverVersion") or cap.get("browserVersion") or "<unknown>"
+        parts.append(f"Driver version    : {drv_ver}")
+        opts = cap.get("goog:chromeOptions") or {}
+        args = opts.get("args") or []
+        # Ensure args is iterable
+        if not isinstance(args, (list, tuple)):
+            args = []
+        parts.append(f"Chrome args       : {' '.join(args)}")
+
+    if exc:
+        parts += [
+            "---- ERROR ----",
+            f"Error type        : {type(exc).__name__}",
+            f"Error message     : {exc}",
+        ]
+
+    return "\n".join(parts)
+
+
+__all__ = ['collect_diagnostics']