DroidMind

Instructions

Implementation Reference

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

  Primary handler function for the 'android-log' MCP tool. Includes registration via @mcp.tool decorator and dispatches to specialized helper functions based on the action enum.
  @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-28 (schema)

  Enum type definition for the 'action' input parameter, specifying the sub-operations supported by the android-log tool.
  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:30-82 (helper)

  Key helper function used by the handler to execute logcat commands on the Android device with filtering, buffering, and truncation options.
  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}"
• droidmind/tools/logs.py:84-133 (helper)

  Implementation helper for 'get_device_logcat' action, formats and retrieves device logcat output.
  async def _get_device_logcat_impl( serial: str, ctx: Context, lines: int = 1000, filter_expr: str = "", buffer: str = "main", format_type: str = "threadtime", max_size: int | None = 100000, ) -> str: """ Get logcat output from a device with flexible filtering options. Args: serial: Device serial number lines: Number of recent lines to fetch (default: 1000) Higher values may impact performance and context window limits. filter_expr: Optional filter expression (e.g., "ActivityManager:I *:S") Use to focus on specific tags or priority levels buffer: Logcat buffer to use (main, system, crash, radio, events, etc.) format_type: Format for logcat output (threadtime, brief, tag, process, etc.) max_size: Maximum output size in characters (default: 100000) Set to None for unlimited (not recommended) Returns: Recent logcat entries in markdown format """ device = await get_device_manager().get_device(serial) if device is None: return f"Error: Device {serial} not found." await ctx.info(f"Retrieving logcat from device {serial} (buffer: {buffer})...") try: output = await _get_filtered_logcat(device, filter_expr, lines, buffer, format_type, max_size) # Format the output result = ["# Device Logcat Output 📱\n"] result.append(f"## Last {lines} Lines from '{buffer}' Buffer") if filter_expr: result.append(f"\nFilter: `{filter_expr}`") result.append("\n```log") result.append(output) result.append("```") return "\n".join(result) except Exception as e: logger.exception("Error getting logcat output in _get_device_logcat_impl") return f"Error retrieving logcat output: {e!s}"