DroidMind

Instructions

Implementation Reference

• droidmind/tools/device_management.py:205-285 (handler)

  The main handler function for the 'android-device' MCP tool. Decorated with @mcp.tool(name='android-device'). It validates inputs based on action and dispatches to specific helper implementations (_list_devices_impl, _connect_device_impl, etc.) for list_devices, connect_device, disconnect_device, reboot_device, and device_properties actions.

  @mcp.tool(name="android-device")
  async def android_device(
      action: DeviceAction,
      ctx: Context,
      serial: str | None = None,
      ip_address: str | None = None,
      port: int = 5555,
      mode: str = "normal",
  ) -> str:
      """
      Perform various device management operations on Android devices.
  
      This single tool consolidates various device-related actions.
      The 'action' parameter determines the operation.
  
      Args:
          action: The specific device operation to perform.
          ctx: MCP Context for logging and interaction.
          serial (Optional[str]): Device serial number. Required by most actions except connect/list.
          ip_address (Optional[str]): IP address for 'connect_device' action.
          port (Optional[int]): Port for 'connect_device' action (default: 5555).
          mode (Optional[str]): Reboot mode for 'reboot_device' action (default: "normal").
  
      Returns:
          A string message indicating the result or status of the operation.
  
      ---
      Available Actions and their specific argument usage:
  
      1.  `action="list_devices"`
          - No specific arguments required beyond `ctx`.
      2.  `action="connect_device"`
          - Requires: `ip_address`
          - Optional: `port`
      3.  `action="disconnect_device"`
          - Requires: `serial`
      4.  `action="reboot_device"`
          - Requires: `serial`
          - Optional: `mode` (e.g., "normal", "recovery", "bootloader")
      5.  `action="device_properties"`
          - Requires: `serial`
      ---
      """
      try:
          # Argument checks based on action
          if (
              action
              in [
                  DeviceAction.DISCONNECT_DEVICE,
                  DeviceAction.REBOOT_DEVICE,
                  DeviceAction.DEVICE_PROPERTIES,
              ]
              and serial is None
          ):
              return f"❌ Error: 'serial' is required for action '{action.value}'."
  
          if action == DeviceAction.CONNECT_DEVICE and ip_address is None:
              return "❌ Error: 'ip_address' is required for action 'connect_device'."
  
          # Dispatch to implementations
          if action == DeviceAction.LIST_DEVICES:
              return await _list_devices_impl(ctx)
          if action == DeviceAction.CONNECT_DEVICE:
              # ip_address is checked not None above
              return await _connect_device_impl(ctx, ip_address, port)  # type: ignore
          if action == DeviceAction.DISCONNECT_DEVICE:
              return await _disconnect_device_impl(serial, ctx)  # type: ignore
          if action == DeviceAction.REBOOT_DEVICE:
              return await _reboot_device_impl(serial, ctx, mode)  # type: ignore
          if action == DeviceAction.DEVICE_PROPERTIES:
              return await _device_properties_impl(serial, ctx)  # type: ignore
  
          # Should not be reached if DeviceAction enum is comprehensive
          valid_actions = ", ".join([act.value for act in DeviceAction])
          logger.error("Invalid device action '%s' received. Valid actions are: %s", action, valid_actions)
          return f"❌ Error: Unknown device action '{action}'. Valid actions are: {valid_actions}."
  
      except Exception as e:
          logger.exception("Unexpected error during device operation %s for serial '%s': %s", action, serial, e)
          return f"❌ Error: An unexpected error occurred during '{action.value}': {e!s}"

• droidmind/tools/device_management.py:18-26 (schema)

  Enum class DeviceAction defining the possible actions (sub-commands) for the android-device tool, used as the 'action' parameter in the handler.

  class DeviceAction(str, Enum):
      """Defines the available sub-actions for the 'android-device' tool."""
  
      LIST_DEVICES = "list_devices"
      CONNECT_DEVICE = "connect_device"
      DISCONNECT_DEVICE = "disconnect_device"
      REBOOT_DEVICE = "reboot_device"
      DEVICE_PROPERTIES = "device_properties"

• droidmind/tools/device_management.py:28-56 (helper)

  Helper function implementing the 'list_devices' action: lists connected devices using get_device_manager().

  async def _list_devices_impl(ctx: Context) -> str:
      """
      List all connected Android devices.
  
      Returns:
          A formatted list of connected devices with their basic information.
      """
      try:
          devices = await get_device_manager().list_devices()
  
          if not devices:
              return "No devices connected. Use the connect_device tool to connect to a device."
  
          # Format the device information
          result = f"# Connected Android Devices ({len(devices)})\n\n"
  
          for i, device in enumerate(devices, 1):
              model = await device.model
              android_version = await device.android_version
              result += f"""## Device {i}: {model}
  - **Serial**: `{device.serial}`
  - **Android Version**: {android_version}
  """
  
          return result
      except Exception as e:
          logger.exception("Error in list_devices_impl: %s", e)
          return f"❌ Error listing devices: {e}\n\nCheck logs for detailed traceback."

• droidmind/tools/device_management.py:58-101 (helper)

  Helper function implementing the 'connect_device' action: validates IP/port and connects using get_device_manager().connect().

  async def _connect_device_impl(ctx: Context, ip_address: str, port: int = 5555) -> str:
      """
      Connect to an Android device over TCP/IP.
  
      Args:
          ip_address: The IP address of the device to connect to
          port: The port to connect to (default: 5555)
  
      Returns:
          A message indicating success or failure
      """
      # Validate IP address format
      ip_pattern = r"^(\d{1,3})\.(\d{1,3})\.(\d{1,3})\.(\d{1,3})$"
      if not re.match(ip_pattern, ip_address):
          return "❌ Invalid IP address format. Please use the format: xxx.xxx.xxx.xxx"
  
      # Validate port range
      if port < 1 or port > 65535:
          return "❌ Invalid port number. Port must be between 1 and 65535."
  
      try:
          # Attempt to connect to the device
          device = await get_device_manager().connect(ip_address, port)
  
          if device:
              model = await device.model
              android_version = await device.android_version
  
              return f"""
  # ✨ Device Connected Successfully! ✨
  
  - **Device**: {model}
  - **Connection**: {ip_address}:{port}
  - **Android Version**: {android_version}
  
  The device is now available for commands and operations.
              """
  
          return f"❌ Failed to connect to device at {ip_address}:{port}"
      except Exception as e:
          logger.exception("Error connecting to device in _connect_device_impl: %s", e)
          return f"❌ Error connecting to device: {e!s}"

• droidmind/tools/device_management.py:205-205 (registration)

  MCP tool registration decorator specifying the tool name as 'android-device'.

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