minitap-mcp 0.9.0__py3-none-any.whl

minitap/mcp/core/device.py

@@ -0,0 +1,249 @@
+"""Device detection and screenshot utilities for Android and iOS devices."""
+
+import base64
+import json
+import os
+import subprocess
+import tempfile
+from pathlib import Path
+from typing import Literal
+
+from adbutils import AdbClient, AdbDevice
+from pydantic import BaseModel, ConfigDict
+
+DevicePlatform = Literal["android", "ios"]
+
+
+class MobileDevice(BaseModel):
+    """Represents a mobile device with its platform and connection details."""
+
+    model_config = ConfigDict(arbitrary_types_allowed=True)
+
+    device_id: str
+    platform: DevicePlatform
+    adb_device: AdbDevice | None = None  # Only for Android
+
+
+class DeviceInfo(BaseModel):
+    """Serializable device information."""
+
+    device_id: str
+    platform: DevicePlatform
+    name: str | None = None
+    state: str | None = None
+
+
+class DeviceNotFoundError(Exception):
+    """Raised when no device can be found."""
+
+    pass
+
+
+class DeviceNotReadyError(Exception):
+    """Raised when a device exists but is not ready (e.g., still starting)."""
+
+    def __init__(self, message: str, state: str | None = None):
+        super().__init__(message)
+        self.state = state
+
+
+def get_adb_client() -> AdbClient:
+    """Get an ADB client instance."""
+    custom_adb_socket = os.getenv("ADB_SERVER_SOCKET")
+    if not custom_adb_socket:
+        return AdbClient()
+    parts = custom_adb_socket.split(":")
+    if len(parts) != 3:
+        raise ValueError(f"Invalid ADB server socket: {custom_adb_socket}")
+    _, host, port = parts
+    return AdbClient(host=host, port=int(port))
+
+
+def list_available_devices() -> list[DeviceInfo]:
+    """
+    List all available mobile devices (Android and iOS).
+
+    Returns:
+        list[DeviceInfo]: A list of device information objects.
+    """
+    devices: list[DeviceInfo] = []
+
+    # List Android devices
+    try:
+        adb_client = get_adb_client()
+        android_devices = adb_client.device_list()
+
+        for device in android_devices:
+            if device.serial:
+                devices.append(
+                    DeviceInfo(
+                        device_id=device.serial,
+                        platform="android",
+                        name=device.serial,
+                        state="connected",
+                    )
+                )
+    except Exception:
+        # ADB not available or error listing devices
+        pass
+
+    # List iOS devices (only booted simulators to match SDK behavior)
+    try:
+        cmd = ["xcrun", "simctl", "list", "devices", "booted", "-j"]
+        result = subprocess.run(cmd, capture_output=True, text=True, check=True)
+        data = json.loads(result.stdout)
+
+        for runtime, ios_devices in data.get("devices", {}).items():
+            if "iOS" not in runtime:
+                continue
+
+            for device in ios_devices:
+                udid = device.get("udid")
+                name = device.get("name")
+                state = device.get("state")
+
+                if udid and state == "Booted":
+                    devices.append(
+                        DeviceInfo(
+                            device_id=udid,
+                            platform="ios",
+                            name=name,
+                            state=state,
+                        )
+                    )
+    except (subprocess.CalledProcessError, FileNotFoundError, json.JSONDecodeError):
+        # xcrun not available or error listing devices
+        pass
+
+    return devices
+
+
+def find_mobile_device(device_id: str | None = None) -> MobileDevice:
+    """
+    Find a mobile device (Android via ADB or iOS via xcrun).
+
+    Args:
+        device_id: Optional device ID to target a specific device.
+                   If None, returns the first available device.
+
+    Returns:
+        MobileDevice: A reference to the device with its platform information.
+
+    Raises:
+        DeviceNotFoundError: If no device is found or the specified device_id is not found.
+    """
+    # Get all available devices
+    available_devices = list_available_devices()
+
+    if not available_devices:
+        raise DeviceNotFoundError(
+            "No mobile device found. "
+            "Make sure you have an Android device connected via ADB "
+            "or an iOS simulator running."
+        )
+
+    # Find the target device
+    target_device = None
+    if device_id:
+        # Look for specific device
+        for dev in available_devices:
+            if dev.device_id == device_id:
+                target_device = dev
+                break
+        if not target_device:
+            raise DeviceNotFoundError(
+                f"Device with ID '{device_id}' not found. "
+                "Make sure the device is connected and accessible via adb or xcrun."
+            )
+    else:
+        # Prefer connected/booted devices first
+        for dev in available_devices:
+            if dev.state in ("connected", "Booted"):
+                target_device = dev
+                break
+        # Fall back to any device if no connected/booted device found
+        if not target_device:
+            target_device = available_devices[0]
+
+    # Create MobileDevice instance with platform-specific details
+    if target_device.platform == "android":
+        # For Android, get the AdbDevice reference
+        try:
+            adb_client = get_adb_client()
+            adb_device = adb_client.device(serial=target_device.device_id)
+            return MobileDevice(
+                device_id=target_device.device_id,
+                platform="android",
+                adb_device=adb_device,
+            )
+        except Exception as e:
+            raise DeviceNotFoundError(f"Failed to connect to Android device: {e}")
+    else:
+        # For iOS, just return the device info
+        return MobileDevice(device_id=target_device.device_id, platform="ios")
+
+
+def capture_screenshot(device: MobileDevice) -> str:
+    """
+    Capture a screenshot from the given mobile device.
+
+    Args:
+        device: MobileDevice instance returned by find_mobile_device()
+
+    Returns:
+        str: Base64-encoded screenshot image (PNG format)
+
+    Raises:
+        RuntimeError: If screenshot capture fails
+    """
+    if device.platform == "android":
+        return _capture_android_screenshot(device)
+    else:
+        return _capture_ios_screenshot(device)
+
+
+def _capture_android_screenshot(device: MobileDevice) -> str:
+    """Capture screenshot from Android device using ADB."""
+    if not device.adb_device:
+        # Reconnect to device if not available
+        adb_client = get_adb_client()
+        adb_device = adb_client.device(serial=device.device_id)
+        if not adb_device:
+            raise RuntimeError(f"Android device {device.device_id} not found")
+        device.adb_device = adb_device
+
+    try:
+        # Use ADB screencap to get PNG screenshot
+        screenshot_bytes = device.adb_device.shell("screencap -p", encoding=None)
+        if isinstance(screenshot_bytes, bytes):
+            return base64.b64encode(screenshot_bytes).decode("utf-8")
+        else:
+            raise RuntimeError("Unexpected screenshot data type from ADB")
+    except Exception as e:
+        raise RuntimeError(f"Failed to capture Android screenshot: {e}")
+
+
+def _capture_ios_screenshot(device: MobileDevice) -> str:
+    """Capture screenshot from iOS simulator using xcrun."""
+    try:
+        # Create temporary file for screenshot
+        with tempfile.NamedTemporaryFile(suffix=".png", delete=False) as tmp_file:
+            tmp_path = Path(tmp_file.name)
+
+        try:
+            # Capture screenshot using xcrun simctl
+            cmd = ["xcrun", "simctl", "io", device.device_id, "screenshot", str(tmp_path)]
+            subprocess.run(cmd, capture_output=True, text=True, check=True)
+
+            # Read and encode the screenshot
+            screenshot_bytes = tmp_path.read_bytes()
+            return base64.b64encode(screenshot_bytes).decode("utf-8")
+        finally:
+            # Clean up temporary file
+            if tmp_path.exists():
+                tmp_path.unlink()
+
+    except subprocess.CalledProcessError as e:
+        raise RuntimeError(f"Failed to capture iOS screenshot: {e.stderr}")
+    except Exception as e:
+        raise RuntimeError(f"Failed to capture iOS screenshot: {e}")

minitap/mcp/core/llm.py

@@ -0,0 +1,39 @@
+from langchain_openai import ChatOpenAI
+
+from minitap.mcp.core.config import settings
+
+
+def get_minitap_llm(
+    trace_id: str,
+    remote_tracing: bool = False,
+    model: str = "google/gemini-2.5-pro",
+    temperature: float | None = None,
+    max_retries: int | None = None,
+) -> ChatOpenAI:
+    assert settings.MINITAP_API_KEY is not None
+    assert settings.MINITAP_API_BASE_URL is not None
+    if max_retries is None and model.startswith("google/"):
+        max_retries = 2
+    client = ChatOpenAI(
+        model=model,
+        temperature=temperature,
+        max_retries=max_retries,
+        api_key=settings.MINITAP_API_KEY,
+        base_url=settings.MINITAP_API_BASE_URL,
+        default_query={
+            "sessionId": trace_id,
+            "traceOnlyUsage": remote_tracing,
+        },
+    )
+    return client
+
+
+def get_openrouter_llm(model_name: str, temperature: float = 1):
+    assert settings.OPEN_ROUTER_API_KEY is not None
+    client = ChatOpenAI(
+        model=model_name,
+        temperature=temperature,
+        api_key=settings.OPEN_ROUTER_API_KEY,
+        base_url="https://openrouter.ai/api/v1",
+    )
+    return client

minitap/mcp/core/logging_config.py

@@ -0,0 +1,59 @@
+"""Structured logging configuration using structlog."""
+
+import logging
+import sys
+
+import structlog
+
+
+def configure_logging(log_level: str = "INFO") -> None:
+    """Configure structlog with sensible defaults for the MCP server.
+
+    Args:
+        log_level: The logging level (DEBUG, INFO, WARNING, ERROR, CRITICAL)
+    """
+    # Configure standard library logging
+    logging.basicConfig(
+        format="%(message)s",
+        stream=sys.stdout,
+        level=getattr(logging, log_level.upper()),
+    )
+
+    # Configure structlog
+    structlog.configure(
+        processors=[
+            # Add log level to event dict
+            structlog.stdlib.add_log_level,
+            # Add timestamp
+            structlog.processors.TimeStamper(fmt="iso"),
+            # Add caller information (file, line, function)
+            structlog.processors.CallsiteParameterAdder(
+                parameters=[
+                    structlog.processors.CallsiteParameter.FILENAME,
+                    structlog.processors.CallsiteParameter.LINENO,
+                    structlog.processors.CallsiteParameter.FUNC_NAME,
+                ]
+            ),
+            # Stack info and exception formatting
+            structlog.processors.StackInfoRenderer(),
+            structlog.processors.format_exc_info,
+            # Render as JSON for structured output
+            structlog.processors.JSONRenderer(),
+        ],
+        wrapper_class=structlog.stdlib.BoundLogger,
+        context_class=dict,
+        logger_factory=structlog.stdlib.LoggerFactory(),
+        cache_logger_on_first_use=True,
+    )
+
+
+def get_logger(name: str) -> structlog.stdlib.BoundLogger:
+    """Get a structured logger instance.
+
+    Args:
+        name: The logger name (typically __name__ of the module)
+
+    Returns:
+        A structlog BoundLogger instance
+    """
+    return structlog.get_logger(name)

minitap/mcp/core/models.py

@@ -0,0 +1,59 @@
+"""Core models for the MCP server."""
+
+from enum import Enum
+
+from pydantic import BaseModel, Field
+
+
+class FigmaAsset(BaseModel):
+    """Represents a single Figma asset."""
+
+    variable_name: str = Field(description="The variable name from the code (e.g., imgSignal)")
+    url: str = Field(description="The full URL to the asset")
+    extension: str = Field(description="The file extension (e.g., svg, png, jpg)")
+
+
+class FigmaDesignContextOutput(BaseModel):
+    """Output from Figma design context containing code and guidelines."""
+
+    code_implementation: str = Field(description="The React/TypeScript code implementation")
+    code_implementation_guidelines: str | None = Field(
+        default=None, description="Guidelines for implementing the code"
+    )
+    nodes_guidelines: str | None = Field(
+        default=None, description="Guidelines specific to the nodes"
+    )
+
+
+class DownloadStatus(str, Enum):
+    """Status of asset download operation."""
+
+    SUCCESS = "success"
+    FAILED = "failed"
+
+
+class AssetDownloadResult(BaseModel):
+    """Result of downloading a single asset."""
+
+    filename: str = Field(description="The filename of the asset")
+    status: DownloadStatus = Field(description="The download status")
+    error: str | None = Field(default=None, description="Error message if download failed")
+
+
+class AssetDownloadSummary(BaseModel):
+    """Summary of all asset download operations."""
+
+    successful: list[AssetDownloadResult] = Field(
+        default_factory=list, description="List of successfully downloaded assets"
+    )
+    failed: list[AssetDownloadResult] = Field(
+        default_factory=list, description="List of failed asset downloads"
+    )
+
+    def success_count(self) -> int:
+        """Return the number of successful downloads."""
+        return len(self.successful)
+
+    def failure_count(self) -> int:
+        """Return the number of failed downloads."""
+        return len(self.failed)

minitap/mcp/core/sdk_agent.py

@@ -0,0 +1,35 @@
+import os
+
+from minitap.mobile_use.sdk import Agent
+from minitap.mobile_use.sdk.builders import Builders
+
+from minitap.mcp.core.config import settings
+
+# Lazy-initialized singleton agent
+_agent: Agent | None = None
+
+
+def get_mobile_use_agent() -> Agent:
+    """Get or create the mobile-use agent singleton.
+
+    This function lazily initializes the agent on first call, ensuring
+    that CLI arguments are parsed before agent creation.
+    """
+    global _agent
+    if _agent is None:
+        config = Builders.AgentConfig
+        custom_adb_socket = os.getenv("ADB_SERVER_SOCKET")
+        if custom_adb_socket:
+            parts = custom_adb_socket.split(":")
+            if len(parts) != 3:
+                raise ValueError(f"Invalid ADB server socket: {custom_adb_socket}")
+            _, host, port = parts
+            config = config.with_adb_server(host=host, port=int(port))
+
+        # Add cloud mobile configuration if set
+        if settings.CLOUD_MOBILE_NAME:
+            config = config.for_cloud_mobile(cloud_mobile_id_or_ref=settings.CLOUD_MOBILE_NAME)
+
+        _agent = Agent(config=config.build())
+
+    return _agent