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

u2mcp/tools/app.py

@@ -1,231 +1,231 @@
-from __future__ import annotations
-
-import asyncio
-from typing import Any
-
-from ..mcp import mcp
-from .device import get_device
-
-__all__ = (
-    "app_install",
-    "app_uninstall",
-    "app_uninstall_all",
-    "app_start",
-    "app_stop",
-    "app_stop_all",
-    "app_clear",
-    "app_info",
-    "app_current",
-    "app_list",
-    "app_list_running",
-    "app_auto_grant_permissions",
-)
-
-
-@mcp.tool("app_install")
-async def app_install(serial: str, data: str):
-    """Install app
-
-    Args:
-        serial (str): Android device serialno
-        data (str): APK file path or url
-    """
-    async with get_device(serial) as device:
-        await asyncio.to_thread(device.app_install, data)
-
-
-@mcp.tool("app_uninstall")
-async def app_uninstall(serial: str, package_name: str) -> bool:
-    """Uninstall an app
-
-    Args:
-        serial (str): Android device serialno
-        package_name (str): package name
-
-    Returns:
-        bool: success
-    """
-    async with get_device(serial) as device:
-        return await asyncio.to_thread(device.app_uninstall, package_name)
-
-
-@mcp.tool("app_uninstall_all")
-async def app_uninstall_all(serial: str, excludes: list[str] | None = None) -> list[str]:
-    """Uninstall all apps
-
-    Args:
-        serial (str): Android device serialno
-        excludes (list[str] | None): packages that do not want to uninstall
-
-    Returns:
-        list[str]: list of uninstalled apps
-    """
-    async with get_device(serial) as device:
-        return await asyncio.to_thread(device.app_uninstall_all, excludes or [])
-
-
-@mcp.tool("app_start")
-async def app_start(
-    serial: str,
-    package_name: str,
-    activity: str | None = None,
-    wait: bool = False,
-    stop: bool = False,
-):
-    """Launch application
-
-    Args:
-        serial (str): Android device serialno
-        package_name (str): package name
-        activity (str): app activity
-        stop (bool): Stop app before starting the activity. (require activity)
-        wait (bool): wait until app started. default False
-    """
-    async with get_device(serial) as device:
-        await asyncio.to_thread(device.app_start, package_name, activity, wait, stop)
-
-
-@mcp.tool("app_wait")
-async def app_wait(serial: str, package_name: str, timeout: float = 20.0, front=False):
-    """Wait until app launched
-
-    Args:
-        serial (str): Android device serialno
-        package_name (str): package name
-        timeout (float): maximum wait time seconds
-        front (bool): wait until app is current app
-    """
-    async with get_device(serial) as device:
-        if not await asyncio.to_thread(device.app_wait, package_name, timeout, front):
-            raise RuntimeError(f"Failed to wait App {package_name} to launch")
-
-
-@mcp.tool("app_stop")
-async def app_stop(serial: str, package_name: str):
-    """Stop one application
-
-    Args:
-        serial (str): Android device serialno
-        package_name (str): package name
-    """
-    async with get_device(serial) as device:
-        await asyncio.to_thread(device.app_stop, package_name)
-
-
-@mcp.tool("app_stop_all")
-async def app_stop_all(serial: str, excludes: list[str] | None = None) -> list[str]:
-    """Stop all third party applications
-
-    Args:
-        excludes (list): apps that do now want to kill
-
-    Returns:
-        list[str]: a list of killed apps
-    """
-    async with get_device(serial) as device:
-        return await asyncio.to_thread(device.app_stop_all, excludes or [])
-
-
-@mcp.tool("app_clear")
-async def app_clear(serial: str, package_name: str):
-    """Stop and clear app data: pm clear
-
-    Args:
-        serial (str): Android device serialno
-        package_name (str): package name
-
-    Returns:
-        bool: success
-    """
-    async with get_device(serial) as device:
-        await asyncio.to_thread(device.app_clear, package_name)
-
-
-@mcp.tool("app_info")
-async def app_info(serial: str, package_name: str) -> dict[str, Any]:
-    """
-    Get app info
-
-    Args:
-        serial (str): Android device serialno
-        package_name (str): package name
-
-    Returns:
-        dict[str,Any]: app info
-
-        Example:
-            {"versionName": "1.1.7", "versionCode": 1001007}
-    """
-    async with get_device(serial) as device:
-        return await asyncio.to_thread(device.app_info, package_name)
-
-
-@mcp.tool("app_current")
-async def app_current(serial: str) -> dict[str, Any]:
-    """
-    Get current app info
-
-    Args:
-        serial (str): Android device serialno
-
-    Returns:
-        dict[str,Any]: running app info
-    """
-    async with get_device(serial) as device:
-        return await asyncio.to_thread(device.app_current)
-
-
-@mcp.tool("app_list")
-async def app_list(serial: str, filter: str = "") -> list[str]:
-    """
-    List installed app package names
-
-    Args:
-        serial (str): Android device serialno
-        filter (str): [-f] [-d] [-e] [-s] [-3] [-i] [-u] [--user USER_ID] [FILTER]
-
-    Returns:
-        list[str]: list of apps by filter
-    """
-    async with get_device(serial) as device:
-        return await asyncio.to_thread(device.app_list, filter.strip())
-
-
-@mcp.tool("app_list_running")
-async def app_list_running(serial: str) -> list[str]:
-    """
-    List running apps
-
-    Args:
-        serial (str): Android device serialno
-
-    Returns:
-        list[str]: list of running apps
-    """
-    async with get_device(serial) as device:
-        return await asyncio.to_thread(device.app_list_running)
-
-
-@mcp.tool("app_auto_grant_permissions")
-async def app_auto_grant_permissions(serial: str, package_name: str):
-    """auto grant permissions
-
-    Args:
-        serial (str): Android device serialno
-        package_name (str): package name
-
-    Help of "adb shell pm":
-        grant [--user USER_ID] PACKAGE PERMISSION
-        revoke [--user USER_ID] PACKAGE PERMISSION
-            These commands either grant or revoke permissions to apps.  The permissions
-            must be declared as used in the app's manifest, be runtime permissions
-            (protection level dangerous), and the app targeting SDK greater than Lollipop MR1 (API level 22).
-
-    Help of "Android official pm" see <https://developer.android.com/tools/adb#pm>
-        Grant a permission to an app. On devices running Android 6.0 (API level 23) and higher,
-            the permission can be any permission declared in the app manifest.
-        On devices running Android 5.1 (API level 22) and lower,
-            must be an optional permission defined by the app.
-    """
-    async with get_device(serial) as device:
-        await asyncio.to_thread(device.app_auto_grant_permissions, package_name)
+from __future__ import annotations
+
+import asyncio
+from typing import Any
+
+from ..mcp import mcp
+from .device import get_device
+
+__all__ = (
+    "app_install",
+    "app_uninstall",
+    "app_uninstall_all",
+    "app_start",
+    "app_stop",
+    "app_stop_all",
+    "app_clear",
+    "app_info",
+    "app_current",
+    "app_list",
+    "app_list_running",
+    "app_auto_grant_permissions",
+)
+
+
+@mcp.tool("app_install")
+async def app_install(serial: str, data: str):
+    """Install app
+
+    Args:
+        serial (str): Android device serialno
+        data (str): APK file path or url
+    """
+    async with get_device(serial) as device:
+        await asyncio.to_thread(device.app_install, data)
+
+
+@mcp.tool("app_uninstall")
+async def app_uninstall(serial: str, package_name: str) -> bool:
+    """Uninstall an app
+
+    Args:
+        serial (str): Android device serialno
+        package_name (str): package name
+
+    Returns:
+        bool: success
+    """
+    async with get_device(serial) as device:
+        return await asyncio.to_thread(device.app_uninstall, package_name)
+
+
+@mcp.tool("app_uninstall_all")
+async def app_uninstall_all(serial: str, excludes: list[str] | None = None) -> list[str]:
+    """Uninstall all apps
+
+    Args:
+        serial (str): Android device serialno
+        excludes (list[str] | None): packages that do not want to uninstall
+
+    Returns:
+        list[str]: list of uninstalled apps
+    """
+    async with get_device(serial) as device:
+        return await asyncio.to_thread(device.app_uninstall_all, excludes or [])
+
+
+@mcp.tool("app_start")
+async def app_start(
+    serial: str,
+    package_name: str,
+    activity: str | None = None,
+    wait: bool = False,
+    stop: bool = False,
+):
+    """Launch application
+
+    Args:
+        serial (str): Android device serialno
+        package_name (str): package name
+        activity (str): app activity
+        stop (bool): Stop app before starting the activity. (require activity)
+        wait (bool): wait until app started. default False
+    """
+    async with get_device(serial) as device:
+        await asyncio.to_thread(device.app_start, package_name, activity, wait, stop)
+
+
+@mcp.tool("app_wait")
+async def app_wait(serial: str, package_name: str, timeout: float = 20.0, front=False):
+    """Wait until app launched
+
+    Args:
+        serial (str): Android device serialno
+        package_name (str): package name
+        timeout (float): maximum wait time seconds
+        front (bool): wait until app is current app
+    """
+    async with get_device(serial) as device:
+        if not await asyncio.to_thread(device.app_wait, package_name, timeout, front):
+            raise RuntimeError(f"Failed to wait App {package_name} to launch")
+
+
+@mcp.tool("app_stop")
+async def app_stop(serial: str, package_name: str):
+    """Stop one application
+
+    Args:
+        serial (str): Android device serialno
+        package_name (str): package name
+    """
+    async with get_device(serial) as device:
+        await asyncio.to_thread(device.app_stop, package_name)
+
+
+@mcp.tool("app_stop_all")
+async def app_stop_all(serial: str, excludes: list[str] | None = None) -> list[str]:
+    """Stop all third party applications
+
+    Args:
+        excludes (list): apps that do now want to kill
+
+    Returns:
+        list[str]: a list of killed apps
+    """
+    async with get_device(serial) as device:
+        return await asyncio.to_thread(device.app_stop_all, excludes or [])
+
+
+@mcp.tool("app_clear")
+async def app_clear(serial: str, package_name: str):
+    """Stop and clear app data: pm clear
+
+    Args:
+        serial (str): Android device serialno
+        package_name (str): package name
+
+    Returns:
+        bool: success
+    """
+    async with get_device(serial) as device:
+        await asyncio.to_thread(device.app_clear, package_name)
+
+
+@mcp.tool("app_info")
+async def app_info(serial: str, package_name: str) -> dict[str, Any]:
+    """
+    Get app info
+
+    Args:
+        serial (str): Android device serialno
+        package_name (str): package name
+
+    Returns:
+        dict[str,Any]: app info
+
+        Example:
+            {"versionName": "1.1.7", "versionCode": 1001007}
+    """
+    async with get_device(serial) as device:
+        return await asyncio.to_thread(device.app_info, package_name)
+
+
+@mcp.tool("app_current")
+async def app_current(serial: str) -> dict[str, Any]:
+    """
+    Get current app info
+
+    Args:
+        serial (str): Android device serialno
+
+    Returns:
+        dict[str,Any]: running app info
+    """
+    async with get_device(serial) as device:
+        return await asyncio.to_thread(device.app_current)
+
+
+@mcp.tool("app_list")
+async def app_list(serial: str, filter: str = "") -> list[str]:
+    """
+    List installed app package names
+
+    Args:
+        serial (str): Android device serialno
+        filter (str): [-f] [-d] [-e] [-s] [-3] [-i] [-u] [--user USER_ID] [FILTER]
+
+    Returns:
+        list[str]: list of apps by filter
+    """
+    async with get_device(serial) as device:
+        return await asyncio.to_thread(device.app_list, filter.strip())
+
+
+@mcp.tool("app_list_running")
+async def app_list_running(serial: str) -> list[str]:
+    """
+    List running apps
+
+    Args:
+        serial (str): Android device serialno
+
+    Returns:
+        list[str]: list of running apps
+    """
+    async with get_device(serial) as device:
+        return await asyncio.to_thread(device.app_list_running)
+
+
+@mcp.tool("app_auto_grant_permissions")
+async def app_auto_grant_permissions(serial: str, package_name: str):
+    """auto grant permissions
+
+    Args:
+        serial (str): Android device serialno
+        package_name (str): package name
+
+    Help of "adb shell pm":
+        grant [--user USER_ID] PACKAGE PERMISSION
+        revoke [--user USER_ID] PACKAGE PERMISSION
+            These commands either grant or revoke permissions to apps.  The permissions
+            must be declared as used in the app's manifest, be runtime permissions
+            (protection level dangerous), and the app targeting SDK greater than Lollipop MR1 (API level 22).
+
+    Help of "Android official pm" see <https://developer.android.com/tools/adb#pm>
+        Grant a permission to an app. On devices running Android 6.0 (API level 23) and higher,
+            the permission can be any permission declared in the app manifest.
+        On devices running Android 5.1 (API level 22) and lower,
+            must be an optional permission defined by the app.
+    """
+    async with get_device(serial) as device:
+        await asyncio.to_thread(device.app_auto_grant_permissions, package_name)

u2mcp/tools/device.py

@@ -3,14 +3,14 @@ from __future__ import annotations
 import asyncio
 import sys
 from base64 import b64encode
+from collections.abc import AsyncGenerator
 from contextlib import asynccontextmanager
 from io import BytesIO
 from typing import Any, Literal
 
 import uiautomator2 as u2
 from adbutils import adb
-from fastmcp.dependencies import CurrentContext
-from fastmcp.server.context import Context
+from fastmcp.server.dependencies import get_context
 from fastmcp.utilities.logging import get_logger
 from PIL.Image import Image
 
@@ -36,7 +36,7 @@ _device_connect_lock = asyncio.Lock()
 
 
 @asynccontextmanager
-async def get_device(serial: str):
+async def get_device(serial: str) -> AsyncGenerator[u2.Device]:
     async with _device_connect_lock:
         try:
             semaphore, device = _devices[serial]
@@ -61,7 +61,7 @@ async def device_list() -> list[dict[str, Any]]:
 
 
 @mcp.tool("init")
-async def init(serial: str = "", ctx: Context = CurrentContext()):
+async def init(serial: str = ""):
     """Install essential resources to device.
 
     Important:
@@ -110,6 +110,8 @@ async def init(serial: str = "", ctx: Context = CurrentContext()):
 
     logger.info("read uiautomator2 init command stdio")
 
+    ctx = get_context()
+
     while True:
         tag, line = await output_queue.get()
 
@@ -156,10 +158,10 @@ async def connect(serial: str = ""):
 
     if serial := serial.strip():
         try:
-            async with get_device(serial) as device:
+            async with get_device(serial) as device_1:
                 # Found, then check if it's still connected
                 try:
-                    return await asyncio.to_thread(lambda: device.device_info | device.info)
+                    return await asyncio.to_thread(lambda: device_1.device_info | device_1.info)
                 except u2.ConnectError as e:
                     # Found, but not connected, delete it
                     logger.warning("Device %s is no longer connected, delete it!", serial)
@@ -172,6 +174,8 @@ async def connect(serial: str = ""):
     # make new connection here!
     async with _device_connect_lock:
         device = await asyncio.to_thread(u2.connect, serial)
+        if device is None:
+            raise RuntimeError("Cannot connect to device")
         logger.info("Connected to device %s", device.serial)
         result = await asyncio.to_thread(lambda: device.device_info | device.info)
         _devices[device.serial] = asyncio.Semaphore(), device
@@ -287,4 +291,3 @@ async def info(serial: str) -> dict[str, Any]:
 
     async with get_device(serial) as device:
         return await asyncio.to_thread(lambda: device.info)
-

uiautomator2_mcp_server-0.1.2.dist-info/METADATA

@@ -0,0 +1,113 @@
+Metadata-Version: 2.4
+Name: uiautomator2-mcp-server
+Version: 0.1.2
+Summary: uiautomator2 mcp server
+Author-email: tanbro <tanbro@163.com>
+License-Expression: GPL-3.0-or-later
+Project-URL: homepage, https://github.com/tanbro/uiautomator2-mcp-server
+Project-URL: documentation, https://github.com/tanbro/uiautomator2-mcp-server/blob/main/README.md
+Project-URL: repository, https://github.com/tanbro/uiautomator2-mcp-server.git
+Project-URL: issues, https://github.com/tanbro/uiautomator2-mcp-server/issues
+Project-URL: changelog, https://github.com/tanbro/uiautomator2-mcp-server/blob/main/CHANGELOG.md
+Keywords: uiautomator2,mcp,fastmcp,adb,android,adbutils
+Classifier: Development Status :: 4 - Beta
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: fastmcp<3.0,>=2.11.0
+Requires-Dist: uiautomator2<4.0,>=3.5
+Dynamic: license-file
+
+# uiautomator2-mcp-server
+
+[![GitHub Tag](https://img.shields.io/github/v/tag/tanbro/uiautomator2-mcp-server)](https://github.com/tanbro/uiautomator2-mcp-server)
+[![PyPI - Version](https://img.shields.io/pypi/v/uiautomator2-mcp-server)](https://pypi.org/project/uiautomator2-mcp-server/)
+
+A MCP (Model Context Protocol) server that provides tools for controlling and interacting with Android devices using uiautomator2. This server allows you to perform various operations on Android devices such as connecting to devices, taking screenshots, getting device information, accessing UI hierarchy, tap on screens, and more.
+
+## Features
+
+- **Device Management**: List connected devices, initialize devices, connect/disconnect from devices
+- **Screen Operations**: Take screenshots, get device window size, dump UI hierarchy
+- **Touch Actions**: Click, long click, double click at specific coordinates
+- **Gesture Controls**: Swipe, swipe through multiple points, drag operations
+- **System Controls**: Screen on/off, key presses
+- **App Management**: Install, uninstall, start, stop, clear, and manage Android applications
+- **Text Operations**: Send text input, clear text fields
+
+## Requirements
+
+- Python >= 3.11
+- adb executable in your PATH
+- Android device connected in debug mode
+
+## Installation
+
+```bash
+# Install the package
+pip install uiautomator2-mcp-server
+```
+
+## Usage
+
+### Running the Server
+
+The server can be run in different transport modes:
+
+```bash
+# Run in streamable HTTP mode
+u2mcp --host 0.0.0.0 --port 8000 --no-token http
+
+# Run in stdio mode
+u2mcp stdio
+```
+
+### Using the Tools
+
+Connect it to any tool that supports MCP protocol.
+
+## Available Tools
+
+### Device Management
+- `device_list`: Get list of connected devices
+- `init`: Install essential resources to device
+- `connect`, `disconnect`, `disconnect_all`: Manage device connections
+- `info`: Get device information
+- `window_size`: Get device window size
+- `screenshot`: Take device screenshot
+- `dump_hierarchy`: Get UI hierarchy of device
+
+### Action Tools
+- `click`: Click at specific coordinates
+- `long_click`: Long click at specific coordinates
+- `double_click`: Double click at specific coordinates
+- `swipe`: Swipe from one point to another
+- `swipe_points`: Swipe through multiple points
+- `drag`: Drag from one point to another
+- `press_key`: Press device key
+- `send_text`: Send text to device
+- `clear_text`: Clear text input
+- `screen_on`/`screen_off`: Control screen state
+
+### App Management
+- `app_install`: Install an app
+- `app_uninstall`: Uninstall an app
+- `app_uninstall_all`: Uninstall all apps
+- `app_start`: Start an app
+- `app_stop`: Stop an app
+- `app_stop_all`: Stop all apps
+- `app_clear`: Clear app data
+- `app_info`: Get app information
+- `app_current`: Get current app
+- `app_list`: List installed apps
+- `app_list_running`: List running apps
+- `app_auto_grant_permissions`: Auto grant permissions
+
+## License
+
+This project is licensed under the GNU General Public License v3.0 (GPL-3.0).

uiautomator2_mcp_server-0.1.2.dist-info/RECORD

@@ -0,0 +1,16 @@
+u2mcp/.gitignore,sha256=mr9Izcwvjgv215xjRKhWEZ7vsyrKWhMqvWjSLHRYDjk,13
+u2mcp/__init__.py,sha256=xsioVkbaN9sg-us_kNMeH-DojD8xM-h6Nlhde6uRHCQ,104
+u2mcp/__main__.py,sha256=CBZpaNarWiWkg-g-BCfwFxaMdP4EqG5ckHtc-ZMMwcE,2813
+u2mcp/_version.py,sha256=UPabfftDNarXNRt7p9IXx9_aYhCVscDiY35GxOcfT8s,738
+u2mcp/mcp.py,sha256=jP87QaNePDt3LGzdZnlI5W8r8P-I0NrH3Tyj336ZQO8,2017
+u2mcp/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+u2mcp/tools/__init__.py,sha256=tKfsoF6tYQSapfGC1ybEcU4S77cipyfO5tYR6u0eAlI,66
+u2mcp/tools/action.py,sha256=A9dCED1NiKOJpw9lBewOQ9YQvfGOkK8bEL1L9FLjCQg,5088
+u2mcp/tools/app.py,sha256=b-cOdDtjSKC8KeUK5TTJCPRXtzvwSH74P02Cm3mS-ck,6809
+u2mcp/tools/device.py,sha256=herrj5IQ1jEav2W6K4i7UidJ7eQsg-WJCiHJD1qYKVA,9196
+uiautomator2_mcp_server-0.1.2.dist-info/licenses/LICENSE,sha256=ea2KuPdrBJ0Dhw1ncbc7siZDKG4cz2z-_8cSQiu4n1g,33122
+uiautomator2_mcp_server-0.1.2.dist-info/METADATA,sha256=9BxLeh6VjVBCtTx4S6w4YMcl2Nu7aFv8lfUJZpbk44s,4251
+uiautomator2_mcp_server-0.1.2.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+uiautomator2_mcp_server-0.1.2.dist-info/entry_points.txt,sha256=y7lg94G2U5_VgrDtyY8-Ne4ZClFtHo6eAs3RnShuDSI,92
+uiautomator2_mcp_server-0.1.2.dist-info/top_level.txt,sha256=elTNF05b2GS8jjS4Haa3ESnG6xbfRjpyoSRsivT0Uks,6
+uiautomator2_mcp_server-0.1.2.dist-info/RECORD,,

uiautomator2_mcp_server-0.1.2.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (80.9.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

{uiautomator2_mcp_server-0.1.0.dist-info → uiautomator2_mcp_server-0.1.2.dist-info}/entry_points.txt

@@ -1,3 +1,3 @@
 [console_scripts]
 u2mcp = u2mcp.__main__:main
-
+uiautomator2-mcp-server = u2mcp.__main__:main