minitap-mcp 0.8.1__py3-none-any.whl → 0.9.1__py3-none-any.whl

minitap/mcp/core/cloud_apk.py

@@ -32,7 +32,15 @@ async def upload_apk_to_cloud_mobile(apk_path: str) -> str:
     if not apk_file.exists():
         raise FileNotFoundError(f"APK file not found: {apk_path}")
 
-    filename = f"app_{uuid.uuid4().hex[:6]}.apk"
+    # Use APP_PACKAGE_NAME env var if set, otherwise generate a random name
+    # Preserve the original file extension
+    extension = apk_file.suffix  # e.g., ".apk"
+    if settings.APP_PACKAGE_NAME:
+        # Strip any existing extension from APP_PACKAGE_NAME to avoid double extensions
+        base_name = Path(settings.APP_PACKAGE_NAME).stem
+        filename = f"{base_name}{extension}"
+    else:
+        filename = f"app_{uuid.uuid4().hex[:6]}{extension}"
     api_key = settings.MINITAP_API_KEY.get_secret_value()
     api_base_url = settings.MINITAP_API_BASE_URL.rstrip("/")
 

minitap/mcp/core/config.py

@@ -1,5 +1,6 @@
 """Configuration for the MCP server."""
 
+import os
 from urllib.parse import urlparse
 
 from dotenv import load_dotenv
@@ -27,7 +28,17 @@ def _derive_daas_url_from_base(base_url: str) -> str:
     Example: https://dev.platform.minitap.ai/api/v1 -> https://dev.platform.minitap.ai/api/daas/
     """
     parsed = urlparse(base_url)
-    return f"{parsed.scheme}://{parsed.netloc}/api/daas/"
+    return f"{parsed.scheme}://{parsed.netloc}/api/daas"
+
+
+def _derive_platform_base_url(api_base_url: str) -> str:
+    """Derive the platform base URL from the API base URL.
+
+    Extracts the scheme and host from the API URL (strips /api/v1 path).
+    Example: https://dev.platform.minitap.ai/api/v1 -> https://dev.platform.minitap.ai
+    """
+    parsed = urlparse(api_base_url)
+    return f"{parsed.scheme}://{parsed.netloc}"
 
 
 class MCPSettings(BaseSettings):
@@ -57,6 +68,16 @@ class MCPSettings(BaseSettings):
     # Create cloud mobiles at https://platform.minitap.ai/cloud-mobiles
     CLOUD_MOBILE_NAME: str | None = Field(default=None)
 
+    # Trajectory GIF download configuration
+    # When set, downloads the trajectory GIF after task execution to the specified folder.
+    # The folder is a directory where the GIF will be saved with the task run ID as filename.
+    TRAJECTORY_GIF_DOWNLOAD_FOLDER: str | None = Field(default=None)
+
+    # App package name override for uploads
+    # When set, uploaded APK/IPA files will use this name instead of a random UUID.
+    # The original file extension is preserved. Example: "my_app" -> "my_app.apk"
+    APP_PACKAGE_NAME: str | None = Field(default=None)
+
     @model_validator(mode="after")
     def derive_urls_from_base(self) -> "MCPSettings":
         """Derive MCP and DaaS URLs from base URL if not explicitly set.
@@ -79,6 +100,11 @@ class MCPSettings(BaseSettings):
                 _derive_daas_url_from_base(self.MINITAP_API_BASE_URL),
             )
 
+        # Set MINITAP_BASE_URL in environment for mobile-use SDK compatibility.
+        # The SDK uses MINITAP_BASE_URL (e.g., https://dev.platform.minitap.ai) while
+        # MCP uses MINITAP_API_BASE_URL (e.g., https://dev.platform.minitap.ai/api/v1).
+        os.environ["MINITAP_BASE_URL"] = _derive_platform_base_url(self.MINITAP_API_BASE_URL)
+
         return self
 
 

minitap/mcp/core/logging_config.py

@@ -13,9 +13,11 @@ def configure_logging(log_level: str = "INFO") -> None:
         log_level: The logging level (DEBUG, INFO, WARNING, ERROR, CRITICAL)
     """
     # Configure standard library logging
+    # CRITICAL: Use stderr to avoid polluting stdout with non-JSONRPC data
+    # MCP servers communicate via stdio - stdout MUST only contain JSONRPC messages
     logging.basicConfig(
         format="%(message)s",
-        stream=sys.stdout,
+        stream=sys.stderr,
         level=getattr(logging, log_level.upper()),
     )
 

minitap/mcp/core/storage.py

@@ -272,3 +272,136 @@ def _guess_mime_type(extension: str) -> str:
         "txt": "text/plain",
     }
     return ext_to_mime.get(ext, "application/octet-stream")
+
+
+class StorageDownloadError(Exception):
+    """Error raised when file download fails."""
+
+    pass
+
+
+async def get_trajectory_gif_download_url(task_run_id: str) -> str:
+    """Get a signed download URL for a trajectory GIF.
+
+    This function calls the MaaS API to get a signed S3 download URL for the
+    trajectory GIF associated with a task run.
+
+    Args:
+        task_run_id: The ID of the task run to get the GIF for
+
+    Returns:
+        The signed download URL for the GIF
+
+    Raises:
+        StorageDownloadError: If the request fails or no URL is returned
+    """
+    try:
+        api_key = _get_api_key()
+    except StorageUploadError as e:
+        raise StorageDownloadError(str(e)) from e
+    base_url = settings.MINITAP_API_BASE_URL
+    endpoint = f"{base_url}/storage/trajectory-gif-download/{task_run_id}"
+
+    async with httpx.AsyncClient(timeout=30.0) as client:
+        try:
+            logger.debug("Requesting trajectory GIF download URL", task_run_id=task_run_id)
+            response = await client.get(
+                endpoint,
+                headers={"Authorization": f"Bearer {api_key}"},
+            )
+
+            if response.status_code == 404:
+                raise StorageDownloadError(f"Trajectory GIF not found for task run: {task_run_id}")
+
+            if response.status_code != 200:
+                logger.error(
+                    "Failed to get trajectory GIF download URL",
+                    status_code=response.status_code,
+                    response=response.text,
+                )
+                raise StorageDownloadError(
+                    f"Failed to get trajectory GIF download URL: HTTP {response.status_code}"
+                )
+
+            data = response.json()
+            download_url = data.get("signed_url")
+            if not download_url:
+                raise StorageDownloadError("No download URL returned in response")
+
+            logger.debug("Got trajectory GIF download URL", task_run_id=task_run_id)
+            return download_url
+
+        except httpx.TimeoutException as e:
+            logger.error("Trajectory GIF download URL request timed out", error=str(e))
+            raise StorageDownloadError("Request timed out") from e
+        except httpx.RequestError as e:
+            logger.error("Trajectory GIF download URL request failed", error=str(e))
+            raise StorageDownloadError(f"Request failed: {str(e)}") from e
+        except StorageDownloadError:
+            raise
+        except Exception as e:
+            logger.error("Unexpected error getting trajectory GIF download URL", error=str(e))
+            raise StorageDownloadError(f"Unexpected error: {str(e)}") from e
+
+
+async def download_trajectory_gif(task_run_id: str, download_path: str | Path) -> Path:
+    """Download a trajectory GIF to a local path.
+
+    This function:
+    1. Gets a signed download URL from the MaaS API
+    2. Downloads the GIF from that URL
+    3. Saves it to the specified local path
+
+    Args:
+        task_run_id: The ID of the task run to download the GIF for
+        download_path: Directory path where the GIF will be saved.
+                      The file will be saved as {task_run_id}/trajectory.gif
+
+    Returns:
+        The full path to the downloaded GIF file
+
+    Raises:
+        StorageDownloadError: If download fails at any step
+    """
+    download_dir = Path(download_path) / task_run_id
+
+    try:
+        download_dir.mkdir(parents=True, exist_ok=True)
+    except OSError as e:
+        raise StorageDownloadError(f"Failed to create download directory: {e}") from e
+
+    download_url = await get_trajectory_gif_download_url(task_run_id)
+
+    output_file = download_dir / "trajectory.gif"
+
+    async with httpx.AsyncClient(timeout=60.0) as client:
+        try:
+            logger.info(
+                "Downloading trajectory GIF", task_run_id=task_run_id, path=str(output_file)
+            )
+            response = await client.get(download_url)
+
+            if response.status_code != 200:
+                raise StorageDownloadError(f"Failed to download GIF: HTTP {response.status_code}")
+
+            output_file.write_bytes(response.content)
+            logger.info(
+                "Trajectory GIF downloaded successfully",
+                task_run_id=task_run_id,
+                path=str(output_file),
+                size=len(response.content),
+            )
+
+            return output_file
+
+        except httpx.TimeoutException as e:
+            logger.error("GIF download timed out", error=str(e))
+            raise StorageDownloadError("Download timed out") from e
+        except httpx.RequestError as e:
+            logger.error("GIF download request failed", error=str(e))
+            raise StorageDownloadError(f"Download failed: {str(e)}") from e
+        except StorageDownloadError:
+            raise
+        except Exception as e:
+            logger.error("Unexpected error downloading GIF", error=str(e))
+            raise StorageDownloadError(f"Unexpected error: {str(e)}") from e

minitap/mcp/core/task_runs.py

@@ -0,0 +1,100 @@
+"""Task runs API utilities.
+
+This module provides functionality to interact with the task runs API
+for fetching information about executed tasks.
+"""
+
+import httpx
+
+from minitap.mcp.core.config import settings
+from minitap.mcp.core.logging_config import get_logger
+
+logger = get_logger(__name__)
+
+
+class TaskRunsError(Exception):
+    """Error raised when task runs API operations fail."""
+
+    pass
+
+
+def _get_api_key() -> str:
+    """Get the API key from settings.
+
+    Returns:
+        The API key string
+
+    Raises:
+        TaskRunsError: 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 TaskRunsError("MINITAP_API_KEY is required for task runs API")
+    return api_key
+
+
+async def get_latest_task_run_id() -> str:
+    """Get the ID of the most recently finished task run.
+
+    This function calls the MaaS API to get the latest task run,
+    sorted by finished_at in descending order.
+
+    Returns:
+        The ID of the latest task run
+
+    Raises:
+        TaskRunsError: If the request fails or no task run is found
+    """
+    api_key = _get_api_key()
+    base_url = settings.MINITAP_API_BASE_URL
+    endpoint = f"{base_url}/task-runs"
+
+    params = {
+        "page": 1,
+        "pageSize": 1,
+        "orphans": "include",
+        "virtualMobile": "include",
+        "sortBy": "finished_at",
+        "sortOrder": "desc",
+    }
+
+    async with httpx.AsyncClient(timeout=30.0) as client:
+        try:
+            logger.debug("Fetching latest task run ID")
+            response = await client.get(
+                endpoint,
+                params=params,
+                headers={"Authorization": f"Bearer {api_key}"},
+            )
+
+            if response.status_code != 200:
+                logger.error(
+                    "Failed to get latest task run",
+                    status_code=response.status_code,
+                    response=response.text,
+                )
+                raise TaskRunsError(f"Failed to get latest task run: HTTP {response.status_code}")
+
+            data = response.json()
+            items = data.get("runs", [])
+            if not items:
+                raise TaskRunsError("No task runs found")
+
+            task_run_id = items[0].get("id")
+            if not task_run_id:
+                raise TaskRunsError("Task run ID not found in response")
+
+            logger.debug("Got latest task run ID", task_run_id=task_run_id)
+            return task_run_id
+
+        except httpx.TimeoutException as e:
+            logger.error("Latest task run request timed out", error=str(e))
+            raise TaskRunsError("Request timed out") from e
+        except httpx.RequestError as e:
+            logger.error("Latest task run request failed", error=str(e))
+            raise TaskRunsError(f"Request failed: {str(e)}") from e
+        except TaskRunsError:
+            raise
+        except Exception as e:
+            logger.error("Unexpected error getting latest task run", error=str(e))
+            raise TaskRunsError(f"Unexpected error: {str(e)}") from e

minitap/mcp/tools/execute_mobile_command.py

@@ -1,9 +1,12 @@
 """Tool for running manual tasks on a connected mobile device."""
 
 from collections.abc import Mapping
+from pathlib import Path
 from typing import Any
 
 from fastmcp.exceptions import ToolError
+from fastmcp.tools.tool import ToolResult
+from mcp.types import TextContent
 from minitap.mobile_use.sdk.types import ManualTaskConfig
 from minitap.mobile_use.sdk.types.task import PlatformTaskRequest
 from pydantic import Field
@@ -11,10 +14,15 @@ from pydantic import Field
 from minitap.mcp.core.cloud_apk import install_apk_on_cloud_mobile, upload_apk_to_cloud_mobile
 from minitap.mcp.core.config import settings
 from minitap.mcp.core.decorators import handle_tool_errors
+from minitap.mcp.core.logging_config import get_logger
 from minitap.mcp.core.sdk_agent import get_mobile_use_agent
+from minitap.mcp.core.storage import StorageDownloadError, download_trajectory_gif
+from minitap.mcp.core.task_runs import TaskRunsError, get_latest_task_run_id
 from minitap.mcp.main import mcp
 from minitap.mcp.server.cloud_mobile import check_cloud_mobile_status
 
+logger = get_logger(__name__)
+
 
 def _serialize_result(result: Any) -> Any:
     """Convert SDK responses to serializable data for MCP."""
@@ -77,7 +85,7 @@ async def execute_mobile_command(
         "The APK will be uploaded to cloud storage and installed before task execution. "
         "Requires MINITAP_API_KEY to be configured. ",
     ),
-) -> str | dict[str, Any]:
+) -> str | dict[str, Any] | ToolResult:
     """Run a manual task on a mobile device via the Minitap platform."""
     try:
         if settings.CLOUD_MOBILE_NAME:
@@ -110,6 +118,65 @@ async def execute_mobile_command(
             request=request,
             locked_app_package=locked_app_package,
         )
-        return _serialize_result(result)
+
+        trajectory_gif_path: Path | None = None
+        if settings.TRAJECTORY_GIF_DOWNLOAD_FOLDER:
+            trajectory_gif_path = await _download_trajectory_gif_if_available()
+
+        serialized_result = _serialize_result(result)
+
+        # If trajectory was saved, return a ToolResult with multiple content items
+        if trajectory_gif_path:
+            import json
+
+            result_text = (
+                json.dumps(serialized_result, indent=2)
+                if isinstance(serialized_result, dict)
+                else str(serialized_result)
+            )
+            return ToolResult(
+                content=[
+                    TextContent(type="text", text=result_text),
+                    TextContent(type="text", text=f"Trajectory saved to {trajectory_gif_path}"),
+                ],
+            )
+
+        return serialized_result
     except Exception as e:
         raise ToolError(str(e))
+
+
+async def _download_trajectory_gif_if_available() -> Path | None:
+    """Download the trajectory GIF if available and folder is configured.
+
+    Fetches the latest task run ID from the API and downloads the GIF.
+
+    Returns:
+        The path to the downloaded GIF file, or None if download failed or not configured.
+    """
+    download_folder = settings.TRAJECTORY_GIF_DOWNLOAD_FOLDER
+    if not download_folder:
+        logger.warning("TRAJECTORY_GIF_DOWNLOAD_FOLDER not configured, skipping GIF download")
+        return None
+
+    task_run_id = None
+    try:
+        task_run_id = await get_latest_task_run_id()
+
+        gif_path = await download_trajectory_gif(
+            task_run_id=task_run_id,
+            download_path=download_folder,
+        )
+        logger.info(
+            "Trajectory GIF downloaded",
+            task_run_id=task_run_id,
+            path=str(gif_path),
+        )
+        return gif_path
+    except (StorageDownloadError, TaskRunsError) as e:
+        logger.warning(
+            "Failed to download trajectory GIF",
+            task_run_id=task_run_id,
+            error=str(e),
+        )
+        return None

{minitap_mcp-0.8.1.dist-info → minitap_mcp-0.9.1.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: minitap-mcp
-Version: 0.8.1
+Version: 0.9.1
 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

{minitap_mcp-0.8.1.dist-info → minitap_mcp-0.9.1.dist-info}/RECORD

@@ -7,15 +7,16 @@ minitap/mcp/core/agents/compare_screenshots/eval/scenario_1_add_cartoon_img_and_
 minitap/mcp/core/agents/compare_screenshots/eval/scenario_1_add_cartoon_img_and_move_button/prompt_1/model_params.json,sha256=p93kbUGxLYwc4NAEzPTBDA2XZ1ucsa7yevXZRe6V4Mc,37
 minitap/mcp/core/agents/compare_screenshots/eval/scenario_1_add_cartoon_img_and_move_button/prompt_1/output.md,sha256=Q0_5w9x5WAMqx6-I7KgjlS-tt7HnWKIunP43J7F0W_o,3703
 minitap/mcp/core/agents/compare_screenshots/prompt.md,sha256=qAyqOroSJROgrvlbsLCtiwFyBKuIMCQ-720A5cwgwPY,3563
-minitap/mcp/core/cloud_apk.py,sha256=Xeg1jrycm50UC72J4qVZ2NS9qs20oXKhvBcmBRs4rEA,3896
-minitap/mcp/core/config.py,sha256=aX4dGz-tZ88AVX6AeoBcEMUT-iVlabgtcwsCf47dSgY,3113
+minitap/mcp/core/cloud_apk.py,sha256=K0PmmkvkCzYo-eRfwGmfPcBbMy8KD32pHvrehm_L_YM,4308
+minitap/mcp/core/config.py,sha256=dCQMuT-jvGHBxIsvTQoUDOvZ98MTO5iwgCc3_bngX5M,4407
 minitap/mcp/core/decorators.py,sha256=ipzR7kbMXacG91f6CliN-nl9unRTtjmANrfueaOXJ2s,3591
 minitap/mcp/core/device.py,sha256=0AU8qGi26axC6toqHrPIzNeDbNDtll0YRwkspHouPmM,8198
 minitap/mcp/core/llm.py,sha256=tI5m5rFDLeMkXE5WExnzYSzHU3nTIEiSC9nAsPzVMaU,1144
-minitap/mcp/core/logging_config.py,sha256=OJlArPJxflbhckerFsRHVTzy3jwsLsNSPN0LVpkmpNM,1861
+minitap/mcp/core/logging_config.py,sha256=GElnKsOFtk58EMJWPKRGtKW101tnCubNKRFTe0gEh4I,2020
 minitap/mcp/core/models.py,sha256=egLScxPAMo4u5cqY33UKba7z7DsdgqfPW409UAqW1Jg,1942
 minitap/mcp/core/sdk_agent.py,sha256=5YEr7aDjoiwbRQkZBK3jDa08c5QhPwLxahzlYrEB_KE,1132
-minitap/mcp/core/storage.py,sha256=y92pnE0pfLtH4nDKHZeUAZm_udR5sbRQGWbw13mjd_U,8189
+minitap/mcp/core/storage.py,sha256=t9BAEqXH7Nu8p8hgGIk3mO6rxLwviBP0FqvQD4Lz8CQ,13184
+minitap/mcp/core/task_runs.py,sha256=vGv8G-oZcfe_lpMOGiM649u10WNzoU3uWDgYWm1owdQ,3115
 minitap/mcp/core/utils/figma.py,sha256=L5aAHm59mrRYaqrwMJSM24SSdZPu2yVg-wsHTF3L8vk,2310
 minitap/mcp/core/utils/images.py,sha256=3uExpRoh7affIieZx3TLlZTmZCcoxWfx1YpPbwhjiJY,1791
 minitap/mcp/main.py,sha256=p5E_dBIBiS_sp_v9u8gNxjRGwl25T4De-ivZQbSqJa8,11269
@@ -23,12 +24,12 @@ minitap/mcp/server/cloud_mobile.py,sha256=4cKnUzOJE5tBzgXgJXmyH0ESf6OyCTlNllputE
 minitap/mcp/server/middleware.py,sha256=SjPc4pcfPuG0TnaDH7a19DS_HRFPl3bkbovdOLzy_IU,768
 minitap/mcp/server/poller.py,sha256=JsdW6nvj4r3tsn8AaTwXD4H9dVAAau4BhJXHXHit9nA,2528
 minitap/mcp/server/remote_proxy.py,sha256=IM7UfjbJlQRpFD_tdpdck1mFT1QOnlxj5OA1nS4tRhQ,3073
-minitap/mcp/tools/execute_mobile_command.py,sha256=YXHLKvNFmuvwh7d_kPYw0R64bHzKCjyqp38adx8jWWI,4453
+minitap/mcp/tools/execute_mobile_command.py,sha256=K5KhSAqLdcmc6WH_u2TKAybECPw53TuSLEoSVrGCPOE,6776
 minitap/mcp/tools/read_swift_logs.py,sha256=Wc1XqQWWuNuPEIBioYD2geVd1p9Yq2USik6SX47Fq9A,9285
 minitap/mcp/tools/screen_analyzer.md,sha256=TTO80JQWusbA9cKAZn-9cqhgVHm6F_qJh5w152hG3YM,734
 minitap/mcp/tools/take_screenshot.py,sha256=gGySPSeVnx8lHiseGF_Wat82JLF-D8GuQIJ_hCaLZlQ,1730
 minitap/mcp/tools/upload_screenshot.py,sha256=kwh8Q46LWF3nyKbKlvnlf-CtGrPkctXSnLyeebQGNFI,2959
-minitap_mcp-0.8.1.dist-info/WHEEL,sha256=XV0cjMrO7zXhVAIyyc8aFf1VjZ33Fen4IiJk5zFlC3g,80
-minitap_mcp-0.8.1.dist-info/entry_points.txt,sha256=rYVoXm7tSQCqQTtHx4Lovgn1YsjwtEEHfddKrfEVHuY,55
-minitap_mcp-0.8.1.dist-info/METADATA,sha256=KTCif4x5DUhUq3yhquy4XzZ2N03qkiVUp-aOxC12GSs,10619
-minitap_mcp-0.8.1.dist-info/RECORD,,
+minitap_mcp-0.9.1.dist-info/WHEEL,sha256=fAguSjoiATBe7TNBkJwOjyL1Tt4wwiaQGtNtjRPNMQA,80
+minitap_mcp-0.9.1.dist-info/entry_points.txt,sha256=rYVoXm7tSQCqQTtHx4Lovgn1YsjwtEEHfddKrfEVHuY,55
+minitap_mcp-0.9.1.dist-info/METADATA,sha256=3zTwoaqHLDMUhftH78b7rO284NkyoBgBoOBPvuttzRM,10619
+minitap_mcp-0.9.1.dist-info/RECORD,,

{minitap_mcp-0.8.1.dist-info → minitap_mcp-0.9.1.dist-info}/WHEEL

@@ -1,4 +1,4 @@
 Wheel-Version: 1.0
-Generator: uv 0.9.26
+Generator: uv 0.9.28
 Root-Is-Purelib: true
 Tag: py3-none-any