minitap-mcp 0.5.3__py3-none-any.whl → 0.7.0__py3-none-any.whl

minitap/mcp/core/agents/compare_screenshots/agent.py

@@ -1,4 +1,5 @@
 import asyncio
+import base64
 from pathlib import Path
 from uuid import uuid4
 
@@ -9,6 +10,7 @@ from pydantic import BaseModel
 from minitap.mcp.core.device import capture_screenshot, find_mobile_device
 from minitap.mcp.core.llm import get_minitap_llm
 from minitap.mcp.core.utils.images import get_screenshot_message_for_llm
+from minitap.mcp.server.cloud_mobile import get_cloud_mobile_id, get_cloud_screenshot
 
 
 class CompareScreenshotsOutput(BaseModel):
@@ -23,6 +25,8 @@ async def compare_screenshots(
     """
     Compare screenshots and return the comparison text along with both screenshots.
 
+    Supports both local devices (Android/iOS) and cloud devices.
+
     Returns:
         CompareScreenshotsOutput
     """
@@ -30,8 +34,14 @@ async def compare_screenshots(
         Path(__file__).parent.joinpath("prompt.md").read_text(encoding="utf-8")
     ).render()
 
-    device = find_mobile_device()
-    current_screenshot = capture_screenshot(device)
+    cloud_mobile_id = get_cloud_mobile_id()
+
+    if cloud_mobile_id:
+        screenshot_bytes = await get_cloud_screenshot(cloud_mobile_id)
+        current_screenshot = base64.b64encode(screenshot_bytes).decode("utf-8")
+    else:
+        device = find_mobile_device()
+        current_screenshot = capture_screenshot(device)
 
     messages: list[BaseMessage] = [
         SystemMessage(content=system_message),

minitap/mcp/core/cloud_apk.py

@@ -0,0 +1,109 @@
+"""Cloud APK deployment utilities for uploading and installing APKs on cloud mobiles."""
+
+import uuid
+from pathlib import Path
+
+import httpx
+
+from minitap.mcp.core.config import settings
+
+
+async def upload_apk_to_cloud_mobile(apk_path: str) -> str:
+    """
+    Upload an APK file via Platform storage API to user storage bucket.
+
+    Args:
+        apk_path: Path to the APK file
+
+    Returns:
+        Filename to use with install-apk endpoint
+
+    Raises:
+        FileNotFoundError: If APK file doesn't exist
+        httpx.HTTPError: If upload fails
+        ValueError: If MINITAP_API_KEY or MINITAP_API_BASE_URL is not configured
+    """
+    if not settings.MINITAP_API_KEY:
+        raise ValueError("MINITAP_API_KEY is not configured")
+    if not settings.MINITAP_API_BASE_URL:
+        raise ValueError("MINITAP_API_BASE_URL is not configured")
+
+    apk_file = Path(apk_path)
+    if not apk_file.exists():
+        raise FileNotFoundError(f"APK file not found: {apk_path}")
+
+    filename = f"app_{uuid.uuid4().hex[:6]}.apk"
+    api_key = settings.MINITAP_API_KEY.get_secret_value()
+    api_base_url = settings.MINITAP_API_BASE_URL.rstrip("/")
+
+    async with httpx.AsyncClient(timeout=300.0) as client:
+        # Step 1: Get signed upload URL from storage API
+        response = await client.get(
+            f"{api_base_url}/storage/signed-upload",
+            headers={"Authorization": f"Bearer {api_key}"},
+            params={"filenames": filename},
+        )
+        response.raise_for_status()
+        upload_data = response.json()
+
+        # Extract the signed URL for our file
+        signed_urls = upload_data.get("signed_urls", {})
+        if filename not in signed_urls:
+            raise ValueError(f"No signed URL returned for {filename}")
+
+        signed_url = signed_urls[filename]
+
+        # Step 2: Upload APK to signed URL
+        with open(apk_file, "rb") as f:
+            upload_response = await client.put(
+                signed_url,
+                content=f.read(),
+                headers={"Content-Type": "application/vnd.android.package-archive"},
+            )
+            upload_response.raise_for_status()
+
+        # Step 3: Return filename for install-apk call
+        return filename
+
+
+async def install_apk_on_cloud_mobile(filename: str) -> None:
+    """
+    Install an APK on a cloud mobile device via mobile-manager API.
+
+    Args:
+        filename: Filename returned from upload_apk_to_cloud_mobile
+
+    Raises:
+        httpx.HTTPError: If installation fails
+        ValueError: If required config settings are not configured
+    """
+    if not settings.MINITAP_API_KEY:
+        raise ValueError("MINITAP_API_KEY is not configured")
+    if not settings.MINITAP_DAAS_API:
+        raise ValueError("MINITAP_DAAS_API is not configured")
+    if not settings.CLOUD_MOBILE_NAME:
+        raise ValueError("CLOUD_MOBILE_NAME is not configured")
+
+    api_key = settings.MINITAP_API_KEY.get_secret_value()
+    base_url = settings.MINITAP_DAAS_API
+    cloud_mobile_name = settings.CLOUD_MOBILE_NAME
+
+    async with httpx.AsyncClient(timeout=120.0) as client:
+        cloud_mobile_response = await client.get(
+            f"{base_url}/virtual-mobiles/{cloud_mobile_name}",
+            headers={"Authorization": f"Bearer {api_key}"},
+        )
+        cloud_mobile_response.raise_for_status()
+        response_data = cloud_mobile_response.json()
+        cloud_mobile_uuid = response_data.get("id")
+        if not cloud_mobile_uuid:
+            raise ValueError(f"Cloud mobile '{cloud_mobile_name}' response missing 'id' field")
+        response = await client.post(
+            f"{base_url}/virtual-mobiles/{cloud_mobile_uuid}/install-apk",
+            headers={
+                "Authorization": f"Bearer {api_key}",
+                "Content-Type": "application/json",
+            },
+            json={"filename": filename},
+        )
+        response.raise_for_status()

minitap/mcp/core/config.py

@@ -16,16 +16,21 @@ class MCPSettings(BaseSettings):
     # Minitap API configuration
     MINITAP_API_KEY: SecretStr | None = Field(default=None)
     MINITAP_API_BASE_URL: str = Field(default="https://platform.minitap.ai/api/v1")
+    MINITAP_DAAS_API: str = Field(default="https://platform.minitap.ai/api/daas")
+    MINITAP_API_MCP_BASE_URL: str | None = Field(default="https://platform.minitap.ai/mcp")
     OPEN_ROUTER_API_KEY: SecretStr | None = Field(default=None)
 
-    VISION_MODEL: str = Field(default="qwen/qwen-2.5-vl-7b-instruct")
-
-    # Figma MCP server configuration
-    FIGMA_MCP_SERVER_URL: str = Field(default="http://127.0.0.1:3845/mcp")
+    VISION_MODEL: str = Field(default="google/gemini-3-flash-preview")
 
     # MCP server configuration (optional, for remote access)
     MCP_SERVER_HOST: str = Field(default="0.0.0.0")
     MCP_SERVER_PORT: int = Field(default=8000)
 
+    # Cloud Mobile configuration
+    # When set, the MCP server runs in cloud mode connecting to a Minitap cloud mobile
+    # instead of requiring a local device. Value can be a device name.
+    # Create cloud mobiles at https://platform.minitap.ai/cloud-mobiles
+    CLOUD_MOBILE_NAME: str | None = Field(default=None)
+
 
 settings = MCPSettings()  # type: ignore

minitap/mcp/core/decorators.py

@@ -6,7 +6,7 @@ from collections.abc import Callable
 from functools import wraps
 from typing import Any, TypeVar
 
-from minitap.mcp.core.device import DeviceNotFoundError
+from minitap.mcp.core.device import DeviceNotFoundError, DeviceNotReadyError
 from minitap.mcp.core.logging_config import get_logger
 
 F = TypeVar("F", bound=Callable[..., Any])
@@ -42,6 +42,15 @@ def handle_tool_errors[T: Callable[..., Any]](func: T) -> T:
                 error_type=type(e).__name__,
             )
             return f"Error: {str(e)}"
+        except DeviceNotReadyError as e:
+            logger.error(
+                "device_not_ready_error",
+                tool_name=func.__name__,
+                error=str(e),
+                error_type=type(e).__name__,
+                device_state=e.state,
+            )
+            return f"Error: {str(e)}"
         except Exception as e:
             logger.error(
                 "tool_error",
@@ -72,6 +81,15 @@ def handle_tool_errors[T: Callable[..., Any]](func: T) -> T:
                 error_type=type(e).__name__,
             )
             return f"Error: {str(e)}"
+        except DeviceNotReadyError as e:
+            logger.error(
+                "device_not_ready_error",
+                tool_name=func.__name__,
+                error=str(e),
+                error_type=type(e).__name__,
+                device_state=e.state,
+            )
+            return f"Error: {str(e)}"
         except Exception as e:
             logger.error(
                 "tool_error",

minitap/mcp/core/device.py

@@ -11,7 +11,6 @@ from typing import Literal
 from adbutils import AdbClient, AdbDevice
 from pydantic import BaseModel, ConfigDict
 
-
 DevicePlatform = Literal["android", "ios"]
 
 
@@ -40,6 +39,14 @@ class DeviceNotFoundError(Exception):
     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")
@@ -80,9 +87,9 @@ def list_available_devices() -> list[DeviceInfo]:
         # ADB not available or error listing devices
         pass
 
-    # List iOS devices
+    # List iOS devices (only booted simulators to match SDK behavior)
     try:
-        cmd = ["xcrun", "simctl", "list", "devices", "-j"]
+        cmd = ["xcrun", "simctl", "list", "devices", "booted", "-j"]
         result = subprocess.run(cmd, capture_output=True, text=True, check=True)
         data = json.loads(result.stdout)
 
@@ -95,7 +102,7 @@ def list_available_devices() -> list[DeviceInfo]:
                 name = device.get("name")
                 state = device.get("state")
 
-                if udid:
+                if udid and state == "Booted":
                     devices.append(
                         DeviceInfo(
                             device_id=udid,

minitap/mcp/core/sdk_agent.py

@@ -3,6 +3,8 @@ 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
 
@@ -23,5 +25,11 @@ def get_mobile_use_agent() -> Agent:
                 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

minitap/mcp/core/storage.py

@@ -0,0 +1,274 @@
+"""Storage utilities for uploading local files to remote storage.
+
+This module provides functionality to upload local files (like screenshots)
+to the MaaS API storage backend and get presigned URLs that can be passed
+to remote MCP tools.
+"""
+
+import base64
+import uuid
+from pathlib import Path
+
+import httpx
+
+from minitap.mcp.core.config import settings
+from minitap.mcp.core.logging_config import get_logger
+
+logger = get_logger(__name__)
+
+
+class StorageUploadError(Exception):
+    """Error raised when file upload fails."""
+
+    pass
+
+
+def _get_api_key() -> str:
+    """Get the API key from settings.
+
+    Returns:
+        The API key string
+
+    Raises:
+        StorageUploadError: If API key is not configured
+    """
+    api_key = settings.MINITAP_API_KEY.get_secret_value() if settings.MINITAP_API_KEY else None
+    if not api_key:
+        raise StorageUploadError("MINITAP_API_KEY is required for file uploads")
+    return api_key
+
+
+def _generate_filename(content_type: str) -> str:
+    """Generate a unique filename based on content type.
+
+    Args:
+        content_type: MIME type of the file
+
+    Returns:
+        UUID-based filename with appropriate extension
+    """
+    ext = _get_extension_from_mime_type(content_type)
+    return f"{uuid.uuid4()}.{ext}"
+
+
+async def _get_signed_upload_url(
+    client: httpx.AsyncClient,
+    filename: str,
+    api_key: str,
+) -> str:
+    """Get a signed upload URL from the MaaS API.
+
+    Args:
+        client: HTTP client to use for the request
+        filename: Name of the file to upload
+        api_key: API key for authentication
+
+    Returns:
+        Signed upload URL
+
+    Raises:
+        StorageUploadError: If request fails or no URL is returned
+    """
+    base_url = settings.MINITAP_API_BASE_URL
+    endpoint = f"{base_url}/storage/signed-upload"
+
+    try:
+        logger.debug("Requesting signed upload URL", filename=filename)
+        response = await client.get(
+            endpoint,
+            params={"filenames": filename},
+            headers={"Authorization": f"Bearer {api_key}"},
+        )
+
+        if response.status_code != 200:
+            logger.error(
+                "Failed to get signed upload URL",
+                status_code=response.status_code,
+                response=response.text,
+            )
+            raise StorageUploadError(
+                f"Failed to get signed upload URL: HTTP {response.status_code}"
+            )
+
+        signed_urls = response.json().get("signed_urls", {})
+        if filename not in signed_urls:
+            raise StorageUploadError(f"No signed URL returned for {filename}")
+
+        logger.debug("Got signed upload URL", filename=filename)
+        return signed_urls[filename]
+
+    except httpx.TimeoutException as e:
+        logger.error("Signed URL request timed out", error=str(e))
+        raise StorageUploadError("Signed URL request timed out") from e
+    except httpx.RequestError as e:
+        logger.error("Signed URL request failed", error=str(e))
+        raise StorageUploadError(f"Signed URL request failed: {str(e)}") from e
+    except StorageUploadError:
+        raise
+    except Exception as e:
+        logger.error("Unexpected error getting signed URL", error=str(e))
+        raise StorageUploadError(f"Unexpected error: {str(e)}") from e
+
+
+async def _upload_to_signed_url(
+    client: httpx.AsyncClient,
+    url: str,
+    content: bytes,
+    content_type: str,
+    filename: str,
+) -> None:
+    """Upload content to a signed URL.
+
+    Args:
+        client: HTTP client to use for the request
+        url: Signed upload URL
+        content: File content as bytes
+        content_type: MIME type of the content
+        filename: Filename (for logging)
+
+    Raises:
+        StorageUploadError: If upload fails
+    """
+    try:
+        logger.debug("Uploading file to storage", filename=filename, size=len(content))
+        response = await client.put(
+            url,
+            content=content,
+            headers={"Content-Type": content_type},
+        )
+
+        if response.status_code not in (200, 201):
+            logger.error(
+                "Failed to upload file",
+                status_code=response.status_code,
+                response=response.text,
+            )
+            raise StorageUploadError(f"Failed to upload file: HTTP {response.status_code}")
+
+        logger.info("File uploaded successfully", filename=filename)
+
+    except httpx.TimeoutException as e:
+        logger.error("Upload request timed out", error=str(e))
+        raise StorageUploadError("Upload request timed out") from e
+    except httpx.RequestError as e:
+        logger.error("Upload request failed", error=str(e))
+        raise StorageUploadError(f"Upload request failed: {str(e)}") from e
+    except StorageUploadError:
+        raise
+    except Exception as e:
+        logger.error("Unexpected error during upload", error=str(e))
+        raise StorageUploadError(f"Unexpected error: {str(e)}") from e
+
+
+async def upload_file_to_storage(
+    file_content: bytes,
+    filename: str | None = None,
+    content_type: str = "image/png",
+) -> str:
+    """Upload file content to remote storage and return the filename.
+
+    This function:
+    1. Gets a signed upload URL from the MaaS API
+    2. Uploads the file content to that URL
+    3. Returns the filename for use with remote MCP tools
+
+    Args:
+        file_content: The file content as bytes
+        filename: Optional filename (will generate UUID-based name if not provided)
+        content_type: MIME type of the file (default: image/png)
+
+    Returns:
+        Filename of the uploaded file (to be used with remote MCP tools)
+
+    Raises:
+        StorageUploadError: If upload fails at any step
+    """
+    api_key = _get_api_key()
+    filename = filename or _generate_filename(content_type)
+
+    async with httpx.AsyncClient(timeout=30.0) as client:
+        signed_url = await _get_signed_upload_url(client, filename, api_key)
+        await _upload_to_signed_url(client, signed_url, file_content, content_type, filename)
+
+    return filename
+
+
+async def upload_screenshot_to_storage(screenshot_base64: str) -> str:
+    """Upload a base64-encoded screenshot to storage.
+
+    Convenience function for uploading screenshots captured from devices.
+
+    Args:
+        screenshot_base64: Base64-encoded screenshot data
+
+    Returns:
+        Filename of the uploaded screenshot
+
+    Raises:
+        StorageUploadError: If upload fails
+    """
+
+    try:
+        screenshot_bytes = base64.b64decode(screenshot_base64)
+    except Exception as e:
+        raise StorageUploadError(f"Invalid base64 data: {str(e)}") from e
+
+    return await upload_file_to_storage(
+        file_content=screenshot_bytes,
+        content_type="image/png",
+    )
+
+
+async def upload_local_file_to_storage(file_path: str | Path) -> str:
+    """Upload a local file to storage.
+
+    Args:
+        file_path: Path to the local file
+
+    Returns:
+        Public download URL for the uploaded file
+
+    Raises:
+        StorageUploadError: If file doesn't exist or upload fails
+    """
+    path = Path(file_path)
+
+    if not path.exists():
+        raise StorageUploadError(f"File not found: {file_path}")
+
+    mime_type = _guess_mime_type(path.suffix)
+    file_content = path.read_bytes()
+
+    return await upload_file_to_storage(
+        file_content=file_content,
+        filename=f"{uuid.uuid4()}{path.suffix}",
+        content_type=mime_type,
+    )
+
+
+def _get_extension_from_mime_type(mime_type: str) -> str:
+    """Get file extension from MIME type."""
+    mime_to_ext = {
+        "image/png": "png",
+        "image/jpeg": "jpg",
+        "image/gif": "gif",
+        "image/webp": "webp",
+        "application/json": "json",
+        "text/plain": "txt",
+    }
+    return mime_to_ext.get(mime_type, "bin")
+
+
+def _guess_mime_type(extension: str) -> str:
+    """Guess MIME type from file extension."""
+    ext = extension.lower().lstrip(".")
+    ext_to_mime = {
+        "png": "image/png",
+        "jpg": "image/jpeg",
+        "jpeg": "image/jpeg",
+        "gif": "image/gif",
+        "webp": "image/webp",
+        "json": "application/json",
+        "txt": "text/plain",
+    }
+    return ext_to_mime.get(ext, "application/octet-stream")