minitap-mcp 0.5.3__tar.gz → 0.7.0__tar.gz

{minitap_mcp-0.5.3 → minitap_mcp-0.7.0}/PKG-INFO

@@ -1,17 +1,19 @@
 Metadata-Version: 2.3
 Name: minitap-mcp
-Version: 0.5.3
+Version: 0.7.0
 Summary: Model Context Protocol server for controlling Android & iOS devices with natural language
 Author: Pierre-Louis Favreau, Jean-Pierre Lo, Clément Guiguet
 Requires-Dist: fastmcp>=2.12.4
 Requires-Dist: python-dotenv>=1.1.1
 Requires-Dist: pydantic>=2.12.0
 Requires-Dist: pydantic-settings>=2.10.1
-Requires-Dist: minitap-mobile-use>=2.9.3
+Requires-Dist: minitap-mobile-use>=3.4.0
 Requires-Dist: jinja2>=3.1.6
 Requires-Dist: langchain-core>=0.3.75
 Requires-Dist: pillow>=11.1.0
 Requires-Dist: structlog>=24.4.0
+Requires-Dist: aiohttp>=3.9.0
+Requires-Dist: httpx>=0.28.1
 Requires-Dist: ruff==0.5.3 ; extra == 'dev'
 Requires-Dist: pytest==8.4.1 ; extra == 'dev'
 Requires-Dist: pytest-cov==5.0.0 ; extra == 'dev'
@@ -40,11 +42,19 @@ Before running the MCP server, ensure you have the required mobile automation to
 - **For Android devices:**
 
   - [ADB (Android Debug Bridge)](https://developer.android.com/tools/adb) - For device communication
-  - [Maestro](https://maestro.mobile.dev/) - For mobile automation
 
 - **For iOS devices (macOS only):**
   - Xcode Command Line Tools with `xcrun`
-  - [Maestro](https://maestro.mobile.dev/) - For mobile automation
+  - **[fb-idb](https://fbidb.io/docs/installation/)**: Facebook's iOS Development Bridge for device automation.
+
+```bash
+# Install via Homebrew (macOS)
+brew tap facebook/fb
+brew install idb-companion
+```
+
+> [!NOTE]
+> `idb_companion` is required to communicate with iOS simulators. Make sure it's in your PATH after installation.
 
 For detailed setup instructions, see the [mobile-use repository](https://github.com/minitap-ai/mobile-use).
 
@@ -244,6 +254,50 @@ The tool will:
 3. Compare both screenshots using vision AI
 4. Return a detailed analysis highlighting differences
 
+## Cloud Mobile Mode
+
+Run the MCP server with cloud-hosted mobile devices instead of requiring a local device. This enables:
+
+- **Zero local setup**: No ADB or physical device required
+- **Remote development**: Control cloud mobiles from anywhere
+- **Scalable automation**: Access multiple cloud devices
+
+### Setting Up Cloud Mobile Mode
+
+1. **Create a Cloud Mobile** on [Minitap Platform](https://platform.minitap.ai/cloud-mobiles):
+   - Click **Create New Device**
+   - Choose platform (currently Android v11 / API level 30)
+   - Set a **Reference Name** (e.g., `my-dev-device`)
+
+2. **Configure the environment variable**:
+
+```bash
+# Using reference name (recommended)
+export CLOUD_MOBILE_NAME="my-dev-device"
+```
+
+3. **Start the server** (no local device needed):
+
+```bash
+minitap-mcp --server --api-key your_minitap_api_key
+```
+
+The server will:
+- Connect to your cloud mobile on startup
+- Maintain a keep-alive connection while running
+- Automatically disconnect when the server stops
+
+> ⚠️ **Important**: Cloud mobiles are billed while connected. The MCP server automatically stops the connection when you close your IDE or stop the server. Make sure to properly shut down the server to avoid unexpected charges.
+
+### Cloud vs Local Mode
+
+| Feature | Local Mode | Cloud Mode |
+|---------|------------|------------|
+| Device requirement | Physical/emulator | None |
+| Setup complexity | ADB setup required | Low (env var only) |
+| `CLOUD_MOBILE_NAME` | Not set | Set to device name/UUID |
+| Billing | None | Per-minute usage |
+
 ## Advanced Configuration
 
 ### Custom ADB Server
@@ -259,7 +313,7 @@ export ADB_SERVER_SOCKET="tcp:192.168.1.100:5037"
 Customize the vision model used for screen analysis:
 
 ```bash
-export VISION_MODEL="qwen/qwen-2.5-vl-7b-instruct"
+export VISION_MODEL="google/gemini-3-flash-preview"
 ```
 
 ## Device Setup

{minitap_mcp-0.5.3 → minitap_mcp-0.7.0}/PYPI_README.md

@@ -17,11 +17,19 @@ Before running the MCP server, ensure you have the required mobile automation to
 - **For Android devices:**
 
   - [ADB (Android Debug Bridge)](https://developer.android.com/tools/adb) - For device communication
-  - [Maestro](https://maestro.mobile.dev/) - For mobile automation
 
 - **For iOS devices (macOS only):**
   - Xcode Command Line Tools with `xcrun`
-  - [Maestro](https://maestro.mobile.dev/) - For mobile automation
+  - **[fb-idb](https://fbidb.io/docs/installation/)**: Facebook's iOS Development Bridge for device automation.
+
+```bash
+# Install via Homebrew (macOS)
+brew tap facebook/fb
+brew install idb-companion
+```
+
+> [!NOTE]
+> `idb_companion` is required to communicate with iOS simulators. Make sure it's in your PATH after installation.
 
 For detailed setup instructions, see the [mobile-use repository](https://github.com/minitap-ai/mobile-use).
 
@@ -221,6 +229,50 @@ The tool will:
 3. Compare both screenshots using vision AI
 4. Return a detailed analysis highlighting differences
 
+## Cloud Mobile Mode
+
+Run the MCP server with cloud-hosted mobile devices instead of requiring a local device. This enables:
+
+- **Zero local setup**: No ADB or physical device required
+- **Remote development**: Control cloud mobiles from anywhere
+- **Scalable automation**: Access multiple cloud devices
+
+### Setting Up Cloud Mobile Mode
+
+1. **Create a Cloud Mobile** on [Minitap Platform](https://platform.minitap.ai/cloud-mobiles):
+   - Click **Create New Device**
+   - Choose platform (currently Android v11 / API level 30)
+   - Set a **Reference Name** (e.g., `my-dev-device`)
+
+2. **Configure the environment variable**:
+
+```bash
+# Using reference name (recommended)
+export CLOUD_MOBILE_NAME="my-dev-device"
+```
+
+3. **Start the server** (no local device needed):
+
+```bash
+minitap-mcp --server --api-key your_minitap_api_key
+```
+
+The server will:
+- Connect to your cloud mobile on startup
+- Maintain a keep-alive connection while running
+- Automatically disconnect when the server stops
+
+> ⚠️ **Important**: Cloud mobiles are billed while connected. The MCP server automatically stops the connection when you close your IDE or stop the server. Make sure to properly shut down the server to avoid unexpected charges.
+
+### Cloud vs Local Mode
+
+| Feature | Local Mode | Cloud Mode |
+|---------|------------|------------|
+| Device requirement | Physical/emulator | None |
+| Setup complexity | ADB setup required | Low (env var only) |
+| `CLOUD_MOBILE_NAME` | Not set | Set to device name/UUID |
+| Billing | None | Per-minute usage |
+
 ## Advanced Configuration
 
 ### Custom ADB Server
@@ -236,7 +288,7 @@ export ADB_SERVER_SOCKET="tcp:192.168.1.100:5037"
 Customize the vision model used for screen analysis:
 
 ```bash
-export VISION_MODEL="qwen/qwen-2.5-vl-7b-instruct"
+export VISION_MODEL="google/gemini-3-flash-preview"
 ```
 
 ## Device Setup

{minitap_mcp-0.5.3 → minitap_mcp-0.7.0}/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-0.7.0/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-0.5.3 → minitap_mcp-0.7.0}/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-0.5.3 → minitap_mcp-0.7.0}/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-0.5.3 → minitap_mcp-0.7.0}/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-0.5.3 → minitap_mcp-0.7.0}/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