minitap-mcp 0.4.3__tar.gz → 0.5.1__tar.gz

{minitap_mcp-0.4.3 → minitap_mcp-0.5.1}/PKG-INFO

@@ -1,13 +1,13 @@
 Metadata-Version: 2.3
 Name: minitap-mcp
-Version: 0.4.3
+Version: 0.5.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
 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.8.2
+Requires-Dist: minitap-mobile-use>=2.9.1
 Requires-Dist: jinja2>=3.1.6
 Requires-Dist: langchain-core>=0.3.75
 Requires-Dist: pillow>=11.1.0

minitap_mcp-0.4.3/minitap/mcp/core/agents/compare_screenshots.py → minitap_mcp-0.5.1/minitap/mcp/core/agents/compare_screenshots/agent.py

@@ -8,7 +8,7 @@ from pydantic import BaseModel
 
 from minitap.mcp.core.device import capture_screenshot, find_mobile_device
 from minitap.mcp.core.llm import get_minitap_llm
-from minitap.mcp.core.utils import get_screenshot_message_for_llm
+from minitap.mcp.core.utils.images import get_screenshot_message_for_llm
 
 
 class CompareScreenshotsOutput(BaseModel):
@@ -27,7 +27,7 @@ async def compare_screenshots(
         CompareScreenshotsOutput
     """
     system_message = Template(
-        Path(__file__).parent.joinpath("compare_screenshots.md").read_text(encoding="utf-8")
+        Path(__file__).parent.joinpath("prompt.md").read_text(encoding="utf-8")
     ).render()
 
     device = find_mobile_device()

minitap_mcp-0.4.3/minitap/mcp/core/agents/compare_screenshots.md → minitap_mcp-0.5.1/minitap/mcp/core/agents/compare_screenshots/eval/prompts/prompt_1.md

@@ -55,8 +55,8 @@ 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)
+Second screen is what is implemented (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.
+Go ahead and generate your report.

minitap_mcp-0.5.1/minitap/mcp/core/agents/compare_screenshots/eval/scenario_1_add_cartoon_img_and_move_button/human_feedback.txt

@@ -0,0 +1,18 @@
+6 differences found :
+- Add button moved and restyled
+The “+ Add” button is now at the top instead of the bottom, and its style is very different. This is a big layout change — confirm with design.
+
+- Title typo
+“Languges” should be “Languages”.
+
+- Subtitle casing
+The subtitle should be sentence case (“You are learning”), not title case.
+
+- Extra robot illustration
+A large yellow robot was added but isn’t in the design. Confirm if it should be there.
+
+- Extra sub-label in list item
+“Norwegian” has a second line (“from French”), which isn’t part of the design. Check if this is intended.
+
+- Missing small “M” icon
+The red “M” in the bottom-right is missing.

minitap_mcp-0.5.1/minitap/mcp/core/agents/compare_screenshots/eval/scenario_1_add_cartoon_img_and_move_button/prompt_1/model_params.json

@@ -0,0 +1,3 @@
+{
+  "model_name": "gemini-2.5-pro"
+}

minitap_mcp-0.5.1/minitap/mcp/core/agents/compare_screenshots/eval/scenario_1_add_cartoon_img_and_move_button/prompt_1/output.md

@@ -0,0 +1,46 @@
+Based on the visual comparison of the provided screenshots, here is a detailed report of the differences.
+
+---
+
+1.  **Location**: Top-right of the header area vs. bottom-center of the screen
+    **Change**: The `+ Add` button has been moved from a full-width element at the bottom of the screen to a smaller, pill-shaped button in the top-right header area. Its style has also changed from a button with only a text label and icon to one with a solid yellow background and white text/icon.
+    **Type**: Position/Movement, Style Change, Size Change
+    **Impact**: This is a major structural change to the page layout. The primary call-to-action is in a completely different location, which fundamentally alters the user's interaction pattern with the screen.
+    **Recommendation**: The development team should align with the design team on the intended placement and style of this critical action button. This change is too significant to be accidental and suggests a disconnect between design and implementation requirements.
+
+2.  **Location**: Page title area, below the `X` icon.
+    **Change**: The page title text is misspelled as "Languges" in the implementation, whereas the design specifies "Languages".
+    **Type**: Text Change
+    **Impact**: Introduces a spelling error on a primary screen title, which appears unprofessional.
+    **Recommendation**: Correct the typo in the title to "Languages".
+
+3.  **Location**: Subtitle area, directly below the page title.
+    **Change**: The text casing for the subtitle has been changed from sentence case ("You are learning") to title case ("You are Learning").
+    **Type**: Text Change / Style Change
+    **Impact**: A minor visual inconsistency that deviates from the typographic style defined in the design.
+    **Recommendation**: Update the subtitle text to use sentence case ("You are learning") to match the design specification.
+
+4.  **Location**: Bottom half of the screen.
+    **Change**: The implemented screen includes a large illustration of a yellow robot character that is not present in the expected design.
+    **Type**: Added Element
+    **Impact**: This new element significantly alters the visual hierarchy and feel of the screen, consuming a large amount of whitespace and adding a strong branding element not specified in the design.
+    **Recommendation**: Verify with the product/design team if this illustration is an intended addition. If not, it should be removed to match the figma design.
+
+5.  **Location**: Second item in the language list ("Norwegian").
+    **Change**: One of the language list items in the implementation includes a gray sub-label ("from French") below the language name. The design for list items shows only a single line of text for the language.
+    **Type**: Added Element (within a component)
+    **Impact**: The implemented list item component has a different structure than designed, supporting two lines of text instead of one. This affects component height and internal layout.
+    **Recommendation**: Clarify if this two-line state is a required feature. If so, the design should be updated to include this variant. If not, the sub-label should be removed.
+
+6.  **Location**: Bottom-right corner of the screen.
+    **Change**: The expected design includes a small, red "M" character/logo in the bottom-right corner. This element is missing from the implemented screen.
+    **Type**: Removed Element
+    **Impact**: A subtle branding or UI element has been omitted from the final implementation.
+    **Recommendation**: Add the "M" element back to the screen in the position specified by the design.
+
+---
+
+### Summary
+
+- **Total differences found**: 6
+- **Overall "match score"**: 50/100

minitap_mcp-0.5.1/minitap/mcp/core/agents/compare_screenshots/prompt.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 implemented (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-0.5.1/minitap/mcp/core/utils/figma.py

@@ -0,0 +1,69 @@
+"""Agent to extract Figma asset URLs from design context code using regex."""
+
+import re
+
+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 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 with imports instead of const declarations"
+    )
+
+
+def extract_figma_assets(design_context_code: str) -> ExtractedAssets:
+    """Extract asset URLs from Figma design context code using regex.
+
+    Args:
+        design_context_code: The React/TypeScript code from get_design_context
+
+    Returns:
+        ExtractedAssets with list of assets and transformed code
+    """
+    # Regex captures: (1) variable name, (2) full URL, (4) extension
+    # Supports http/https, any domain, query strings, optional semicolon
+    pattern = r'const\s+(\w+)\s*=\s*["\']((https?://[^"\']+?)\.(\w+)(?:\?[^"\']*)?)["\'];?'
+    matches = re.finditer(pattern, design_context_code)
+
+    assets = []
+    asset_lines = []
+
+    for match in matches:
+        var_name = match.group(1)
+        url = match.group(2)
+        extension = match.group(4)
+
+        assets.append(FigmaAsset(variable_name=var_name, url=url, extension=extension))
+        asset_lines.append(match.group(0))
+
+    import_statements = []
+    for asset in assets:
+        import_statements.append(
+            f"import {asset.variable_name} from './{asset.variable_name}.{asset.extension}';"
+        )
+
+    transformed_code = design_context_code
+    for line in asset_lines:
+        transformed_code = transformed_code.replace(line, "")
+
+    lines = transformed_code.split("\n")
+    while lines and not lines[0].strip():
+        lines.pop(0)
+
+    final_code = "\n".join(import_statements) + "\n\n" + "\n".join(lines)
+
+    return ExtractedAssets(assets=assets, code_implementation=final_code)

{minitap_mcp-0.4.3 → minitap_mcp-0.5.1}/minitap/mcp/tools/analyze_screen.py

@@ -1,15 +1,15 @@
 from pathlib import Path
-from jinja2 import Template
-from langchain_core.messages import BaseMessage, HumanMessage, SystemMessage
 from uuid import uuid4
 
+from jinja2 import Template
+from langchain_core.messages import BaseMessage, HumanMessage, SystemMessage
 from pydantic import Field
 
 from minitap.mcp.core.config import settings
 from minitap.mcp.core.decorators import handle_tool_errors
 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 compress_base64_jpeg, get_screenshot_message_for_llm
+from minitap.mcp.core.utils.images import compress_base64_jpeg, get_screenshot_message_for_llm
 from minitap.mcp.main import mcp
 
 

{minitap_mcp-0.4.3 → minitap_mcp-0.5.1}/minitap/mcp/tools/compare_screenshot_with_figma.py

@@ -11,7 +11,7 @@ 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.agents.compare_screenshots.agent 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

{minitap_mcp-0.4.3 → minitap_mcp-0.5.1}/minitap/mcp/tools/execute_mobile_command.py

@@ -34,10 +34,6 @@ def _serialize_result(result: Any) -> Any:
     - "Open the settings app and tell me the battery level"
     - "Find the first 3 unread emails in Gmail"
     - "Take a screenshot and save it"
-    
-    The tool uses the Minitap platform with API key authentication.
-    Set MINITAP_API_KEY and MINITAP_API_BASE_URL environment variables.
-    Visit https://platform.minitap.ai to get your API key.
     """,
 )
 @handle_tool_errors
@@ -53,11 +49,21 @@ async def execute_mobile_command(
         default="default",
         description="Name of the profile to use for this task. Defaults to 'default'.",
     ),
+    locked_app_package: str | None = Field(
+        default=None,
+        description="Optional package name of the app to lock the device to. "
+        "Will launch the app if not already running, and keep it in foreground "
+        "until the task is completed.",
+    ),
 ) -> str | dict[str, Any]:
     """Run a manual task on a mobile device via the Minitap platform."""
     try:
         request = PlatformTaskRequest(
-            task=ManualTaskConfig(goal=goal, output_description=output_description),
+            task=ManualTaskConfig(
+                goal=goal,
+                output_description=output_description,
+                locked_app_package=locked_app_package,
+            ),
         )
         agent = get_mobile_use_agent()
         result = await agent.run_task(request=request)

{minitap_mcp-0.4.3 → minitap_mcp-0.5.1}/minitap/mcp/tools/save_figma_assets.py

@@ -11,11 +11,6 @@ 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.logging_config import get_logger
@@ -25,6 +20,7 @@ from minitap.mcp.core.models import (
     DownloadStatus,
     FigmaDesignContextOutput,
 )
+from minitap.mcp.core.utils.figma import ExtractedAssets, FigmaAsset, extract_figma_assets
 from minitap.mcp.main import mcp
 from minitap.mcp.tools.compare_screenshot_with_figma import (
     compress_image_base64,
@@ -41,9 +37,9 @@ logger = get_logger(__name__)
     
     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
+    2. Extracts asset URLs and transforms const declarations to import statements
     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
+    4. Saves the transformed code to .mobile-use/figma_assets/<node-id>/code_implementation.ts
     5. Returns a list of downloaded files
     """,
 )
@@ -75,10 +71,8 @@ async def save_figma_assets(
     # 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
-    )
+    # Step 2: Extract asset URLs and transform code
+    extracted_context: ExtractedAssets = extract_figma_assets(design_context.code_implementation)
     if not extracted_context.assets:
         raise ToolError("No assets found in the Figma design context.")
 

{minitap_mcp-0.4.3 → minitap_mcp-0.5.1}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "minitap-mcp"
-version = "0.4.3"
+version = "0.5.1"
 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>=2.8.2",
+    "minitap-mobile-use>=2.9.1",
     "jinja2>=3.1.6",
     "langchain-core>=0.3.75",
     "pillow>=11.1.0",

minitap_mcp-0.4.3/minitap/mcp/core/agents/extract_figma_assets.md

@@ -1,64 +0,0 @@
-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-0.4.3/minitap/mcp/core/agents/extract_figma_assets.py

@@ -1,96 +0,0 @@
-"""Agent to extract Figma asset URLs from design context code."""
-
-import re
-import uuid
-from pathlib import Path
-
-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"
-        )
-    )
-
-
-def sanitize_unicode_for_llm(text: str) -> str:
-    """Remove or replace problematic Unicode characters that increase token consumption.
-
-    Characters outside the Basic Multilingual Plane (BMP) like emoji and special symbols
-    get escaped as \\U sequences when sent to LLMs, dramatically increasing token count
-    and processing time.
-
-    Args:
-        text: The text to sanitize
-
-    Returns:
-        Text with problematic Unicode characters replaced with placeholders
-    """
-
-    # Replace characters outside BMP (U+10000 and above) with a placeholder
-    # These are typically emoji, special symbols, or rare characters
-    def replace_high_unicode(match):
-        char = match.group(0)
-        codepoint = ord(char)
-        # Return a descriptive placeholder
-        return f"[U+{codepoint:X}]"
-
-    # Pattern matches characters with codepoints >= U+10000
-    pattern = re.compile(r"[\U00010000-\U0010FFFF]")
-    sanitized = pattern.sub(replace_high_unicode, text)
-
-    return sanitized
-
-
-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()
-
-    sanitized_code = sanitize_unicode_for_llm(design_context_code)
-
-    messages: list[BaseMessage] = [
-        SystemMessage(content=system_message),
-        HumanMessage(
-            content=f"Here is the code to analyze:\n\n```typescript\n{sanitized_code}\n```"
-        ),
-    ]
-
-    llm = get_minitap_llm(
-        model="openai/gpt-5",
-        temperature=0,
-        trace_id=str(uuid.uuid4()),
-        remote_tracing=True,
-    ).with_structured_output(ExtractedAssets)
-    result: ExtractedAssets = await llm.ainvoke(messages)  # type: ignore
-
-    return result