minitap-mcp 0.9.0__py3-none-any.whl

minitap_mcp-0.9.0.dist-info/METADATA

@@ -0,0 +1,352 @@
+Metadata-Version: 2.3
+Name: minitap-mcp
+Version: 0.9.0
+Summary: Model Context Protocol server for controlling Android & iOS devices with natural language
+Author: Pierre-Louis Favreau, Jean-Pierre Lo, Clément Guiguet
+Requires-Dist: fastmcp>=2.12.4
+Requires-Dist: python-dotenv>=1.1.1
+Requires-Dist: pydantic>=2.12.0
+Requires-Dist: pydantic-settings>=2.10.1
+Requires-Dist: minitap-mobile-use>=3.4.0
+Requires-Dist: jinja2>=3.1.6
+Requires-Dist: langchain-core>=0.3.75
+Requires-Dist: pillow>=11.1.0
+Requires-Dist: structlog>=24.4.0
+Requires-Dist: aiohttp>=3.9.0
+Requires-Dist: httpx>=0.28.1
+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
+
+- **For iOS devices (macOS only):**
+  - Xcode Command Line Tools with `xcrun`
+  - **[fb-idb](https://fbidb.io/docs/installation/)**: Facebook's iOS Development Bridge for device automation.
+
+```bash
+# Install via Homebrew (macOS)
+brew tap facebook/fb
+brew install idb-companion
+```
+
+> [!NOTE]
+> `idb_companion` is required to communicate with iOS simulators. Make sure it's in your PATH after installation.
+
+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`. You can customize the port:
+
+```bash
+# Using CLI argument
+minitap-mcp --server --port 9000
+
+# Or using environment variable
+export MCP_SERVER_PORT="9000"
+minitap-mcp --server
+
+# You can also customize the host
+export MCP_SERVER_HOST="0.0.0.0"
+```
+
+## 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 Resources & Tools
+
+Once connected, your AI assistant can use these resources and tools:
+
+### Resource: `data://devices`
+
+Lists all connected mobile devices (Android and iOS).
+
+**Returns:** Array of device information objects with:
+
+- `device_id`: Device serial (Android) or UDID (iOS)
+- `platform`: `"android"` or `"ios"`
+- `name`: Device name
+- `state`: Device state (`"connected"` or `"Booted"`)
+
+### Tool: `analyze_screen`
+
+Captures a screenshot from a mobile device and analyzes it using a vision language model.
+
+**Parameters:**
+
+- `prompt` (required): Analysis prompt describing what information to extract
+- `device_id` (optional): Specific device ID to target. If not provided, uses the first available device.
+
+**Returns:** AI-generated analysis of the screenshot based on the prompt.
+
+**Example:**
+
+```
+Prompt: "What app is currently open? List all visible UI elements."
+```
+
+The tool will:
+
+1. Find the specified device (or first available)
+2. Capture a screenshot
+3. Analyze it with the vision model
+4. Return the analysis
+
+### Tool: `execute_mobile_command`
+
+Execute natural language commands on your mobile device using the mobile-use SDK. This tool allows you to control your Android or iOS device with simple instructions.
+
+**Parameters:**
+
+- `goal` (required): Natural language command to execute on the device
+- `output_description` (optional): Description of the expected output format (e.g., "A JSON list of objects with sender and subject keys")
+- `profile` (optional): Name of the profile to use for this task. Defaults to 'default'
+- `locked_app_package` (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.
+
+**Returns:** Execution result with status, output, and any extracted data.
+
+**Examples:**
+
+```python
+# Simple command
+goal: "Go to settings and tell me my current battery level"
+
+# Data extraction with structured output
+goal: "Open Gmail, find first 3 unread emails, and list their sender and subject line"
+output_description: "A JSON list of objects, each with 'sender' and 'subject' keys"
+
+# App navigation
+goal: "Open Twitter and scroll to the latest tweet"
+```
+
+The tool will:
+
+1. Find the specified device (or first available)
+2. Execute the command using the mobile-use AI agent
+3. Return the result or extracted data
+
+### Tool: `save_figma_assets`
+
+Fetch Figma design assets and React implementation code, then save them locally in the workspace.
+
+**Parameters:**
+
+- `node_id` (required): The node ID of the Figma design in format "1:2" (colon-separated). Extract from URLs like `https://figma.com/design/:fileKey/:fileName?node-id=1-2`
+- `file_key` (required): The file key from the Figma URL (e.g., "abc123" from `https://figma.com/design/abc123/MyFile`)
+- `workspace_path` (optional): The workspace path where assets should be saved. Defaults to current directory.
+
+**Returns:** Download summary with list of successfully downloaded assets and any failures.
+
+**Example:**
+
+```python
+node_id: "1:2"
+file_key: "abc123xyz"
+workspace_path: "."
+```
+
+The tool will:
+
+1. Call `get_design_context` from Figma MCP to get React/TypeScript code
+2. Extract all asset URLs from the code implementation
+3. Download each asset to `.mobile-use/figma_assets/<node-id>/` folder
+4. Save the code implementation to `.mobile-use/figma_assets/<node-id>/code_implementation.ts`
+5. Return a list of downloaded files with success/failure status
+
+### Tool: `compare_screenshot_with_figma`
+
+Compare a screenshot of the current mobile device state with a Figma design to identify visual differences.
+
+**Parameters:**
+
+- `node_id` (required): The node ID of the Figma design in format "1:2" (colon-separated). Extract from URLs like `https://figma.com/design/:fileKey/:fileName?node-id=1-2`
+
+**Returns:** Detailed comparison report with both the Figma design and current device screenshots for visual context.
+
+The tool will:
+
+1. Capture a screenshot of the current device state
+2. Fetch the Figma design screenshot
+3. Compare both screenshots using vision AI
+4. Return a detailed analysis highlighting differences
+
+## Cloud Mobile Mode
+
+Run the MCP server with cloud-hosted mobile devices instead of requiring a local device. This enables:
+
+- **Zero local setup**: No ADB or physical device required
+- **Remote development**: Control cloud mobiles from anywhere
+- **Scalable automation**: Access multiple cloud devices
+
+### Setting Up Cloud Mobile Mode
+
+1. **Create a Cloud Mobile** on [Minitap Platform](https://platform.minitap.ai/cloud-mobiles):
+   - Click **Create New Device**
+   - Choose platform (currently Android v11 / API level 30)
+   - Set a **Reference Name** (e.g., `my-dev-device`)
+
+2. **Configure the environment variable**:
+
+```bash
+# Using reference name (recommended)
+export CLOUD_MOBILE_NAME="my-dev-device"
+```
+
+3. **Start the server** (no local device needed):
+
+```bash
+minitap-mcp --server --api-key your_minitap_api_key
+```
+
+The server will:
+- Connect to your cloud mobile on startup
+- Maintain a keep-alive connection while running
+- Automatically disconnect when the server stops
+
+> ⚠️ **Important**: Cloud mobiles are billed while connected. The MCP server automatically stops the connection when you close your IDE or stop the server. Make sure to properly shut down the server to avoid unexpected charges.
+
+### Cloud vs Local Mode
+
+| Feature | Local Mode | Cloud Mode |
+|---------|------------|------------|
+| Device requirement | Physical/emulator | None |
+| Setup complexity | ADB setup required | Low (env var only) |
+| `CLOUD_MOBILE_NAME` | Not set | Set to device name/UUID |
+| Billing | None | Per-minute usage |
+
+## 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="google/gemini-3-flash-preview"
+```
+
+## 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.9.0.dist-info/RECORD

@@ -0,0 +1,35 @@
+minitap/mcp/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+minitap/mcp/core/agents/compare_screenshots/agent.py,sha256=XRYyrv9QA4eb1b44hPjAqz6MKYM6y3THosxP21xzBY4,2458
+minitap/mcp/core/agents/compare_screenshots/eval/prompts/prompt_1.md,sha256=qAyqOroSJROgrvlbsLCtiwFyBKuIMCQ-720A5cwgwPY,3563
+minitap/mcp/core/agents/compare_screenshots/eval/scenario_1_add_cartoon_img_and_move_button/actual.png,sha256=woKE-aTTdb-9ArqfnV-xKKyit1Fu_hklavVwAaMQ14E,99455
+minitap/mcp/core/agents/compare_screenshots/eval/scenario_1_add_cartoon_img_and_move_button/figma.png,sha256=ghxi1P-ofnmMv5_ASm0Rzo5ll_C8-E6ojQUCHRR33TA,102098
+minitap/mcp/core/agents/compare_screenshots/eval/scenario_1_add_cartoon_img_and_move_button/human_feedback.txt,sha256=0gVEqIFpmCX1cx1tlGBdfqDGbTeedyVfwTJZqePURkA,700
+minitap/mcp/core/agents/compare_screenshots/eval/scenario_1_add_cartoon_img_and_move_button/prompt_1/model_params.json,sha256=p93kbUGxLYwc4NAEzPTBDA2XZ1ucsa7yevXZRe6V4Mc,37
+minitap/mcp/core/agents/compare_screenshots/eval/scenario_1_add_cartoon_img_and_move_button/prompt_1/output.md,sha256=Q0_5w9x5WAMqx6-I7KgjlS-tt7HnWKIunP43J7F0W_o,3703
+minitap/mcp/core/agents/compare_screenshots/prompt.md,sha256=qAyqOroSJROgrvlbsLCtiwFyBKuIMCQ-720A5cwgwPY,3563
+minitap/mcp/core/cloud_apk.py,sha256=K0PmmkvkCzYo-eRfwGmfPcBbMy8KD32pHvrehm_L_YM,4308
+minitap/mcp/core/config.py,sha256=dCQMuT-jvGHBxIsvTQoUDOvZ98MTO5iwgCc3_bngX5M,4407
+minitap/mcp/core/decorators.py,sha256=ipzR7kbMXacG91f6CliN-nl9unRTtjmANrfueaOXJ2s,3591
+minitap/mcp/core/device.py,sha256=0AU8qGi26axC6toqHrPIzNeDbNDtll0YRwkspHouPmM,8198
+minitap/mcp/core/llm.py,sha256=tI5m5rFDLeMkXE5WExnzYSzHU3nTIEiSC9nAsPzVMaU,1144
+minitap/mcp/core/logging_config.py,sha256=OJlArPJxflbhckerFsRHVTzy3jwsLsNSPN0LVpkmpNM,1861
+minitap/mcp/core/models.py,sha256=egLScxPAMo4u5cqY33UKba7z7DsdgqfPW409UAqW1Jg,1942
+minitap/mcp/core/sdk_agent.py,sha256=5YEr7aDjoiwbRQkZBK3jDa08c5QhPwLxahzlYrEB_KE,1132
+minitap/mcp/core/storage.py,sha256=t9BAEqXH7Nu8p8hgGIk3mO6rxLwviBP0FqvQD4Lz8CQ,13184
+minitap/mcp/core/task_runs.py,sha256=vGv8G-oZcfe_lpMOGiM649u10WNzoU3uWDgYWm1owdQ,3115
+minitap/mcp/core/utils/figma.py,sha256=L5aAHm59mrRYaqrwMJSM24SSdZPu2yVg-wsHTF3L8vk,2310
+minitap/mcp/core/utils/images.py,sha256=3uExpRoh7affIieZx3TLlZTmZCcoxWfx1YpPbwhjiJY,1791
+minitap/mcp/main.py,sha256=p5E_dBIBiS_sp_v9u8gNxjRGwl25T4De-ivZQbSqJa8,11269
+minitap/mcp/server/cloud_mobile.py,sha256=4cKnUzOJE5tBzgXgJXmyH0ESf6OyCTlNllputEQwFvE,18261
+minitap/mcp/server/middleware.py,sha256=SjPc4pcfPuG0TnaDH7a19DS_HRFPl3bkbovdOLzy_IU,768
+minitap/mcp/server/poller.py,sha256=JsdW6nvj4r3tsn8AaTwXD4H9dVAAau4BhJXHXHit9nA,2528
+minitap/mcp/server/remote_proxy.py,sha256=IM7UfjbJlQRpFD_tdpdck1mFT1QOnlxj5OA1nS4tRhQ,3073
+minitap/mcp/tools/execute_mobile_command.py,sha256=K5KhSAqLdcmc6WH_u2TKAybECPw53TuSLEoSVrGCPOE,6776
+minitap/mcp/tools/read_swift_logs.py,sha256=Wc1XqQWWuNuPEIBioYD2geVd1p9Yq2USik6SX47Fq9A,9285
+minitap/mcp/tools/screen_analyzer.md,sha256=TTO80JQWusbA9cKAZn-9cqhgVHm6F_qJh5w152hG3YM,734
+minitap/mcp/tools/take_screenshot.py,sha256=gGySPSeVnx8lHiseGF_Wat82JLF-D8GuQIJ_hCaLZlQ,1730
+minitap/mcp/tools/upload_screenshot.py,sha256=kwh8Q46LWF3nyKbKlvnlf-CtGrPkctXSnLyeebQGNFI,2959
+minitap_mcp-0.9.0.dist-info/WHEEL,sha256=fAguSjoiATBe7TNBkJwOjyL1Tt4wwiaQGtNtjRPNMQA,80
+minitap_mcp-0.9.0.dist-info/entry_points.txt,sha256=rYVoXm7tSQCqQTtHx4Lovgn1YsjwtEEHfddKrfEVHuY,55
+minitap_mcp-0.9.0.dist-info/METADATA,sha256=-b-kTZM_KwIY3478ZBqCebSM2UbffTA0Kkfro-svxic,10619
+minitap_mcp-0.9.0.dist-info/RECORD,,

minitap_mcp-0.9.0.dist-info/WHEEL

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

minitap_mcp-0.9.0.dist-info/entry_points.txt

@@ -0,0 +1,3 @@
+[console_scripts]
+minitap-mcp = minitap.mcp.main:main
+