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

u2mcp/tools/device.py

@@ -1,18 +1,16 @@
 from __future__ import annotations
 
-import sys
+import argparse
 from base64 import b64encode
 from collections.abc import AsyncGenerator
-from contextlib import asynccontextmanager
+from contextlib import asynccontextmanager, closing
 from io import BytesIO
+from pathlib import Path
 from typing import Any
 
 import uiautomator2 as u2
 from adbutils import adb
-from anyio import Lock, create_task_group, open_process, to_thread
-from anyio.abc import AnyByteReceiveStream
-from anyio.streams.text import TextReceiveStream
-from fastmcp.server.dependencies import get_context
+from anyio import Lock, to_thread
 from fastmcp.utilities.logging import get_logger
 from PIL.Image import Image
 
@@ -20,12 +18,14 @@ from ..mcp import mcp
 
 __all__ = (
     "device_list",
+    "shell_command",
     "init",
     "connect",
     "disconnect",
     "disconnect_all",
     "window_size",
     "screenshot",
+    "save_screenshot",
     "dump_hierarchy",
     "info",
 )
@@ -55,15 +55,9 @@ async def get_device(serial: str) -> AsyncGenerator[u2.Device]:
         yield device
 
 
-@mcp.tool("device_list")
-async def device_list() -> list[dict[str, Any]]:
-    device_list = await to_thread.run_sync(adb.device_list)
-    return [d.info for d in device_list]
-
-
-@mcp.tool("init")
+@mcp.tool("init", tags={"device:manage"})
 async def init(serial: str = ""):
-    """Install essential resources to device.
+    """Install essential resources (minicap, minitouch, uiautomator ...) to device.
 
     Important:
         This tool must be run on the Android device before running operation actions.
@@ -72,51 +66,70 @@ async def init(serial: str = ""):
         serial (str): Android device serialno to initialize. If empty string, all devices will be initialized.
 
     Returns:
-        None upon successful completion (exit code 0).
+        None upon successful completion
         Raises an exception if the subprocess returns a non-zero exit code.
     """
-    logger = get_logger(f"{__name__}.init")
-    command = [sys.executable, "-m", "uiautomator2", "init"]
-    if serial := serial.strip():
-        command.extend(["--serial", serial])
-
-    logger.info("Running uiautomator2 init command: %s %s", sys.executable, command)
-    # Capture stdio prevent polluting the output
-    ctx = get_context()
-
-    async def receive(name: str, stream: AnyByteReceiveStream):
-        async for line in TextReceiveStream(stream):
-            match name:
-                case "stdout":
-                    await ctx.info(line)
-                case "stderr":
-                    await ctx.error(line)
-                case _:
-                    raise ValueError(f"Unknown stream name: {name}")
-
-    async with await open_process(command) as process:
-        if process.stdout is None:
-            raise RuntimeError("stdout is None")
-        if process.stderr is None:
-            raise RuntimeError("stderr is None")
-        async with create_task_group() as tg:
-            for name, handle in zip(("stdout", "stderr"), (process.stdout, process.stderr)):
-                tg.start_soon(receive, name, handle)
-
-    if exit_code := process.returncode:
-        raise RuntimeError(f"uiautomator2 init command exited with non-zero code: {exit_code}")
-    else:
-        logger.info("uiautomator2 init command exited with code: %s", exit_code)
-
-
-@mcp.tool("connect")
-async def connect(serial: str = ""):
+    from uiautomator2.__main__ import cmd_init
+
+    args = argparse.Namespace(serial=serial, serial_optional=None)
+    return await to_thread.run_sync(cmd_init, args)
+
+
+@mcp.tool("purge", tags={"device:manage"})
+async def purge(serial: str = ""):
+    """Purge all resources (minicap, minitouch, uiautomator ...) from device.
+
+    Important:
+        This tool must be run on the Android device before running operation actions.
+
+    Args:
+        serial (str): Android device serialno to purge. If empty string, all devices will be purged.
+
+    Returns:
+        None upon successful completion
+        Raises an exception if the subprocess returns a non-zero exit code.
+    """
+    from uiautomator2.__main__ import cmd_purge
+
+    args = argparse.Namespace(serial=serial)
+    return await to_thread.run_sync(cmd_purge, args)
+
+
+@mcp.tool("shell_command", tags={"device:shell"})
+async def shell_command(serial: str, command: str, timeout: float = 60) -> tuple[int, str]:
+    """Run a shell command on an Android device
+
+    Args:
+        serial (str): Android device serialno
+        command (str): Shell command to run
+        timeout (float): Seconds to wait for command to complete.
+
+    Returns:
+        tuple[int,str]: Return code and output of the command
+    """
+    async with get_device(serial) as device:
+        return_value = await to_thread.run_sync(device.adb_device.shell2, command, timeout)
+        return return_value.returncode, return_value.output
+
+
+@mcp.tool("device_list", tags={"device:info"})
+async def device_list() -> list[dict[str, Any]]:
+    """List of Adb Device with state:device
+
+    Returns:
+        list[dict[str,Any]]: List Adb Device information
+    """
+    device_list = await to_thread.run_sync(adb.device_list)
+    return [d.info for d in device_list]
+
+
+@mcp.tool("connect", tags={"device:manage"})
+async def connect(serial: str = "") -> dict[str, Any]:
     """Connect to an Android device
 
     Args:
         serial (str): Android device serial number. If empty string, connects to the unique device if only one device is connected.
 
-
     Returns:
         dict[str,Any]: Device information
     """
@@ -151,7 +164,7 @@ async def connect(serial: str = ""):
         return result
 
 
-@mcp.tool("disconnect")
+@mcp.tool("disconnect", tags={"device:manage"})
 async def disconnect(serial: str):
     """Disconnect from an Android device
 
@@ -164,17 +177,17 @@ async def disconnect(serial: str):
     if not (serial := serial.strip()):
         raise ValueError("serial cannot be empty")
     async with _global_device_connection_lock:
-        del _devices[serial]
+        _devices.pop(serial, None)
 
 
-@mcp.tool("disconnect_all")
+@mcp.tool("disconnect_all", tags={"device:manage"})
 async def disconnect_all():
     """Disconnect from all Android devices"""
     async with _global_device_connection_lock:
         _devices.clear()
 
 
-@mcp.tool("window_size")
+@mcp.tool("window_size", tags={"device:info"})
 async def window_size(serial: str) -> dict[str, int]:
     """Get window size of an Android device
 
@@ -191,39 +204,74 @@ async def window_size(serial: str) -> dict[str, int]:
         return {"width": width, "height": height}
 
 
-@mcp.tool("screenshot")
-async def screenshot(serial: str, display_id: int = -1) -> dict[str, Any]:
+@mcp.tool("screenshot", tags={"device:capture", "screen:capture"})
+async def screenshot(serial: str, format: str = "jpeg", display_id: int = -1) -> dict[str, Any]:
     """
     Take screenshot of device
 
     Args:
-        serial (str): Android device serialno
+        serial (str): Android device serialno.
+        format (str): Image format. Defaults to "jpeg".
         display_id (int): use specific display if device has multiple screen. Defaults to -1.
 
     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)
+            - image (str): Base64 encoded image data in data URL format (data:image/jpeg;base64,...)
+            - height (int): Image height
+            - width (int): Image width
+    """
+    display_id = int(display_id)
+    async with get_device(serial) as device:
+        im = await to_thread.run_sync(lambda: device.screenshot(display_id=display_id if display_id >= 0 else None))
+
+    if not isinstance(im, Image):
+        raise RuntimeError("Invalid image")
+
+    with closing(im):
+        with BytesIO() as fp:
+            im.save(fp, format)
+            im_data = fp.getvalue()
+
+        return {
+            "image": "data:image/jpeg;base64," + b64encode(im_data).decode(),
+            "height": im.height,
+            "width": im.width,
+        }
+
+
+@mcp.tool("save_screenshot", tags={"device:capture", "screen:capture"})
+async def save_screenshot(serial: str, file: str, display_id: int = -1) -> str:
+    """
+    Save screenshot of device to file
+
+    Args:
+        serial(str): Android device serial number.
+        file(str): File path to save the screenshot. Supports both absolute and relative paths.
+        display_id(int): Use specific display if device has multiple screens. Defaults to -1 (default display).
+
+    Returns:
+        str: Screenshot save file path
     """
     display_id = int(display_id)
+
     async with get_device(serial) as device:
         im = await to_thread.run_sync(lambda: device.screenshot(display_id=display_id if display_id >= 0 else None))
 
     if not isinstance(im, Image):
         raise RuntimeError("Invalid image")
 
-    with BytesIO() as fp:
-        im.save(fp, "jpeg")
-        im_data = fp.getvalue()
+    with closing(im):
+        # Convert path to Path object and resolve
+        file_path = Path(file)
+        # Create parent directory if it doesn't exist
+        file_path.parent.mkdir(parents=True, exist_ok=True)
+        # Save the image
+        im.save(file_path)
 
-    return {
-        "width": im.width,
-        "height": im.height,
-        "image": "data:image/jpeg;base64," + b64encode(im_data).decode(),
-    }
+    return file_path.resolve().as_posix()
 
 
-@mcp.tool("dump_hierarchy")
+@mcp.tool("dump_hierarchy", tags={"device:capture"})
 async def dump_hierarchy(serial: str, compressed: bool = False, pretty: bool = False, max_depth: int = -1) -> str:
     """
     Dump window hierarchy
@@ -243,7 +291,7 @@ async def dump_hierarchy(serial: str, compressed: bool = False, pretty: bool = F
         )
 
 
-@mcp.tool("info")
+@mcp.tool("info", tags={"device:info"})
 async def info(serial: str) -> dict[str, Any]:
     """
     Get device info

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

@@ -7,7 +7,7 @@ from ..mcp import mcp
 __all__ = ("delay",)
 
 
-@mcp.tool("delay")
+@mcp.tool("delay", tags={"util:delay"})
 async def delay(seconds: float):
     """Delay for a specific amount of time