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

u2mcp/mcp.py

@@ -1,61 +1,172 @@
-"""
-This MCP server provides tools for controlling and interacting with Android devices using uiautomator2.
-
-It 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...
-
-It also provides tools for managing Android applications, such as installing, uninstalling, starting, stopping, and clearing applications.
-
-Before performing operations on a device, you need to initialize it using the init tool.
-
-All operations require a device serial number to identify the target device.
-"""
-
-from contextlib import asynccontextmanager
-from textwrap import dedent
-from typing import Any
-
-from fastmcp import FastMCP
-from fastmcp.server.auth import AccessToken, AuthProvider
-from rich.console import Console
-from rich.markdown import Markdown
-
-__all__ = ["mcp"]
-
-_params: dict[str, Any] = {}
-
-
-def update_params(**kwargs):
-    global _params
-    _params.update(kwargs)
-
-
-@asynccontextmanager
-async def _lifespan(instance: FastMCP):
-    if _params.get("transport") == "http" and (token := _params.get("token")):
-        content = dedent(f"""
-        ------
-
-        **Server configured with authentication token. Connect using this token in the Authorization header:**
-
-        `Authorization: Bearer {token}`
-
-        ------
-        """).strip()
-        Console().print(Markdown(content))
-
-    yield
-
-
-class _SimpleTokenAuthProvider(AuthProvider):
-    _scopes = ["mcp:tools"]
-
-    async def verify_token(self, token: str) -> AccessToken | None:
-        if server_token := _params.get("token"):
-            if token == server_token:
-                return AccessToken(token=token, client_id="user", scopes=self._scopes)
-            return None
-        return AccessToken(token=token, client_id="user", scopes=self._scopes)
-
-
-mcp = FastMCP(name="uiautomator2", instructions=__doc__, lifespan=_lifespan, auth=_SimpleTokenAuthProvider())
+"""
+This MCP server provides tools for controlling and interacting with Android devices using uiautomator2.
+
+It 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...
+
+It also provides tools for managing Android applications, such as installing, uninstalling, starting, stopping, and clearing applications.
+
+Before performing operations on a device, you need to initialize it using the init tool.
+
+All operations require a device serial number to identify the target device.
+"""
+
+from __future__ import annotations
+
+import fnmatch
+import sys
+from contextlib import asynccontextmanager
+from functools import partial
+from textwrap import dedent
+from typing import Any
+
+from anyio import create_task_group
+from fastmcp import FastMCP
+from fastmcp.server.auth import AccessToken, AuthProvider
+from pydantic import AnyHttpUrl
+from rich.console import Console
+from rich.markdown import Markdown
+
+from .background import set_background_task_group
+from .helpers import print_tags
+from .middlewares import EmptyResponseMiddleware
+
+if sys.version_info >= (3, 12):  # qa: noqa
+    from typing import override
+else:  # qa: noqa
+    from typing_extensions import override
+
+__all__ = ["mcp", "make_mcp"]
+
+
+# Warning: You can NOT import it unless call `make_mcp()`
+mcp: FastMCP
+
+
+def _parse_tags(tags: str | None) -> set[str] | None:
+    """Parse comma-separated tags string into a set."""
+    if not tags:
+        return None
+    return {tag.strip() for tag in tags.split(",") if tag.strip()}
+
+
+def _expand_wildcards(tags: set[str] | None, all_available_tags: set[str] | None) -> set[str] | None:
+    """Expand wildcard patterns in tags.
+
+    Supports:
+    - *  matches any characters
+    - ?  matches exactly one character
+    - device:*  matches all device:* tags
+    - *:shell  matches all shell tags (device:shell, etc.)
+
+    Examples:
+        device:* -> device:manage, device:info, device:capture, device:shell
+        *:shell -> device:shell
+        action:to* -> action:touch, action:tool (if exists)
+    """
+    if not tags or not all_available_tags:
+        return None
+
+    expanded = set()
+
+    for tag in tags:
+        if "*" in tag or "?" in tag:
+            # Use fnmatch for wildcard matching
+            for existing_tag in all_available_tags:
+                if fnmatch.fnmatch(existing_tag, tag):
+                    expanded.add(existing_tag)
+        else:
+            # No wildcard, add as-is
+            expanded.add(tag)
+
+    return expanded if expanded else None
+
+
+@asynccontextmanager
+async def _lifespan(instance: FastMCP, /, show_tags: bool = True, token: str | None = None):
+    console = Console(stderr=True)
+
+    # Show enabled tags and tools if requested
+    if show_tags:
+        console.print("\n[bold cyan]Enabled Tags and Tools:[/bold cyan]")
+        await print_tags(instance, console)
+        console.print("")
+
+    if token:
+        content = Markdown(
+            dedent(f"""
+            ------
+
+            Server configured with **authentication token**. Connect using this token in the Authorization header:
+
+            `Authorization: Bearer {token}`
+
+            ------
+            """)
+        )
+        console.print(content)
+
+    # Global task group for background tasks - keeps running until server shuts down
+    async with create_task_group() as tg:
+        set_background_task_group(tg)
+        yield
+
+
+class _SimpleTokenAuthProvider(AuthProvider):
+    @override
+    def __init__(
+        self,
+        base_url: AnyHttpUrl | str | None = None,
+        required_scopes: list[str] | None = ["mcp:tools"],
+        token: str | None = None,
+    ):
+        super().__init__(base_url, required_scopes)
+        self.token = token
+
+    @override
+    async def verify_token(self, token: str) -> AccessToken | None:
+        if self.token == token:
+            return AccessToken(token=token, client_id="user", scopes=self.required_scopes)
+        return None
+
+
+def make_mcp(
+    token: str | None = None,
+    include_tags: str | None = None,
+    exclude_tags: str | None = None,
+    show_tags: bool = False,
+    fix_empty_responses: bool = False,
+) -> FastMCP:
+    global mcp
+    params: dict[str, Any] = dict(name="uiautomator2", instructions=__doc__)
+    lifespan_kwargs: dict[str, Any] = {"show_tags": show_tags}
+    if token:
+        lifespan_kwargs["token"] = token
+        params.update(lifespan=partial(_lifespan, **lifespan_kwargs), auth=_SimpleTokenAuthProvider(token=token))
+    else:
+        params.update(lifespan=partial(_lifespan, **lifespan_kwargs))
+    mcp = FastMCP(**params)
+
+    # Add middleware to fix empty responses if enabled
+    if fix_empty_responses:
+        mcp.add_middleware(EmptyResponseMiddleware())
+
+    # Import tools to register them with the MCP (needed for wildcard expansion)
+    from . import tools as _  # noqa: F401
+
+    # Collect all available tags from registered tools for wildcard expansion
+    all_tag_set: set[str] = set()
+    for tool in mcp._tool_manager._tools.values():
+        all_tag_set.update(tool.tags or [])
+
+    # Parse and expand tag filters
+    parsed_include_tags = _expand_wildcards(_parse_tags(include_tags), all_tag_set)
+    parsed_exclude_tags = _expand_wildcards(_parse_tags(exclude_tags), all_tag_set)
+
+    # Set tag filters on the MCP instance
+    if parsed_include_tags is not None:
+        mcp.include_tags = parsed_include_tags
+    if parsed_exclude_tags is not None:
+        mcp.exclude_tags = parsed_exclude_tags
+
+    return mcp

u2mcp/middlewares.py

@@ -0,0 +1,40 @@
+"""Middleware to fix empty responses for Zhipu AI compatibility."""
+
+from __future__ import annotations
+
+from fastmcp.server.middleware.middleware import CallNext, Middleware, MiddlewareContext
+from fastmcp.tools.tool import ToolResult
+from mcp.types import CallToolRequestParams, TextContent
+
+
+class EmptyResponseMiddleware(Middleware):
+    """Middleware that converts empty tool responses to non-empty values.
+
+    This is needed for compatibility with ZhiPu AI model service, which doesn't handle empty responses (content: []) correctly.
+
+    When enabled, this middleware will convert empty content to "" (empty string).
+    """
+
+    async def on_call_tool(
+        self,
+        context: MiddlewareContext[CallToolRequestParams],
+        call_next: CallNext[CallToolRequestParams, ToolResult],
+    ) -> ToolResult:
+        """Intercept tool calls and fix empty responses."""
+        result = await call_next(context)
+
+        # Convert empty content to empty string for ZhiPu compatibility
+        if isinstance(result, ToolResult):
+            if not result.content:
+                # Empty content - return empty string
+                result.content = [TextContent(type="text", text="")]
+            elif (
+                isinstance(result.content, list)
+                and len(result.content) == 1
+                and isinstance(result.content[0], dict)
+                and not result.content[0].get("text")
+            ):
+                # Missing/empty text - set to empty string
+                result.content[0]["text"] = ""
+
+        return result

u2mcp/tools/__init__.py

@@ -1,3 +1,8 @@
-from .action import *
-from .app import *
-from .device import *
+from .action import *
+from .app import *
+from .clipboard import *
+from .device import *
+from .element import *
+from .input import *
+from .misc import *
+from .scrcpy import *

u2mcp/tools/action.py

@@ -1,169 +1,143 @@
-from __future__ import annotations
-
-import asyncio
-
-from ..mcp import mcp
-from .device import get_device
-
-__all__ = (
-    "click",
-    "long_click",
-    "double_click",
-    "swipe",
-    "swipe_points",
-    "drag",
-    "press_key",
-    "send_text",
-    "clear_text",
-    "screen_on",
-    "screen_off",
-)
-
-
-@mcp.tool("click")
-async def click(serial: str, x: int, y: int):
-    """Click at specific coordinates
-
-    Args:
-        serial (str): Android device serialno
-        x (int): X coordinate
-        y (int): Y coordinate
-    """
-    async with get_device(serial) as device:
-        await asyncio.to_thread(device.click, x, y)
-
-
-@mcp.tool("long_click")
-async def long_click(serial: str, x: int, y: int, duration: float = 0.5):
-    """Long click at specific coordinates
-
-    Args:
-        serial (str): Android device serialno
-        x (int): X coordinate
-        y (int): Y coordinate
-        duration (float): Duration of the long click in seconds, default is 0.5
-    """
-    async with get_device(serial) as device:
-        await asyncio.to_thread(device.long_click, x, y, duration)
-
-
-@mcp.tool("double_click")
-async def double_click(serial: str, x: int, y: int, duration: float = 0.1):
-    """Double click at specific coordinates
-
-    Args:
-        serial (str): Android device serialno
-        x (int): X coordinate
-        y (int): Y coordinate
-        duration (float): Duration between clicks in seconds, default is 0.1
-    """
-    async with get_device(serial) as device:
-        await asyncio.to_thread(device.double_click, x, y, duration)
-
-
-@mcp.tool("swipe")
-async def swipe(serial: str, fx: int, fy: int, tx: int, ty: int, duration: float = 0.0, step: int = 0):
-    """Swipe from one point to another
-
-    Args:
-        serial (str): Android device serialno
-        fx (int): From position X coordinate
-        fy (int): From position Y coordinate
-        tx (int): To position X coordinate
-        ty (int): To position Y coordinate
-        duration (float): duration
-        steps: 1 steps is about 5ms, if set, duration will be ignore
-    """
-    async with get_device(serial) as device:
-        await asyncio.to_thread(device.swipe, fx, fy, tx, ty, duration if duration > 0 else None, step if step > 0 else None)
-
-
-@mcp.tool("swipe_points")
-async def swipe_points(serial: str, points: list[tuple[int, int]], duration: float = 0.5):
-    """Swipe through multiple points
-
-    Args:
-        serial (str): Android device serialno
-        points (list[tuple[int, int]]): List of (x, y) coordinates to swipe through
-        duration (float): Duration of swipe in seconds, default is 0.5
-    """
-    async with get_device(serial) as device:
-        await asyncio.to_thread(device.swipe_points, points, duration)
-
-
-@mcp.tool("drag")
-async def drag(serial: str, sx: int, sy: int, ex: int, ey: int, duration: float = 0.5):
-    """Swipe from one point to another point.
-
-    Args:
-        serial (str): Android device serialno
-        sx (int): Start X coordinate
-        sy (int): Start Y coordinate
-        ex (int): End X coordinate
-        ey (int): End Y coordinate
-        duration (float): Duration of drag in seconds, default is 0.5
-    """
-    async with get_device(serial) as device:
-        await asyncio.to_thread(device.drag, sx, sy, ex, ey, duration)
-
-
-@mcp.tool("press_key")
-async def press_key(serial: str, key: str):
-    """Press a key
-
-    Args:
-        serial (str): Android device serialno
-        key (str): Key to press.
-            Supported key name includes:
-            home, back, left, right, up, down, center, menu, search, enter,
-            delete(or del), recent(recent apps), volume_up, volume_down,
-            volume_mute, camera, power
-    """
-    async with get_device(serial) as device:
-        await asyncio.to_thread(device.press, key)
-
-
-@mcp.tool("send_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 asyncio.to_thread(device.send_keys, text, clear)
-
-
-@mcp.tool("clear_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 asyncio.to_thread(device.clear_text)
-
-
-@mcp.tool("screen_on")
-async def screen_on(serial: str):
-    """Turn screen on
-
-    Args:
-        serial (str): Android device serialno
-    """
-    async with get_device(serial) as device:
-        await asyncio.to_thread(device.screen_on)
-
-
-@mcp.tool("screen_off")
-async def screen_off(serial: str):
-    """Turn screen off
-
-    Args:
-        serial (str): Android device serialno
-    """
-    async with get_device(serial) as device:
-        await asyncio.to_thread(device.screen_off)
+from __future__ import annotations
+
+from anyio import to_thread
+
+from ..mcp import mcp
+from .device import get_device
+
+__all__ = (
+    "click",
+    "long_click",
+    "double_click",
+    "swipe",
+    "swipe_points",
+    "drag",
+    "press_key",
+    "screen_on",
+    "screen_off",
+)
+
+
+@mcp.tool("click", tags={"action:touch"})
+async def click(serial: str, x: int, y: int):
+    """Click at specific coordinates
+
+    Args:
+        serial (str): Android device serialno
+        x (int): X coordinate
+        y (int): Y coordinate
+    """
+    async with get_device(serial) as device:
+        await to_thread.run_sync(device.click, x, y)
+
+
+@mcp.tool("long_click", tags={"action:touch"})
+async def long_click(serial: str, x: int, y: int, duration: float = 0.5):
+    """Long click at specific coordinates
+
+    Args:
+        serial (str): Android device serialno
+        x (int): X coordinate
+        y (int): Y coordinate
+        duration (float): Duration of the long click in seconds, default is 0.5
+    """
+    async with get_device(serial) as device:
+        await to_thread.run_sync(device.long_click, x, y, duration)
+
+
+@mcp.tool("double_click", tags={"action:touch"})
+async def double_click(serial: str, x: int, y: int, duration: float = 0.1):
+    """Double click at specific coordinates
+
+    Args:
+        serial (str): Android device serialno
+        x (int): X coordinate
+        y (int): Y coordinate
+        duration (float): Duration between clicks in seconds, default is 0.1
+    """
+    async with get_device(serial) as device:
+        await to_thread.run_sync(device.double_click, x, y, duration)
+
+
+@mcp.tool("swipe", tags={"action:gesture"})
+async def swipe(serial: str, fx: int, fy: int, tx: int, ty: int, duration: float = 0.0, step: int = 0):
+    """Swipe from one point to another
+
+    Args:
+        serial (str): Android device serialno
+        fx (int): From position X coordinate
+        fy (int): From position Y coordinate
+        tx (int): To position X coordinate
+        ty (int): To position Y coordinate
+        duration (float): duration
+        steps: 1 steps is about 5ms, if set, duration will be ignore
+    """
+    async with get_device(serial) as device:
+        await to_thread.run_sync(device.swipe, fx, fy, tx, ty, duration if duration > 0 else None, step if step > 0 else None)
+
+
+@mcp.tool("swipe_points", tags={"action:gesture"})
+async def swipe_points(serial: str, points: list[tuple[int, int]], duration: float = 0.5):
+    """Swipe through multiple points
+
+    Args:
+        serial (str): Android device serialno
+        points (list[tuple[int, int]]): List of (x, y) coordinates to swipe through
+        duration (float): Duration of swipe in seconds, default is 0.5
+    """
+    async with get_device(serial) as device:
+        await to_thread.run_sync(device.swipe_points, points, duration)
+
+
+@mcp.tool("drag", tags={"action:gesture"})
+async def drag(serial: str, sx: int, sy: int, ex: int, ey: int, duration: float = 0.5):
+    """Swipe from one point to another point.
+
+    Args:
+        serial (str): Android device serialno
+        sx (int): Start X coordinate
+        sy (int): Start Y coordinate
+        ex (int): End X coordinate
+        ey (int): End Y coordinate
+        duration (float): Duration of drag in seconds, default is 0.5
+    """
+    async with get_device(serial) as device:
+        await to_thread.run_sync(device.drag, sx, sy, ex, ey, duration)
+
+
+@mcp.tool("press_key", tags={"action:key"})
+async def press_key(serial: str, key: str):
+    """Press a key
+
+    Args:
+        serial (str): Android device serialno
+        key (str): Key to press.
+            Supported key name includes:
+            home, back, left, right, up, down, center, menu, search, enter,
+            delete(or del), recent(recent apps), volume_up, volume_down,
+            volume_mute, camera, power
+    """
+    async with get_device(serial) as device:
+        await to_thread.run_sync(device.press, key)
+
+
+@mcp.tool("screen_on", tags={"action:screen"})
+async def screen_on(serial: str):
+    """Turn screen on
+
+    Args:
+        serial (str): Android device serialno
+    """
+    async with get_device(serial) as device:
+        await to_thread.run_sync(device.screen_on)
+
+
+@mcp.tool("screen_off", tags={"action:screen"})
+async def screen_off(serial: str):
+    """Turn screen off
+
+    Args:
+        serial (str): Android device serialno
+    """
+    async with get_device(serial) as device:
+        await to_thread.run_sync(device.screen_off)