DroidMind

Instructions

Implementation Reference

• droidmind/tools/app_management.py:750-899 (handler)

  Main handler for 'android-app' tool. Decorated with @mcp.tool(name='android-app'). Handles multiple sub-actions via AppAction enum by dispatching to internal helper functions.

  @mcp.tool(name="android-app")
  async def app_operations(
      # pylint: disable=too-many-arguments
      serial: str,
      action: AppAction,
      ctx: Context,
      package: str | None = None,  # Required for most actions
      apk_path: str | None = None,  # For install_app
      reinstall: bool = False,  # For install_app
      grant_permissions: bool = True,  # For install_app
      keep_data: bool = False,  # For uninstall_app
      activity: str = "",  # For start_app
      extras: dict[str, str] | None = None,  # For start_intent
      include_system_apps: bool = False,  # For list_packages
      include_app_name: bool = False,  # For list_packages
      include_apk_path: bool = True,  # For list_packages
      max_packages: int | None = 200,  # For list_packages
  ) -> str:
      """
      Perform various application management operations on an Android device.
  
      This single tool consolidates various app-related actions.
      The 'action' parameter determines the operation.
  
      Args:
          serial: Device serial number.
          action: The specific app operation to perform.
          ctx: MCP Context for logging and interaction.
          package (Optional[str]): Package name for the target application. Required by most actions.
          apk_path (Optional[str]): Path to the APK file (local to the server). Used by `install_app`.
          reinstall (Optional[bool]): Whether to reinstall if app exists. Used by `install_app`.
          grant_permissions (Optional[bool]): Whether to grant all requested permissions. Used by `install_app`.
          keep_data (Optional[bool]): Whether to keep app data and cache directories. Used by `uninstall_app`.
          activity (Optional[str]): Optional activity name to start. Used by `start_app`.
          extras (Optional[dict[str, str]]): Optional intent extras. Used by `start_intent`.
          include_system_apps (Optional[bool]): Whether to include system apps. Used by `list_packages`.
          include_app_name (Optional[bool]): Whether to include app labels (best-effort). Used by `list_packages`.
          include_apk_path (Optional[bool]): Whether to include APK paths. Used by `list_packages`.
          max_packages (Optional[int]): Max packages to return. Used by `list_packages`.
  
      Returns:
          A string message indicating the result or status of the operation.
  
      ---
      Available Actions and their specific argument usage:
  
      1.  `action="install_app"`
          - Requires: `apk_path`
          - Optional: `reinstall`, `grant_permissions`
      2.  `action="uninstall_app"`
          - Requires: `package`
          - Optional: `keep_data`
      3.  `action="start_app"`
          - Requires: `package`
          - Optional: `activity`
      3b. `action="start_intent"`
          - Requires: `package`, `activity`
          - Optional: `extras`
      4.  `action="stop_app"`
          - Requires: `package`
      5.  `action="clear_app_data"`
          - Requires: `package`
      6.  `action="list_packages"`
          - Optional: `include_system_apps`, `include_app_name`, `include_apk_path`, `max_packages`
      7.  `action="get_app_manifest"`
          - Requires: `package`
      8.  `action="get_app_permissions"`
          - Requires: `package`
      9.  `action="get_app_activities"`
          - Requires: `package`
      10. `action="get_app_info"`
          - Requires: `package`
      ---
      """
      try:
          # Basic argument checks
          if (
              action
              in [
                  AppAction.UNINSTALL_APP,
                  AppAction.START_APP,
                  AppAction.START_INTENT,
                  AppAction.STOP_APP,
                  AppAction.CLEAR_APP_DATA,
                  AppAction.GET_APP_MANIFEST,
                  AppAction.GET_APP_PERMISSIONS,
                  AppAction.GET_APP_ACTIVITIES,
                  AppAction.GET_APP_INFO,
              ]
              and package is None
          ):
              return f"❌ Error: 'package' is required for action '{action.value}'."
  
          if action == AppAction.INSTALL_APP and apk_path is None:
              return "❌ Error: 'apk_path' is required for action 'install_app'."
  
          if action == AppAction.START_INTENT and not activity:
              return "❌ Error: 'activity' is required for action 'start_intent'."
  
          # Dispatch to implementations
          if action == AppAction.INSTALL_APP:
              # We already checked apk_path is not None
              return await _install_app_impl(serial, apk_path, ctx, reinstall, grant_permissions)  # type: ignore
          if action == AppAction.UNINSTALL_APP:
              return await _uninstall_app_impl(serial, package, ctx, keep_data)  # type: ignore
          if action == AppAction.START_APP:
              return await _start_app_impl(serial, package, ctx, activity)  # type: ignore
          if action == AppAction.START_INTENT:
              assert package is not None
              return await start_intent(
                  serial=serial,
                  package=package,
                  activity=activity,
                  ctx=ctx,
                  extras=extras,
                  device_manager=get_device_manager(),
              )  # type: ignore[arg-type]
          if action == AppAction.STOP_APP:
              return await _stop_app_impl(serial, package, ctx)  # type: ignore
          if action == AppAction.CLEAR_APP_DATA:
              return await _clear_app_data_impl(serial, package, ctx)  # type: ignore
          if action == AppAction.LIST_PACKAGES:
              return await _list_packages_impl(
                  serial,
                  ctx,
                  include_system_apps=include_system_apps,
                  include_app_name=include_app_name,
                  include_apk_path=include_apk_path,
                  max_packages=max_packages,
              )
          if action == AppAction.GET_APP_MANIFEST:
              return await _get_app_manifest_impl(serial, package, ctx)  # type: ignore
          if action == AppAction.GET_APP_PERMISSIONS:
              return await _get_app_permissions_impl(serial, package, ctx)  # type: ignore
          if action == AppAction.GET_APP_ACTIVITIES:
              return await _get_app_activities_impl(serial, package, ctx)  # type: ignore
          if action == AppAction.GET_APP_INFO:
              return await _get_app_info_impl(serial, package, ctx)  # type: ignore
  
          # Should not be reached if AppAction enum is comprehensive
          valid_actions = ", ".join([act.value for act in AppAction])
          logger.error("Invalid app action '%s' received. Valid actions are: %s", action, valid_actions)
          return f"❌ Error: Unknown app action '{action}'. Valid actions are: {valid_actions}."
  
      except Exception as e:
          logger.exception(
              "Unexpected error during app operation %s on %s for package '%s': %s", action, serial, package, e
          )
          return f"❌ Error: An unexpected error occurred during '{action.value}': {e!s}"

• droidmind/tools/app_management.py:21-35 (schema)

  AppAction Enum: Defines all sub-actions (install_app, uninstall_app, etc.) for the android-app tool, used as the 'action' parameter.

  class AppAction(str, Enum):
      """Defines the available sub-actions for the 'android-app' tool."""
  
      INSTALL_APP = "install_app"
      UNINSTALL_APP = "uninstall_app"
      START_APP = "start_app"
      START_INTENT = "start_intent"
      STOP_APP = "stop_app"
      CLEAR_APP_DATA = "clear_app_data"
      LIST_PACKAGES = "list_packages"
      GET_APP_MANIFEST = "get_app_manifest"
      GET_APP_PERMISSIONS = "get_app_permissions"
      GET_APP_ACTIVITIES = "get_app_activities"
      GET_APP_INFO = "get_app_info"

• droidmind/tools/app_management.py:37-52 (schema)

  PackageInfo dataclass: Type definition for extracted package metadata like version, paths, etc.

  @dataclass
  class PackageInfo:
      """Basic package information."""
  
      version_code: str | None = None
      version_name: str | None = None
      min_sdk: str | None = None
      target_sdk: str | None = None
      install_path: str = "Unknown"
      first_install: str = "Unknown"
      last_update: str | None = None
      user_id: str = "Unknown"
      cpu_arch: str | None = None
      data_dir: str | None = None
      flags: str | None = None

• droidmind/tools/app_management.py:54-283 (helper)

  AppAnalyzer class: Static methods for parsing dumpsys package output to extract and format manifest info, permissions, components (activities, services, etc.).

  class AppAnalyzer:
      """Class for analyzing and extracting app information."""
  
      @staticmethod
      def extract_package_info(dump_output: str) -> PackageInfo:
          """Extract basic package information from dumpsys output."""
          info = PackageInfo()
  
          # Version info
          if match := re.search(r"versionCode=(\d+)", dump_output):
              info.version_code = match.group(1)
          if match := re.search(r"versionName=([^\s]+)", dump_output):
              info.version_name = match.group(1)
          if match := re.search(r"minSdk=(\d+)", dump_output):
              info.min_sdk = match.group(1)
          if match := re.search(r"targetSdk=(\d+)", dump_output):
              info.target_sdk = match.group(1)
  
          # Paths and IDs
          if match := re.search(r"codePath=([^\s]+)", dump_output):
              info.install_path = match.group(1)
          if match := re.search(r"firstInstallTime=([^\r\n]+)", dump_output):
              info.first_install = match.group(1)
          if match := re.search(r"lastUpdateTime=([^\r\n]+)", dump_output):
              info.last_update = match.group(1)
          if match := re.search(r"userId=(\d+)", dump_output):
              info.user_id = match.group(1)
  
          # System info
          if match := re.search(r"primaryCpuAbi=([^\s]+)", dump_output):
              if match.group(1) != "null":
                  info.cpu_arch = match.group(1)
          if match := re.search(r"dataDir=([^\s]+)", dump_output):
              info.data_dir = match.group(1)
          if match := re.search(r"flags=\[\s([^\]]+)\s\]", dump_output):
              info.flags = match.group(1)
  
          return info
  
      @staticmethod
      def format_package_info(info: PackageInfo) -> str:
          """Format package information as markdown."""
          manifest = "## Package Information\n\n"
  
          # Version info
          if any([info.version_code, info.version_name, info.min_sdk, info.target_sdk]):
              if info.version_code:
                  manifest += f"- **Version Code**: {info.version_code}\n"
              if info.version_name:
                  manifest += f"- **Version Name**: {info.version_name}\n"
              if info.min_sdk:
                  manifest += f"- **Min SDK**: {info.min_sdk}\n"
              if info.target_sdk:
                  manifest += f"- **Target SDK**: {info.target_sdk}\n"
  
          # Paths and dates
          manifest += f"- **Install Path**: {info.install_path}\n"
          manifest += f"- **First Install**: {info.first_install}\n"
          if info.last_update:
              manifest += f"- **Last Update**: {info.last_update}\n"
          manifest += f"- **User ID**: {info.user_id}\n"
  
          # Optional system info
          if info.cpu_arch:
              manifest += f"- **CPU Architecture**: {info.cpu_arch}\n"
          if info.data_dir:
              manifest += f"- **Data Directory**: {info.data_dir}\n"
          if info.flags:
              manifest += f"- **Flags**: {info.flags}\n"
  
          return manifest
  
      @staticmethod
      def extract_permissions(dump_output: str) -> tuple[list[str], list[str]]:
          """Extract declared and requested permissions from dumpsys output."""
          declared_perms = []
          requested_perms = []
  
          # Extract declared permissions
          if declared_match := re.compile(r"declared permissions:\s*\r?\n((?:\s+[^\r\n]+\r?\n)+)", re.MULTILINE).search(
              dump_output
          ):
              declared_block = declared_match.group(1)
              for line in declared_block.split("\n"):
                  if perm_match := re.match(r"\s+([^:]+):", line.strip()):
                      declared_perms.append(perm_match.group(1))
  
          # Extract requested permissions
          if requested_match := re.compile(r"requested permissions:\s*\r?\n((?:\s+[^\r\n]+\r?\n)+)", re.MULTILINE).search(
              dump_output
          ):
              requested_block = requested_match.group(1)
              requested_perms = [line.strip() for line in requested_block.split("\n") if line.strip()]
  
          return declared_perms, requested_perms
  
      @staticmethod
      def format_permissions(declared_perms: list[str], requested_perms: list[str]) -> str:
          """Format permissions as markdown."""
          manifest = "\n## Permissions\n\n"
  
          # Declared permissions
          manifest += "### Declared Permissions\n\n"
          if declared_perms:
              for perm in declared_perms:
                  manifest += f"- `{perm}`\n"
          else:
              manifest += "No declared permissions.\n"
  
          # Requested permissions
          manifest += "\n### Requested Permissions\n\n"
          if requested_perms:
              for perm in requested_perms:
                  manifest += f"- `{perm}`\n"
          else:
              manifest += "No requested permissions.\n"
  
          return manifest
  
      @staticmethod
      def extract_components(dump_output: str, package: str) -> tuple[list[str], list[str], list[str], list[str]]:
          """Extract activities, services, providers, and receivers from dumpsys output."""
          activities = []
          services = []
          providers = []
          receivers = []
  
          # Extract activities
          activity_pattern = re.compile(r"([a-zA-Z0-9_$.\/]+/[a-zA-Z0-9_$.]+) filter", re.MULTILINE)
          main_activity_pattern = re.compile(r"([a-zA-Z0-9_$.]+/\.[a-zA-Z0-9_$.]+) filter", re.MULTILINE)
  
          for match in activity_pattern.finditer(dump_output):
              activity = match.group(1)
              if activity not in activities and activity.startswith(f"{package}/"):
                  activities.append(activity)
  
          for match in main_activity_pattern.finditer(dump_output):
              activity = match.group(1)
              if activity not in activities and activity.startswith(f"{package}/"):
                  activities.append(activity)
  
          # Extract services
          if service_section_match := re.search(
              r"Service Resolver Table:(.*?)(?:\r?\n\r?\n|\r?\nProvider Resolver Table:)", dump_output, re.DOTALL
          ):
              service_section = service_section_match.group(1)
              service_pattern = re.compile(r"([a-zA-Z0-9_$.\/]+/[a-zA-Z0-9_$.]+)", re.MULTILINE)
              for match in service_pattern.finditer(service_section):
                  service = match.group(1)
                  if service not in services and service.startswith(f"{package}/"):
                      services.append(service)
  
          # Extract providers
          if provider_section_match := re.search(
              r"Provider Resolver Table:(.*?)(?:\r?\n\r?\n|\r?\nReceiver Resolver Table:)", dump_output, re.DOTALL
          ):
              provider_section = provider_section_match.group(1)
              provider_pattern = re.compile(r"([a-zA-Z0-9_$.\/]+/[a-zA-Z0-9_$.]+)", re.MULTILINE)
              for match in provider_pattern.finditer(provider_section):
                  provider = match.group(1)
                  if provider not in providers and provider.startswith(f"{package}/"):
                      providers.append(provider)
  
          # Extract receivers
          if receiver_section_match := re.search(
              r"Receiver Resolver Table:(.*?)(?:\r?\n\r?\n|\r?\nService Resolver Table:)", dump_output, re.DOTALL
          ):
              receiver_section = receiver_section_match.group(1)
              receiver_pattern = re.compile(r"([a-zA-Z0-9_$.\/]+/[a-zA-Z0-9_$.]+)", re.MULTILINE)
              for match in receiver_pattern.finditer(receiver_section):
                  receiver = match.group(1)
                  if receiver not in receivers and receiver.startswith(f"{package}/"):
                      receivers.append(receiver)
  
          return activities, services, providers, receivers
  
      @staticmethod
      def get_intent_filters(component: str, dump_output: str) -> list[str]:
          """Extract intent filters for a component."""
          component_short = component.split("/")[-1]
          filters = []
          in_filter = False
  
          for line in dump_output.splitlines():
              if component_short in line and "filter" in line:
                  in_filter = True
                  continue
              if in_filter:
                  if not line.strip() or line.startswith("      Filter"):
                      continue
                  if not line.startswith(" " * 10):
                      in_filter = False
                      break
                  filter_info = line.strip()
                  if filter_info and filter_info not in filters:
                      filters.append(filter_info)
  
          return filters
  
      @staticmethod
      def format_component_section(title: str, components: list[str], dump_output: str) -> str:
          """Format a component section as markdown."""
          manifest = f"\n### {title}\n\n"
  
          if not components:
              manifest += f"No {title.lower()} found.\n"
              return manifest
  
          for component in components:
              manifest += f"- `{component}`\n"
              filters = AppAnalyzer.get_intent_filters(component, dump_output)
              if filters:
                  manifest += "  Intent Filters:\n"
                  for f in filters:
                      manifest += f"  - {f}\n"
  
          return manifest
  
      @staticmethod
      def format_components(
          activities: list[str], services: list[str], providers: list[str], receivers: list[str], dump_output: str
      ) -> str:
          """Format all components as markdown."""
          manifest = "\n## Components\n"
          manifest += AppAnalyzer.format_component_section("Activities", activities, dump_output)
          manifest += AppAnalyzer.format_component_section("Services", services, dump_output)
          manifest += AppAnalyzer.format_component_section("Content Providers", providers, dump_output)
          manifest += AppAnalyzer.format_component_section("Broadcast Receivers", receivers, dump_output)
          return manifest

• droidmind/tools/app_management.py:750-750 (registration)

  Tool registration decorator @mcp.tool(name='android-app') applied to the handler function.

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