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

minitap_mcp-0.2.0/PKG-INFO

@@ -0,0 +1,193 @@
+Metadata-Version: 2.3
+Name: minitap-mcp
+Version: 0.2.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.5.3
+Requires-Dist: jinja2>=3.1.6
+Requires-Dist: langchain-core>=0.3.75
+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 (optional but recommended)
+
+- **For iOS devices (macOS only):**
+  - Xcode Command Line Tools with `xcrun`
+  - [Maestro](https://maestro.mobile.dev/) - For mobile automation (optional but recommended)
+
+For detailed setup instructions, see the [mobile-use repository](https://github.com/minitap-ai/mobile-use).
+
+### Configuration
+
+Set your Minitap API credentials as environment variables:
+
+```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"
+```
+
+You can set these variables in your `.bashrc` or equivalent.
+
+### Running the Server
+
+**With environment variables:**
+
+```bash
+minitap-mcp --server
+```
+
+**With API key as argument:**
+
+```bash
+minitap-mcp --server --api-key your_api_key_here
+```
+
+Using `--api-key` overrides the `MINITAP_API_KEY` environment variable, useful for quick testing.
+
+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`
+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): Description of expected output format
+- `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.2.0/PYPI_README.md

@@ -0,0 +1,172 @@
+# 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 (optional but recommended)
+
+- **For iOS devices (macOS only):**
+  - Xcode Command Line Tools with `xcrun`
+  - [Maestro](https://maestro.mobile.dev/) - For mobile automation (optional but recommended)
+
+For detailed setup instructions, see the [mobile-use repository](https://github.com/minitap-ai/mobile-use).
+
+### Configuration
+
+Set your Minitap API credentials as environment variables:
+
+```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"
+```
+
+You can set these variables in your `.bashrc` or equivalent.
+
+### Running the Server
+
+**With environment variables:**
+
+```bash
+minitap-mcp --server
+```
+
+**With API key as argument:**
+
+```bash
+minitap-mcp --server --api-key your_api_key_here
+```
+
+Using `--api-key` overrides the `MINITAP_API_KEY` environment variable, useful for quick testing.
+
+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`
+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): Description of expected output format
+- `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.2.0/minitap/mcp/core/agents.py

@@ -0,0 +1,27 @@
+import os
+
+from minitap.mobile_use.sdk import Agent
+from minitap.mobile_use.sdk.builders import Builders
+
+# Lazy-initialized singleton agent
+_agent: Agent | None = None
+
+
+def get_mobile_use_agent() -> Agent:
+    """Get or create the mobile-use agent singleton.
+
+    This function lazily initializes the agent on first call, ensuring
+    that CLI arguments are parsed before agent creation.
+    """
+    global _agent
+    if _agent is None:
+        config = Builders.AgentConfig
+        custom_adb_socket = os.getenv("ADB_SERVER_SOCKET")
+        if custom_adb_socket:
+            parts = custom_adb_socket.split(":")
+            if len(parts) != 3:
+                raise ValueError(f"Invalid ADB server socket: {custom_adb_socket}")
+            _, host, port = parts
+            config = config.with_adb_server(host=host, port=int(port))
+        _agent = Agent(config=config.build())
+    return _agent

{minitap_mcp-0.1.1 → minitap_mcp-0.2.0}/minitap/mcp/core/config.py

@@ -14,7 +14,7 @@ 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")

{minitap_mcp-0.1.1 → minitap_mcp-0.2.0}/minitap/mcp/main.py

@@ -24,18 +24,54 @@ if sys.platform == "win32":
 
 from fastmcp import FastMCP  # noqa: E402
 
-from minitap.mcp.core.agents import agent
 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,  # noqa: E402; noqa: E402
+    list_available_devices,
 )
 from minitap.mcp.server.middleware import MaestroCheckerMiddleware
 from minitap.mcp.server.poller import device_health_poller
 
-logger = logging.getLogger(__name__)
+
+def main() -> None:
+    """Main entry point for the MCP server."""
+
+    parser = argparse.ArgumentParser(description="Mobile Use MCP Server")
+    parser.add_argument("--api-key", type=str, required=False, default=None)
+    parser.add_argument(
+        "--server",
+        action="store_true",
+        help="Run as network server (uses MCP_SERVER_HOST and MCP_SERVER_PORT from env)",
+    )
+
+    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 not settings.MINITAP_API_KEY:
+        raise ValueError("Minitap API key is required to run the MCP")
+
+    # Run MCP server with optional host/port for remote access
+    if args.server:
+        logger.info(f"Starting MCP server on {settings.MCP_SERVER_HOST}:{settings.MCP_SERVER_PORT}")
+        mcp_lifespan(
+            transport="http",
+            host=settings.MCP_SERVER_HOST,
+            port=settings.MCP_SERVER_PORT,
+        )
+    else:
+        logger.info("Starting MCP server in local mode")
+        mcp_lifespan()
 
 
+logger = logging.getLogger(__name__)
+
 mcp = FastMCP(
     name="mobile-use-mcp",
     instructions="""
@@ -46,9 +82,8 @@ mcp = FastMCP(
 )
 
 from minitap.mcp.tools import (  # noqa: E402, F401
-    analyze_screen,
-    execute_mobile_command,
-    go_back,
+    analyze_screen,  # noqa: E402, F401
+    execute_mobile_command,  # noqa: E402, F401
 )
 
 
@@ -59,6 +94,9 @@ def get_available_devices() -> list[DeviceInfo]:
 
 
 def mcp_lifespan(**mcp_run_kwargs):
+    from minitap.mcp.core.agents import get_mobile_use_agent  # noqa: E402
+
+    agent = get_mobile_use_agent()
     mcp.add_middleware(MaestroCheckerMiddleware(agent))
 
     # Start device health poller in background
@@ -83,27 +121,3 @@ def mcp_lifespan(**mcp_run_kwargs):
     logger.info("Device health poller stopping...")
     poller_thread.join()
     logger.info("Device health poller stopped")
-
-
-def main() -> None:
-    """Main entry point for the MCP server."""
-    parser = argparse.ArgumentParser(description="Mobile Use MCP Server")
-    parser.add_argument(
-        "--server",
-        action="store_true",
-        help="Run as network server (uses MCP_SERVER_HOST and MCP_SERVER_PORT from env)",
-    )
-
-    args = parser.parse_args()
-
-    # Run MCP server with optional host/port for remote access
-    if args.server:
-        logger.info(f"Starting MCP server on {settings.MCP_SERVER_HOST}:{settings.MCP_SERVER_PORT}")
-        mcp_lifespan(
-            transport="http",
-            host=settings.MCP_SERVER_HOST,
-            port=settings.MCP_SERVER_PORT,
-        )
-    else:
-        logger.info("Starting MCP server in local mode")
-        mcp_lifespan()

{minitap_mcp-0.1.1 → minitap_mcp-0.2.0}/minitap/mcp/tools/execute_mobile_command.py

@@ -3,11 +3,12 @@
 from collections.abc import Mapping
 from typing import Any
 
+from fastmcp.exceptions import ToolError
 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 agent
+from minitap.mcp.core.agents import get_mobile_use_agent
 from minitap.mcp.core.decorators import handle_tool_errors
 from minitap.mcp.main import mcp
 
@@ -58,7 +59,8 @@ async def execute_mobile_command(
         request = PlatformTaskRequest(
             task=ManualTaskConfig(goal=goal, output_description=output_description),
         )
+        agent = get_mobile_use_agent()
         result = await agent.run_task(request=request)
         return _serialize_result(result)
-    finally:
-        agent.clean()
+    except Exception as e:
+        raise ToolError(str(e))

{minitap_mcp-0.1.1 → minitap_mcp-0.2.0}/pyproject.toml

@@ -1,8 +1,8 @@
 [project]
 name = "minitap-mcp"
-version = "0.1.1"
-description = "MCP server for mobile-use"
-readme = "README.md"
+version = "0.2.0"
+description = "Model Context Protocol server for controlling Android & iOS devices with natural language"
+readme = "PYPI_README.md"
 
 authors = [
     { name = "Pierre-Louis Favreau" },

minitap_mcp-0.1.1/PKG-INFO

@@ -1,348 +0,0 @@
-Metadata-Version: 2.3
-Name: minitap-mcp
-Version: 0.1.1
-Summary: MCP server for mobile-use
-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.5.3
-Requires-Dist: jinja2>=3.1.6
-Requires-Dist: langchain-core>=0.3.75
-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
-
-# Mobile-Use MCP Server
-
-A Model Context Protocol (MCP) server that provides AI-powered mobile device screen analysis. Automatically detects connected Android (via ADB) and iOS devices (via xcrun), captures screenshots, and analyzes them using vision language models.
-
-## Features
-
-- **🔍 Device Discovery**: Automatically finds connected Android devices (ADB) and iOS simulators (xcrun)
-- **📱 Screen Analysis**: Capture and analyze device screenshots using vision-capable LLMs
-- **🤖 Natural Language Control**: Execute commands on your device using natural language via the mobile-use SDK
-- **🚀 Easy Integration**: Built with FastMCP for seamless MCP protocol implementation
-- **⚙️ Flexible Configuration**: Uses Minitap API with support for various vision models
-
-## Installation
-
-### Prerequisites
-
-- **Python 3.12+**
-- **uv** (recommended) or pip
-- **For Android**: ADB installed and accessible
-- **For iOS**: Xcode Command Line Tools (macOS only)
-- **Minitap API Key** - Get one at [platform.minitap.ai](https://platform.minitap.ai)
-
-### Setup
-
-1. **Clone and navigate to the project:**
-
-```bash
-cd mobile-use-mcp
-```
-
-2. **Install dependencies:**
-
-```bash
-# Create a virtual environment
-uv venv
-source .venv/bin/activate
-
-# Install dependencies
-uv sync
-```
-
-3. **Configure for MCP usage:**
-
-The MCP server is configured via environment variables passed from your MCP client (e.g., Windsurf). 
-
-Required environment variable:
-- `MINITAP_API_KEY`: Your Minitap API key
-
-Optional environment variables:
-- `MINITAP_API_BASE_URL`: API base URL (default: `https://platform.minitap.ai/api/v1`)
-- `VISION_MODEL`: Vision model to use (default: `baidu/ernie-4.5-vl-28b-a3b`)
-- `ADB_SERVER_SOCKET`: Custom ADB server socket (format: `tcp:host:port`)
-
-## Available Resources & 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'
-
-**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
-
-## Usage
-
-### Running the MCP Server
-
-#### Local Mode (Default)
-
-The MCP server is typically started by your MCP client (e.g., Windsurf). For manual testing:
-
-```bash
-minitap-mcp
-```
-
-#### Network Server Mode
-
-You can run the MCP server as a network server for remote access:
-
-```bash
-# Run as network server (uses MCP_SERVER_HOST and MCP_SERVER_PORT from env)
-minitap-mcp --server
-```
-
-The server will bind to the host and port specified in your environment variables:
-- `MCP_SERVER_HOST` (default: `0.0.0.0`)
-- `MCP_SERVER_PORT` (default: `8000`)
-
-Configure these in your `.env` file or via environment variables to customize the binding address.
-
-Inside Windsurf, you can configure the MCP server by adding the following to your `~/.codeium/windsurf/mcp_settings.json` file:
-
-```json
-{
-  "mcpServers": {
-    "minitap-mcp": {
-      "serverUrl": "http://localhost:8000/mcp"
-    }
-  }
-}
-```
-
-N.B. You may need to change the port based on what you've configured in your `.env` file.
-
-## Development
-
-### Quick Testing
-
-Test device detection and screenshot capture (no API key required):
-
-```bash
-python tests/test_devices.py
-```
-
-Test the complete MCP flow with LLM analysis (requires API key):
-
-```bash
-cp .env.example .env
-# Edit .env and add your MINITAP_API_KEY
-python tests/test_mcp.py
-```
-
-### Code Quality
-
-**Format code:**
-```bash
-ruff format .
-```
-
-**Lint:**
-```bash
-ruff check --fix
-```
-
-## Project Structure
-
-```
-minitap/mcp/
-├── __init__.py
-├── main.py                    # FastMCP server entry point
-├── core/
-│   ├── __init__.py
-│   ├── config.py              # Pydantic settings configuration
-│   ├── decorators.py          # Error handling decorators
-│   ├── device.py              # Device discovery & screenshot capture
-│   ├── llm.py                 # LLM client initialization
-│   └── utils.py               # Utility functions (image compression, etc.)
-└── tools/
-    ├── __init__.py
-    ├── analyze_screen.py      # Screen analysis tool
-    ├── execute_mobile_command.py  # Mobile-use SDK integration tool
-    └── screen_analyzer.md     # System prompt for analysis
-
-tests/
-├── test_devices.py            # Device detection tests
-└── test_mcp.py                # Full MCP integration tests
-```
-
-## Creating New Tools
-
-When adding new MCP tools, use the `@handle_tool_errors` decorator to prevent unhandled exceptions from causing infinite loops:
-
-```python
-from minitap.mcp.core.decorators import handle_tool_errors
-from minitap.mcp.main import mcp
-
-@mcp.tool(name="my_tool", description="...")
-@handle_tool_errors  # Add this decorator
-async def my_tool(param: str) -> str:
-    # Your tool logic here
-    # Any exception will be caught and returned as an error message
-    return "result"
-```
-
-The decorator automatically:
-- Catches all exceptions (including `DeviceNotFoundError`)
-- Returns user-friendly error messages
-- Prevents the MCP server from hanging or looping infinitely
-- Works with both sync and async functions
-
-## Integration with Windsurf
-
-To use this MCP server in Windsurf, add it to your MCP settings:
-
-**Location:** `~/.codeium/windsurf/mcp_settings.json`
-
-**Configuration:**
-
-```json
-{
-  "mcpServers": {
-    "minitap-mcp": {
-      "command": "uv",
-      "args": ["-c", "cd /path/to/minitap-mcp && source .venv/bin/activate && uv sync && minitap-mcp"],
-      "env": {
-        "MINITAP_API_KEY": "your_minitap_api_key_here",
-        "MINITAP_API_BASE_URL": "https://platform.minitap.ai/api/v1",
-        "VISION_MODEL": "baidu/ernie-4.5-vl-28b-a3b" // optional
-      }
-    }
-  }
-}
-```
-
-**After configuration:**
-1. Restart Windsurf
-2. The `analyze_screen` and `execute_mobile_command` tools will be available in Cascade
-3. The `data://devices` resource will list connected devices
-
-### Available Vision Models
-
-The Minitap API supports various vision models:
-- `qwen/qwen-2.5-vl-7b-instruct` (default)
-- `baidu/ernie-4.5-vl-28b-a3b`
-- `openai/gpt-4o`
-- And more - check the Minitap platform for the full list
-
-## Device Requirements
-
-### Android Devices
-
-**Requirements:**
-- ADB installed and in PATH
-- USB debugging enabled on the device
-- Device connected via USB or network ADB
-
-**Verify connection:**
-```bash
-adb devices
-```
-
-**Custom ADB Server:**
-If using a custom ADB server (e.g., Docker, WSL), set the socket:
-```bash
-export ADB_SERVER_SOCKET="tcp:localhost:5037"
-```
-
-N.B. You may need to reboot your IDE
-
-### iOS Devices
-
-**Requirements:**
-- macOS with Xcode Command Line Tools
-- iOS Simulator running
-
-**Verify simulators:**
-```bash
-xcrun simctl list devices booted
-```
-
-**Start a simulator:**
-```bash
-open -a Simulator
-```
-
-## Troubleshooting
-
-### No devices found
-
-1. **Android:** Run `adb devices` to verify device connection
-2. **iOS:** Run `xcrun simctl list devices booted` to check running simulators
-3. Ensure USB debugging is enabled (Android)
-4. Try restarting ADB: `adb kill-server && adb start-server`
-
-### Screenshot capture fails
-
-1. Ensure device screen is unlocked
-2. For Android, verify screencap permission
-3. For iOS, ensure simulator is fully booted
-
-### Tool not detected in Windsurf
-
-1. Verify the import in `main.py` includes the tools module
-2. Check that `tools/__init__.py` exists
-3. Restart Windsurf after configuration changes

minitap_mcp-0.1.1/README.md

@@ -1,327 +0,0 @@
-# Mobile-Use MCP Server
-
-A Model Context Protocol (MCP) server that provides AI-powered mobile device screen analysis. Automatically detects connected Android (via ADB) and iOS devices (via xcrun), captures screenshots, and analyzes them using vision language models.
-
-## Features
-
-- **🔍 Device Discovery**: Automatically finds connected Android devices (ADB) and iOS simulators (xcrun)
-- **📱 Screen Analysis**: Capture and analyze device screenshots using vision-capable LLMs
-- **🤖 Natural Language Control**: Execute commands on your device using natural language via the mobile-use SDK
-- **🚀 Easy Integration**: Built with FastMCP for seamless MCP protocol implementation
-- **⚙️ Flexible Configuration**: Uses Minitap API with support for various vision models
-
-## Installation
-
-### Prerequisites
-
-- **Python 3.12+**
-- **uv** (recommended) or pip
-- **For Android**: ADB installed and accessible
-- **For iOS**: Xcode Command Line Tools (macOS only)
-- **Minitap API Key** - Get one at [platform.minitap.ai](https://platform.minitap.ai)
-
-### Setup
-
-1. **Clone and navigate to the project:**
-
-```bash
-cd mobile-use-mcp
-```
-
-2. **Install dependencies:**
-
-```bash
-# Create a virtual environment
-uv venv
-source .venv/bin/activate
-
-# Install dependencies
-uv sync
-```
-
-3. **Configure for MCP usage:**
-
-The MCP server is configured via environment variables passed from your MCP client (e.g., Windsurf). 
-
-Required environment variable:
-- `MINITAP_API_KEY`: Your Minitap API key
-
-Optional environment variables:
-- `MINITAP_API_BASE_URL`: API base URL (default: `https://platform.minitap.ai/api/v1`)
-- `VISION_MODEL`: Vision model to use (default: `baidu/ernie-4.5-vl-28b-a3b`)
-- `ADB_SERVER_SOCKET`: Custom ADB server socket (format: `tcp:host:port`)
-
-## Available Resources & 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'
-
-**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
-
-## Usage
-
-### Running the MCP Server
-
-#### Local Mode (Default)
-
-The MCP server is typically started by your MCP client (e.g., Windsurf). For manual testing:
-
-```bash
-minitap-mcp
-```
-
-#### Network Server Mode
-
-You can run the MCP server as a network server for remote access:
-
-```bash
-# Run as network server (uses MCP_SERVER_HOST and MCP_SERVER_PORT from env)
-minitap-mcp --server
-```
-
-The server will bind to the host and port specified in your environment variables:
-- `MCP_SERVER_HOST` (default: `0.0.0.0`)
-- `MCP_SERVER_PORT` (default: `8000`)
-
-Configure these in your `.env` file or via environment variables to customize the binding address.
-
-Inside Windsurf, you can configure the MCP server by adding the following to your `~/.codeium/windsurf/mcp_settings.json` file:
-
-```json
-{
-  "mcpServers": {
-    "minitap-mcp": {
-      "serverUrl": "http://localhost:8000/mcp"
-    }
-  }
-}
-```
-
-N.B. You may need to change the port based on what you've configured in your `.env` file.
-
-## Development
-
-### Quick Testing
-
-Test device detection and screenshot capture (no API key required):
-
-```bash
-python tests/test_devices.py
-```
-
-Test the complete MCP flow with LLM analysis (requires API key):
-
-```bash
-cp .env.example .env
-# Edit .env and add your MINITAP_API_KEY
-python tests/test_mcp.py
-```
-
-### Code Quality
-
-**Format code:**
-```bash
-ruff format .
-```
-
-**Lint:**
-```bash
-ruff check --fix
-```
-
-## Project Structure
-
-```
-minitap/mcp/
-├── __init__.py
-├── main.py                    # FastMCP server entry point
-├── core/
-│   ├── __init__.py
-│   ├── config.py              # Pydantic settings configuration
-│   ├── decorators.py          # Error handling decorators
-│   ├── device.py              # Device discovery & screenshot capture
-│   ├── llm.py                 # LLM client initialization
-│   └── utils.py               # Utility functions (image compression, etc.)
-└── tools/
-    ├── __init__.py
-    ├── analyze_screen.py      # Screen analysis tool
-    ├── execute_mobile_command.py  # Mobile-use SDK integration tool
-    └── screen_analyzer.md     # System prompt for analysis
-
-tests/
-├── test_devices.py            # Device detection tests
-└── test_mcp.py                # Full MCP integration tests
-```
-
-## Creating New Tools
-
-When adding new MCP tools, use the `@handle_tool_errors` decorator to prevent unhandled exceptions from causing infinite loops:
-
-```python
-from minitap.mcp.core.decorators import handle_tool_errors
-from minitap.mcp.main import mcp
-
-@mcp.tool(name="my_tool", description="...")
-@handle_tool_errors  # Add this decorator
-async def my_tool(param: str) -> str:
-    # Your tool logic here
-    # Any exception will be caught and returned as an error message
-    return "result"
-```
-
-The decorator automatically:
-- Catches all exceptions (including `DeviceNotFoundError`)
-- Returns user-friendly error messages
-- Prevents the MCP server from hanging or looping infinitely
-- Works with both sync and async functions
-
-## Integration with Windsurf
-
-To use this MCP server in Windsurf, add it to your MCP settings:
-
-**Location:** `~/.codeium/windsurf/mcp_settings.json`
-
-**Configuration:**
-
-```json
-{
-  "mcpServers": {
-    "minitap-mcp": {
-      "command": "uv",
-      "args": ["-c", "cd /path/to/minitap-mcp && source .venv/bin/activate && uv sync && minitap-mcp"],
-      "env": {
-        "MINITAP_API_KEY": "your_minitap_api_key_here",
-        "MINITAP_API_BASE_URL": "https://platform.minitap.ai/api/v1",
-        "VISION_MODEL": "baidu/ernie-4.5-vl-28b-a3b" // optional
-      }
-    }
-  }
-}
-```
-
-**After configuration:**
-1. Restart Windsurf
-2. The `analyze_screen` and `execute_mobile_command` tools will be available in Cascade
-3. The `data://devices` resource will list connected devices
-
-### Available Vision Models
-
-The Minitap API supports various vision models:
-- `qwen/qwen-2.5-vl-7b-instruct` (default)
-- `baidu/ernie-4.5-vl-28b-a3b`
-- `openai/gpt-4o`
-- And more - check the Minitap platform for the full list
-
-## Device Requirements
-
-### Android Devices
-
-**Requirements:**
-- ADB installed and in PATH
-- USB debugging enabled on the device
-- Device connected via USB or network ADB
-
-**Verify connection:**
-```bash
-adb devices
-```
-
-**Custom ADB Server:**
-If using a custom ADB server (e.g., Docker, WSL), set the socket:
-```bash
-export ADB_SERVER_SOCKET="tcp:localhost:5037"
-```
-
-N.B. You may need to reboot your IDE
-
-### iOS Devices
-
-**Requirements:**
-- macOS with Xcode Command Line Tools
-- iOS Simulator running
-
-**Verify simulators:**
-```bash
-xcrun simctl list devices booted
-```
-
-**Start a simulator:**
-```bash
-open -a Simulator
-```
-
-## Troubleshooting
-
-### No devices found
-
-1. **Android:** Run `adb devices` to verify device connection
-2. **iOS:** Run `xcrun simctl list devices booted` to check running simulators
-3. Ensure USB debugging is enabled (Android)
-4. Try restarting ADB: `adb kill-server && adb start-server`
-
-### Screenshot capture fails
-
-1. Ensure device screen is unlocked
-2. For Android, verify screencap permission
-3. For iOS, ensure simulator is fully booted
-
-### Tool not detected in Windsurf
-
-1. Verify the import in `main.py` includes the tools module
-2. Check that `tools/__init__.py` exists
-3. Restart Windsurf after configuration changes

minitap_mcp-0.1.1/minitap/mcp/core/agents.py

@@ -1,19 +0,0 @@
-import os
-
-from minitap.mobile_use.sdk import Agent
-from minitap.mobile_use.sdk.builders import Builders
-
-
-def get_mobile_use_agent():
-    config = Builders.AgentConfig
-    custom_adb_socket = os.getenv("ADB_SERVER_SOCKET")
-    if custom_adb_socket:
-        parts = custom_adb_socket.split(":")
-        if len(parts) != 3:
-            raise ValueError(f"Invalid ADB server socket: {custom_adb_socket}")
-        _, host, port = parts
-        config = config.with_adb_server(host=host, port=int(port))
-    return Agent(config=config.build())
-
-
-agent = get_mobile_use_agent()