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

mcp_browser_use/tools/browser_management.py

@@ -0,0 +1,260 @@
+"""Browser lifecycle management tool implementations."""
+
+import json
+import psutil
+from pathlib import Path
+from ..context import get_context, reset_context
+from ..config import get_env_config, profile_key
+from ..constants import ACTION_LOCK_TTL_SECS
+from ..utils.diagnostics import collect_diagnostics
+
+# Import specific functions we need
+from ..browser.driver import (
+    _ensure_driver_and_window,
+    close_singleton_window,
+    _close_extra_blank_windows_safe,
+    ensure_process_tag,
+)
+from ..actions.navigation import _wait_document_ready
+from ..actions.screenshots import _make_page_snapshot
+from ..locking.action_lock import _release_action_lock
+
+
+async def start_browser():
+    """
+    Start browser session or open new window in existing session.
+
+    Returns:
+        JSON string with session info and snapshot
+    """
+    ctx = get_context()
+
+    # Ensure process tag
+    if ctx.process_tag is None:
+        ctx.process_tag = ensure_process_tag()
+
+    owner = ctx.process_tag
+
+    try:
+        # Initialize driver and window
+        _ensure_driver_and_window()
+
+        # Check if initialization succeeded
+        if not ctx.is_driver_initialized():
+            diag = collect_diagnostics(None, None, ctx.config)
+            if isinstance(diag, str):
+                diag = {"summary": diag}
+
+            return json.dumps({
+                "ok": False,
+                "error": "driver_not_initialized",
+                "driver_initialized": False,
+                "debugger": ctx.get_debugger_address(),
+                "diagnostics": diag,
+                "message": "Failed to attach/launch a debuggable Chrome session."
+            })
+
+        # Clean up extra blank windows
+        handle = getattr(ctx.driver, "current_window_handle", None)
+        try:
+            _close_extra_blank_windows_safe(
+                ctx.driver,
+                exclude_handles={handle} if handle else None
+            )
+        except Exception:
+            pass
+
+        # Wait for page ready and get snapshot
+        _wait_document_ready(timeout=5.0)
+        try:
+            snapshot = _make_page_snapshot()
+        except Exception:
+            snapshot = None
+
+        snapshot = snapshot or {
+            "url": "about:blank",
+            "title": "",
+            "html": "",
+            "truncated": False,
+        }
+
+        msg = (
+            f"Browser session created successfully. "
+            f"Session ID: {owner}. "
+            f"Current URL: {snapshot.get('url') or 'about:blank'}"
+        )
+
+        payload = {
+            "ok": True,
+            "session_id": owner,
+            "debugger": ctx.get_debugger_address(),
+            "lock_ttl_seconds": ACTION_LOCK_TTL_SECS,
+            "snapshot": snapshot,
+            "message": msg,
+        }
+
+        return json.dumps(payload)
+
+    except Exception as e:
+        diag = collect_diagnostics(ctx.driver, e, ctx.config)
+        snapshot = _make_page_snapshot() or {
+            "url": "about:blank",
+            "title": "",
+            "html": "",
+            "truncated": False,
+        }
+        return json.dumps({
+            "ok": False,
+            "error": str(e),
+            "diagnostics": diag,
+            "snapshot": snapshot
+        })
+
+
+async def unlock_browser():
+    """Release the action lock for this process."""
+    ctx = get_context()
+
+    if ctx.process_tag is None:
+        ctx.process_tag = ensure_process_tag()
+
+    owner = ctx.process_tag
+    released = _release_action_lock(owner)
+
+    return json.dumps({
+        "ok": True,
+        "released": bool(released)
+    })
+
+async def close_browser() -> str:
+    """Close the browser window for this session."""
+    ctx = get_context()
+
+    try:
+        closed = close_singleton_window()
+        msg = "Browser window closed successfully" if closed else "No window to close"
+
+        return json.dumps({
+            "ok": True,
+            "closed": bool(closed),
+            "message": msg
+        })
+
+    except Exception as e:
+        diag = collect_diagnostics(ctx.driver, e, ctx.config)
+        return json.dumps({
+            "ok": False,
+            "error": str(e),
+            "diagnostics": diag
+        })
+
+async def force_close_all_chrome() -> str:
+    """
+    Force close all Chrome processes, quit driver, and clean up all state.
+    Use this to recover from stuck Chrome instances.
+    """
+    ctx = get_context()
+    killed_processes = []
+    errors = []
+
+    try:
+        # 1. Try to quit the Selenium driver gracefully
+        if ctx.driver is not None:
+            try:
+                ctx.driver.quit()
+            except Exception as e:
+                errors.append(f"Driver quit failed: {e}")
+
+            ctx.driver = None
+
+        # 2. Get config to find which Chrome processes to kill
+        user_data_dir = ctx.config.get("user_data_dir", "")
+        if not user_data_dir:
+            try:
+                cfg = get_env_config()
+                user_data_dir = cfg.get("user_data_dir", "")
+            except Exception as e:
+                errors.append(f"Could not get config: {e}")
+
+        # 3. Kill all Chrome processes using the MCP profile
+        chrome_processes_found = []
+        for p in psutil.process_iter(["name", "cmdline", "pid"]):
+            try:
+                if not p.info.get("name"):
+                    continue
+                if "chrome" not in p.info["name"].lower():
+                    continue
+
+                chrome_processes_found.append(p)
+
+                # If we have a user_data_dir, check if this process matches
+                if user_data_dir:
+                    cmd = p.info.get("cmdline")
+                    if cmd:
+                        user_data_normalized = user_data_dir.replace("\\", "/").lower()
+                        for arg in cmd:
+                            if arg and "--user-data-dir" in arg:
+                                arg_normalized = arg.replace("\\", "/").lower()
+                                if user_data_normalized in arg_normalized:
+                                    p.kill()
+                                    killed_processes.append(p.info["pid"])
+                                    break
+            except (psutil.NoSuchProcess, psutil.AccessDenied) as e:
+                errors.append(f"Could not access process: {e}")
+
+        # 4. Fallback: If no processes killed but some found, kill them all
+        if not killed_processes and chrome_processes_found:
+            for p in chrome_processes_found:
+                try:
+                    p.kill()
+                    killed_processes.append(p.info["pid"])
+                except (psutil.NoSuchProcess, psutil.AccessDenied) as e:
+                    errors.append(f"Could not kill process in fallback: {e}")
+
+        # 5. Clean up context state
+        ctx.debugger_host = None
+        ctx.debugger_port = None
+        ctx.reset_window_state()
+
+        # 6. Release locks
+        try:
+            if ctx.process_tag:
+                _release_action_lock(ctx.process_tag)
+        except Exception as e:
+            errors.append(f"Lock release failed: {e}")
+
+        # 7. Clean up lock files
+        try:
+            if user_data_dir:
+                lock_dir = Path(ctx.lock_dir)
+                if lock_dir.exists():
+                    profile_key_val = profile_key(ctx.config) if ctx.config else ""
+                    for lock_file in lock_dir.glob(f"*{profile_key_val}*"):
+                        try:
+                            lock_file.unlink()
+                        except Exception:
+                            pass
+        except Exception as e:
+            errors.append(f"Lock file cleanup failed: {e}")
+
+        msg = f"Force closed Chrome. Killed {len(killed_processes)} processes."
+        if errors:
+            msg += f" Errors: {'; '.join(errors)}"
+
+        return json.dumps({
+            "ok": True,
+            "killed_processes": killed_processes,
+            "errors": errors,
+            "message": msg
+        })
+
+    except Exception as e:
+        return json.dumps({
+            "ok": False,
+            "error": str(e),
+            "killed_processes": killed_processes,
+            "errors": errors
+        })
+
+
+__all__ = ['start_browser', 'unlock_browser', 'close_browser', 'force_close_all_chrome']

mcp_browser_use/tools/debugging.py

@@ -0,0 +1,195 @@
+"""Debugging and diagnostic tool implementations."""
+
+import json
+from pathlib import Path
+from typing import Dict, Any
+from selenium.common.exceptions import TimeoutException
+from ..context import get_context
+from ..utils.diagnostics import collect_diagnostics
+from ..actions.elements import find_element, _wait_clickable_element
+from ..actions.screenshots import _make_page_snapshot
+from ..utils.retry import retry_op
+
+
+async def get_debug_diagnostics_info() -> str:
+    """Get debug diagnostics using context."""
+    ctx = get_context()
+
+    try:
+        cfg = ctx.config
+        udir = cfg.get("user_data_dir")
+        port_file = str(Path(udir) / "DevToolsActivePort") if udir else None
+
+        # Read DevToolsActivePort
+        port_val = None
+        if udir:
+            p = Path(udir) / "DevToolsActivePort"
+            if p.exists():
+                try:
+                    port_val = int(p.read_text().splitlines()[0].strip())
+                except Exception:
+                    port_val = None
+
+        devtools_http = None
+        if port_val:
+            import urllib.request, json as _json
+            try:
+                with urllib.request.urlopen(f"http://127.0.0.1:{port_val}/json/version", timeout=1.0) as r:
+                    devtools_http = _json.loads(r.read().decode("utf-8"))
+            except Exception:
+                devtools_http = {"ok": False}
+
+        diag_summary = collect_diagnostics(driver=ctx.driver, exc=None, config=cfg)
+        diagnostics = {
+            "summary": diag_summary,
+            "driver_initialized": ctx.is_driver_initialized(),
+            "debugger": ctx.get_debugger_address(),
+            "devtools_active_port_file": {"path": port_file, "port": port_val, "exists": port_val is not None},
+            "devtools_http_version": devtools_http,
+            "context_state": {
+                "driver_initialized": ctx.is_driver_initialized(),
+                "window_ready": ctx.is_window_ready(),
+                "debugger_address": ctx.get_debugger_address(),
+                "process_tag": ctx.process_tag,
+            }
+        }
+
+        snapshot = (_make_page_snapshot()
+                    if ctx.is_driver_initialized()
+                    else {"url": None, "title": None, "html": "", "truncated": False})
+        return json.dumps({"ok": True, "diagnostics": diagnostics, "snapshot": snapshot})
+
+    except Exception as e:
+        diag = collect_diagnostics(driver=ctx.driver, exc=e, config=ctx.config)
+        return json.dumps({"ok": False, "error": str(e), "diagnostics": {"summary": diag}})
+
+async def debug_element(
+    selector,
+    selector_type,
+    timeout,
+    iframe_selector,
+    iframe_selector_type,
+    shadow_root_selector,
+    shadow_root_selector_type,
+    max_html_length=5000,
+    include_html=True,
+):
+    """
+    Debug an element on the page.
+
+    Args:
+        selector: CSS selector, XPath, or ID of the element
+        selector_type: Type of selector (css, xpath, id)
+        timeout: Maximum time to wait for element
+        iframe_selector: Optional iframe selector
+        iframe_selector_type: Iframe selector type
+        shadow_root_selector: Optional shadow root selector
+        shadow_root_selector_type: Shadow root selector type
+        max_html_length: Maximum length of outerHTML to return (default: 5000 chars)
+        include_html: Whether to include HTML in response (default: True)
+
+    Returns:
+        JSON string with debug information
+    """
+    ctx = get_context()
+
+    try:
+        info: Dict[str, Any] = {
+            "selector": selector,
+            "selector_type": selector_type,
+            "exists": False,
+            "displayed": None,
+            "enabled": None,
+            "clickable": None,
+            "rect": None,
+            "outerHTML": None,
+            "truncated": False,
+            "notes": [],
+        }
+
+        try:
+            el = retry_op(fn=lambda: find_element(
+                driver=ctx.driver,
+                selector=selector,
+                selector_type=selector_type,
+                timeout=int(timeout),
+                visible_only=False,
+                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,
+            ))
+            info["exists"] = True
+
+            try:
+                info["displayed"] = bool(el.is_displayed())
+            except Exception:
+                info["displayed"] = None
+            try:
+                info["enabled"] = bool(el.is_enabled())
+            except Exception:
+                info["enabled"] = None
+
+            try:
+                _wait_clickable_element(el=el, driver=ctx.driver, timeout=timeout)
+                info["clickable"] = True
+            except Exception:
+                info["clickable"] = False
+
+            try:
+                r = el.rect
+                info["rect"] = {
+                    "x": r.get("x"),
+                    "y": r.get("y"),
+                    "width": r.get("width"),
+                    "height": r.get("height"),
+                }
+            except Exception:
+                info["rect"] = None
+
+            # Get HTML if requested
+            if include_html:
+                try:
+                    html = ctx.driver.execute_script("return arguments[0].outerHTML;", el)
+                    # Clean invalid characters
+                    html = html.replace('\x00', '').encode('utf-8', errors='ignore').decode('utf-8')
+
+                    # Truncate if too large
+                    full_length = len(html)
+                    if max_html_length and len(html) > max_html_length:
+                        info["outerHTML"] = html[:max_html_length]
+                        info["truncated"] = True
+                        info["full_html_length"] = full_length
+                        info["notes"].append(f"HTML truncated from {full_length} to {max_html_length} chars")
+                    else:
+                        info["outerHTML"] = html
+                        info["truncated"] = False
+                except Exception as e:
+                    info["outerHTML"] = None
+                    info["notes"].append(f"Could not get HTML: {str(e)}")
+            else:
+                info["notes"].append("HTML omitted (include_html=False)")
+
+        except TimeoutException:
+            info["notes"].append("Element not found within timeout")
+        except Exception as e:
+            info["notes"].append(f"Error while probing element: {repr(e)}")
+
+        snapshot = _make_page_snapshot()
+        return json.dumps({"ok": True, "debug": info, "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
+
+
+__all__ = ['get_debug_diagnostics_info', 'debug_element']

mcp_browser_use/tools/extraction.py

@@ -0,0 +1,58 @@
+"""Element extraction tool implementations."""
+
+from typing import Optional, List, Dict
+from ..actions.extraction import extract_elements as _extract_elements_action
+
+
+async def extract_elements(
+    selectors: Optional[List[Dict[str, str]]] = None,
+    container_selector: Optional[str] = None,
+    fields: Optional[List[Dict[str, str]]] = None,
+    selector_type: Optional[str] = None,
+    wait_for_visible: bool = False,
+    timeout: int = 10,
+    max_items: Optional[int] = None,
+    offset: Optional[int] = None,
+    discover_containers: bool = False,
+    wait_for_content_loaded: Optional[Dict[str, any]] = None,
+) -> str:
+    """
+    Extract content from specific elements on the current page.
+
+    This is a wrapper around the extraction action that provides the tool interface.
+
+    Supports two modes:
+    - Simple extraction: Use 'selectors' parameter
+    - Structured extraction: Use 'container_selector' + 'fields' parameters
+    - Discovery mode: Use 'container_selector' + 'discover_containers=True'
+
+    Args:
+        selectors: [MODE 1] Optional list of selector specifications
+        container_selector: [MODE 2] CSS or XPath selector for containers
+        fields: [MODE 2] List of field extractors with field_name, selector, etc.
+        selector_type: [MODE 2] Type of container_selector (auto-detects if None)
+        wait_for_visible: [MODE 2] Wait for containers to be visible
+        timeout: [MODE 2] Timeout in seconds
+        max_items: [MODE 2] Limit number of containers to extract
+        offset: [MODE 2] Skip first N containers before extracting (useful for pagination)
+        discover_containers: [MODE 2] Return container analysis instead of extraction
+        wait_for_content_loaded: [MODE 2] Smart wait config for lazy-loaded content
+
+    Returns:
+        JSON string with extraction results and page snapshot.
+    """
+    return await _extract_elements_action(
+        selectors=selectors,
+        container_selector=container_selector,
+        fields=fields,
+        selector_type=selector_type,
+        wait_for_visible=wait_for_visible,
+        timeout=timeout,
+        max_items=max_items,
+        offset=offset,
+        discover_containers=discover_containers,
+        wait_for_content_loaded=wait_for_content_loaded
+    )
+
+
+__all__ = ['extract_elements']