uiautomator2-mcp-server 0.1.2__py3-none-any.whl → 0.2.0__py3-none-any.whl

u2mcp/tools/element.py

@@ -0,0 +1,267 @@
+from __future__ import annotations
+
+from base64 import b64encode
+from io import BytesIO
+from typing import Any
+
+from anyio import to_thread
+from PIL.Image import Image
+
+from ..mcp import mcp
+from .device import get_device
+
+__all__ = (
+    "activity_wait",
+    "element_wait",
+    "element_wait_gone",
+    "element_click",
+    "element_click_nowait",
+    "element_click_until_gone",
+    "element_long_click",
+    "element_screenshot",
+    "element_get_text",
+    "element_set_text",
+    "element_bounds",
+    "element_swipe",
+    "element_scroll",
+    "element_scroll_to",
+)
+
+
+@mcp.tool("activity_wait", tags={"element:wait"})
+async def activity_wait(serial: str, activity: str, timeout: float = 20.0) -> bool:
+    """wait activity
+
+    Args:
+        serial (str): Android device serialno
+        activity (str): name of activity
+        timeout (float): max wait time
+
+    Returns:
+        bool of activity
+    """
+    async with get_device(serial) as device:
+        # timeout: float here is actually no problem
+        return await to_thread.run_sync(device.wait_activity, activity, timeout)  # type: ignore[arg-type]
+
+
+@mcp.tool("element_wait", tags={"element:wait"})
+async def element_wait(serial: str, xpath: str, timeout: float | None = None) -> bool:
+    """
+    wait until element found
+
+    Args:
+        serial (str): Android device serialno
+        xpath (str): element xpath
+        timeout (Optional float): seconds wait element show up
+
+    Returns:
+        bool: if element found
+    """
+    async with get_device(serial) as device:
+        return await to_thread.run_sync(lambda: device.xpath(xpath).wait(timeout))
+
+
+@mcp.tool("element_wait_gone", tags={"element:wait"})
+async def element_wait_gone(serial: str, xpath: str, timeout: float | None = None) -> bool:
+    """
+    wait until element gone
+
+    Args:
+        serial (str): Android device serialno
+        xpath (str): element xpath
+        timeout (Optional float): seconds wait element show up
+
+    Returns:
+        bool: True if gone else False
+    """
+    async with get_device(serial) as device:
+        return await to_thread.run_sync(lambda: device.xpath(xpath).wait_gone(timeout))
+
+
+@mcp.tool("element_click", tags={"element:interact"})
+async def element_click(serial: str, xpath: str, timeout: float | None = None) -> bool:
+    """
+    find element and perform click
+
+    Args:
+        serial (str): Android device serialno
+        xpath (str): element xpath
+        timeout (Optional float): seconds wait element show up
+
+    Returns:
+        bool: True if click success else False
+    """
+    async with get_device(serial) as device:
+        return await to_thread.run_sync(lambda: device.xpath(xpath).click_exists(timeout))
+
+
+@mcp.tool("element_click_nowait", tags={"element:interact"})
+async def element_click_nowait(serial: str, xpath: str):
+    """
+    find element and perform click
+
+    Args:
+        serial (str): Android device serialno
+        xpath (str): element xpath
+    """
+    async with get_device(serial) as device:
+        return await to_thread.run_sync(lambda: device.xpath(xpath).click_nowait())
+
+
+@mcp.tool("element_click_until_gone", tags={"element:interact"})
+async def element_click_until_gone(serial: str, xpath: str, maxretry=10, interval=1.0) -> bool:
+    """
+    find element and click until element is gone
+
+    Args:
+        serial (str): Android device serialno
+        xpath (str): element xpath
+        maxretry (int): max click times
+        interval (float): sleep time between clicks
+
+    Return:
+        bool: if element is gone
+    """
+    async with get_device(serial) as device:
+        return await to_thread.run_sync(lambda: device.xpath(xpath).click_gone(maxretry, interval))
+
+
+@mcp.tool("element_long_click", tags={"element:interact"})
+async def element_long_click(serial: str, xpath: str):
+    """
+    find element and perform long click
+
+    Args:
+        serial (str): Android device serialno
+        xpath (str): element xpath
+    """
+    async with get_device(serial) as device:
+        return await to_thread.run_sync(lambda: device.xpath(xpath).long_click())
+
+
+@mcp.tool("element_screenshot", tags={"element:capture"})
+async def element_screenshot(serial: str, xpath: str) -> dict[str, Any]:
+    """
+    find element and take screenshot
+
+    Args:
+        serial (str): Android device serialno
+        xpath (str): element xpath
+
+    Returns:
+        dict[str,Any]: Screenshot image JPEG data with the following keys:
+            - image (str): Base64 encoded image data in data URL format (data:image/jpeg;base64,...)
+            - size (tuple[int,int]): Image dimensions as (width, height)
+    """
+    async with get_device(serial) as device:
+        im = await to_thread.run_sync(lambda: device.xpath(xpath).screenshot())
+        if not isinstance(im, Image):
+            raise RuntimeError("Invalid image")
+
+        with BytesIO() as fp:
+            im.save(fp, "jpeg")
+            im_data = fp.getvalue()
+
+        return {
+            "width": im.width,
+            "height": im.height,
+            "image": "data:image/jpeg;base64," + b64encode(im_data).decode(),
+        }
+
+
+@mcp.tool("element_get_text", tags={"element:query"})
+async def element_get_text(serial: str, xpath: str) -> str | None:
+    """
+    find and get element text
+
+    Args:
+        serial (str): Android device serialno
+        xpath (str): element xpath
+
+    Returns:
+        str: string of node text
+        None: if element has no text attribute
+    """
+    async with get_device(serial) as device:
+        return await to_thread.run_sync(lambda: device.xpath(xpath).get_text())
+
+
+@mcp.tool("element_set_text", tags={"element:modify"})
+async def element_set_text(serial: str, xpath: str, text: str) -> None:
+    """
+    find and set element text
+
+    Args:
+        serial (str): Android device serialno
+        xpath (str): element xpath
+        text (str): string of node text
+    """
+    async with get_device(serial) as device:
+        return await to_thread.run_sync(lambda: device.xpath(xpath).set_text(text))
+
+
+@mcp.tool("element_bounds", tags={"element:query"})
+async def element_bounds(serial: str, xpath: str) -> tuple[int, int, int, int]:
+    """
+    find an element and get bounds
+
+    Args:
+        serial (str): Android device serialno
+        xpath (str): element xpath
+
+    Returns:
+        tuple[int]: tuple of (left, top, right, bottom)
+    """
+    async with get_device(serial) as device:
+        return await to_thread.run_sync(lambda: device.xpath(xpath).bounds)
+
+
+@mcp.tool("element_swipe", tags={"element:gesture"})
+async def element_swipe(serial: str, xpath: str, direction: str, scale: float = 0.6):
+    """
+    find an element and swipe
+
+    Args:
+        serial (str): Android device serialno
+        xpath (str): element xpath
+        direction: one of ["left", "right", "up", "down"]
+        scale: percent of swipe, range (0, 1.0)
+    """
+    async with get_device(serial) as device:
+        return await to_thread.run_sync(lambda: device.xpath(xpath).swipe(direction, scale))
+
+
+@mcp.tool("element_scroll", tags={"element:gesture"})
+async def element_scroll(serial: str, xpath: str, direction: str = "forward") -> bool:
+    """
+    find an element and scroll
+
+    Args:
+        serial (str): Android device serialno
+        xpath (str): element xpath
+        direction (str): scroll direction, one of ["forward", "backward"]
+
+    Returns:
+        bool: if can be scroll again
+    """
+    async with get_device(serial) as device:
+        return await to_thread.run_sync(lambda: device.xpath(xpath).swipe(direction))
+
+
+@mcp.tool("element_scroll_to", tags={"element:gesture"})
+async def element_scroll_to(serial: str, xpath: str, direction: str = "forward", max_swipes: int = 10):
+    """
+    find an element and scroll to
+
+    Args:
+        serial (str): Android device serialno
+        xpath (str): element xpath
+        direction (str): scroll direction, one of ["forward", "backward"]
+        max_swipes (int): max swipe times
+
+    Returns:
+        bool: if can be scroll again
+    """
+    async with get_device(serial) as device:
+        return await to_thread.run_sync(lambda: device.xpath(xpath).scroll_to(direction, max_swipes))

u2mcp/tools/input.py

@@ -0,0 +1,47 @@
+from __future__ import annotations
+
+from anyio import to_thread
+
+from ..mcp import mcp
+from .device import get_device
+
+__all__ = (
+    "send_text",
+    "clear_text",
+    "hide_keyboard",
+)
+
+
+@mcp.tool("send_text", tags={"input:text"})
+async def send_text(serial: str, text: str, clear: bool = False):
+    """Send text to the current input field
+
+    Args:
+        serial (str): Android device serialno
+        text (str): input text
+            clear: clear text before input
+    """
+    async with get_device(serial) as device:
+        await to_thread.run_sync(device.send_keys, text, clear)
+
+
+@mcp.tool("clear_text", tags={"input:text"})
+async def clear_text(serial: str):
+    """Clear text in the current input field
+
+    Args:
+        serial (str): Android device serialno
+    """
+    async with get_device(serial) as device:
+        await to_thread.run_sync(device.clear_text)
+
+
+@mcp.tool("hide_keyboard", tags={"input:keyboard"})
+async def hide_keyboard(serial: str):
+    """Hide keyboard
+
+    Args:
+        serial (str): Android device serialno
+    """
+    async with get_device(serial) as device:
+        await to_thread.run_sync(device.hide_keyboard)

u2mcp/tools/misc.py

@@ -0,0 +1,17 @@
+from __future__ import annotations
+
+import anyio
+
+from ..mcp import mcp
+
+__all__ = ("delay",)
+
+
+@mcp.tool("delay", tags={"util:delay"})
+async def delay(seconds: float):
+    """Delay for a specific amount of time
+
+    Args:
+        seconds(float): Delay duration in seconds
+    """
+    await anyio.sleep(seconds)

u2mcp/tools/scrcpy.py

@@ -0,0 +1,142 @@
+from __future__ import annotations
+
+import os
+
+from anyio import create_task_group, move_on_after, open_process
+from anyio.abc import AnyByteReceiveStream, Process
+from anyio.streams.text import TextReceiveStream
+from fastmcp.server.dependencies import get_context
+from fastmcp.utilities.logging import get_logger
+
+from ..background import get_background_task_group
+from ..mcp import mcp
+
+__all__ = ("start_scrcpy", "stop_scrcpy")
+
+# Keep track of background scrcpy processes
+_background_processes: dict[int, Process] = {}
+
+
+@mcp.tool("start_scrcpy", tags={"screen:mirror"})
+async def start_scrcpy(serial: str = "", timeout: float = 5.0) -> int:
+    """Startup scrcpy in background and returns process id.
+
+    scrcpy is an application mirrors Android devices (video and audio) connected via USB or TCP/IP and allows control using the computer's keyboard and mouse.
+
+    The scrcpy process will run in the background after successful startup.
+    Use stop_scrcpy to terminate the process.
+
+    Args:
+        serial (str): Android device serialno. If empty string, connects to the unique device if only one device is connected.
+        timeout (float): Seconds to wait for process to confirm startup.
+            If process is still running after this time, startup is considered successful.
+
+    Returns:
+        int: process id (pid)
+    """
+
+    logger = get_logger(f"{__name__}.start_scrcpy")
+    ctx = get_context()
+
+    scrcpy_path = os.environ.get("SCRCPY", "scrcpy.exe" if os.name == "nt" else "scrcpy")
+    command = [scrcpy_path]
+    if serial := serial.strip():
+        command.extend(["--serial", serial])
+
+    logger.info("start scrcpy: %s", command)
+
+    process = await open_process(command)
+    pid = process.pid
+
+    # Stream monitoring function
+    async def receive(name: str, stream: AnyByteReceiveStream):
+        logger.info("Starting to monitor %s for pid=%s", name, pid)
+        async for line in TextReceiveStream(stream):
+            logger.debug("Received %s line: %s", name, line.strip())
+            match name:
+                case "stdout":
+                    await ctx.info(line)
+                case "stderr":
+                    await ctx.error(line)
+                case _:
+                    raise ValueError(f"Unknown stream name: {name}")
+        logger.info("Finished monitoring %s for pid=%s", name, pid)
+
+    # Monitor streams and auto-cleanup on process exit
+    async def monitor_streams():
+        if process.stdout is None:
+            raise RuntimeError("stdout is None")
+        if process.stderr is None:
+            raise RuntimeError("stderr is None")
+        try:
+            async with create_task_group() as inner_tg:
+                for name, handle in zip(("stdout", "stderr"), (process.stdout, process.stderr)):
+                    inner_tg.start_soon(receive, name, handle)
+        finally:
+            # Cleanup only if we still own the process (i.e., not manually stopped)
+            if _background_processes.pop(pid, None) is process:
+                logger.info("scrcpy process exited naturally, cleaning up (pid=%s)", pid)
+                await process.aclose()
+            else:
+                logger.info("scrcpy process was manually stopped, skipping cleanup (pid=%s)", pid)
+
+    # Start monitoring immediately (before startup wait) to capture startup logs
+    tg = get_background_task_group()
+    if tg is None:
+        raise RuntimeError("Monitor task group not initialized - server not started?")
+    tg.start_soon(monitor_streams)
+
+    # Store process
+    _background_processes[pid] = process
+
+    # Startup phase: wait for process exit with timeout
+    with move_on_after(timeout) as timeout_scope:
+        await process.wait()
+
+    if timeout_scope.cancel_called:
+        # Timeout reached, process is still running - success!
+        logger.info("scrcpy started successfully in background (pid=%s)", pid)
+    else:
+        # Process exited before timeout - failure
+        _background_processes.pop(pid, None)
+        if process.returncode == 0:
+            raise RuntimeError(f"scrcpy closed during startup (pid={pid}, return code 0)")
+        else:
+            raise RuntimeError(f"scrcpy exited during startup wait with code: {process.returncode} (pid={pid})")
+
+    return pid
+
+
+@mcp.tool("stop_scrcpy", tags={"screen:mirror"})
+async def stop_scrcpy(pid: int, timeout: float = 5.0) -> None:
+    """Stop a running scrcpy process by pid.
+
+    scrcpy is an application mirrors Android devices (video and audio) connected via USB or TCP/IP and allows control using the computer's keyboard and mouse.
+
+    Args:
+        pid (int): Process id of the scrcpy process to stop
+        timeout (float): Seconds to wait for process to terminate.
+
+    Returns:
+        None
+    """
+    logger = get_logger(f"{__name__}.stop_scrcpy")
+
+    if pid not in _background_processes:
+        raise ValueError(f"No scrcpy process found with pid: {pid}")
+
+    process = _background_processes.pop(pid)
+    try:
+        process.kill()
+        # Wait for process to exit with timeout
+        with move_on_after(timeout) as timeout_scope:
+            await process.wait()
+    finally:
+        # Always close the process when manually stopping
+        # The monitor task will detect we popped the process and skip cleanup
+        await process.aclose()
+
+    if timeout_scope.cancel_called:
+        logger.warning("scrcpy process did not exit within %ss (pid=%s)", timeout, pid)
+    else:
+        logger.info("scrcpy process stopped (pid=%s)", pid)

u2mcp/{_version.py → version.py}

@@ -1,34 +1,34 @@
-# file generated by setuptools-scm
-# don't change, don't track in version control
-
-__all__ = [
-    "__version__",
-    "__version_tuple__",
-    "version",
-    "version_tuple",
-    "__commit_id__",
-    "commit_id",
-]
-
-TYPE_CHECKING = False
-if TYPE_CHECKING:
-    from typing import Tuple
-    from typing import Union
-
-    VERSION_TUPLE = Tuple[Union[int, str], ...]
-    COMMIT_ID = Union[str, None]
-else:
-    VERSION_TUPLE = object
-    COMMIT_ID = object
-
-version: str
-__version__: str
-__version_tuple__: VERSION_TUPLE
-version_tuple: VERSION_TUPLE
-commit_id: COMMIT_ID
-__commit_id__: COMMIT_ID
-
-__version__ = version = '0.1.2'
-__version_tuple__ = version_tuple = (0, 1, 2)
-
-__commit_id__ = commit_id = None
+# file generated by setuptools-scm
+# don't change, don't track in version control
+
+__all__ = [
+    "__version__",
+    "__version_tuple__",
+    "version",
+    "version_tuple",
+    "__commit_id__",
+    "commit_id",
+]
+
+TYPE_CHECKING = False
+if TYPE_CHECKING:
+    from typing import Tuple
+    from typing import Union
+
+    VERSION_TUPLE = Tuple[Union[int, str], ...]
+    COMMIT_ID = Union[str, None]
+else:
+    VERSION_TUPLE = object
+    COMMIT_ID = object
+
+version: str
+__version__: str
+__version_tuple__: VERSION_TUPLE
+version_tuple: VERSION_TUPLE
+commit_id: COMMIT_ID
+__commit_id__: COMMIT_ID
+
+__version__ = version = '0.2.0'
+__version_tuple__ = version_tuple = (0, 2, 0)
+
+__commit_id__ = commit_id = None