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

u2mcp/.gitignore

@@ -1 +1 @@
-_version.py
+version.py

u2mcp/__init__.py

@@ -1,2 +1 @@
-from . import _version as version
-from ._version import __commit_id__, __version__, __version_tuple__
+from .version import __commit_id__, __version__, __version_tuple__

u2mcp/__main__.py

@@ -1,82 +1,193 @@
-from __future__ import annotations
-
-import logging
-import re
-import secrets
-from typing import Annotated, Any, Literal
-
-import typer
-
-
-def run(
-    transport: Annotated[
-        Literal["http", "stdio"], typer.Argument(help="Run mcp server on streamable-http http or stdio transport")
-    ] = "stdio",
-    host: Annotated[
-        str, typer.Option("--host", "-H", show_default=False, help="Host address of streamable-http transport")
-    ] = "127.0.0.1",
-    port: Annotated[
-        int, typer.Option("--port", "-p", show_default=False, help="Port number of streamable-http transport")
-    ] = 8000,
-    json_response: Annotated[bool, typer.Option("--json-response", "-j", help="Whether to use JSON response format")] = True,
-    log_level: Annotated[
-        Literal["debug", "info", "warning", "error", "critical"], typer.Option("--log-level", "-l", help="Log level")
-    ] = "info",
-    no_token: Annotated[
-        bool,
-        typer.Option(
-            "--no-token",
-            help="Disable authentication bearer token verification of streamable-http transport. If not set, a token will be generated randomly.",
-        ),
-    ] = False,
-    token: Annotated[
-        str | None,
-        typer.Option("--token", "-t", help="Explicit set token of streamable-http authentication"),
-    ] = None,
-):
-    """Run uiautomator2 mcp server"""
-    logging.basicConfig(
-        level=log_level.upper(),
-        format="[%(asctime)s] %(levelname)s %(name)s - %(message)s",
-        handlers=[logging.StreamHandler()],
-        force=True,
-    )
-
-    logging.getLogger("mcp.server").setLevel(logging.WARNING)
-    logging.getLogger("sse_starlette").setLevel(logging.WARNING)
-    logging.getLogger("docket").setLevel(logging.WARNING)
-    logging.getLogger("fakeredis").setLevel(logging.WARNING)
-
-    from . import tools as _
-    from .mcp import mcp, update_params
-
-    transport_kwargs: dict[str, Any] = {"json_response": json_response}
-
-    update_params(transport=transport)
-
-    if transport == "http":
-        if token:
-            token = token.strip()
-            if not re.match(r"^[a-zA-Z0-9\-_.~!$&'()*+,;=:@]{8,64}$", token):
-                raise typer.BadParameter("Token must be 8-64 characters long and can only contain URL-safe characters")
-        elif not no_token:
-            token = secrets.token_urlsafe()
-        if token:
-            update_params(token=token, host=host, port=port)
-
-        if host:
-            transport_kwargs["host"] = host
-        if port:
-            transport_kwargs["port"] = port
-
-        mcp.run(transport="streamable-http", **transport_kwargs, log_level=log_level)
-    else:
-        mcp.run(log_level=log_level)
-
-
-def main():
-    typer.run(run)
-
-
-if __name__ == "__main__":
-    main()
+from __future__ import annotations
+
+import logging
+import re
+import secrets
+import sys
+from typing import Annotated, Any, Literal
+
+import anyio
+from cyclopts import App, Group, Parameter
+from cyclopts.exceptions import ValidationError
+from rich.console import Console
+
+from .health import check_adb
+from .helpers import print_tags as print_tags_from_mcp
+from .helpers import print_tool_help
+from .mcp import make_mcp
+from .version import __version__
+
+
+def _version_callback() -> str:
+    """Return version information."""
+    return f"{__name__} {__version__} (Python {sys.version})"
+
+
+# Organize commands into groups
+server_group = Group("Server Commands")
+info_group = Group("Information Commands")
+
+# Create CLI app with cyclopts
+app = App(name="u2mcp", help="uiautomator2-mcp-server - MCP server for Android device automation", version=_version_callback())
+
+
+def _setup_logging(log_level: Literal["debug", "info", "warning", "error", "critical"]) -> None:
+    """Configure logging for the MCP server."""
+    logging.basicConfig(
+        level=log_level.upper(),
+        format="[%(asctime)s] %(levelname)8s %(name)s - %(message)s",
+        handlers=[logging.StreamHandler()],
+        force=True,
+    )
+    logging.getLogger("mcp.server").setLevel(logging.WARNING)
+    logging.getLogger("sse_starlette").setLevel(logging.WARNING)
+    logging.getLogger("docket").setLevel(logging.WARNING)
+    logging.getLogger("fakeredis").setLevel(logging.WARNING)
+
+
+def _check_adb(console: Console, check: bool) -> None:
+    """Check ADB availability if enabled."""
+    if check and not check_adb(console):
+        console.print("[yellow]Proceeding anyway. Use --no-check-adb to bypass this check.[/yellow]")
+
+
+def _validate_token(token: str) -> str:
+    """Validate token format."""
+    token = token.strip()
+    if not re.match(r"^[a-zA-Z0-9\-_.~!$&'()*+,;=:@]{8,64}$", token):
+        raise ValidationError("Token must be 8-64 characters long and can only contain URL-safe characters")
+    return token
+
+
+@app.command(group=server_group)
+def stdio(
+    *,
+    check_adb: bool = True,
+    log_level: Annotated[
+        Literal["debug", "info", "warning", "error", "critical"], Parameter(name=["--log-level", "-l"])
+    ] = "info",
+    include_tags: Annotated[str | None, Parameter(name=["--include-tags", "-i"])] = None,
+    exclude_tags: Annotated[str | None, Parameter(name=["--exclude-tags", "-e"])] = None,
+    print_tags: bool = True,
+    fix_empty_responses: bool = False,
+    show_fastmcp_banner: bool = False,
+) -> None:
+    """Run the MCP server with stdio transport.
+
+    Args:
+        check_adb: Check ADB availability at startup.
+        log_level: Log level.
+        include_tags: Only expose tools with these tags (comma-separated, supports * and ? wildcards, e.g., device:*,*:shell).
+        exclude_tags: Exclude tools with these tags (comma-separated, supports * and ? wildcards, e.g., screen:*,*:mirror).
+        print_tags: Show enabled tags and tools at startup.
+        fix_empty_responses: Convert null tool responses to empty string compatibility.
+        show_fastmcp_banner: Show FastMCP banner on startup.
+    """
+    _setup_logging(log_level)
+    _check_adb(Console(stderr=True), check_adb)
+    mcp = make_mcp(
+        show_tags=print_tags, include_tags=include_tags, exclude_tags=exclude_tags, fix_empty_responses=fix_empty_responses
+    )
+    mcp.run("stdio", show_fastmcp_banner, log_level=log_level)
+
+
+@app.command(group=server_group)
+def http(
+    *,
+    host: Annotated[str | None, Parameter(name=["--host", "-H"])] = None,
+    port: Annotated[int | None, Parameter(name=["--port", "-p"])] = None,
+    token: Annotated[str | None, Parameter(name=["--token", "-t"])] = None,
+    no_token: Annotated[bool, Parameter(name=["--no-token", "-n"])] = False,
+    json_response: bool = True,
+    check_adb: bool = True,
+    log_level: Annotated[
+        Literal["debug", "info", "warning", "error", "critical"], Parameter(name=["--log-level", "-l"])
+    ] = "info",
+    include_tags: Annotated[str | None, Parameter(name=["--include-tags", "-i"])] = None,
+    exclude_tags: Annotated[str | None, Parameter(name=["--exclude-tags", "-e"])] = None,
+    print_tags: bool = True,
+    fix_empty_responses: bool = False,
+    show_fastmcp_banner: bool = False,
+) -> None:
+    """Run the MCP server with HTTP (streamable-http) transport.
+
+    Args:
+        host: Host address to bind to.
+        port: Port number to bind to.
+        token: Explicit set authentication token.
+        no_token: Disable authentication bearer token verification. If not set, a token will be generated randomly.
+        json_response: Use JSON response format.
+        check_adb: Check ADB availability at startup.
+        log_level: Log level.
+        include_tags: Only expose tools with these tags (comma-separated, supports * and ? wildcards, e.g., device:*,*:shell).
+        exclude_tags: Exclude tools with these tags (comma-separated, supports * and ? wildcards, e.g., screen:*,*:mirror).
+        print_tags: Show enabled tags and tools at startup.
+        fix_empty_responses: Convert null tool responses to empty string compatibility.
+        show_fastmcp_banner: Show FastMCP banner on startup.
+    """
+    _setup_logging(log_level)
+    _check_adb(Console(stderr=True), check_adb)
+
+    if token:
+        token = _validate_token(token)
+    elif not no_token:
+        token = secrets.token_urlsafe()
+
+    transport_kwargs: dict[str, Any] = {"json_response": json_response}
+    if host is not None:
+        transport_kwargs["host"] = host
+    if port is not None:
+        transport_kwargs["port"] = port
+
+    mcp = make_mcp(
+        token,
+        show_tags=print_tags,
+        include_tags=include_tags,
+        exclude_tags=exclude_tags,
+        fix_empty_responses=fix_empty_responses,
+    )
+    mcp.run("streamable-http", show_fastmcp_banner, **transport_kwargs)
+
+
+@app.command(group=info_group)
+def tools() -> None:
+    """List all available MCP tools."""
+    console = Console()
+    mcp = make_mcp()
+    anyio.run(lambda: print_tool_help(mcp, console, None))
+
+
+@app.command(group=info_group)
+def info(
+    tool_name: str,
+) -> None:
+    """Show detailed information about a specific tool.
+
+    Examples:
+        u2mcp info screenshot        # Show screenshot tool details
+        u2mcp info device:*          # Show all device tools
+        u2mcp info "*screenshot*"    # Show tools with 'screenshot' in name
+
+    Args:
+        tool_name: Tool name or pattern (supports * and ? wildcards).
+    """
+    console = Console()
+    mcp = make_mcp()
+    anyio.run(lambda: print_tool_help(mcp, console, tool_name))
+
+
+@app.command(group=info_group)
+def tags() -> None:
+    """List all available tool tags."""
+    console = Console()
+    mcp = make_mcp()
+    anyio.run(lambda: print_tags_from_mcp(mcp, console, filtered=False))
+
+
+def main() -> None:
+    """Entry point for the CLI."""
+    app()
+
+
+if __name__ == "__main__":
+    main()

u2mcp/background.py

@@ -0,0 +1,19 @@
+"""Global background task management for long-running tasks."""
+
+from __future__ import annotations
+
+from anyio.abc import TaskGroup
+
+# Global task group for background tasks (set by lifespan)
+_task_group: TaskGroup
+
+
+def get_background_task_group() -> TaskGroup:
+    """Get the global background task group."""
+    return _task_group
+
+
+def set_background_task_group(tg: TaskGroup) -> None:
+    """Set the global monitor task group."""
+    global _task_group
+    _task_group = tg

u2mcp/health.py

@@ -0,0 +1,67 @@
+"""Simple ADB availability check for uiautomator2 MCP server."""
+
+from __future__ import annotations
+
+import sys
+
+from rich.console import Console
+
+__all__ = ["check_adb"]
+
+
+def check_adb(console: Console | None = None) -> bool:
+    """Check if ADB is available.
+
+    Returns:
+        True if ADB is working, False otherwise.
+    """
+    if console is None:
+        console = Console(stderr=True)
+
+    try:
+        import adbutils
+
+        # Try to connect to ADB server
+        adb_server_version = adbutils.adb.server_version()
+        console.print(f"[green]✓ ADB server version: {adb_server_version}[/green]")
+        adb_device_list = adbutils.adb.device_list()
+        console.print(f"[green]✓ ADB device list:    {adb_device_list}[/green]")
+        return True
+
+    except Exception as e:
+        console.print(f"[yellow]⚠ Cannot connect to ADB: {e}[/yellow]")
+        console.print()
+
+        _print_adb_fix_help(console)
+        return False
+
+
+def _print_adb_fix_help(console: Console) -> None:
+    """Print helpful messages for fixing ADB issues."""
+    console.print("[cyan]Possible fixes:[/cyan]")
+
+    # Install ADB
+    console.print("  1. Install ADB:")
+    if sys.platform == "darwin":  # pragma: no cover
+        console.print("     [white]brew install android-platform-tools[/white]")
+    elif sys.platform == "linux":  # pragma: no cover
+        console.print("     [white]sudo apt install adb[/white]  # Debian/Ubuntu")
+        console.print("     [white]sudo yum install android-tools[/white]  # Fedora/RHEL")
+    elif sys.platform == "win32":  # pragma: no cover
+        console.print("     Download: https://developer.android.com/tools/releases/platform-tools")
+        console.print("     Or use: [white]winget install Google.PlatformTools[/white]")
+
+    # Start ADB server
+    console.print("  2. Start ADB server:")
+    console.print("     [white]adb start-server[/white]")
+
+    # Custom ADB path
+    console.print("  3. Set custom ADB path (if needed):")
+    if sys.platform == "win32":  # pragma: no cover
+        console.print("     CMD:        [white]set ADBUTILS_ADB_PATH=C:\\path\\to\\adb.exe[/white]")
+        console.print("     PowerShell: [white]$env:ADBUTILS_ADB_PATH='C:\\path\\to\\adb.exe'[/white]")
+    else:  # pragma: no cover
+        console.print("     [white]export ADBUTILS_ADB_PATH=/path/to/adb[/white]")
+
+    console.print()
+    console.print("[yellow]Proceeding anyway. Use --skip-adb-check to bypass this check.[/yellow]")

u2mcp/helpers.py

@@ -0,0 +1,222 @@
+"""Helper functions for u2mcp."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+from docstring_parser import parse
+from rich.console import Console
+from rich.markdown import Markdown
+from rich.panel import Panel
+from rich.table import Table
+
+if TYPE_CHECKING:
+    from .mcp import FastMCP
+
+
+__all__ = ["print_tags", "print_tool_help"]
+
+
+async def print_tags(instance: FastMCP, console: Console, *, filtered: bool = True):
+    """Print tags from an MCP instance.
+
+    Args:
+        instance: The MCP instance to get tools from
+        console: The Rich console to print to
+        filtered: If True, only show tags that match include/exclude filters.
+                   If False, show all available tags. Defaults to True.
+    """
+    tags_map: dict[str, list[str]] = {}
+    include_tags = getattr(instance, "include_tags", None) if filtered else None
+    exclude_tags = getattr(instance, "exclude_tags", None) if filtered else None
+
+    for tool in (await instance.get_tools()).values():
+        # Skip tools with no tags
+        if not tool.tags:
+            continue
+
+        # Apply include filter
+        if include_tags is not None and not any(tag in include_tags for tag in tool.tags):
+            continue
+
+        # Apply exclude filter
+        if exclude_tags is not None and any(tag in exclude_tags for tag in tool.tags):
+            continue
+
+        for tag in tool.tags:
+            # Only include tags that pass the filters
+            if include_tags is not None and tag not in include_tags:
+                continue
+            if exclude_tags is not None and tag in exclude_tags:
+                continue
+
+            if tag not in tags_map:
+                tags_map[tag] = []
+            tags_map[tag].append(tool.name)
+
+    # Sort tags by category
+    sorted_tags = sorted(tags_map.keys())
+
+    # Group by category
+    categories: dict[str, list[tuple[str, list[str]]]] = {}
+    for tag in sorted_tags:
+        if ":" in tag:
+            category, subcategory = tag.split(":", 1)
+            if category not in categories:
+                categories[category] = []
+            categories[category].append((subcategory, tags_map[tag]))
+        else:
+            # Tags without category (if any)
+            if "" not in categories:
+                categories[""] = []
+            categories[""].append((tag, tags_map[tag]))
+
+    # Print table for each category
+    for category in sorted(categories.keys()):
+        if category == "":
+            console.print("\n[bold]Other Tags:[/bold]")
+        else:
+            console.print(f"\n[bold]{category.title()} Tags:[/bold]")
+
+        table = Table(show_header=True, header_style="bold magenta")
+        table.add_column("Tag", style="cyan", width=20)
+        table.add_column("Tools", style="green")
+
+        for subcategory, tools in sorted(categories[category]):
+            tag_name = f"{category}:{subcategory}" if category else subcategory
+            tools_str = ", ".join(sorted(tools))
+            table.add_row(tag_name, tools_str)
+
+        console.print(table)
+
+    console.print(f"\n[bold]Total: {len(tags_map)} tags, {sum(len(v) for v in tags_map.values())} tool-tag assignments[/bold]")
+
+    # Show filter info if filters are active
+    include_tags = getattr(instance, "include_tags", None)
+    exclude_tags = getattr(instance, "exclude_tags", None)
+    if include_tags is not None or exclude_tags is not None:
+        console.print("\n[dim]Active filters:[/dim]")
+        if include_tags is not None:
+            console.print(f"  [cyan]include:[/cyan] {', '.join(sorted(include_tags))}")
+        if exclude_tags is not None:
+            console.print(f"  [cyan]exclude:[/cyan] {', '.join(sorted(exclude_tags))}")
+        console.print("\n[dim]Use --include-tags and --exclude-tags when running the server to filter available tools.[/dim]")
+
+
+async def print_tool_help(instance: FastMCP, console: Console, tool_name: str | None = None):
+    """Print help information for MCP tools.
+
+    Args:
+        instance: The MCP instance to get tools from
+        console: The Rich console to print to
+        tool_name: If specified, show help for tools matching the pattern.
+                   Can be a tool name pattern or a tag pattern (e.g., device:*).
+                   If None, list all available tools. Supports * and ? wildcards.
+    """
+    import fnmatch
+
+    tools = await instance.get_tools()
+
+    if tool_name:
+        # Filter tools by name pattern OR tag pattern
+        matched_tools: dict[str, Any] = {}
+        for name, tool in tools.items():
+            # Check if tool name matches pattern
+            if fnmatch.fnmatch(name, tool_name):
+                matched_tools[name] = tool
+                continue
+
+            # Check if any tag matches pattern
+            if tool.tags:
+                for tag in tool.tags:
+                    if fnmatch.fnmatch(tag, tool_name):
+                        matched_tools[name] = tool
+                        break
+
+        if not matched_tools:
+            console.print(f"[red]No tools found matching pattern: {tool_name}[/red]")
+            console.print("[dim]Tip: Use 'u2mcp tools' (no arguments) to list all tools.[/dim]")
+            console.print("[dim]Tip: Use 'u2mcp tags' to list all available tags.[/dim]")
+            return
+
+        for name, tool in sorted(matched_tools.items()):
+            _print_single_tool_help(console, name, tool)
+    else:
+        # List all tools
+        table = Table(show_header=True, header_style="bold magenta")
+        table.add_column("Tool Name", style="cyan", width=25)
+        table.add_column("Description", style="white")
+        table.add_column("Tags", style="green", width=30)
+
+        for name, tool in sorted(tools.items()):
+            tags_str = ", ".join(sorted(tool.tags or [])) if tool.tags else ""
+            # Extract short description only, skip Args/Returns sections
+            description = tool.description or ""
+            parsed = parse(description)
+            # Use short description, fall back to full description truncated
+            desc = parsed.short_description if parsed.short_description else description
+            # Truncate if too long
+            desc = desc[:57] + "..." if len(desc) > 60 else desc
+            table.add_row(name, desc, tags_str)
+
+        console.print("\n[bold cyan]Available Tools:[/bold cyan]")
+        console.print(table)
+        console.print(f"\n[dim]Total: {len(tools)} tools[/dim]")
+        console.print("\n[dim]Use 'u2mcp info <tool_name>' for detailed information about a specific tool.[/dim]")
+        console.print("[dim]Supports wildcards: 'u2mcp info device:*' (by tag) or 'u2mcp info *screenshot*' (by name)[/dim]")
+
+
+def _print_single_tool_help(console: Console, name: str, tool: Any) -> None:
+    """Print detailed help for a single tool.
+
+    Parses doc-strings and formats Args/Returns with markdown.
+    """
+    # Build markdown content
+    md_lines = []
+
+    # Title and tags (as plain text, not markdown)
+    tags_str = f"**Tags:** {', '.join(sorted(tool.tags))}" if tool.tags else ""
+
+    # Parse the docstring
+    description = tool.description or ""
+    parsed = parse(description)
+
+    # Short description
+    if parsed.short_description:
+        md_lines.append(parsed.short_description)
+
+    # Long description
+    if parsed.long_description:
+        md_lines.append(parsed.long_description)
+
+    # Args section
+    if parsed.params:
+        md_lines.append("\n**Args:**")
+        for p in parsed.params:
+            type_suffix = f" ({p.type_name})" if p.type_name else ""
+            default_suffix = f"(default: `{p.default}`)" if p.default else ""
+            md_lines.append(f"- **{p.arg_name}**{type_suffix}: {p.description}{default_suffix}")
+
+    # Returns section
+    if parsed.returns:
+        md_lines.append("\n**Returns:**")
+        r = parsed.returns
+        if r.type_name:
+            md_lines.append(f"**{r.type_name}**")
+        if r.description:
+            md_lines.append(r.description)
+
+    # Combine tags and description
+    full_md = tags_str + "\n\n" + "\n".join(md_lines) if tags_str else "\n".join(md_lines)
+
+    # Display in a panel with markdown rendering
+    console.print(
+        Panel(
+            Markdown(full_md),
+            title=f"[bold cyan]{name}[/bold cyan]",
+            title_align="left",
+            border_style="cyan",
+            padding=(1, 1, 1, 1),
+        )
+    )
+    console.print()  # Blank line after each tool