minitap-mcp 0.8.0__tar.gz → 0.9.0__tar.gz

{minitap_mcp-0.8.0 → minitap_mcp-0.9.0}/PKG-INFO

@@ -1,13 +1,13 @@
 Metadata-Version: 2.3
 Name: minitap-mcp
-Version: 0.8.0
+Version: 0.9.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>=3.0.0
+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

{minitap_mcp-0.8.0 → minitap_mcp-0.9.0}/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-0.8.0 → minitap_mcp-0.9.0}/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
@@ -14,22 +15,32 @@ def _derive_mcp_url_from_base(base_url: str) -> str:
     """Derive the MCP URL from the API base URL.
 
     Extracts the scheme and host from the base URL and appends /api/mcp.
-    Example: https://dev.platform.minitap.ai/api/v1 -> https://dev.platform.minitap.ai/api/mcp
+    Example: https://dev.platform.minitap.ai/api/v1 -> https://dev.platform.minitap.ai/api/mcp/
     """
     parsed = urlparse(base_url)
-    return f"{parsed.scheme}://{parsed.netloc}/api/mcp"
+    return f"{parsed.scheme}://{parsed.netloc}/api/mcp/"
 
 
 def _derive_daas_url_from_base(base_url: str) -> str:
     """Derive the DaaS API URL from the API base URL.
 
     Extracts the scheme and host from the base URL and appends /api/daas.
-    Example: https://dev.platform.minitap.ai/api/v1 -> https://dev.platform.minitap.ai/api/daas
+    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"
 
 
+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):
     """Configuration class for MCP server."""
 
@@ -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-0.8.0 → minitap_mcp-0.9.0}/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-0.9.0/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-0.8.0 → minitap_mcp-0.9.0}/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.0 → minitap_mcp-0.9.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "minitap-mcp"
-version = "0.8.0"
+version = "0.9.0"
 description = "Model Context Protocol server for controlling Android & iOS devices with natural language"
 readme = "PYPI_README.md"
 
@@ -17,7 +17,7 @@ dependencies = [
     "python-dotenv>=1.1.1",
     "pydantic>=2.12.0",
     "pydantic-settings>=2.10.1",
-    "minitap-mobile-use>=3.0.0",
+    "minitap-mobile-use>=3.4.0",
     "jinja2>=3.1.6",
     "langchain-core>=0.3.75",
     "pillow>=11.1.0",