minitap-mcp 0.1.1__tar.gz → 0.4.0__tar.gz

minitap_mcp-0.4.0/PKG-INFO

@@ -0,0 +1,203 @@
+Metadata-Version: 2.3
+Name: minitap-mcp
+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.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'
+Requires-Python: >=3.12
+Project-URL: Homepage, https://minitap.ai/
+Project-URL: Source, https://github.com/minitap-ai/mobile-use
+Provides-Extra: dev
+Description-Content-Type: text/markdown
+
+# Minitap MCP Server
+
+A Model Context Protocol (MCP) server that enables AI assistants to control and interact with real mobile devices (Android & iOS) through natural language commands.
+
+## Quick Start
+
+### Installation
+
+```bash
+pip install minitap-mcp
+```
+
+### Prerequisites
+
+Before running the MCP server, ensure you have the required mobile automation tools installed:
+
+- **For Android devices:**
+  - [ADB (Android Debug Bridge)](https://developer.android.com/tools/adb) - For device communication
+  - [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
+
+For detailed setup instructions, see the [mobile-use repository](https://github.com/minitap-ai/mobile-use).
+
+### Running the Server
+
+The simplest way to start:
+
+```bash
+minitap-mcp --server --api-key your_minitap_api_key
+```
+
+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).
+
+**Available CLI options:**
+
+```bash
+minitap-mcp --server --api-key YOUR_KEY --llm-profile PROFILE_NAME
+```
+
+- `--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
+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"
+```
+
+You can set these in your `.bashrc` or equivalent, then simply run:
+
+```bash
+minitap-mcp --server
+```
+
+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:
+
+```bash
+export MCP_SERVER_HOST="0.0.0.0"
+export MCP_SERVER_PORT="8000"
+```
+
+## IDE Integration
+
+1. Start the server: `minitap-mcp --server --api-key your_minitap_api_key`
+2. Add to your IDE MCP settings file:
+
+```jsonc
+# For Windsurf
+{
+  "mcpServers": {
+    "minitap-mcp": {
+      "serverUrl": "http://localhost:8000/mcp"
+    }
+  }
+}
+```
+
+```jsonc
+# For Cursor
+{
+  "mcpServers": {
+    "minitap-mcp": {
+      "transport": "http",
+      "url": "http://localhost:8000/mcp"
+    }
+  }
+}
+```
+
+
+## Available Tools
+
+Once connected, your AI assistant can use these tools:
+
+### `execute_mobile_command`
+Execute natural language commands on your mobile device using the Minitap SDK. This tool allows you to control your Android or iOS device using natural language.
+
+**Parameters:**
+- `goal` (required): High-level goal describing the action to perform
+- `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:**
+```
+"Open the settings app and tell me the battery level"
+"Find the first 3 unread emails in Gmail"
+"Open Google Maps and search for the nearest coffee shop"
+"Take a screenshot and save it"
+```
+
+### `analyze_screen`
+Capture and analyze what's currently shown on the mobile device screen using a vision-capable LLM. Useful for understanding UI elements, extracting text, or identifying specific features.
+
+**Parameters:**
+- `prompt` (required): Analysis prompt describing what information to extract
+- `device_id` (optional): Specific device ID to target
+
+**Examples:**
+```js
+"What app is currently open?"
+"Read the text messages visible on screen"
+"List all buttons and their labels on the current screen"
+"Extract the phone number displayed"
+```
+
+## Advanced Configuration
+
+### Custom ADB Server
+
+If using a remote or custom ADB server (like on WSL):
+
+```bash
+export ADB_SERVER_SOCKET="tcp:192.168.1.100:5037"
+```
+
+### Vision Model
+
+Customize the vision model used for screen analysis:
+
+```bash
+export VISION_MODEL="qwen/qwen-2.5-vl-7b-instruct"
+```
+
+## Device Setup
+
+### Android
+1. Enable USB debugging on your device
+2. Connect via USB or network ADB
+3. Verify connection: `adb devices`
+
+### iOS (macOS only)
+1. Install Xcode Command Line Tools
+2. Start a simulator or connect a physical device
+3. Verify: `xcrun simctl list devices booted`
+
+## Troubleshooting
+
+**No devices found:**
+- Verify ADB/xcrun connection
+- Check USB debugging is enabled (Android)
+- Ensure device is unlocked
+
+**Connection refused errors:**
+- Check ADB/xcrun connection
+
+**API authentication errors:**
+- Verify `MINITAP_API_KEY` is set correctly
+
+## Links
+
+- **Mobile-Use SDK:** [github.com/minitap-ai/mobile-use](https://github.com/minitap-ai/mobile-use)
+- **Mobile-Use Documentation:** [docs.minitap.ai](https://docs.minitap.ai)

minitap_mcp-0.4.0/PYPI_README.md

@@ -0,0 +1,181 @@
+# Minitap MCP Server
+
+A Model Context Protocol (MCP) server that enables AI assistants to control and interact with real mobile devices (Android & iOS) through natural language commands.
+
+## Quick Start
+
+### Installation
+
+```bash
+pip install minitap-mcp
+```
+
+### Prerequisites
+
+Before running the MCP server, ensure you have the required mobile automation tools installed:
+
+- **For Android devices:**
+  - [ADB (Android Debug Bridge)](https://developer.android.com/tools/adb) - For device communication
+  - [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
+
+For detailed setup instructions, see the [mobile-use repository](https://github.com/minitap-ai/mobile-use).
+
+### Running the Server
+
+The simplest way to start:
+
+```bash
+minitap-mcp --server --api-key your_minitap_api_key
+```
+
+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).
+
+**Available CLI options:**
+
+```bash
+minitap-mcp --server --api-key YOUR_KEY --llm-profile PROFILE_NAME
+```
+
+- `--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
+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"
+```
+
+You can set these in your `.bashrc` or equivalent, then simply run:
+
+```bash
+minitap-mcp --server
+```
+
+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:
+
+```bash
+export MCP_SERVER_HOST="0.0.0.0"
+export MCP_SERVER_PORT="8000"
+```
+
+## IDE Integration
+
+1. Start the server: `minitap-mcp --server --api-key your_minitap_api_key`
+2. Add to your IDE MCP settings file:
+
+```jsonc
+# For Windsurf
+{
+  "mcpServers": {
+    "minitap-mcp": {
+      "serverUrl": "http://localhost:8000/mcp"
+    }
+  }
+}
+```
+
+```jsonc
+# For Cursor
+{
+  "mcpServers": {
+    "minitap-mcp": {
+      "transport": "http",
+      "url": "http://localhost:8000/mcp"
+    }
+  }
+}
+```
+
+
+## Available Tools
+
+Once connected, your AI assistant can use these tools:
+
+### `execute_mobile_command`
+Execute natural language commands on your mobile device using the Minitap SDK. This tool allows you to control your Android or iOS device using natural language.
+
+**Parameters:**
+- `goal` (required): High-level goal describing the action to perform
+- `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:**
+```
+"Open the settings app and tell me the battery level"
+"Find the first 3 unread emails in Gmail"
+"Open Google Maps and search for the nearest coffee shop"
+"Take a screenshot and save it"
+```
+
+### `analyze_screen`
+Capture and analyze what's currently shown on the mobile device screen using a vision-capable LLM. Useful for understanding UI elements, extracting text, or identifying specific features.
+
+**Parameters:**
+- `prompt` (required): Analysis prompt describing what information to extract
+- `device_id` (optional): Specific device ID to target
+
+**Examples:**
+```js
+"What app is currently open?"
+"Read the text messages visible on screen"
+"List all buttons and their labels on the current screen"
+"Extract the phone number displayed"
+```
+
+## Advanced Configuration
+
+### Custom ADB Server
+
+If using a remote or custom ADB server (like on WSL):
+
+```bash
+export ADB_SERVER_SOCKET="tcp:192.168.1.100:5037"
+```
+
+### Vision Model
+
+Customize the vision model used for screen analysis:
+
+```bash
+export VISION_MODEL="qwen/qwen-2.5-vl-7b-instruct"
+```
+
+## Device Setup
+
+### Android
+1. Enable USB debugging on your device
+2. Connect via USB or network ADB
+3. Verify connection: `adb devices`
+
+### iOS (macOS only)
+1. Install Xcode Command Line Tools
+2. Start a simulator or connect a physical device
+3. Verify: `xcrun simctl list devices booted`
+
+## Troubleshooting
+
+**No devices found:**
+- Verify ADB/xcrun connection
+- Check USB debugging is enabled (Android)
+- Ensure device is unlocked
+
+**Connection refused errors:**
+- Check ADB/xcrun connection
+
+**API authentication errors:**
+- Verify `MINITAP_API_KEY` is set correctly
+
+## Links
+
+- **Mobile-Use SDK:** [github.com/minitap-ai/mobile-use](https://github.com/minitap-ai/mobile-use)
+- **Mobile-Use Documentation:** [docs.minitap.ai](https://docs.minitap.ai)

minitap_mcp-0.4.0/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-0.4.0/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-0.4.0/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-0.4.0/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-0.1.1 → minitap_mcp-0.4.0}/minitap/mcp/core/config.py

@@ -14,11 +14,14 @@ class MCPSettings(BaseSettings):
     model_config = SettingsConfigDict(env_file=".env", extra="ignore")
 
     # Minitap API configuration
-    MINITAP_API_KEY: SecretStr
+    MINITAP_API_KEY: SecretStr | None = Field(default=None)
     MINITAP_API_BASE_URL: str = Field(default="https://platform.minitap.ai/api/v1")
 
     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)