android-log

Instructions

Implementation Reference

• droidmind/tools/logs.py:467-536 (handler)

  Main handler function decorated with @mcp.tool(name='android-log'). Dispatches to implementation functions based on the 'action' parameter (get_device_logcat, get_app_logs, get_anr_logs, get_crash_logs, get_battery_stats).

  @mcp.tool(name="android-log")
  async def android_log(
      serial: str,
      action: LogAction,
      ctx: Context,
      package: str | None = None,
      lines: int = 1000,
      filter_expr: str = "",
      buffer: str = "main",
      format_type: str = "threadtime",
      max_size: int | None = 100000,
  ) -> str:
      """
      Perform various log retrieval operations on an Android device.
  
      This single tool consolidates various log-related actions.
      The 'action' parameter determines the operation.
  
      Args:
          serial: Device serial number.
          action: The specific log operation to perform.
          ctx: MCP Context for logging and interaction.
          package (Optional[str]): Package name for `get_app_logs` action.
          lines (int): Number of lines to fetch for logcat actions (default: 1000).
          filter_expr (Optional[str]): Logcat filter expression for `get_device_logcat`.
          buffer (Optional[str]): Logcat buffer for `get_device_logcat` (default: "main").
          format_type (Optional[str]): Logcat output format for `get_device_logcat` (default: "threadtime").
          max_size (Optional[int]): Max output size for `get_device_logcat` (default: 100KB).
  
      Returns:
          A string message containing the requested logs or status.
  
      ---
      Available Actions and their specific argument usage:
  
      1.  `action="get_device_logcat"`
          - Optional: `lines`, `filter_expr`, `buffer`, `format_type`, `max_size`.
      2.  `action="get_app_logs"`
          - Requires: `package`.
          - Optional: `lines`.
      3.  `action="get_anr_logs"`
          - No specific arguments beyond `serial` and `ctx`.
      4.  `action="get_crash_logs"`
          - No specific arguments beyond `serial` and `ctx`.
      5.  `action="get_battery_stats"`
          - No specific arguments beyond `serial` and `ctx`.
      ---
      """
      try:
          if action == LogAction.GET_APP_LOGS and package is None:
              return "❌ Error: 'package' is required for action 'get_app_logs'."
  
          if action == LogAction.GET_DEVICE_LOGCAT:
              return await _get_device_logcat_impl(serial, ctx, lines, filter_expr, buffer, format_type, max_size)
          if action == LogAction.GET_APP_LOGS:
              return await _get_app_logs_impl(serial, package, ctx, lines)  # type: ignore
          if action == LogAction.GET_ANR_LOGS:
              return await _get_anr_logs_impl(serial, ctx)
          if action == LogAction.GET_CRASH_LOGS:
              return await _get_crash_logs_impl(serial, ctx)
          if action == LogAction.GET_BATTERY_STATS:
              return await _get_battery_stats_impl(serial, ctx)
  
          valid_actions = ", ".join([la.value for la in LogAction])
          logger.error("Invalid log action '%s' received. Valid actions are: %s.", action, valid_actions)
          return f"❌ Error: Unknown log action '{action}'. Valid actions are: {valid_actions}."
  
      except Exception as e:
          logger.exception("Unexpected error during log operation %s for serial '%s': %s", action, serial, e)
          return f"❌ Error: An unexpected error occurred during '{action.value}': {e!s}"

• droidmind/tools/logs.py:20-27 (schema)

  LogAction enum defining the valid sub-actions for the android-log tool: get_device_logcat, get_app_logs, get_anr_logs, get_crash_logs, get_battery_stats.

  class LogAction(str, Enum):
      """Defines the available sub-actions for the 'android-log' tool."""
  
      GET_DEVICE_LOGCAT = "get_device_logcat"
      GET_APP_LOGS = "get_app_logs"
      GET_ANR_LOGS = "get_anr_logs"
      GET_CRASH_LOGS = "get_crash_logs"
      GET_BATTERY_STATS = "get_battery_stats"

• droidmind/tools/logs.py:467-467 (registration)

  Registration of the tool via @mcp.tool(name='android-log') decorator on the FastMCP instance.

  @mcp.tool(name="android-log")

• droidmind/tools/__init__.py:23-25 (registration)

  Re-export of android_log from droidmind.tools.logs for the tools package.

  from droidmind.tools.logs import (
      android_log,
  )

• droidmind/tools/logs.py:30-81 (helper)

  Helper function _get_filtered_logcat used by multiple action implementations to retrieve filtered logcat output.

  async def _get_filtered_logcat(
      device: Any,
      filter_expr: str,
      lines: int = 1000,
      buffer: str = "main",
      format_type: str = "threadtime",
      max_size: int | None = 100000,
  ) -> str:
      """
      Helper function to get filtered logcat output in a consistent format.
  
      Args:
          device: Device instance
          filter_expr: Optional filter expression for logcat
          lines: Number of recent lines to fetch
          buffer: Logcat buffer to use (main, system, crash, etc.)
          format_type: Format for logcat output
          max_size: Maximum output size in characters
  
      Returns:
          Formatted logcat output
      """
      try:
          # Build logcat command
          cmd = ["logcat", "-d", "-v", format_type]
  
          # Specify buffer if not main
          if buffer != "main":
              cmd.extend(["-b", buffer])
  
          # Add line limit if specified
          if lines > 0:
              cmd.extend(["-t", str(lines)])
  
          # Add filter if specified
          if filter_expr:
              cmd.extend(filter_expr.split())
  
          # Join command parts
          logcat_cmd = " ".join(cmd)
  
          # Get logcat output
          output = await device.run_shell(logcat_cmd)
  
          # Truncate if needed
          if max_size and len(output) > max_size:
              output = output[:max_size] + "\n... [Output truncated due to size limit]"
  
          return output
      except Exception as e:
          logger.exception("Error getting logcat output")
          return f"Error retrieving logcat output: {e!s}"