app_data¶

Clearing an installed package's full application data (adb shell pm clear) on a connected device — its databases, shared preferences, files and cache are all wiped, resetting the app to a fresh-install state. This is the unscoped pm clear; there is no reliable cross-version ADB way to clear just the cache (pm clear --cache-only is Android 11+ only), so the tool is destructive-category and only registered when the server opts in.

`adb_automation_mcp.modules.app_data.tools` ¶

Module-level, statically-introspectable tool functions for the app_data module.

Kept as plain top-level functions, never closures, so that documentation tooling and the registry meta-test can both introspect them directly.

`clear_app_cache(ctx: Context, serial: str, package_name: str, user_id: int | None = None) -> ClearAppCacheResult` `async` ¶

Clear only a package's cache, leaving its data intact.

Prefers adb shell pm clear --cache-only (Android 11+). If that command is unsupported, or hangs (a known bug on some emulator images), it falls back to removing the package's per-user cache directories directly (/data/user*/<uid>/<pkg>/cache and code_cache) — which needs adbd running as root. Either path touches only cache, never the app's normal data; this never falls back to the destructive unscoped pm clear.

Parameters:

Name	Type	Description	Default
`serial`	`str`	The target device's adb serial (see list_connected_devices).	required
`package_name`	`str`	The package whose cache to clear, e.g. "com.example.app".	required
`user_id`	`int \| None`	Clear for one specific Android user (see list_users). Omit to clear for the current user — cache is per-user, so a user is always resolved and reported back.	`None`

Returns:

Type	Description
`ClearAppCacheResult`	The serial, package_name, the user_id actually cleared, method ("pm_clear_cache_only" or "rm_cache_dirs"), success (always True — see Error handling), and output.

Error handling

A build where pm clear --cache-only is unavailable AND the direct cache-dir removal is denied (adbd not root) raises CACHE_ONLY_UNSUPPORTED. An unknown serial or unresponsive adb binary raises DEVICE_NOT_FOUND/ADB_UNAVAILABLE. On the pm path: a package not installed for the target user raises PACKAGE_NOT_FOUND, a permission-refused clear raises PERMISSION_DENIED, pm's bare "Failed" raises ANDROID_REJECTED. Any other failure raises BACKEND_ERROR.

Example

Called with serial="emulator-5554", package_name="com.example.app". A typical response:

{
  "status": "success",
  "message": "Cleared cache for com.example.app (user 0) on emulator-5554.",
  "data": {
    "serial": "emulator-5554",
    "package_name": "com.example.app",
    "user_id": 0,
    "method": "pm_clear_cache_only",
    "success": true,
    "output": "Success\n"
  },
  "error": null
}

Source code in src/adb_automation_mcp/modules/app_data/tools.py

@category("write")
async def clear_app_cache(
    ctx: Context, serial: str, package_name: str, user_id: int | None = None
) -> ClearAppCacheResult:
    """Clear only a package's cache, leaving its data intact.

    Prefers `adb shell pm clear --cache-only` (Android 11+). If that command
    is unsupported, or hangs (a known bug on some emulator images), it falls
    back to removing the package's per-user cache directories directly
    (`/data/user*/<uid>/<pkg>/cache` and `code_cache`) — which needs adbd
    running as root. Either path touches only cache, never the app's normal
    data; this never falls back to the destructive unscoped `pm clear`.

    Args:
        serial: The target device's adb serial (see list_connected_devices).
        package_name: The package whose cache to clear, e.g. "com.example.app".
        user_id: Clear for one specific Android user (see list_users). Omit to
            clear for the current user — cache is per-user, so a user is always
            resolved and reported back.

    Returns:
        The serial, package_name, the user_id actually cleared, method
        ("pm_clear_cache_only" or "rm_cache_dirs"), success (always True — see
        Error handling), and output.

    Error handling:
        A build where `pm clear --cache-only` is unavailable AND the direct
        cache-dir removal is denied (adbd not root) raises
        CACHE_ONLY_UNSUPPORTED. An unknown serial or unresponsive adb binary
        raises DEVICE_NOT_FOUND/ADB_UNAVAILABLE. On the `pm` path: a package
        not installed for the target user raises PACKAGE_NOT_FOUND, a
        permission-refused clear raises PERMISSION_DENIED, pm's bare "Failed"
        raises ANDROID_REJECTED. Any other failure raises BACKEND_ERROR.

    Example:
        Called with serial="emulator-5554", package_name="com.example.app".
        A typical response:

        ```json
        {
          "status": "success",
          "message": "Cleared cache for com.example.app (user 0) on emulator-5554.",
          "data": {
            "serial": "emulator-5554",
            "package_name": "com.example.app",
            "user_id": 0,
            "method": "pm_clear_cache_only",
            "success": true,
            "output": "Success\\n"
          },
          "error": null
        }
        ```
    """
    services = cast("dict[str, object]", ctx.lifespan_context["services"])
    app_data = cast(AppDataService, services["app_data"])
    return await app_data.clear_app_cache(serial, package_name, user_id=user_id)

`clear_app_data(ctx: Context, serial: str, package_name: str, user_id: int | None = None) -> ClearAppDataResult` `async` ¶

Wipe a package's full application data on a device: adb shell pm clear.

Resets the app to a fresh-install state — its databases, shared preferences, files and cache are all deleted. This is the unscoped pm clear, the only variant supported on effectively every Android version; there is no reliable cross-version ADB way to clear just the cache (pm clear --cache-only is Android 11+ only). Use this only when losing the app's data is acceptable.