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

u2mcp/mcp.py

@@ -11,23 +11,31 @@ Before performing operations on a device, you need to initialize it using the in
 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
 
-if sys.version_info >= (3, 12):  # qa: noqa
-    from typing import override
-else:  # qa: noqa
-    from typing_extensions import override
-
+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"]
 
 
@@ -35,21 +43,73 @@ __all__ = ["mcp", "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, token: str | None):
-    content = Markdown(
-        dedent(f"""
-        ------
+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:
 
-        Server configured with **authentication token**. Connect using this token in the Authorization header:
+            `Authorization: Bearer {token}`
 
-        `Authorization: Bearer {token}`
+            ------
+            """)
+        )
+        console.print(content)
 
-        ------
-        """)
-    )
-    Console(stderr=True).print(content)
-    yield
+    # 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):
@@ -70,10 +130,43 @@ class _SimpleTokenAuthProvider(AuthProvider):
         return None
 
 
-def make_mcp(token: str | None = None) -> FastMCP:
+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:
-        params.update(lifespan=partial(_lifespan, token=token), auth=_SimpleTokenAuthProvider(token=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,4 +1,8 @@
 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

@@ -13,14 +13,12 @@ __all__ = (
     "swipe_points",
     "drag",
     "press_key",
-    "send_text",
-    "clear_text",
     "screen_on",
     "screen_off",
 )
 
 
-@mcp.tool("click")
+@mcp.tool("click", tags={"action:touch"})
 async def click(serial: str, x: int, y: int):
     """Click at specific coordinates
 
@@ -33,7 +31,7 @@ async def click(serial: str, x: int, y: int):
         await to_thread.run_sync(device.click, x, y)
 
 
-@mcp.tool("long_click")
+@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
 
@@ -47,7 +45,7 @@ async def long_click(serial: str, x: int, y: int, duration: float = 0.5):
         await to_thread.run_sync(device.long_click, x, y, duration)
 
 
-@mcp.tool("double_click")
+@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
 
@@ -61,7 +59,7 @@ async def double_click(serial: str, x: int, y: int, duration: float = 0.1):
         await to_thread.run_sync(device.double_click, x, y, duration)
 
 
-@mcp.tool("swipe")
+@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
 
@@ -78,7 +76,7 @@ async def swipe(serial: str, fx: int, fy: int, tx: int, ty: int, duration: float
         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")
+@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
 
@@ -91,7 +89,7 @@ async def swipe_points(serial: str, points: list[tuple[int, int]], duration: flo
         await to_thread.run_sync(device.swipe_points, points, duration)
 
 
-@mcp.tool("drag")
+@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.
 
@@ -107,7 +105,7 @@ async def drag(serial: str, sx: int, sy: int, ex: int, ey: int, duration: float
         await to_thread.run_sync(device.drag, sx, sy, ex, ey, duration)
 
 
-@mcp.tool("press_key")
+@mcp.tool("press_key", tags={"action:key"})
 async def press_key(serial: str, key: str):
     """Press a key
 
@@ -123,31 +121,7 @@ async def press_key(serial: str, key: str):
         await to_thread.run_sync(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 to_thread.run_sync(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 to_thread.run_sync(device.clear_text)
-
-
-@mcp.tool("screen_on")
+@mcp.tool("screen_on", tags={"action:screen"})
 async def screen_on(serial: str):
     """Turn screen on
 
@@ -158,7 +132,7 @@ async def screen_on(serial: str):
         await to_thread.run_sync(device.screen_on)
 
 
-@mcp.tool("screen_off")
+@mcp.tool("screen_off", tags={"action:screen"})
 async def screen_off(serial: str):
     """Turn screen off
 

u2mcp/tools/app.py

@@ -23,7 +23,7 @@ __all__ = (
 )
 
 
-@mcp.tool("app_install")
+@mcp.tool("app_install", tags={"app:manage"})
 async def app_install(serial: str, data: str):
     """Install app
 
@@ -35,7 +35,7 @@ async def app_install(serial: str, data: str):
         await to_thread.run_sync(device.app_install, data)
 
 
-@mcp.tool("app_uninstall")
+@mcp.tool("app_uninstall", tags={"app:manage"})
 async def app_uninstall(serial: str, package_name: str) -> bool:
     """Uninstall an app
 
@@ -50,7 +50,7 @@ async def app_uninstall(serial: str, package_name: str) -> bool:
         return await to_thread.run_sync(device.app_uninstall, package_name)
 
 
-@mcp.tool("app_uninstall_all")
+@mcp.tool("app_uninstall_all", tags={"app:manage"})
 async def app_uninstall_all(serial: str, excludes: list[str] | None = None) -> list[str]:
     """Uninstall all apps
 
@@ -65,7 +65,7 @@ async def app_uninstall_all(serial: str, excludes: list[str] | None = None) -> l
         return await to_thread.run_sync(device.app_uninstall_all, excludes or [])
 
 
-@mcp.tool("app_start")
+@mcp.tool("app_start", tags={"app:lifecycle"})
 async def app_start(
     serial: str,
     package_name: str,
@@ -86,7 +86,7 @@ async def app_start(
         await to_thread.run_sync(device.app_start, package_name, activity, wait, stop)
 
 
-@mcp.tool("app_wait")
+@mcp.tool("app_wait", tags={"app:lifecycle"})
 async def app_wait(serial: str, package_name: str, timeout: float = 20.0, front=False):
     """Wait until app launched
 
@@ -101,7 +101,7 @@ async def app_wait(serial: str, package_name: str, timeout: float = 20.0, front=
             raise RuntimeError(f"Failed to wait App {package_name} to launch")
 
 
-@mcp.tool("app_stop")
+@mcp.tool("app_stop", tags={"app:lifecycle"})
 async def app_stop(serial: str, package_name: str):
     """Stop one application
 
@@ -113,7 +113,7 @@ async def app_stop(serial: str, package_name: str):
         await to_thread.run_sync(device.app_stop, package_name)
 
 
-@mcp.tool("app_stop_all")
+@mcp.tool("app_stop_all", tags={"app:lifecycle"})
 async def app_stop_all(serial: str, excludes: list[str] | None = None) -> list[str]:
     """Stop all third party applications
 
@@ -127,7 +127,7 @@ async def app_stop_all(serial: str, excludes: list[str] | None = None) -> list[s
         return await to_thread.run_sync(device.app_stop_all, excludes or [])
 
 
-@mcp.tool("app_clear")
+@mcp.tool("app_clear", tags={"app:config"})
 async def app_clear(serial: str, package_name: str):
     """Stop and clear app data: pm clear
 
@@ -142,7 +142,7 @@ async def app_clear(serial: str, package_name: str):
         await to_thread.run_sync(device.app_clear, package_name)
 
 
-@mcp.tool("app_info")
+@mcp.tool("app_info", tags={"app:info"})
 async def app_info(serial: str, package_name: str) -> dict[str, Any]:
     """
     Get app info
@@ -161,7 +161,7 @@ async def app_info(serial: str, package_name: str) -> dict[str, Any]:
         return await to_thread.run_sync(device.app_info, package_name)
 
 
-@mcp.tool("app_current")
+@mcp.tool("app_current", tags={"app:info"})
 async def app_current(serial: str) -> dict[str, Any]:
     """
     Get current app info
@@ -176,7 +176,7 @@ async def app_current(serial: str) -> dict[str, Any]:
         return await to_thread.run_sync(device.app_current)
 
 
-@mcp.tool("app_list")
+@mcp.tool("app_list", tags={"app:info"})
 async def app_list(serial: str, filter: str = "") -> list[str]:
     """
     List installed app package names
@@ -192,7 +192,7 @@ async def app_list(serial: str, filter: str = "") -> list[str]:
         return await to_thread.run_sync(device.app_list, filter.strip())
 
 
-@mcp.tool("app_list_running")
+@mcp.tool("app_list_running", tags={"app:info"})
 async def app_list_running(serial: str) -> list[str]:
     """
     List running apps
@@ -207,7 +207,7 @@ async def app_list_running(serial: str) -> list[str]:
         return await to_thread.run_sync(device.app_list_running)
 
 
-@mcp.tool("app_auto_grant_permissions")
+@mcp.tool("app_auto_grant_permissions", tags={"app:config"})
 async def app_auto_grant_permissions(serial: str, package_name: str):
     """auto grant permissions
 

u2mcp/tools/clipboard.py

@@ -0,0 +1,35 @@
+from __future__ import annotations
+
+from anyio import to_thread
+
+from ..mcp import mcp
+from .device import get_device
+
+__all__ = ("read_clipboard", "write_clipboard")
+
+
+@mcp.tool("read_clipboard", tags={"clipboard:read"})
+async def read_clipboard(serial: str) -> str | None:
+    """Read clipboard from device
+
+    Args:
+        serial (str): Android device serialno
+
+    Returns:
+        str: The actual text in the clip.
+        None: If there is no text in the clip.
+    """
+    async with get_device(serial) as device:
+        return await to_thread.run_sync(lambda: device.clipboard)
+
+
+@mcp.tool("write_clipboard", tags={"clipboard:write"})
+async def write_clipboard(serial: str, text: str):
+    """Write clipboard to device
+
+    Args:
+        serial (str): Android device serialno
+        text: The actual text in the clip.
+    """
+    async with get_device(serial) as device:
+        await to_thread.run_sync(device.set_clipboard, text)