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

{minitap_mcp-0.4.0 → minitap_mcp-0.4.2}/PKG-INFO

@@ -1,16 +1,17 @@
 Metadata-Version: 2.3
 Name: minitap-mcp
-Version: 0.4.0
+Version: 0.4.2
 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: minitap-mobile-use>=2.8.2
 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: ruff==0.5.3 ; extra == 'dev'
 Requires-Dist: pytest==8.4.1 ; extra == 'dev'
 Requires-Dist: pytest-cov==5.0.0 ; extra == 'dev'

{minitap_mcp-0.4.0 → minitap_mcp-0.4.2}/minitap/mcp/core/agents/extract_figma_assets.py

@@ -1,7 +1,8 @@
 """Agent to extract Figma asset URLs from design context code."""
 
+import re
+import uuid
 from pathlib import Path
-from uuid import uuid4
 
 from jinja2 import Template
 from langchain_core.messages import BaseMessage, HumanMessage, SystemMessage
@@ -33,6 +34,35 @@ class ExtractedAssets(BaseModel):
     )
 
 
+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.
 
@@ -46,20 +76,21 @@ async def extract_figma_assets(design_context_code: str) -> ExtractedAssets:
         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{design_context_code}\n```"
+            content=f"Here is the code to analyze:\n\n```typescript\n{sanitized_code}\n```"
         ),
     ]
 
     llm = get_minitap_llm(
-        trace_id=str(uuid4()),
-        remote_tracing=True,
-        model="google/gemini-2.5-pro",
+        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

{minitap_mcp-0.4.0 → minitap_mcp-0.4.2}/minitap/mcp/core/config.py

@@ -16,6 +16,7 @@ class MCPSettings(BaseSettings):
     # Minitap API configuration
     MINITAP_API_KEY: SecretStr | None = Field(default=None)
     MINITAP_API_BASE_URL: str = Field(default="https://platform.minitap.ai/api/v1")
+    OPEN_ROUTER_API_KEY: SecretStr | None = Field(default=None)
 
     VISION_MODEL: str = Field(default="qwen/qwen-2.5-vl-7b-instruct")
 

minitap_mcp-0.4.2/minitap/mcp/core/decorators.py

@@ -0,0 +1,89 @@
+"""Decorators for MCP tools."""
+
+import inspect
+import traceback
+from collections.abc import Callable
+from functools import wraps
+from typing import Any, TypeVar
+
+from minitap.mcp.core.device import DeviceNotFoundError
+from minitap.mcp.core.logging_config import get_logger
+
+F = TypeVar("F", bound=Callable[..., Any])
+
+logger = get_logger(__name__)
+
+
+def handle_tool_errors[T: Callable[..., Any]](func: T) -> T:
+    """
+    Decorator that catches all exceptions in MCP tools and returns error messages.
+
+    This prevents unhandled exceptions from causing infinite loops in the MCP server.
+    Logs all errors with structured logging for better debugging.
+    """
+
+    @wraps(func)
+    async def async_wrapper(*args: Any, **kwargs: Any) -> Any:
+        try:
+            logger.info(
+                "tool_called",
+                tool_name=func.__name__,
+                args_count=len(args),
+                kwargs_keys=list(kwargs.keys()),
+            )
+            result = await func(*args, **kwargs)
+            logger.info("tool_completed", tool_name=func.__name__)
+            return result
+        except DeviceNotFoundError as e:
+            logger.error(
+                "device_not_found_error",
+                tool_name=func.__name__,
+                error=str(e),
+                error_type=type(e).__name__,
+            )
+            return f"Error: {str(e)}"
+        except Exception as e:
+            logger.error(
+                "tool_error",
+                tool_name=func.__name__,
+                error=str(e),
+                error_type=type(e).__name__,
+                traceback=traceback.format_exc(),
+            )
+            return f"Error in {func.__name__}: {type(e).__name__}: {str(e)}"
+
+    @wraps(func)
+    def sync_wrapper(*args: Any, **kwargs: Any) -> Any:
+        try:
+            logger.info(
+                "tool_called",
+                tool_name=func.__name__,
+                args_count=len(args),
+                kwargs_keys=list(kwargs.keys()),
+            )
+            result = func(*args, **kwargs)
+            logger.info("tool_completed", tool_name=func.__name__)
+            return result
+        except DeviceNotFoundError as e:
+            logger.error(
+                "device_not_found_error",
+                tool_name=func.__name__,
+                error=str(e),
+                error_type=type(e).__name__,
+            )
+            return f"Error: {str(e)}"
+        except Exception as e:
+            logger.error(
+                "tool_error",
+                tool_name=func.__name__,
+                error=str(e),
+                error_type=type(e).__name__,
+                traceback=traceback.format_exc(),
+            )
+            return f"Error in {func.__name__}: {type(e).__name__}: {str(e)}"
+
+    # Check if the function is async
+    if inspect.iscoroutinefunction(func):
+        return async_wrapper  # type: ignore
+    else:
+        return sync_wrapper  # type: ignore

{minitap_mcp-0.4.0 → minitap_mcp-0.4.2}/minitap/mcp/core/llm.py

@@ -26,3 +26,14 @@ def get_minitap_llm(
         },
     )
     return client
+
+
+def get_openrouter_llm(model_name: str, temperature: float = 1):
+    assert settings.OPEN_ROUTER_API_KEY is not None
+    client = ChatOpenAI(
+        model=model_name,
+        temperature=temperature,
+        api_key=settings.OPEN_ROUTER_API_KEY,
+        base_url="https://openrouter.ai/api/v1",
+    )
+    return client

minitap_mcp-0.4.2/minitap/mcp/core/logging_config.py

@@ -0,0 +1,59 @@
+"""Structured logging configuration using structlog."""
+
+import logging
+import sys
+
+import structlog
+
+
+def configure_logging(log_level: str = "INFO") -> None:
+    """Configure structlog with sensible defaults for the MCP server.
+
+    Args:
+        log_level: The logging level (DEBUG, INFO, WARNING, ERROR, CRITICAL)
+    """
+    # Configure standard library logging
+    logging.basicConfig(
+        format="%(message)s",
+        stream=sys.stdout,
+        level=getattr(logging, log_level.upper()),
+    )
+
+    # Configure structlog
+    structlog.configure(
+        processors=[
+            # Add log level to event dict
+            structlog.stdlib.add_log_level,
+            # Add timestamp
+            structlog.processors.TimeStamper(fmt="iso"),
+            # Add caller information (file, line, function)
+            structlog.processors.CallsiteParameterAdder(
+                parameters=[
+                    structlog.processors.CallsiteParameter.FILENAME,
+                    structlog.processors.CallsiteParameter.LINENO,
+                    structlog.processors.CallsiteParameter.FUNC_NAME,
+                ]
+            ),
+            # Stack info and exception formatting
+            structlog.processors.StackInfoRenderer(),
+            structlog.processors.format_exc_info,
+            # Render as JSON for structured output
+            structlog.processors.JSONRenderer(),
+        ],
+        wrapper_class=structlog.stdlib.BoundLogger,
+        context_class=dict,
+        logger_factory=structlog.stdlib.LoggerFactory(),
+        cache_logger_on_first_use=True,
+    )
+
+
+def get_logger(name: str) -> structlog.stdlib.BoundLogger:
+    """Get a structured logger instance.
+
+    Args:
+        name: The logger name (typically __name__ of the module)
+
+    Returns:
+        A structlog BoundLogger instance
+    """
+    return structlog.get_logger(name)

{minitap_mcp-0.4.0 → minitap_mcp-0.4.2}/minitap/mcp/main.py

@@ -1,7 +1,6 @@
 """MCP server for mobile-use with screen analysis capabilities."""
 
 import argparse
-import logging
 import os
 import sys
 import threading
@@ -28,9 +27,15 @@ from minitap.mobile_use.config import settings as sdk_settings
 from minitap.mcp.core.config import settings  # noqa: E402
 from minitap.mcp.core.device import DeviceInfo  # noqa: E402
 from minitap.mcp.core.device import list_available_devices
+from minitap.mcp.core.logging_config import (
+    configure_logging,  # noqa: E402
+    get_logger,
+)
 from minitap.mcp.server.middleware import MaestroCheckerMiddleware
 from minitap.mcp.server.poller import device_health_poller
 
+configure_logging(log_level=os.getenv("LOG_LEVEL", "INFO"))
+
 
 def main() -> None:
     """Main entry point for the MCP server."""
@@ -43,6 +48,13 @@ def main() -> None:
         action="store_true",
         help="Run as network server (uses MCP_SERVER_HOST and MCP_SERVER_PORT from env)",
     )
+    parser.add_argument(
+        "--port",
+        type=int,
+        required=False,
+        default=None,
+        help="Port to run the server on (overrides MCP_SERVER_PORT env variable)",
+    )
 
     args = parser.parse_args()
 
@@ -56,6 +68,11 @@ def main() -> None:
         settings.__init__()
         sdk_settings.__init__()
 
+    if args.port:
+        os.environ["MCP_SERVER_PORT"] = str(args.port)
+        settings.__init__()
+        sdk_settings.__init__()
+
     if not settings.MINITAP_API_KEY:
         raise ValueError("Minitap API key is required to run the MCP")
 
@@ -72,7 +89,7 @@ def main() -> None:
         mcp_lifespan()
 
 
-logger = logging.getLogger(__name__)
+logger = get_logger(__name__)
 
 mcp = FastMCP(
     name="mobile-use-mcp",

{minitap_mcp-0.4.0 → minitap_mcp-0.4.2}/minitap/mcp/tools/save_figma_assets.py

@@ -18,6 +18,7 @@ from minitap.mcp.core.agents.extract_figma_assets import (
 )
 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
 from minitap.mcp.core.models import (
     AssetDownloadResult,
     AssetDownloadSummary,
@@ -30,6 +31,8 @@ from minitap.mcp.tools.compare_screenshot_with_figma import (
     get_figma_screenshot,
 )
 
+logger = get_logger(__name__)
+
 
 @mcp.tool(
     name="save_figma_assets",
@@ -94,11 +97,31 @@ async def save_figma_assets(
     # Step 4: Download assets with resilient error handling
     download_summary = AssetDownloadSummary()
 
-    for asset in extracted_context.assets:
+    for idx, asset in enumerate(extracted_context.assets, 1):
+        logger.debug(
+            "Downloading asset",
+            idx=idx,
+            total_count=len(extracted_context.assets),
+            variable_name=asset.variable_name,
+            extension=asset.extension,
+        )
         result = download_asset(asset, assets_dir)
         if result.status == DownloadStatus.SUCCESS:
+            logger.debug(
+                "Asset downloaded successfully",
+                idx=idx,
+                variable_name=asset.variable_name,
+                extension=asset.extension,
+            )
             download_summary.successful.append(result)
         else:
+            logger.debug(
+                "Asset download failed",
+                idx=idx,
+                variable_name=asset.variable_name,
+                extension=asset.extension,
+                error=result.error,
+            )
             download_summary.failed.append(result)
 
     # Step 4.5: Save code implementation
@@ -121,7 +144,8 @@ async def save_figma_assets(
         + "\n\n"
         + commented_code_implementation_guidelines
         + "\n\n"
-        + commented_nodes_guidelines
+        + commented_nodes_guidelines,
+        encoding="utf-8",
     )
 
     # Step 5: Generate friendly output message

{minitap_mcp-0.4.0 → minitap_mcp-0.4.2}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "minitap-mcp"
-version = "0.4.0"
+version = "0.4.2"
 description = "Model Context Protocol server for controlling Android & iOS devices with natural language"
 readme = "PYPI_README.md"
 
@@ -17,10 +17,11 @@ dependencies = [
     "python-dotenv>=1.1.1",
     "pydantic>=2.12.0",
     "pydantic-settings>=2.10.1",
-    "minitap-mobile-use>=2.8.1",
+    "minitap-mobile-use>=2.8.2",
     "jinja2>=3.1.6",
     "langchain-core>=0.3.75",
     "pillow>=11.1.0",
+    "structlog>=24.4.0",
 ]
 
 [project.optional-dependencies]

minitap_mcp-0.4.0/minitap/mcp/core/decorators.py

@@ -1,42 +0,0 @@
-"""Decorators for MCP tools."""
-
-import inspect
-from collections.abc import Callable
-from functools import wraps
-from typing import Any, TypeVar
-
-from minitap.mcp.core.device import DeviceNotFoundError
-
-F = TypeVar("F", bound=Callable[..., Any])
-
-
-def handle_tool_errors[T: Callable[..., Any]](func: T) -> T:
-    """
-    Decorator that catches all exceptions in MCP tools and returns error messages.
-
-    This prevents unhandled exceptions from causing infinite loops in the MCP server.
-    """
-
-    @wraps(func)
-    async def async_wrapper(*args: Any, **kwargs: Any) -> Any:
-        try:
-            return await func(*args, **kwargs)
-        except DeviceNotFoundError as e:
-            return f"Error: {str(e)}"
-        except Exception as e:
-            return f"Error in {func.__name__}: {type(e).__name__}: {str(e)}"
-
-    @wraps(func)
-    def sync_wrapper(*args: Any, **kwargs: Any) -> Any:
-        try:
-            return func(*args, **kwargs)
-        except DeviceNotFoundError as e:
-            return f"Error: {str(e)}"
-        except Exception as e:
-            return f"Error in {func.__name__}: {type(e).__name__}: {str(e)}"
-
-    # Check if the function is async
-    if inspect.iscoroutinefunction(func):
-        return async_wrapper  # type: ignore
-    else:
-        return sync_wrapper  # type: ignore

minitap_mcp-0.4.0/minitap/mcp/tools/go_back.py

@@ -1,42 +0,0 @@
-import requests
-
-from minitap.mcp.core.decorators import handle_tool_errors
-from minitap.mcp.main import mcp
-
-
-@mcp.tool(
-    name="go_back",
-    tags={"requires-maestro"},
-    description="""
-    Sends a 'back' command to the mobile device automation server.
-    """,
-)
-@handle_tool_errors
-async def go_back() -> str:
-    """Send a back command to the mobile device."""
-    try:
-        response = requests.post(
-            "http://localhost:9999/api/run-command",
-            headers={
-                "User-Agent": "python-requests/2.32.4",
-                "Accept-Encoding": "gzip, deflate, zstd",
-                "Accept": "*/*",
-                "Connection": "keep-alive",
-                "Content-Type": "application/json",
-            },
-            json={"yaml": "back\n"},
-            timeout=30,
-        )
-
-        if response.status_code == 200:
-            return f"Successfully sent back command. Response: {response.text}"
-        else:
-            return (
-                f"Failed to send back command. "
-                f"Status code: {response.status_code}, Response: {response.text}"
-            )
-
-    except requests.exceptions.RequestException as e:
-        return f"Error sending back command: {str(e)}"
-    except Exception as e:
-        return f"Unexpected error: {str(e)}"