minitap-mcp 0.9.0__py3-none-any.whl

minitap/mcp/core/agents/compare_screenshots/agent.py

@@ -0,0 +1,75 @@
+import asyncio
+import base64
+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.images import get_screenshot_message_for_llm
+from minitap.mcp.server.cloud_mobile import get_cloud_mobile_id, get_cloud_screenshot
+
+
+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.
+
+    Supports both local devices (Android/iOS) and cloud devices.
+
+    Returns:
+        CompareScreenshotsOutput
+    """
+    system_message = Template(
+        Path(__file__).parent.joinpath("prompt.md").read_text(encoding="utf-8")
+    ).render()
+
+    cloud_mobile_id = get_cloud_mobile_id()
+
+    if cloud_mobile_id:
+        screenshot_bytes = await get_cloud_screenshot(cloud_mobile_id)
+        current_screenshot = base64.b64encode(screenshot_bytes).decode("utf-8")
+    else:
+        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/core/agents/compare_screenshots/eval/prompts/prompt_1.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/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/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/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/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/core/cloud_apk.py

@@ -0,0 +1,117 @@
+"""Cloud APK deployment utilities for uploading and installing APKs on cloud mobiles."""
+
+import uuid
+from pathlib import Path
+
+import httpx
+
+from minitap.mcp.core.config import settings
+
+
+async def upload_apk_to_cloud_mobile(apk_path: str) -> str:
+    """
+    Upload an APK file via Platform storage API to user storage bucket.
+
+    Args:
+        apk_path: Path to the APK file
+
+    Returns:
+        Filename to use with install-apk endpoint
+
+    Raises:
+        FileNotFoundError: If APK file doesn't exist
+        httpx.HTTPError: If upload fails
+        ValueError: If MINITAP_API_KEY or MINITAP_API_BASE_URL is not configured
+    """
+    if not settings.MINITAP_API_KEY:
+        raise ValueError("MINITAP_API_KEY is not configured")
+    if not settings.MINITAP_API_BASE_URL:
+        raise ValueError("MINITAP_API_BASE_URL is not configured")
+
+    apk_file = Path(apk_path)
+    if not apk_file.exists():
+        raise FileNotFoundError(f"APK file not found: {apk_path}")
+
+    # Use APP_PACKAGE_NAME env var if set, otherwise generate a random name
+    # Preserve the original file extension
+    extension = apk_file.suffix  # e.g., ".apk"
+    if settings.APP_PACKAGE_NAME:
+        # Strip any existing extension from APP_PACKAGE_NAME to avoid double extensions
+        base_name = Path(settings.APP_PACKAGE_NAME).stem
+        filename = f"{base_name}{extension}"
+    else:
+        filename = f"app_{uuid.uuid4().hex[:6]}{extension}"
+    api_key = settings.MINITAP_API_KEY.get_secret_value()
+    api_base_url = settings.MINITAP_API_BASE_URL.rstrip("/")
+
+    async with httpx.AsyncClient(timeout=300.0) as client:
+        # Step 1: Get signed upload URL from storage API
+        response = await client.get(
+            f"{api_base_url}/storage/signed-upload",
+            headers={"Authorization": f"Bearer {api_key}"},
+            params={"filenames": filename},
+        )
+        response.raise_for_status()
+        upload_data = response.json()
+
+        # Extract the signed URL for our file
+        signed_urls = upload_data.get("signed_urls", {})
+        if filename not in signed_urls:
+            raise ValueError(f"No signed URL returned for {filename}")
+
+        signed_url = signed_urls[filename]
+
+        # Step 2: Upload APK to signed URL
+        with open(apk_file, "rb") as f:
+            upload_response = await client.put(
+                signed_url,
+                content=f.read(),
+                headers={"Content-Type": "application/vnd.android.package-archive"},
+            )
+            upload_response.raise_for_status()
+
+        # Step 3: Return filename for install-apk call
+        return filename
+
+
+async def install_apk_on_cloud_mobile(filename: str) -> None:
+    """
+    Install an APK on a cloud mobile device via mobile-manager API.
+
+    Args:
+        filename: Filename returned from upload_apk_to_cloud_mobile
+
+    Raises:
+        httpx.HTTPError: If installation fails
+        ValueError: If required config settings are not configured
+    """
+    if not settings.MINITAP_API_KEY:
+        raise ValueError("MINITAP_API_KEY is not configured")
+    if not settings.MINITAP_DAAS_API:
+        raise ValueError("MINITAP_DAAS_API is not configured")
+    if not settings.CLOUD_MOBILE_NAME:
+        raise ValueError("CLOUD_MOBILE_NAME is not configured")
+
+    api_key = settings.MINITAP_API_KEY.get_secret_value()
+    base_url = settings.MINITAP_DAAS_API
+    cloud_mobile_name = settings.CLOUD_MOBILE_NAME
+
+    async with httpx.AsyncClient(timeout=120.0) as client:
+        cloud_mobile_response = await client.get(
+            f"{base_url}/virtual-mobiles/{cloud_mobile_name}",
+            headers={"Authorization": f"Bearer {api_key}"},
+        )
+        cloud_mobile_response.raise_for_status()
+        response_data = cloud_mobile_response.json()
+        cloud_mobile_uuid = response_data.get("id")
+        if not cloud_mobile_uuid:
+            raise ValueError(f"Cloud mobile '{cloud_mobile_name}' response missing 'id' field")
+        response = await client.post(
+            f"{base_url}/virtual-mobiles/{cloud_mobile_uuid}/install-apk",
+            headers={
+                "Authorization": f"Bearer {api_key}",
+                "Content-Type": "application/json",
+            },
+            json={"filename": filename},
+        )
+        response.raise_for_status()

minitap/mcp/core/config.py

@@ -0,0 +1,111 @@
+"""Configuration for the MCP server."""
+
+import os
+from urllib.parse import urlparse
+
+from dotenv import load_dotenv
+from pydantic import Field, SecretStr, model_validator
+from pydantic_settings import BaseSettings, SettingsConfigDict
+
+# Load environment variables from .env file
+load_dotenv(verbose=True)
+
+
+def _derive_mcp_url_from_base(base_url: str) -> str:
+    """Derive the MCP URL from the API base URL.
+
+    Extracts the scheme and host from the base URL and appends /api/mcp.
+    Example: https://dev.platform.minitap.ai/api/v1 -> https://dev.platform.minitap.ai/api/mcp/
+    """
+    parsed = urlparse(base_url)
+    return f"{parsed.scheme}://{parsed.netloc}/api/mcp/"
+
+
+def _derive_daas_url_from_base(base_url: str) -> str:
+    """Derive the DaaS API URL from the API base URL.
+
+    Extracts the scheme and host from the base URL and appends /api/daas.
+    Example: https://dev.platform.minitap.ai/api/v1 -> https://dev.platform.minitap.ai/api/daas/
+    """
+    parsed = urlparse(base_url)
+    return f"{parsed.scheme}://{parsed.netloc}/api/daas"
+
+
+def _derive_platform_base_url(api_base_url: str) -> str:
+    """Derive the platform base URL from the API base URL.
+
+    Extracts the scheme and host from the API URL (strips /api/v1 path).
+    Example: https://dev.platform.minitap.ai/api/v1 -> https://dev.platform.minitap.ai
+    """
+    parsed = urlparse(api_base_url)
+    return f"{parsed.scheme}://{parsed.netloc}"
+
+
+class MCPSettings(BaseSettings):
+    """Configuration class for MCP server."""
+
+    model_config = SettingsConfigDict(env_file=".env", extra="ignore")
+
+    # Minitap API configuration
+    MINITAP_API_KEY: SecretStr | None = Field(default=None)
+    MINITAP_API_BASE_URL: str = Field(default="https://platform.minitap.ai/api/v1")
+
+    # These URLs can be set explicitly, or will be derived from MINITAP_API_BASE_URL
+    MINITAP_DAAS_API: str | None = Field(default=None)
+    MINITAP_API_MCP_BASE_URL: str | None = Field(default=None)
+
+    OPEN_ROUTER_API_KEY: SecretStr | None = Field(default=None)
+
+    VISION_MODEL: str = Field(default="google/gemini-3-flash-preview")
+
+    # MCP server configuration (optional, for remote access)
+    MCP_SERVER_HOST: str = Field(default="0.0.0.0")
+    MCP_SERVER_PORT: int = Field(default=8000)
+
+    # Cloud Mobile configuration
+    # When set, the MCP server runs in cloud mode connecting to a Minitap cloud mobile
+    # instead of requiring a local device. Value can be a device name.
+    # Create cloud mobiles at https://platform.minitap.ai/cloud-mobiles
+    CLOUD_MOBILE_NAME: str | None = Field(default=None)
+
+    # Trajectory GIF download configuration
+    # When set, downloads the trajectory GIF after task execution to the specified folder.
+    # The folder is a directory where the GIF will be saved with the task run ID as filename.
+    TRAJECTORY_GIF_DOWNLOAD_FOLDER: str | None = Field(default=None)
+
+    # App package name override for uploads
+    # When set, uploaded APK/IPA files will use this name instead of a random UUID.
+    # The original file extension is preserved. Example: "my_app" -> "my_app.apk"
+    APP_PACKAGE_NAME: str | None = Field(default=None)
+
+    @model_validator(mode="after")
+    def derive_urls_from_base(self) -> "MCPSettings":
+        """Derive MCP and DaaS URLs from base URL if not explicitly set.
+
+        This ensures that setting MINITAP_API_BASE_URL to a different environment
+        (e.g., dev) automatically updates all related URLs.
+        """
+        if self.MINITAP_API_MCP_BASE_URL is None:
+            # Use object.__setattr__ to bypass Pydantic's frozen model protection
+            object.__setattr__(
+                self,
+                "MINITAP_API_MCP_BASE_URL",
+                _derive_mcp_url_from_base(self.MINITAP_API_BASE_URL),
+            )
+
+        if self.MINITAP_DAAS_API is None:
+            object.__setattr__(
+                self,
+                "MINITAP_DAAS_API",
+                _derive_daas_url_from_base(self.MINITAP_API_BASE_URL),
+            )
+
+        # Set MINITAP_BASE_URL in environment for mobile-use SDK compatibility.
+        # The SDK uses MINITAP_BASE_URL (e.g., https://dev.platform.minitap.ai) while
+        # MCP uses MINITAP_API_BASE_URL (e.g., https://dev.platform.minitap.ai/api/v1).
+        os.environ["MINITAP_BASE_URL"] = _derive_platform_base_url(self.MINITAP_API_BASE_URL)
+
+        return self
+
+
+settings = MCPSettings()  # type: ignore

minitap/mcp/core/decorators.py

@@ -0,0 +1,107 @@
+"""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, DeviceNotReadyError
+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 DeviceNotReadyError as e:
+            logger.error(
+                "device_not_ready_error",
+                tool_name=func.__name__,
+                error=str(e),
+                error_type=type(e).__name__,
+                device_state=e.state,
+            )
+            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 DeviceNotReadyError as e:
+            logger.error(
+                "device_not_ready_error",
+                tool_name=func.__name__,
+                error=str(e),
+                error_type=type(e).__name__,
+                device_state=e.state,
+            )
+            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