minitap-mcp 0.3.0__py3-none-any.whl → 0.4.0__py3-none-any.whl

minitap/mcp/core/agents/compare_screenshots.md

@@ -0,0 +1,62 @@
+You will be given _two screenshots_.
+
+1. "Expected screenshot" — this is the design from Figma.
+2. "Implemented screenshot" — this is the actual phone screen that has been built.
+
+Your task is to **compare the two screenshots** in detail, and generate a structured report that includes:
+
+- A comprehensive list of **all visible differences** between the expected design and the implemented screen.
+- For each difference, provide:
+  - A clear **description** of what changed (for example: "The 'Submit' button label changed from 'Submit' to 'Send'", "The icon moved 8px to the right", "The background colour of header changed from #FFFFFF to #F6F6F6", etc.).
+  - The **type of change** (e.g., text change, color change, position/movement, size change, added element, removed element, style change).
+  - The **location** of the change (for example: "bottom-centre of screen", "top header area", "to the right of search bar"). If possible, approximate coordinates or bounding box (e.g., "approx. 240×180 px at screen width 1080").
+  - The **impact on implementation** (i.e., reasoning about what this means: "The implemented version uses a different text label – so behaviour may differ", "The icon moved and may overlap another element", etc.).
+  - A **recommendation** if relevant (e.g., "Should revert to #FFFFFF to match design", "Check alignment of icon relative to search bar", etc.).
+
+**Important**:
+
+- Assume the screenshots are aligned (same resolution and scale); if not aligned mention that as a difference.
+- Focus on _visible UI differences_ (layout, text, style, iconography) – you do _not_ need to inspect source code, only what is visually rendered.
+- Do _not_ produce generic comments like "looks like a difference" – aim for _precise, actionable descriptions_.
+- **IGNORE dynamic/personal content** that naturally differs between mockups and real implementations:
+  - User profile information (names, usernames, email addresses, profile pictures)
+  - Time-based information (current time, dates, timestamps, "2 hours ago", etc.)
+  - Dynamic data (notification counts, unread badges, live statistics)
+  - Sample/placeholder content that varies (e.g., "John Doe" vs "Jane Smith")
+  - System status information (battery level, signal strength, network indicators)
+  - Only flag these as differences if the _structure, layout, or styling_ of these elements differs, not the content itself.
+- Output in a structured format, for example:
+
+```
+
+1. Location: [top header – full width]
+   Change: Background colour changed from #FFFFFF → #F6F6F6
+   Type: Colour change
+   Impact: The header will appear darker than design; text contrast may be lower.
+   Recommendation: Update header background to #FFFFFF as in design.
+
+```
+
+- At the end produce a summary with ONLY:
+  - Total number of differences found
+  - Overall "match score" out of 100 (your estimation of how closely the implementation matches the design)
+  - Do NOT include any recap, overview, or macro-level summary of changes - all details are already captured in the differences list above.
+
+### Input:
+
+- Screenshot A: Expected (Figma)
+- Screenshot B: Implemented (Phone)
+  Provide both screenshots and then the prompt.
+
+### Output:
+
+Structured list of differences + summary.
+
+Please use the following to start the analysis.
+**Input:**
+First screen is the Figma screenshot (what is expected)
+Second screen is what is expected (taken from the phone, after the implementation)
+
+You will have this data in the next messages sent by the user.
+
+Go ahead and generate your report.

minitap/mcp/core/agents/compare_screenshots.py

@@ -0,0 +1,65 @@
+import asyncio
+from pathlib import Path
+from uuid import uuid4
+
+from jinja2 import Template
+from langchain_core.messages import BaseMessage, HumanMessage, SystemMessage
+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 import get_screenshot_message_for_llm
+
+
+class CompareScreenshotsOutput(BaseModel):
+    comparison_text: str
+    expected_screenshot_base64: str
+    current_screenshot_base64: str
+
+
+async def compare_screenshots(
+    expected_screenshot_base64: str,
+) -> CompareScreenshotsOutput:
+    """
+    Compare screenshots and return the comparison text along with both screenshots.
+
+    Returns:
+        CompareScreenshotsOutput
+    """
+    system_message = Template(
+        Path(__file__).parent.joinpath("compare_screenshots.md").read_text(encoding="utf-8")
+    ).render()
+
+    device = find_mobile_device()
+    current_screenshot = capture_screenshot(device)
+
+    messages: list[BaseMessage] = [
+        SystemMessage(content=system_message),
+        HumanMessage(content="Here is the Figma screenshot (what needs to be matched):"),
+        get_screenshot_message_for_llm(expected_screenshot_base64),
+        HumanMessage(content="Here is the screenshot of the mobile device:"),
+        get_screenshot_message_for_llm(current_screenshot),
+    ]
+
+    llm = get_minitap_llm(
+        trace_id=str(uuid4()),
+        remote_tracing=True,
+        model="google/gemini-2.5-pro",
+        temperature=1,
+    )
+    response = await llm.ainvoke(messages)
+    return CompareScreenshotsOutput(
+        comparison_text=str(response.content),
+        expected_screenshot_base64=expected_screenshot_base64,
+        current_screenshot_base64=current_screenshot,
+    )
+
+
+async def main():
+    expected_screenshot_base64 = "Base64 encoded screenshot to compare with."
+    result = await compare_screenshots(expected_screenshot_base64)
+    print(result.model_dump_json(indent=2))
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

minitap/mcp/core/agents/extract_figma_assets.md

@@ -0,0 +1,64 @@
+You are an expert at parsing React/TypeScript code to extract asset URLs and generate clean, documented code implementations.
+
+Your task is to:
+
+1. Extract all asset URLs from the provided code snippet
+2. Generate a clean `code_implementation` output that includes the React code with embedded comments referencing implementation and node guidelines
+
+**Instructions:**
+
+## Part 1: Extract Asset URLs
+
+1. Look for all constant declarations that contain URLs pointing to assets (images, SVGs, etc.)
+2. These constants typically follow patterns like:
+
+   - `const imgVariableName = "http://localhost:3845/assets/[hash].[extension]";`
+   - The variable names usually start with `img` followed by a descriptive name in camelCase
+
+3. For each asset URL found, extract:
+   - The **variable name** (e.g., `imgSignal`, `imgBatteryThreeQuarters`)
+   - The **full URL** (e.g., `http://localhost:3845/assets/685c5ac58caa29556e29737cf8f8c9605d9c8571.svg`)
+   - The **file extension** from the URL (e.g., `svg`, `png`, `jpg`)
+
+## Part 2: Generate Code Implementation
+
+The `code_implementation` field should contain:
+
+1. The React/TypeScript code with **LOCAL asset imports** instead of HTTP URLs:
+
+   - Convert `const imgSignal = "http://localhost:3845/assets/[hash].svg";`
+   - To `import imgSignal from './assets/imgSignal.svg';` (or appropriate relative path)
+   - Use the **exact same variable names** as in the original const declarations
+   - **CRITICAL**: Preserve the variable naming convention
+
+2. Preserve all `data-node-id` attributes and other metadata in the code
+
+## Part 3: Return Format
+
+Return a JSON object with two fields:
+
+- `assets`: Array of extracted asset objects
+- `code_implementation`: String containing the React code with embedded guideline comments
+
+```json
+{
+  "assets": [
+    {
+      "variable_name": "imgSignal",
+      "url": "http://localhost:3845/assets/685c5ac58caa29556e29737cf8f8c9605d9c8571.svg",
+      "extension": "svg"
+    },
+    ...
+  ],
+  "code_implementation": "import ... function ..."
+}
+```
+
+**Important:**
+
+- Only extract asset URLs
+- Preserve the exact variable names as they appear in the code
+- DO NOT MISS any assets
+- If no assets are found, return an empty array for `assets`
+- Return ONLY the JSON object with both `assets` and `code_implementation` fields
+- Do NOT include the const declarations of the assets in the code_implementation output - convert them to imports.

minitap/mcp/core/agents/extract_figma_assets.py

@@ -0,0 +1,65 @@
+"""Agent to extract Figma asset URLs from design context code."""
+
+from pathlib import Path
+from uuid import uuid4
+
+from jinja2 import Template
+from langchain_core.messages import BaseMessage, HumanMessage, SystemMessage
+from pydantic import BaseModel, Field
+
+from minitap.mcp.core.llm import get_minitap_llm
+
+
+class FigmaAsset(BaseModel):
+    """Represents a single Figma asset."""
+
+    variable_name: str = Field(description="The variable name from the code (e.g., imgSignal)")
+    url: str = Field(description="The full URL to the asset")
+    extension: str = Field(description="The file extension (e.g., svg, png, jpg)")
+
+
+class ExtractedAssets(BaseModel):
+    """Container for all extracted Figma assets."""
+
+    assets: list[FigmaAsset] = Field(
+        default_factory=list,
+        description="List of all extracted assets from the Figma design context",
+    )
+    code_implementation: str = Field(
+        description=(
+            "The React/TypeScript code\n"
+            "with the local url declarations turned into const declarations"
+        )
+    )
+
+
+async def extract_figma_assets(design_context_code: str) -> ExtractedAssets:
+    """Extract asset URLs from Figma design context code.
+
+    Args:
+        design_context_code: The React/TypeScript code from get_design_context
+
+    Returns:
+        List of dictionaries containing variable_name, url, and extension
+    """
+    system_message = Template(
+        Path(__file__).parent.joinpath("extract_figma_assets.md").read_text(encoding="utf-8")
+    ).render()
+
+    messages: list[BaseMessage] = [
+        SystemMessage(content=system_message),
+        HumanMessage(
+            content=f"Here is the code to analyze:\n\n```typescript\n{design_context_code}\n```"
+        ),
+    ]
+
+    llm = get_minitap_llm(
+        trace_id=str(uuid4()),
+        remote_tracing=True,
+        model="google/gemini-2.5-pro",
+        temperature=0,
+    ).with_structured_output(ExtractedAssets)
+
+    result: ExtractedAssets = await llm.ainvoke(messages)  # type: ignore
+
+    return result

minitap/mcp/core/config.py

@@ -19,6 +19,9 @@ class MCPSettings(BaseSettings):
 
     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")
+
     # MCP server configuration (optional, for remote access)
     MCP_SERVER_HOST: str = Field(default="0.0.0.0")
     MCP_SERVER_PORT: int = Field(default=8000)

minitap/mcp/core/models.py

@@ -0,0 +1,59 @@
+"""Core models for the MCP server."""
+
+from enum import Enum
+
+from pydantic import BaseModel, Field
+
+
+class FigmaAsset(BaseModel):
+    """Represents a single Figma asset."""
+
+    variable_name: str = Field(description="The variable name from the code (e.g., imgSignal)")
+    url: str = Field(description="The full URL to the asset")
+    extension: str = Field(description="The file extension (e.g., svg, png, jpg)")
+
+
+class FigmaDesignContextOutput(BaseModel):
+    """Output from Figma design context containing code and guidelines."""
+
+    code_implementation: str = Field(description="The React/TypeScript code implementation")
+    code_implementation_guidelines: str | None = Field(
+        default=None, description="Guidelines for implementing the code"
+    )
+    nodes_guidelines: str | None = Field(
+        default=None, description="Guidelines specific to the nodes"
+    )
+
+
+class DownloadStatus(str, Enum):
+    """Status of asset download operation."""
+
+    SUCCESS = "success"
+    FAILED = "failed"
+
+
+class AssetDownloadResult(BaseModel):
+    """Result of downloading a single asset."""
+
+    filename: str = Field(description="The filename of the asset")
+    status: DownloadStatus = Field(description="The download status")
+    error: str | None = Field(default=None, description="Error message if download failed")
+
+
+class AssetDownloadSummary(BaseModel):
+    """Summary of all asset download operations."""
+
+    successful: list[AssetDownloadResult] = Field(
+        default_factory=list, description="List of successfully downloaded assets"
+    )
+    failed: list[AssetDownloadResult] = Field(
+        default_factory=list, description="List of failed asset downloads"
+    )
+
+    def success_count(self) -> int:
+        """Return the number of successful downloads."""
+        return len(self.successful)
+
+    def failure_count(self) -> int:
+        """Return the number of failed downloads."""
+        return len(self.failed)

minitap/mcp/main.py

@@ -23,13 +23,11 @@ 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.mobile_use.config import settings as sdk_settings
-from minitap.mcp.core.device import (
-    DeviceInfo,  # noqa: E402
-    list_available_devices,
-)
+from minitap.mcp.core.device import DeviceInfo  # noqa: E402
+from minitap.mcp.core.device import list_available_devices
 from minitap.mcp.server.middleware import MaestroCheckerMiddleware
 from minitap.mcp.server.poller import device_health_poller
 
@@ -39,6 +37,7 @@ def main() -> None:
 
     parser = argparse.ArgumentParser(description="Mobile Use MCP Server")
     parser.add_argument("--api-key", type=str, required=False, default=None)
+    parser.add_argument("--llm-profile", type=str, required=False, default=None)
     parser.add_argument(
         "--server",
         action="store_true",
@@ -46,14 +45,17 @@ def main() -> None:
     )
 
     args = parser.parse_args()
-    print("parsing args")
-    print(args)
 
     if args.api_key:
         os.environ["MINITAP_API_KEY"] = args.api_key
         settings.__init__()
         sdk_settings.__init__()
 
+    if args.llm_profile:
+        os.environ["MINITAP_LLM_PROFILE_NAME"] = args.llm_profile
+        settings.__init__()
+        sdk_settings.__init__()
+
     if not settings.MINITAP_API_KEY:
         raise ValueError("Minitap API key is required to run the MCP")
 
@@ -80,11 +82,10 @@ mcp = FastMCP(
         Call get_available_devices() to list them.
     """,
 )
-
-from minitap.mcp.tools import (  # noqa: E402, F401
-    analyze_screen,  # noqa: E402, F401
-    execute_mobile_command,  # noqa: E402, F401
-)
+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
 
 
 @mcp.resource("data://devices")
@@ -94,7 +95,7 @@ def get_available_devices() -> list[DeviceInfo]:
 
 
 def mcp_lifespan(**mcp_run_kwargs):
-    from minitap.mcp.core.agents import get_mobile_use_agent  # noqa: E402
+    from minitap.mcp.core.sdk_agent import get_mobile_use_agent  # noqa: E402
 
     agent = get_mobile_use_agent()
     mcp.add_middleware(MaestroCheckerMiddleware(agent))
@@ -108,16 +109,25 @@ def mcp_lifespan(**mcp_run_kwargs):
             stop_event,
             agent,
         ),
+        daemon=True,
     )
     poller_thread.start()
 
     try:
         mcp.run(**mcp_run_kwargs)
     except KeyboardInterrupt:
-        pass
-
-    # Stop device health poller
-    stop_event.set()
-    logger.info("Device health poller stopping...")
-    poller_thread.join()
-    logger.info("Device health poller stopped")
+        logger.info("Keyboard interrupt received, shutting down...")
+    except Exception as e:
+        logger.error(f"Error running MCP server: {e}")
+    finally:
+        # Stop device health poller
+        logger.info("Stopping device health poller...")
+        stop_event.set()
+
+        # Give the poller thread a reasonable time to stop gracefully
+        poller_thread.join(timeout=10.0)
+
+        if poller_thread.is_alive():
+            logger.warning("Device health poller thread did not stop gracefully")
+        else:
+            logger.info("Device health poller stopped successfully")

minitap/mcp/server/poller.py

@@ -1,38 +1,78 @@
 """Device health monitoring poller for the MCP server."""
 
+import asyncio
 import logging
-import time
 import threading
 
-from minitap.mcp.core.device import list_available_devices
 from minitap.mobile_use.sdk import Agent
 
+from minitap.mcp.core.device import list_available_devices
+
 logger = logging.getLogger(__name__)
 
 
-def device_health_poller(stop_event: threading.Event, agent: Agent) -> None:
+async def _async_device_health_poller(stop_event: threading.Event, agent: Agent) -> None:
     """
-    Background poller that monitors device availability and agent health.
-    Runs every 5 seconds to ensure a device is connected and the agent is healthy.
+    Async implementation of device health poller.
 
     Args:
+        stop_event: Threading event to signal when to stop polling.
         agent: The Agent instance to monitor and reinitialize if needed.
     """
     while not stop_event.is_set():
         try:
-            time.sleep(5)
+            # Sleep in smaller chunks to be more responsive to stop signal
+            for _ in range(50):  # 50 * 0.1 = 5 seconds total
+                if stop_event.is_set():
+                    break
+                await asyncio.sleep(0.1)
+
+            if stop_event.is_set():
+                break
 
             devices = list_available_devices()
 
             if len(devices) > 0:
                 if not agent.is_healthy():
                     logger.warning("Agent is not healthy. Reinitializing...")
-                    agent.clean(force=True)
-                    agent.init()
+                    await agent.clean(force=True)
+                    await agent.init()
                     logger.info("Agent reinitialized successfully")
             else:
                 logger.info("No mobile device found, retrying in 5 seconds...")
 
         except Exception as e:
             logger.error(f"Error in device health poller: {e}")
-    agent.clean(force=True)
+
+    try:
+        await agent.clean(force=True)
+        logger.info("Agent cleaned up successfully")
+    except Exception as e:
+        logger.error(f"Error cleaning up agent: {e}")
+
+
+def device_health_poller(stop_event: threading.Event, agent: Agent) -> None:
+    """
+    Background poller that monitors device availability and agent health.
+    Runs every 5 seconds to ensure a device is connected and the agent is healthy.
+
+    This is a sync wrapper that runs the async poller in a new event loop.
+
+    Args:
+        stop_event: Threading event to signal when to stop polling.
+        agent: The Agent instance to monitor and reinitialize if needed.
+    """
+    loop = None
+    try:
+        loop = asyncio.new_event_loop()
+        asyncio.set_event_loop(loop)
+
+        loop.run_until_complete(_async_device_health_poller(stop_event, agent))
+    except Exception as e:
+        logger.error(f"Error in device health poller thread: {e}")
+    finally:
+        if loop is not None:
+            try:
+                loop.close()
+            except Exception:
+                pass

minitap/mcp/tools/compare_screenshot_with_figma.py

@@ -0,0 +1,132 @@
+"""Tool for navigating to a screen and comparing it with Figma design."""
+
+import base64
+from io import BytesIO
+
+import mcp as mcp_ref
+from fastmcp import Client
+from fastmcp.client.client import CallToolResult
+from fastmcp.exceptions import ToolError
+from fastmcp.tools.tool import ToolResult
+from PIL import Image
+from pydantic import Field
+
+from minitap.mcp.core.agents.compare_screenshots import compare_screenshots
+from minitap.mcp.core.config import settings
+from minitap.mcp.core.decorators import handle_tool_errors
+from minitap.mcp.main import mcp
+
+
+@mcp.tool(
+    name="compare_screenshot_with_figma",
+    description="""
+    Compare a screenshot of the current state with a Figma design.
+    
+    This tool:
+    1. Captures a screenshot of the current state
+    2. Compares the live device screenshot with the Figma design
+    3. Returns a detailed comparison report with both screenshots for visual context
+    """,
+)
+@handle_tool_errors
+async def compare_screenshot_with_figma(
+    node_id: str = Field(
+        description=(
+            "The node ID of the Figma design. Expected format is ':' separated.\n"
+            "Example: If given the URL https://figma.com/design/:fileKey/:fileName?node-id=1-2,\n"
+            "the extracted nodeId would be 1:2. Strictly respect this format."
+        )
+    ),
+) -> ToolResult:
+    expected_screenshot_base64 = await get_figma_screenshot(node_id)
+
+    result = await compare_screenshots(
+        expected_screenshot_base64=expected_screenshot_base64,
+    )
+
+    compressed_expected = compress_image_base64(result.expected_screenshot_base64)
+    compressed_current = compress_image_base64(result.current_screenshot_base64)
+
+    return ToolResult(
+        content=[
+            mcp_ref.types.TextContent(
+                type="text",
+                text="## Comparison Analysis\n\n" + str(result.comparison_text),
+            ),
+            mcp_ref.types.ImageContent(
+                type="image",
+                data=compressed_expected,
+                mimeType="image/jpeg",
+            ),
+            mcp_ref.types.TextContent(
+                type="text",
+                text="**Expected (Figma design)** ↑\n\n**Actual (Current device)** ↓",
+            ),
+            mcp_ref.types.ImageContent(
+                type="image",
+                data=compressed_current,
+                mimeType="image/jpeg",
+            ),
+        ]
+    )
+
+
+def compress_image_base64(base64_str: str, max_width: int = 800, quality: int = 75) -> str:
+    """Compress and resize a base64-encoded image to reduce size.
+
+    Args:
+        base64_str: Base64-encoded image string
+        max_width: Maximum width for the resized image
+        quality: JPEG quality (1-95, lower = smaller file)
+
+    Returns:
+        Compressed base64-encoded image string
+    """
+    try:
+        img_data = base64.b64decode(base64_str)
+        img = Image.open(BytesIO(img_data))
+
+        if img.mode in ("RGBA", "P", "LA"):
+            background = Image.new("RGB", img.size, (255, 255, 255))
+            if img.mode == "P":
+                img = img.convert("RGBA")
+            if "A" in img.mode:
+                background.paste(img, mask=img.split()[-1])
+            else:
+                background.paste(img)
+            img = background
+        elif img.mode != "RGB":
+            img = img.convert("RGB")
+
+        if img.width > max_width:
+            ratio = max_width / img.width
+            new_height = int(img.height * ratio)
+            img = img.resize((max_width, new_height), Image.Resampling.LANCZOS)
+
+        buffer = BytesIO()
+        img.save(buffer, format="JPEG", quality=quality, optimize=True)
+        compressed_data = buffer.getvalue()
+
+        return base64.b64encode(compressed_data).decode("utf-8")
+    except Exception:
+        return base64_str
+
+
+async def get_figma_screenshot(node_id: str) -> str:
+    try:
+        async with Client(settings.FIGMA_MCP_SERVER_URL) as client:
+            result: CallToolResult = await client.call_tool(
+                "get_screenshot",
+                {
+                    "nodeId": node_id,
+                    "clientLanguages": "javascript",
+                    "clientFrameworks": "react",
+                },
+            )
+            if len(result.content) == 0 or not isinstance(
+                result.content[0], mcp_ref.types.ImageContent
+            ):
+                raise ToolError("Failed to fetch screenshot from Figma")
+        return result.content[0].data
+    except Exception as e:
+        raise ToolError(f"Failed to fetch screenshot from Figma: {str(e)}")

minitap/mcp/tools/execute_mobile_command.py

@@ -8,8 +8,8 @@ from minitap.mobile_use.sdk.types import ManualTaskConfig
 from minitap.mobile_use.sdk.types.task import PlatformTaskRequest
 from pydantic import Field
 
-from minitap.mcp.core.agents import get_mobile_use_agent
 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
 
 

minitap/mcp/tools/save_figma_assets.py

@@ -0,0 +1,258 @@
+"""Tool for fetching and saving Figma assets locally."""
+
+import shutil
+from pathlib import Path
+
+import mcp as mcp_ref
+import requests
+from fastmcp import Client
+from fastmcp.client.client import CallToolResult
+from fastmcp.exceptions import ToolError
+from fastmcp.tools.tool import ToolResult
+from pydantic import Field
+
+from minitap.mcp.core.agents.extract_figma_assets import (
+    ExtractedAssets,
+    FigmaAsset,
+    extract_figma_assets,
+)
+from minitap.mcp.core.config import settings
+from minitap.mcp.core.decorators import handle_tool_errors
+from minitap.mcp.core.models import (
+    AssetDownloadResult,
+    AssetDownloadSummary,
+    DownloadStatus,
+    FigmaDesignContextOutput,
+)
+from minitap.mcp.main import mcp
+from minitap.mcp.tools.compare_screenshot_with_figma import (
+    compress_image_base64,
+    get_figma_screenshot,
+)
+
+
+@mcp.tool(
+    name="save_figma_assets",
+    description="""
+    Fetch Figma design assets/react implementation code and save them locally in the workspace.
+    
+    This tool:
+    1. Calls get_design_context from Figma MCP to get the React/TypeScript code
+    2. Extracts all asset URLs and code implementation from the code
+    3. Downloads each asset to .mobile-use/figma_assets/<node-id>/ folder
+    4. Saves the code implementation to .mobile-use/figma_assets/<node-id>/code_implementation.ts
+    5. Returns a list of downloaded files
+    """,
+)
+@handle_tool_errors
+async def save_figma_assets(
+    node_id: str = Field(
+        description=(
+            "The node ID of the Figma design. Expected format is ':' separated.\n"
+            "Example: If given the URL https://figma.com/design/:fileKey/:fileName?node-id=1-2,\n"
+            "the extracted nodeId would be 1:2. Strictly respect this format."
+        )
+    ),
+    file_key: str = Field(
+        description=(
+            "The file key of the Figma file.\n"
+            "Example: If given the URL https://figma.com/design/abc123/MyFile?node-id=1-2,\n"
+            "the extracted fileKey would be 'abc123'."
+        )
+    ),
+    workspace_path: str = Field(
+        default=".",
+        description=(
+            "The workspace path where assets should be saved. Defaults to current directory."
+        ),
+    ),
+) -> ToolResult:
+    """Fetch and save Figma assets locally."""
+
+    # Step 1: Get design context from Figma MCP
+    design_context = await get_design_context(node_id, file_key)
+
+    # Step 2: Extract asset URLs using LLM agent
+    extracted_context: ExtractedAssets = await extract_figma_assets(
+        design_context.code_implementation
+    )
+    if not extracted_context.assets:
+        raise ToolError("No assets found in the Figma design context.")
+
+    # Step 3: Create directory structure
+    # Convert node_id format (1:2) to folder name (1-2)
+    folder_name = node_id.replace(":", "-")
+    assets_dir = Path(workspace_path) / ".mobile-use" / "figma_assets" / folder_name
+
+    # Delete existing directory to remove stale assets
+    if assets_dir.exists():
+        shutil.rmtree(assets_dir)
+
+    # Create fresh directory
+    assets_dir.mkdir(parents=True, exist_ok=True)
+
+    # Step 4: Download assets with resilient error handling
+    download_summary = AssetDownloadSummary()
+
+    for asset in extracted_context.assets:
+        result = download_asset(asset, assets_dir)
+        if result.status == DownloadStatus.SUCCESS:
+            download_summary.successful.append(result)
+        else:
+            download_summary.failed.append(result)
+
+    # Step 4.5: Save code implementation
+    code_implementation_file = assets_dir / "code_implementation.ts"
+
+    commented_code_implementation_guidelines = ""
+    if design_context.code_implementation_guidelines:
+        commented_code_implementation_guidelines = "\n".join(
+            ["// " + line for line in design_context.code_implementation_guidelines.split("\n")]
+        )
+
+    commented_nodes_guidelines = ""
+    if design_context.nodes_guidelines:
+        commented_nodes_guidelines = "\n".join(
+            ["// " + line for line in design_context.nodes_guidelines.split("\n")]
+        )
+
+    code_implementation_file.write_text(
+        extracted_context.code_implementation
+        + "\n\n"
+        + commented_code_implementation_guidelines
+        + "\n\n"
+        + commented_nodes_guidelines
+    )
+
+    # Step 5: Generate friendly output message
+    result_parts = []
+
+    if download_summary.successful:
+        result_parts.append(
+            f"✅ Successfully downloaded {download_summary.success_count()} asset(s) "
+            f"to .mobile-use/figma_assets/{folder_name}/:\n"
+        )
+        for asset_result in download_summary.successful:
+            result_parts.append(f"  • {asset_result.filename}")
+
+    if download_summary.failed:
+        result_parts.append(
+            f"\n\n⚠️ Failed to download {download_summary.failure_count()} asset(s):"
+        )
+        for asset_result in download_summary.failed:
+            error_msg = f": {asset_result.error}" if asset_result.error else ""
+            result_parts.append(f"  • {asset_result.filename}{error_msg}")
+
+    if code_implementation_file.exists():
+        result_parts.append(
+            f"\n\n✅ Successfully saved code implementation to {code_implementation_file.name}"
+        )
+
+    expected_screenshot = await get_figma_screenshot(node_id)
+    compressed_expected = compress_image_base64(expected_screenshot)
+
+    return ToolResult(
+        content=[
+            mcp_ref.types.TextContent(
+                type="text",
+                text="\n".join(result_parts),
+            ),
+            mcp_ref.types.TextContent(
+                type="text",
+                text="**Expected (Figma design)**",
+            ),
+            mcp_ref.types.ImageContent(
+                type="image",
+                data=compressed_expected,
+                mimeType="image/jpeg",
+            ),
+        ]
+    )
+
+
+async def get_design_context(node_id: str, file_key: str) -> FigmaDesignContextOutput:
+    """Fetch design context from Figma MCP server.
+
+    Args:
+        node_id: The Figma node ID in format "1:2"
+        file_key: The Figma file key
+
+    Returns:
+        The React/TypeScript code as a string
+
+    Raises:
+        ToolError: If fetching fails
+    """
+    try:
+        async with Client(settings.FIGMA_MCP_SERVER_URL) as client:
+            result: CallToolResult = await client.call_tool(
+                "get_design_context",
+                {
+                    "nodeId": node_id,
+                    "fileKey": file_key,
+                    "clientLanguages": "typescript",
+                    "clientFrameworks": "react",
+                },
+            )
+
+            code_implementation = ""
+            code_implementation_guidelines = None
+            nodes_guidelines = None
+
+            if len(result.content) > 0 and isinstance(result.content[0], mcp_ref.types.TextContent):
+                code_implementation = result.content[0].text
+            else:
+                raise ToolError("Failed to fetch design context from Figma")
+
+            if len(result.content) > 1:
+                if isinstance(result.content[1], mcp_ref.types.TextContent):
+                    code_implementation_guidelines = result.content[1].text
+            if len(result.content) > 2 and isinstance(result.content[2], mcp_ref.types.TextContent):
+                nodes_guidelines = result.content[2].text
+
+            return FigmaDesignContextOutput(
+                code_implementation=code_implementation,
+                code_implementation_guidelines=code_implementation_guidelines,
+                nodes_guidelines=nodes_guidelines,
+            )
+    except Exception as e:
+        raise ToolError(
+            f"Failed to fetch design context from Figma: {str(e)}.\n"
+            "Ensure the Figma MCP server is running through the official Figma desktop app."
+        )
+
+
+def download_asset(asset: FigmaAsset, assets_dir: Path) -> AssetDownloadResult:
+    """Download a single asset with error handling.
+
+    Args:
+        asset: FigmaAsset model with variable_name, url, and extension
+        assets_dir: Directory to save the asset
+
+    Returns:
+        AssetDownloadResult with status and optional error message
+    """
+    variable_name = asset.variable_name
+    url = asset.url
+    extension = asset.extension
+
+    # Convert camelCase variable name to filename
+    # e.g., imgSignal -> imgSignal.svg
+    filename = f"{variable_name}.{extension}"
+    filepath = assets_dir / filename
+
+    try:
+        response = requests.get(url, timeout=30)
+        if response.status_code == 200:
+            filepath.write_bytes(response.content)
+            return AssetDownloadResult(filename=filename, status=DownloadStatus.SUCCESS)
+        else:
+            return AssetDownloadResult(
+                filename=filename,
+                status=DownloadStatus.FAILED,
+                error=f"HTTP {response.status_code}",
+            )
+    except requests.exceptions.Timeout:
+        return AssetDownloadResult(filename=filename, status=DownloadStatus.FAILED, error="Timeout")
+    except Exception as e:
+        return AssetDownloadResult(filename=filename, status=DownloadStatus.FAILED, error=str(e))

{minitap_mcp-0.3.0.dist-info → minitap_mcp-0.4.0.dist-info}/METADATA

@@ -1,15 +1,16 @@
 Metadata-Version: 2.3
 Name: minitap-mcp
-Version: 0.3.0
+Version: 0.4.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.6.0
+Requires-Dist: minitap-mobile-use>=2.8.1
 Requires-Dist: jinja2>=3.1.6
 Requires-Dist: langchain-core>=0.3.75
+Requires-Dist: pillow>=11.1.0
 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'
@@ -37,41 +38,50 @@ 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 (optional but recommended)
+  - [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 (optional but recommended)
+  - [Maestro](https://maestro.mobile.dev/) - For mobile automation
 
 For detailed setup instructions, see the [mobile-use repository](https://github.com/minitap-ai/mobile-use).
 
-### Configuration
+### Running the Server
 
-Set your Minitap API credentials as environment variables:
+The simplest way to start:
 
 ```bash
-export MINITAP_API_KEY="your_api_key_here"
-export MINITAP_API_BASE_URL="https://platform.minitap.ai/api/v1"
-export MINITAP_LLM_PROFILE_NAME="default"
+minitap-mcp --server --api-key your_minitap_api_key
 ```
 
-You can set these variables in your `.bashrc` or equivalent.
+This starts the server on `localhost:8000` with your API key. Get your free API key at [platform.minitap.ai/api-keys](https://platform.minitap.ai/api-keys).
 
-### Running the Server
+**Available CLI options:**
+
+```bash
+minitap-mcp --server --api-key YOUR_KEY --llm-profile PROFILE_NAME
+```
 
-**With environment variables:**
+- `--api-key`: Your Minitap API key (overrides `MINITAP_API_KEY` env var). Get yours at [platform.minitap.ai/api-keys](https://platform.minitap.ai/api-keys).
+- `--llm-profile`: LLM profile name to use (overrides `MINITAP_LLM_PROFILE_NAME` env var). If unset, uses the default profile. Configure profiles at [platform.minitap.ai/llm-profiles](https://platform.minitap.ai/llm-profiles).
+
+### Configuration (Optional)
+
+Alternatively, you can set environment variables instead of using CLI flags:
 
 ```bash
-minitap-mcp --server
+export MINITAP_API_KEY="your_minitap_api_key"
+export MINITAP_API_BASE_URL="https://platform.minitap.ai/api/v1"
+export MINITAP_LLM_PROFILE_NAME="default"
 ```
 
-**With API key as argument:**
+You can set these in your `.bashrc` or equivalent, then simply run:
 
 ```bash
-minitap-mcp --server --api-key your_api_key_here
+minitap-mcp --server
 ```
 
-Using `--api-key` overrides the `MINITAP_API_KEY` environment variable, useful for quick testing.
+CLI flags always override environment variables when both are present.
 
 By default, the server will bind to `0.0.0.0:8000`. Configure via environment variables:
 
@@ -82,7 +92,7 @@ export MCP_SERVER_PORT="8000"
 
 ## IDE Integration
 
-1. Start the server: `minitap-mcp --server`
+1. Start the server: `minitap-mcp --server --api-key your_minitap_api_key`
 2. Add to your IDE MCP settings file:
 
 ```jsonc
@@ -118,7 +128,7 @@ Execute natural language commands on your mobile device using the Minitap SDK. T
 
 **Parameters:**
 - `goal` (required): High-level goal describing the action to perform
-- `output_description` (optional): Description of expected output format
+- `output_description` (optional): Natural language description of the desired output format. Results are returned as structured JSON (e.g., "An array with sender and subject for each email")
 - `profile` (optional): Profile name to use (defaults to "default")
 
 **Examples:**

minitap_mcp-0.4.0.dist-info/RECORD

@@ -0,0 +1,25 @@
+minitap/mcp/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+minitap/mcp/core/agents/compare_screenshots.md,sha256=Gt27HVzXzu71BxcanKPokz1dFPvq90vXbjE2HOn5X0I,3559
+minitap/mcp/core/agents/compare_screenshots.py,sha256=Yb7kR8Cv0gWzXyNf-6IS7_9l1npfqYmL-SONJJGgzM4,2060
+minitap/mcp/core/agents/extract_figma_assets.md,sha256=JrXuWF8-2PeQpVix-kf-p6zmu2gQVf9Z6ptTK1cedDk,2413
+minitap/mcp/core/agents/extract_figma_assets.py,sha256=WAmn4CvN1ONJkJp2KH9l080hhZ_ge0Pdan6ejk_GWOo,2038
+minitap/mcp/core/config.py,sha256=gfx-cXJsgB_W2dSNHnb5jeWEYfe3VBZUMeF1nbNAdiQ,962
+minitap/mcp/core/decorators.py,sha256=iekv181o_rkv0upacFWkmPqxsZRTzuLFyOZ0sIDtQnQ,1317
+minitap/mcp/core/device.py,sha256=sEO3Z-8F325hDOObdH1YBhZE60f17FmIclt5UlhY_nU,7875
+minitap/mcp/core/llm.py,sha256=z_pYZkZcAchsiWPh4W79frQPANsfYyFPUe8DJo8lZO0,822
+minitap/mcp/core/models.py,sha256=egLScxPAMo4u5cqY33UKba7z7DsdgqfPW409UAqW1Jg,1942
+minitap/mcp/core/sdk_agent.py,sha256=-9l1YetD93dzxOeSFOT_j8dDfDFjhJLiir8bhzEjI3Y,900
+minitap/mcp/core/utils.py,sha256=3uExpRoh7affIieZx3TLlZTmZCcoxWfx1YpPbwhjiJY,1791
+minitap/mcp/main.py,sha256=B7KE6_5UNGKanS0WMJYBq8vp0HE_Lr0BG9KR4BwYxwU,4341
+minitap/mcp/server/middleware.py,sha256=fbry_IiHmwUxVjsWgOU2goybcS1kLRXFZZ89KPH1d8E,880
+minitap/mcp/server/poller.py,sha256=Qakq4yO3EJ9dXmRqtE3sJjyk0ij7VBU-NuupHhTf37g,2539
+minitap/mcp/tools/analyze_screen.py,sha256=fjcjf3tTZDlxzmiQFHFNgw38bxPz4eisw57zuxshN2A,1984
+minitap/mcp/tools/compare_screenshot_with_figma.py,sha256=G69F6vRFI2tE2wW-oFYPjnY8oFMD9nRZH0H-yvtD4gE,4575
+minitap/mcp/tools/execute_mobile_command.py,sha256=qY3UfcDq1BtYcny1YlEF4WV9LwUJxLAmLJCm1VBzxS8,2442
+minitap/mcp/tools/go_back.py,sha256=lEmADkDkXu8JGm-sY7zL7M6GlBy-lD7Iffv4yzwoQfo,1301
+minitap/mcp/tools/save_figma_assets.py,sha256=EN0u0TkCUXoz8guehxm-CywKYYmZFg_d4x35eTNAovQ,9182
+minitap/mcp/tools/screen_analyzer.md,sha256=TTO80JQWusbA9cKAZn-9cqhgVHm6F_qJh5w152hG3YM,734
+minitap_mcp-0.4.0.dist-info/WHEEL,sha256=5w2T7AS2mz1-rW9CNagNYWRCaB0iQqBMYLwKdlgiR4Q,78
+minitap_mcp-0.4.0.dist-info/entry_points.txt,sha256=rYVoXm7tSQCqQTtHx4Lovgn1YsjwtEEHfddKrfEVHuY,55
+minitap_mcp-0.4.0.dist-info/METADATA,sha256=27wi_Bedtm971es6fHljAF8wE45uCkSoYYwwqqFvmY0,5885
+minitap_mcp-0.4.0.dist-info/RECORD,,

{minitap_mcp-0.3.0.dist-info → minitap_mcp-0.4.0.dist-info}/WHEEL

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

minitap_mcp-0.3.0.dist-info/RECORD

@@ -1,18 +0,0 @@
-minitap/mcp/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-minitap/mcp/core/agents.py,sha256=-9l1YetD93dzxOeSFOT_j8dDfDFjhJLiir8bhzEjI3Y,900
-minitap/mcp/core/config.py,sha256=ohJ50qQp6wKFBcX8hr0IbSGnrlbWg1YAwrgJ9I1_vLE,849
-minitap/mcp/core/decorators.py,sha256=iekv181o_rkv0upacFWkmPqxsZRTzuLFyOZ0sIDtQnQ,1317
-minitap/mcp/core/device.py,sha256=sEO3Z-8F325hDOObdH1YBhZE60f17FmIclt5UlhY_nU,7875
-minitap/mcp/core/llm.py,sha256=z_pYZkZcAchsiWPh4W79frQPANsfYyFPUe8DJo8lZO0,822
-minitap/mcp/core/utils.py,sha256=3uExpRoh7affIieZx3TLlZTmZCcoxWfx1YpPbwhjiJY,1791
-minitap/mcp/main.py,sha256=eoF-wDgXmS_eZYpWBJBXTQaOOGhHHxY-IIwG0C6cW9s,3557
-minitap/mcp/server/middleware.py,sha256=fbry_IiHmwUxVjsWgOU2goybcS1kLRXFZZ89KPH1d8E,880
-minitap/mcp/server/poller.py,sha256=C2h5Ir3nY5gZ6qTDOHBw_Tb8PfAY54A-we2HrwjNLvg,1222
-minitap/mcp/tools/analyze_screen.py,sha256=fjcjf3tTZDlxzmiQFHFNgw38bxPz4eisw57zuxshN2A,1984
-minitap/mcp/tools/execute_mobile_command.py,sha256=f5yObnn9r2pZ33w0I2TwvCZKKepqlKbpVANZnUkfFjU,2439
-minitap/mcp/tools/go_back.py,sha256=lEmADkDkXu8JGm-sY7zL7M6GlBy-lD7Iffv4yzwoQfo,1301
-minitap/mcp/tools/screen_analyzer.md,sha256=TTO80JQWusbA9cKAZn-9cqhgVHm6F_qJh5w152hG3YM,734
-minitap_mcp-0.3.0.dist-info/WHEEL,sha256=k57ZwB-NkeM_6AsPnuOHv5gI5KM5kPD6Vx85WmGEcI0,78
-minitap_mcp-0.3.0.dist-info/entry_points.txt,sha256=rYVoXm7tSQCqQTtHx4Lovgn1YsjwtEEHfddKrfEVHuY,55
-minitap_mcp-0.3.0.dist-info/METADATA,sha256=5BB82VEtjp_R5mcyxD40DspuYXdgEOijlFf9nFqr3NM,5128
-minitap_mcp-0.3.0.dist-info/RECORD,,