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

minitap/mcp/core/config.py

@@ -17,12 +17,10 @@ class MCPSettings(BaseSettings):
     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")

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/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")

minitap/mcp/main.py

@@ -25,7 +25,6 @@ if sys.platform == "win32":
 
 
 from fastmcp import FastMCP  # noqa: E402
-from minitap.mobile_use.config import settings as sdk_settings
 
 from minitap.mcp.core.config import settings  # noqa: E402
 from minitap.mcp.core.device import (
@@ -39,6 +38,7 @@ from minitap.mcp.core.logging_config import (
 from minitap.mcp.server.cloud_mobile import CloudMobileService
 from minitap.mcp.server.middleware import LocalDeviceHealthMiddleware
 from minitap.mcp.server.poller import device_health_poller
+from minitap.mobile_use.config import settings as sdk_settings
 
 configure_logging(log_level=os.getenv("LOG_LEVEL", "INFO"))
 
@@ -126,6 +126,7 @@ class MCPLifespanContext:
     cloud_mobile_service: CloudMobileService | None = None
     local_poller_stop_event: threading.Event | None = None
     local_poller_thread: threading.Thread | None = None
+    remote_mcp_proxy: FastMCP | None = None
 
 
 @asynccontextmanager
@@ -210,6 +211,46 @@ async def mcp_lifespan(server: FastMCP) -> AsyncIterator[MCPLifespanContext]:
         context.local_poller_thread = poller_thread
         logger.info("Device health poller started")
 
+    # ==================== REMOTE MCP PROXY ====================
+    # Mount remote MCP proxy if configured (works in both cloud and local modes)
+    if settings.MINITAP_API_MCP_BASE_URL and api_key:
+        from minitap.mcp.server.remote_proxy import (
+            check_remote_mcp_availability,
+            create_remote_mcp_proxy,
+        )
+
+        logger.info(f"Attempting to connect to remote MCP at: {settings.MINITAP_API_MCP_BASE_URL}")
+
+        try:
+            is_available = await check_remote_mcp_availability(
+                mcp_url=settings.MINITAP_API_MCP_BASE_URL,
+                api_key=api_key,
+            )
+
+            if is_available:
+                remote_proxy = create_remote_mcp_proxy(
+                    mcp_url=settings.MINITAP_API_MCP_BASE_URL,
+                    api_key=api_key,
+                    prefix="",
+                )
+
+                server.mount(remote_proxy)
+                logger.info("Remote MCP proxy mounted successfully without prefix")
+
+                context.remote_mcp_proxy = remote_proxy
+            else:
+                logger.warning(
+                    "Remote MCP server is not available. "
+                    "Local tools will remain functional, but remote tools (Figma, Jira) "
+                    "will not be accessible."
+                )
+        except Exception as e:
+            # Log warning but don't crash - local tools should remain functional
+            logger.warning(
+                f"Failed to create remote MCP proxy: {e}. "
+                "Local tools will remain functional, but remote tools will not be accessible."
+            )
+
     try:
         yield context
     finally:
@@ -236,6 +277,16 @@ async def mcp_lifespan(server: FastMCP) -> AsyncIterator[MCPLifespanContext]:
             else:
                 logger.info("Device health poller stopped successfully")
 
+        # Clean up remote MCP proxy connection
+        # basically not super important for now, but will be in the
+        # future when cloud dependencies must be cleaned up
+        if context.remote_mcp_proxy:
+            try:
+                logger.info("Cleaning up remote MCP proxy connection")
+                context.remote_mcp_proxy = None
+            except Exception as e:
+                logger.warning(f"Error cleaning up remote MCP proxy: {e}")
+
         logger.info("MCP server shutdown complete")
 
 
@@ -250,10 +301,11 @@ mcp = FastMCP(
     lifespan=mcp_lifespan,
 )
 
-from minitap.mcp.tools import analyze_screen  # noqa: E402, F401
-from minitap.mcp.tools import compare_screenshot_with_figma  # noqa: E402, F401
-from minitap.mcp.tools import execute_mobile_command  # noqa: E402, F401
-from minitap.mcp.tools import save_figma_assets  # noqa: E402, F401
+from minitap.mcp.tools import (  # noqa: E402
+    execute_mobile_command,  # noqa: E402, F401
+    read_swift_logs,  # noqa: E402, F401
+    upload_screenshot,  # noqa: E402, F401
+)
 
 
 @mcp.resource("data://devices")

minitap/mcp/server/cloud_mobile.py

@@ -19,6 +19,7 @@ from typing import Any
 import aiohttp
 
 from minitap.mcp.core.config import settings
+from minitap.mcp.core.device import DeviceNotReadyError
 
 logger = logging.getLogger(__name__)
 
@@ -395,3 +396,97 @@ async def get_cloud_screenshot(mobile_id: str | None = None) -> bytes:
                 )
 
             return await response.read()
+
+
+async def check_cloud_mobile_status(
+    cloud_mobile_name: str | None = None,
+) -> VirtualMobileInfo:
+    """Check the current status of a cloud mobile device.
+
+    This function checks the device state once and raises an appropriate error
+    if the device is not ready. The MCP client can then decide to retry.
+
+    Args:
+        cloud_mobile_name: The reference name or UUID of the cloud mobile.
+                          If None, uses CLOUD_MOBILE_NAME from settings.
+
+    Returns:
+        VirtualMobileInfo: Device info if ready.
+
+    Raises:
+        DeviceNotReadyError: If device is not ready (starting, stopping, etc.).
+        RuntimeError: If device is in an error state, stopped, or not found.
+    """
+    target_name = cloud_mobile_name or settings.CLOUD_MOBILE_NAME
+    if not target_name:
+        raise RuntimeError(
+            "No cloud mobile specified. Either provide cloud_mobile_name or set CLOUD_MOBILE_NAME."
+        )
+
+    api_key = settings.MINITAP_API_KEY.get_secret_value() if settings.MINITAP_API_KEY else None
+    if not api_key:
+        raise RuntimeError("MINITAP_API_KEY is required for cloud mobile operations.")
+
+    base_url = settings.MINITAP_DAAS_API.rstrip("/")
+    url = f"{base_url}/virtual-mobiles/{target_name}"
+    headers = {
+        "Authorization": f"Bearer {api_key}",
+        "Content-Type": "application/json",
+    }
+
+    timeout = aiohttp.ClientTimeout(total=30)
+    async with aiohttp.ClientSession(timeout=timeout) as session:
+        async with session.get(url, headers=headers) as response:
+            if response.status == 404:
+                raise RuntimeError(
+                    f"Cloud mobile '{target_name}' not found. "
+                    "Please verify the name/UUID exists in your Minitap Platform account."
+                )
+            if response.status == 401:
+                raise RuntimeError(
+                    "Authentication failed. Please verify your MINITAP_API_KEY is valid."
+                )
+            if response.status != 200:
+                error_text = await response.text()
+                raise RuntimeError(
+                    f"Failed to fetch cloud mobile: HTTP {response.status} - {error_text}"
+                )
+
+            data = await response.json()
+            info = VirtualMobileInfo.from_api_response(data)
+
+            if info.state == "Ready":
+                logger.info(f"Cloud mobile '{target_name}' is ready")
+                return info
+
+            if info.state == "Error":
+                raise RuntimeError(
+                    f"Cloud mobile '{target_name}' is in error state. "
+                    "Please check the Minitap Platform for details."
+                )
+
+            if info.state == "Stopped":
+                raise DeviceNotReadyError(
+                    f"Cloud mobile '{target_name}' is stopped. ",
+                    state=info.state,
+                )
+
+            if info.state == "Starting":
+                raise DeviceNotReadyError(
+                    f"Cloud mobile '{target_name}' is still starting. "
+                    "Please wait a minute and try again.",
+                    state=info.state,
+                )
+
+            if info.state == "Stopping":
+                raise DeviceNotReadyError(
+                    f"Cloud mobile '{target_name}' is stopping. ",
+                    state=info.state,
+                )
+
+            # Unknown state
+            raise DeviceNotReadyError(
+                f"Cloud mobile '{target_name}' is in state '{info.state}'. "
+                "Please check the Minitap Platform for details.",
+                state=info.state,
+            )

minitap/mcp/server/remote_proxy.py

@@ -0,0 +1,96 @@
+"""Remote MCP proxy for bridging with the MaaS API MCP server.
+
+This module provides functionality to create a proxy to the remote MaaS API
+MCP server, enabling the local MCP to expose remote tools (Figma, Jira, etc.)
+through a unified interface.
+"""
+
+import asyncio
+from urllib.parse import urlparse
+
+from fastmcp import FastMCP
+from fastmcp.client.transports import StreamableHttpTransport
+from fastmcp.server.proxy import ProxyClient
+
+from minitap.mcp.core.logging_config import get_logger
+
+logger = get_logger(__name__)
+
+
+def create_remote_mcp_proxy(
+    mcp_url: str,
+    api_key: str,
+    prefix: str = "",
+) -> FastMCP:
+    """Create a proxy to the remote MaaS API MCP server.
+
+    This function creates a FastMCP proxy that connects to the remote MaaS API
+    MCP server using StreamableHTTP transport with Bearer authentication.
+
+    Args:
+        mcp_url: The URL of the remote MCP server (e.g., "http://127.0.0.1:8000/mcp").
+        api_key: The Minitap API key for authentication.
+        prefix: The prefix for remote tools (default: empty string, no prefix).
+
+    Returns:
+        A FastMCP proxy server configured to forward requests to the remote MCP.
+
+    Example:
+        >>> proxy = create_remote_mcp_proxy(
+        ...     mcp_url="http://127.0.0.1:8000/mcp",
+        ...     api_key="your-api-key"
+        ... )
+        >>> main_mcp.mount(proxy, prefix="remote")
+    """
+    logger.info(f"Creating remote MCP proxy for: {mcp_url}")
+
+    transport = StreamableHttpTransport(
+        url=mcp_url,
+        headers={
+            "Authorization": f"Bearer {api_key}",
+        },
+    )
+
+    proxy = FastMCP.as_proxy(
+        ProxyClient(transport),
+        name=f"remote-mcp-proxy-{prefix}",
+    )
+
+    logger.info(f"Remote MCP proxy created successfully with prefix: {prefix}")
+    return proxy
+
+
+async def check_remote_mcp_availability(mcp_url: str, api_key: str) -> bool:
+    """Check if the remote MCP server is available by testing TCP connection.
+
+    Args:
+        mcp_url: The URL of the remote MCP server (e.g., http://localhost:8000/mcp).
+        api_key: The Minitap API key for authentication (unused, kept for API compat).
+
+    Returns:
+        True if the remote MCP is available, False otherwise.
+    """
+
+    parsed = urlparse(mcp_url)
+    host = parsed.hostname or "localhost"
+    port = parsed.port or (443 if parsed.scheme == "https" else 80)
+
+    try:
+        # Simple TCP connection check
+        _, writer = await asyncio.wait_for(
+            asyncio.open_connection(host, port),
+            timeout=5.0,
+        )
+        writer.close()
+        await writer.wait_closed()
+        logger.info(f"Remote MCP availability check: connected to {host}:{port}")
+        return True
+    except TimeoutError:
+        logger.warning(f"Remote MCP availability check timed out: {mcp_url}")
+        return False
+    except OSError as e:
+        logger.warning(f"Remote MCP connection failed: {mcp_url} - {e}")
+        return False
+    except Exception as e:
+        logger.warning(f"Remote MCP availability check failed: {e}")
+        return False

minitap/mcp/tools/execute_mobile_command.py

@@ -13,6 +13,7 @@ from minitap.mcp.core.config import settings
 from minitap.mcp.core.decorators import handle_tool_errors
 from minitap.mcp.core.sdk_agent import get_mobile_use_agent
 from minitap.mcp.main import mcp
+from minitap.mcp.server.cloud_mobile import check_cloud_mobile_status
 
 
 def _serialize_result(result: Any) -> Any:
@@ -79,6 +80,9 @@ async def execute_mobile_command(
 ) -> str | dict[str, Any]:
     """Run a manual task on a mobile device via the Minitap platform."""
     try:
+        if settings.CLOUD_MOBILE_NAME:
+            await check_cloud_mobile_status(settings.CLOUD_MOBILE_NAME)
+
         if apk_path:
             if not settings.CLOUD_MOBILE_NAME:
                 raise ToolError(